Phase 4: LangGraph reasoning agent integration

[jv-singh]

Summary

This PR implements the Phase 4 LangGraph Reasoning Agent for the recommendation engine and introduces LLM-powered recommendation generation grounded in real user goals and activity signals.

The previous recommendation engine consumed real Supabase data but generated recommendations using deterministic templates. While recommendations referenced actual goals and signals, the reasoning itself remained static.

This implementation introduces a LangGraph-based reasoning layer that uses an LLM (Groq by default, with Anthropic support preserved) to generate contextual recommendations while maintaining complete backward compatibility through deterministic fallback logic.

Key Changes

• Added src/lpi/langgraph_agent.py
• Added LangGraph reasoning workflow
• Added Groq provider integration
• Preserved Anthropic compatibility
• Added hybrid recommendation architecture
• Preserved deterministic fallback contract
• Preserved recommendation API schema
• Preserved frontend compatibility
• Added required dependencies (langgraph, anthropic, groq)
• Applied repository-wide Ruff formatting updates

Architecture

GET /api/v1/recommendations/{user_id}
        │
        ▼
generate_recommendations(user_id)
        │
        ├─► Try LangGraph Agent
        │       │
        │       ├─► Success → Return LLM recommendations
        │       │
        │       └─► Failure → Return None
        │
        └─► Deterministic fallback engine

Hybrid Recommendation Strategy

The final implementation uses a hybrid architecture:

• LLM generates recommendation actions and reasoning.
• Engine derives phase progression deterministically.
• Engine derives priority scoring deterministically.
• Goal and signal references are validated against real user data.
• Existing recommendation contracts remain unchanged.

Validation Performed

Checkpoint 1

LangGraph agent imports successfully and safely returns None when API key is unavailable.

Checkpoint 2

Recommendation engine invokes LangGraph first and falls back correctly.

Checkpoint 3

Recommendation test suite passes.

26 passed
0 failed

Checkpoint 4

Live LLM integration verified.

Example goal:

Ship the dashboard

Generated recommendations explicitly referenced:

• dashboard
• goal-1
• reality-emulation
• concurrent-engineering

confirming grounded reasoning rather than template-based output.

Checkpoint 5

Full repository validation completed.

164 passed

Type

• Feature (new endpoint / model)
• Fix (bug, test failure)
• Refactor
• Docs / reports

Checklist

• Ruff checks completed
• Recommendation tests passing
• Full test suite passing
• Live LLM integration verified
• No secrets committed
• PR targets staging

Tests Passing

• tests/test_recommendations.py
• Full test suite (164 passed)

Daily Report Reference

Phase 4 LangGraph Reasoning Agent implementation report.

Note:

You see many files changed however the reality is this PR
Phase4_LangGraph_Reasoning_Agent_Report.docx
contains 27 files of formatting changes mixed with 4 files of actual feature work.