The Problem

Clients that need a single, local source of real‑time global events must stitch together dozens of APIs, each with its own keys, rate limits and data model. Maintaining that pipeline consumes engineering time and introduces latency, making it hard to feed up‑to‑date world context into downstream agents or decision systems.

What This Does

PYTHIA fuses the open‑source Osiris live‑feed engine with the MiroFish swarm‑intelligence predictor. The Python back‑end (engine/) pulls >40 keyless feeds, normalises them into a unified world‑state, runs the MiroFish model to produce 24‑hour, 1‑week, 1‑month and 1‑year forecasts, and serves the results via a FastAPI server (engine/server.py). The React front‑end (integrations/osiris/) visualises feeds, forecasts and interactive panels such as PythiaPanel.tsx and BriefPanel.tsx.

Key files:

  • engine/server.py – launches the HTTP API, configures CORS, mounts route modules.
  • engine/config.py – central configuration hub imported by 12 other modules.
  • engine/pipeline.py – orchestrates ingestion of Osiris feeds and feeds the model.
  • engine/models.py – data‑class definitions shared by the pipeline and the API.
  • integrations/osiris/routes/*.ts – TypeScript route definitions that proxy API calls to the front‑end.

How It Is Wired

Execution starts in engine/server.py. The file creates a FastAPI app, loads settings from engine/config.py, and registers CORS with allow_origins=["*"]. It then includes the route modules found under integrations/osiris/routes/, each exposing a path that ultimately calls back into the Python engine.

  • engine/server.py → imports engine/config.py (hub, 12 inbound imports).
  • Request handlers import engine/state.py (holds the live world‑state) and engine/runtime.py (runs the prediction loop).
  • The runtime invokes engine/pipeline.py, which pulls raw feed data via the Osiris integration (integrations/osiris/*) and populates engine/state.py.
  • engine/pipeline.py calls into engine/models.py to validate and store feed objects, then triggers engine/mcp.py (MiroFish controller) to generate forecasts.
  • Forecast results flow back through engine/brief.py (produces human‑readable briefs) and are returned as JSON by the API.

The most‑connected modules are engine/config.py (12 dependents) and engine/models.py (10 dependents), giving them the largest blast radius: changes here ripple through the entire ingestion, modelling, and API layers. engine/pipeline.py has an instability score of 0.78 (imports 7 modules, is imported by 2), indicating moderate coupling that should be monitored when refactoring.

No circular imports were detected, so the call graph is acyclic and safe for incremental changes.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Pythia
cd Pythia

# Install Python dependencies (uv is bundled via uv.lock)
uv sync          # creates a virtualenv and installs exact versions

# Copy example environment file and adjust if needed
cp .env.example .env

# Start the API server
python -m engine.server   # runs FastAPI on the default host/port

The front‑end can be launched with a standard React toolchain (e.g., npm install && npm start) inside the integrations/osiris/ folder, although the repository does not include a package.json; developers must add one if they wish to build the UI.

Real‑World Use

A logistics platform can run PYTHIA on a local edge server, call http://localhost:8000/forecast?horizon=24h to obtain a probability‑weighted list of upcoming disruptions (storms, port closures, market swings), and feed that into its routing optimizer. The same endpoint can be queried by an LLM‑based assistant to enrich conversational responses with current world context.

Code Health & Issues

  • HIGH – No test suite – 92 source files, no tests/ directory.
  • HIGH – No CI workflow – repository lacks any GitHub Actions or other pipeline.
  • HIGH – Wildcard CORS – engine/server.py sets allow_origins=["*"], exposing the API to any origin.
  • MEDIUM – Dependabot missing – only pyproject.toml is present; no automated dependency updates.
  • MEDIUM – Large binary in repo – screenshots/demo.mp4 (7.3 MiB) inflates clone size.
  • LOW – Convention files absent – no .editorconfig, .gitattributes, or formatter config.

Additional static findings (not in the health audit): deep nesting in several engine modules, duplicated UI snippets across many integrations/osiris/*.tsx files, and several file‑open calls without context managers in scripts/.

The Bottom Line

PYTHIA delivers a locally hosted, key‑free aggregation of global events and forecasts, which is valuable for privacy‑sensitive or offline deployments. The codebase is functional but under‑engineered: it lacks automated testing, CI, and proper security defaults, and the UI contains considerable duplication. Teams should prioritize adding tests, tightening CORS, and refactoring the most‑connected modules before extending the platform.