ADR 0011: LangGraph.js + GPT-5.4 Mini (primary) + Gemini 2.5 Flash (fallback)

Status: Accepted
Date: 2026-04-17
Deciders: Ideony team

Context

Ideony’s triage flow converts free-form user descriptions (“my bathroom tap is dripping, needs fixing today”) into structured booking fields (category, urgency, details). Simple regex/keyword matching produces poor extraction quality. A stateful multi-step agent with fallback and confidence-gating is needed.

Decision

Use LangGraph.js (StateGraph orchestration) with LangSmith EU tracing (free tier, 5K traces/month). GPT-5.4 Mini is the primary model for all LangGraph agents. Gemini 2.5 Flash ($0.30/M input, 96% JSON validity, EU region) is the fallback model on a conditional edge when the primary fails or produces unparseable JSON. The AI module lives in apps/api/src/modules/ai/; graph code is separated from NestJS decorators in agent.factory.ts.

Consequences

LangGraph StateGraph provides conditional edges, checkpoints, and retry logic without custom orchestration code.
LangSmith EU gives free distributed tracing; EU region satisfies GDPR.
Gemini 2.5 Flash fallback provides model-level redundancy with strong JSON validity.
Weighted search scoring (0.4 × rating + 0.3 × proximity + 0.2 × response_rate + 0.1 × completion_rate) is env-configurable for tuning without deploys.

Two LLM providers mean two API key secrets and two billing accounts to manage.
LangGraph adds a non-trivial dependency surface; upgrades must be tested against graph node contracts.
Sentry langGraphIntegration deferred (not blocking MVP).

Alternatives considered

Raw LLM API calls (no framework) — rejected: no retry/fallback logic, no tracing, no stateful multi-turn conversation without re-implementing graph primitives.
LangChain.js without LangGraph — rejected: LangChain chains are less flexible for conditional branching and checkpointing.
Claude Haiku (Anthropic) — rejected: GPT-5.4 Mini selected per user preference and budget; Gemini Flash selected for EU residency and cost-per-quality.