Axiom Macro Intelligence

A production-oriented macroeconomic intelligence service and financial workspace for the Titan automated trading platform.

Axiom turns provider observations into validated, frequency-aware indicators, interpretable regime probabilities, baseline forecasts, risk diagnostics, and stable versioned APIs. The React client is one consumer of those APIs; signal generation, portfolio optimization, risk, execution, and research systems can consume the same contracts independently.

Product surface

• Macro pulse with current regime, confidence, market health, global context, key indicators, and events.
• Searchable and sortable indicator explorer with interactive drill-downs, zoom, crosshair, image export, and CSV export.
• Regime lab with probability history and factor-level explainability.
• Risk monitor spanning the cycle, credit, liquidity, curve, and inflation.
• Forecast baselines with uncertainty bands and explicit model provenance.
• Dark/light themes, responsive navigation, keyboard command palette (Ctrl/⌘ K), loading states, empty states, and accessible semantics.
• FastAPI /api/v1 contract for Titan and other non-UI consumers.
• Deterministic demo fallback that is visibly labeled and never masquerades as a live market feed.

Architecture

flowchart LR
    P["Providers<br/>FRED / demo fallback"] --> V["Validation<br/>schema · range · duplicate · time"]
    V --> N["Normalization<br/>frequency-aware transforms"]
    N --> C["Cache + repository"]
    C --> F["Features<br/>point-in-time rolling context"]
    F --> R["Regime + forecasts"]
    R --> A["Analytics composition"]
    A --> API["FastAPI /api/v1"]
    API --> UI["React financial workspace"]
    API --> T["Titan consumers"]

Loading

Backend boundaries live under backend/; client feature slices live under frontend/src/. The old synchronous Jinja/Plotly request path, unsafe pickle cache, request-time LightGBM training, and disconnected CRUD layer have been removed.

The full audit and engineering rationale are in docs/ENGINEERING_PLAN.md.

Quick start

Prerequisites:

• Python 3.12+
• Node.js 22+

Install and run the API:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
uvicorn backend.main:app --reload

In a second terminal, install and run the client:

cd frontend
npm ci
npm run dev

Open http://localhost:5173. API documentation is at http://localhost:8000/api/docs.

The default is deterministic demo mode. To use FRED, copy .env.example to .env, set FRED_API_KEY, and set DEMO_MODE=false. Provider failures fall back to the clearly identified demo dataset unless production policy is changed.

Verification

python -m ruff format --check backend tests
python -m ruff check backend tests
python -m mypy backend tests
python -m pytest -q
cd frontend
npm run lint
npm run test
npm run build

The application can also be built and run as one image:

docker compose up --build

Then open http://localhost:8080. The container listens on port 8000; set AXIOM_PORT in .env to publish it on a different host port.

Documentation

• Architecture and audit
• API guide
• Developer and deployment guide
• Migration from the prototype
• Troubleshooting
• Final engineering review

Important model boundary

Regime and forecast outputs are research intelligence, not autonomous orders. The retired model had no reproducible point-in-time dataset or credible out-of-sample promotion evidence. Axiom therefore ships an interpretable baseline and records the evidence required for future model comparison. Titan should gate any production allocation use behind freshness, coverage, calibration, and after-cost validation.