feat(backend): orchestration foundation — health check, state contracts, traces and LangGraph empty flow (A-10, A-11, A-12, A-13)

[Andres-Torrez]

Closes

Closes #10
Closes #11
Closes #12
Closes #13

Summary

Complete orchestration foundation for Aria. This PR delivers the full
backend skeleton so the team can start Phase 3 (agents, SSE, frontend)
on solid contracts. It bundles 4 stacked issues into one PR, as agreed
by the team (exception to the per-PR size guideline: this is foundation
code that only makes sense together).

A-10 — Minimal backend with health check

• FastAPI app with /docs and /redoc
• GET / returns API info
• GET /salud verifies connectivity with the LiteLLM gateway
  (GATEWAY_URL / GATEWAY_TIMEOUT env vars, Docker Compose defaults)
• Returns 200 even when the gateway is down — the frontend needs the
  backend status regardless
• Dockerfile, .env.example and tests included

A-11 — Shared state contracts (Contract 1)

• CampaignState (TypedDict, 8 fields): objetivo, tono_marca,
  contenido, plan_campana, informe_analitica, campana_ok,
  iteraciones, historial
• SupportState (TypedDict, 4 fields): pregunta, respuesta,
  escalado_humano, historial
• Factory functions with correct defaults (iteraciones = 0,
  campana_ok = True, historial = [])
• Field names in Spanish, matching the functional document exactly
• Frozen contract: changing a field requires team architecture discussion

A-12 — Trace emission module (Contract 3)

• Single pure function emitir_traza(agente, fase, razon, historial)
  used by ALL agents — if this breaks, the dashboard breaks
• Fixed format: agente, fase, razon, timestamp (UTC ISO 8601)
• Validates the 5 agent names and inicio/fin phases; on invalid
  input it logs and returns history unchanged — never raises
• Pure stdlib, zero dependencies

A-13 — LangGraph graph with empty nodes (Phase 2 exit criterion)

• Fixed deterministic sequence:
  orquestador → contenido → campañas → analítica → END
• 4 placeholder nodes emitting inicio/fin traces per Contract 3
• build_graph() factory + compiled graph singleton for the API
  layer (SSE endpoint, [Agentes] Real-time SSE trace endpoint #14)
• langgraph>=0.2.0 added to dependencies
• Fix: testpaths corrected (tests → test) so pytest discovers
  the suite

Out of scope (next issues):

• Conditional edge + improvement cycle → [Orquestación] Conditional edge in the orchestrator #22
• Hard limit of 2 iterations → [Orquestación] Hard limit of 2 iterations #23
• Real agent logic → [Agentes] Content agent #18, [Agentes] Campaign agent #19, [Agentes] Analytics agent with verdict #20
• SSE endpoint → [Agentes] Real-time SSE trace endpoint #14

How to test

1. cd backend && uv sync --extra dev
2. uv run pytest — full suite passes (state, traces, graph, main)
3. Health check:

   uv run uvicorn app.main:app --reload
   curl http://localhost:8000/salud
   # gateway up   → "gateway": "reachable"
   # gateway down → "gateway": "unreachable" (HTTP 200 anyway)

4. Empty flow produces exactly 8 traces in order:

   from app.graph import graph
   from app.state import create_empty_campaign_state
   result = graph.invoke(create_empty_campaign_state(
       objetivo="campaña lanzamiento X", tono_marca="profesional y cercano"))
   assert len(result["historial"]) == 8
   assert result["historial"][0]["agente"] == "orquestador"
   assert result["historial"][7]["agente"] == "analitica"

Dashboard screenshot

N/A — traces will be visible once #14 (SSE) and #16 (frontend) land.

Checklist

• Traces emitted correctly (start/end) if agents were touched — 8 traces per run, tested
• No provider SDK imported outside the gateway client
• docker compose up still works — no infra changes
• README updated if setup/config changed — backend/README.md included