README.md

metadata

title: APEX Backend
emoji: 🏎️
colorFrom: green
colorTo: red
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: APEX race-engineer backend (FastAPI + LangGraph + Granite)

APEX Backend on HuggingFace Spaces

This Space hosts the APEX race-engineer backend for the IBM SkillsBuild AI Builders Challenge May 2026 submission. The frontend lives at https://apex-one-black.vercel.app; this Space is the Python FastAPI backend it calls.

Endpoints

Method	Path	Purpose
GET	/healthz	container readiness probe
GET	/api/session-context	race-session tile feed
GET	/api/orchestration	LangGraph 6-node trace on canonical Sarah Reynolds fixture
POST	/api/audit-log	append-only Guardian audit log (JSONL + flock)
POST	/api/what-if-replay	byte-deterministic V2 cvxpylayers replay
POST	/api/analyze	end-to-end pipeline (JSON file-path input; legacy)
POST	/api/analyze-upload	end-to-end pipeline (multipart upload; wave-48)

Honesty surface

• Forecast engine: deterministic seasonal-naive baseline. Frozen TTM r2 wire is gated behind APEX_ENABLE_TTM=1 Space env (see Phase 4 Day 4 G4 FAIL pivot in logs/day-04-g4.md).
• Narrator engine: OpenRouter Granite 4.1 8B when OPENROUTER_API_KEY is set; deterministic template floor otherwise. Honest engine surfaced in the per-node trace detail.
• Orchestration: deterministic 6-node Python state machine modeled on LangGraph semantics; not the langgraph package runtime. See docs/decision-log.md D-067.

License

Apache 2.0. Repo: https://github.com/StephenSook/apex.