# jangles-byte/pythia architecture

> Architecture diagram of the GitHub repository jangles-byte/pythia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jangles-byte/pythia
- Repository: https://github.com/jangles-byte/pythia

## Overview

PYTHIA combines Osiris live intelligence feeds with a local forecasting engine and a globe-oriented interface. The principal flow is live signals into normalized events and a world brief, then oracle forecasts, optional council deliberation, and API/UI delivery. The README also documents alerts, the scheduled Morning Brief, markets, health scoring, and many feed integrations. Some routes and UI components are represented by their exact paths but were not sampled; their internal wiring is therefore not asserted.

Main entry points: [`engine/pipeline.py`](https://github.com/jangles-byte/pythia/blob/main/engine/pipeline.py) (Oracle pass), [`engine/loop.py`](https://github.com/jangles-byte/pythia/blob/main/engine/loop.py) (Scheduled loop), [`engine/server.py`](https://github.com/jangles-byte/pythia/blob/main/engine/server.py) (Engine API), [`engine/osiris_intake.py`](https://github.com/jangles-byte/pythia/blob/main/engine/osiris_intake.py) (Event intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_feeds["Live intelligence"]
  node_feed_routes["Feed API routes"]
  node_camera_route["Camera API<br/>[cams-route.ts]"]
  node_market_routes["Markets and odds<br/>[quotes-route.ts]"]
end

subgraph group_engine["Forecast engine"]
  node_intake["Event intake<br/>[osiris_intake.py]"]
  node_world_brief["World brief<br/>[world_state.py]"]
  node_pipeline["Oracle pass<br/>[pipeline.py]"]
  node_oracle["LLM oracle<br/>[oracle.py]"]
  node_swarm["Council deliberation<br/>[swarm.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_state[("Live engine state<br/>[state.py]")]
end

subgraph group_services["Oracle services"]
  node_ledger[("Forecast ledger<br/>[ledger.py]")]
  node_server["Engine API<br/>[server.py]"]
  node_loop["Scheduled loop<br/>[loop.py]"]
  node_alerts["Signal rules<br/>[alerts.py]"]
  node_webhooks["Webhook delivery<br/>[webhooks.py]"]
  node_brief_service["Morning Brief<br/>[brief.py]"]
  node_health["Global Health Score<br/>[healthscore.py]"]
  node_tickers["Ticker watch<br/>[tickers.py]"]
end

subgraph group_interface["Osiris interface"]
  node_pythia_panel["Forecast panel<br/>[PythiaPanel.tsx]"]
  node_deliberation_ui["Council view"]
  node_cams_ui["Nearby cameras<br/>[CamsNearby.tsx]"]
  node_brief_ui["Brief panel<br/>[BriefPanel.tsx]"]
  node_alerts_ui["Live alerts<br/>[LiveAlerts.tsx]"]
  node_markets_ui["Markets panel<br/>[MarketsPanel.tsx]"]
  node_calendar_ui["Forecast calendar"]
  node_scorecard_ui["Forecast scorecard<br/>[ScorecardPanel.tsx]"]
  node_whatif_ui["What-if panel<br/>[WhatIfPanel.tsx]"]
  node_tv_ui["TV kiosk<br/>[tv-page.tsx]"]
end

node_user(("Operator or agent"))
node_osiris(("Osiris feeds"))

node_user -.->|"requests forecasts"| node_pythia_panel
node_osiris -->|"serves live feeds"| node_feed_routes
node_feed_routes -->|"provides event data"| node_intake
node_intake -->|"fetches events"| node_pipeline
node_pipeline -->|"builds brief"| node_world_brief
node_pipeline -->|"publishes world"| node_state
node_pipeline -.->|"requests forecasts"| node_oracle
node_pipeline -->|"deliberates forecasts"| node_swarm
node_swarm -->|"queries personas"| node_oracle
node_swarm -->|"reads track record"| node_ledger
node_pipeline -->|"fires event hooks"| node_webhooks
node_server -->|"starts loop"| node_loop
node_loop -->|"runs oracle pass"| node_pipeline
node_server -->|"serves snapshots"| node_state
node_pipeline -->|"records briefs"| node_ledger
node_state -->|"stores domain data"| node_models
node_intake -->|"normalizes events"| node_models
node_alerts -->|"pushes fired alerts"| node_webhooks
node_loop -->|"evaluates rules"| node_alerts
node_loop -->|"schedules digest"| node_brief_service
node_brief_service -->|"reads forecasts"| node_ledger
node_health -->|"reads world state"| node_state
node_user -->|"queries engine"| node_server
node_server -.->|"returns forecasts"| node_pythia_panel
node_pythia_panel -->|"opens deliberation"| node_deliberation_ui
node_pythia_panel -->|"shows digest"| node_brief_ui
node_user -.->|"opens nearby cameras"| node_cams_ui
node_user -.->|"configures signals"| node_alerts_ui
node_user -.->|"views markets"| node_markets_ui
node_user -.->|"views forecast dates"| node_calendar_ui
node_user -.->|"reviews performance"| node_scorecard_ui
node_user -.->|"explores scenarios"| node_whatif_ui
node_user -.->|"opens kiosk"| node_tv_ui
node_camera_route -.->|"serves camera data"| node_cams_ui
node_market_routes -.->|"serves quotes"| node_markets_ui
node_feed_routes -->|"supplies world signals"| node_intake

click node_feed_routes "https://github.com/jangles-byte/pythia/tree/main/integrations/osiris/routes"
click node_camera_route "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/routes/cams-route.ts"
click node_market_routes "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/routes/quotes-route.ts"
click node_intake "https://github.com/jangles-byte/pythia/blob/main/engine/osiris_intake.py"
click node_world_brief "https://github.com/jangles-byte/pythia/blob/main/engine/world_state.py"
click node_pipeline "https://github.com/jangles-byte/pythia/blob/main/engine/pipeline.py"
click node_oracle "https://github.com/jangles-byte/pythia/blob/main/engine/oracle.py"
click node_swarm "https://github.com/jangles-byte/pythia/blob/main/engine/swarm.py"
click node_models "https://github.com/jangles-byte/pythia/blob/main/engine/models.py"
click node_state "https://github.com/jangles-byte/pythia/blob/main/engine/state.py"
click node_ledger "https://github.com/jangles-byte/pythia/blob/main/engine/ledger.py"
click node_server "https://github.com/jangles-byte/pythia/blob/main/engine/server.py"
click node_loop "https://github.com/jangles-byte/pythia/blob/main/engine/loop.py"
click node_alerts "https://github.com/jangles-byte/pythia/blob/main/engine/alerts.py"
click node_webhooks "https://github.com/jangles-byte/pythia/blob/main/engine/webhooks.py"
click node_brief_service "https://github.com/jangles-byte/pythia/blob/main/engine/brief.py"
click node_health "https://github.com/jangles-byte/pythia/blob/main/engine/healthscore.py"
click node_tickers "https://github.com/jangles-byte/pythia/blob/main/engine/tickers.py"
click node_pythia_panel "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/PythiaPanel.tsx"
click node_deliberation_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/DeliberationModal.tsx"
click node_cams_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/CamsNearby.tsx"
click node_brief_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/BriefPanel.tsx"
click node_alerts_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/LiveAlerts.tsx"
click node_markets_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/MarketsPanel.tsx"
click node_calendar_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/ForecastCalendar.tsx"
click node_scorecard_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/ScorecardPanel.tsx"
click node_whatif_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/WhatIfPanel.tsx"
click node_tv_ui "https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/tv-page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_feed_routes,node_camera_route,node_market_routes toneBlue
class node_intake,node_world_brief,node_pipeline,node_oracle,node_swarm,node_models,node_state toneAmber
class node_ledger,node_server,node_loop,node_alerts,node_webhooks,node_brief_service,node_health,node_tickers toneMint
class node_pythia_panel,node_deliberation_ui,node_cams_ui,node_brief_ui,node_alerts_ui,node_markets_ui,node_calendar_ui,node_scorecard_ui,node_whatif_ui,node_tv_ui toneRose
class node_user,node_osiris toneIndigo
```

## Components

### Live intelligence

- [Feed API routes](https://github.com/jangles-byte/pythia/tree/main/integrations/osiris/routes): `integrations/osiris/routes`
- [Camera API](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/routes/cams-route.ts): `integrations/osiris/routes/cams-route.ts`
- [Markets and odds](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/routes/quotes-route.ts): `integrations/osiris/routes/quotes-route.ts`

### Forecast engine

- [Event intake](https://github.com/jangles-byte/pythia/blob/main/engine/osiris_intake.py): `engine/osiris_intake.py`
- [World brief](https://github.com/jangles-byte/pythia/blob/main/engine/world_state.py): `engine/world_state.py`
- [Oracle pass](https://github.com/jangles-byte/pythia/blob/main/engine/pipeline.py): `engine/pipeline.py`
- [LLM oracle](https://github.com/jangles-byte/pythia/blob/main/engine/oracle.py): `engine/oracle.py`
- [Council deliberation](https://github.com/jangles-byte/pythia/blob/main/engine/swarm.py): `engine/swarm.py`
- [Domain models](https://github.com/jangles-byte/pythia/blob/main/engine/models.py): `engine/models.py`
- [Live engine state](https://github.com/jangles-byte/pythia/blob/main/engine/state.py): `engine/state.py`

### Oracle services

- [Forecast ledger](https://github.com/jangles-byte/pythia/blob/main/engine/ledger.py): `engine/ledger.py`
- [Engine API](https://github.com/jangles-byte/pythia/blob/main/engine/server.py): `engine/server.py`
- [Scheduled loop](https://github.com/jangles-byte/pythia/blob/main/engine/loop.py): `engine/loop.py`
- [Signal rules](https://github.com/jangles-byte/pythia/blob/main/engine/alerts.py): `engine/alerts.py`
- [Webhook delivery](https://github.com/jangles-byte/pythia/blob/main/engine/webhooks.py): `engine/webhooks.py`
- [Morning Brief](https://github.com/jangles-byte/pythia/blob/main/engine/brief.py): `engine/brief.py`
- [Global Health Score](https://github.com/jangles-byte/pythia/blob/main/engine/healthscore.py): `engine/healthscore.py`
- [Ticker watch](https://github.com/jangles-byte/pythia/blob/main/engine/tickers.py): `engine/tickers.py`

### Osiris interface

- [Forecast panel](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/PythiaPanel.tsx): `integrations/osiris/PythiaPanel.tsx`
- [Council view](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/DeliberationModal.tsx): `integrations/osiris/DeliberationModal.tsx`
- [Nearby cameras](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/CamsNearby.tsx): `integrations/osiris/CamsNearby.tsx`
- [Brief panel](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/BriefPanel.tsx): `integrations/osiris/BriefPanel.tsx`
- [Live alerts](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/LiveAlerts.tsx): `integrations/osiris/LiveAlerts.tsx`
- [Markets panel](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/MarketsPanel.tsx): `integrations/osiris/MarketsPanel.tsx`
- [Forecast calendar](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/ForecastCalendar.tsx): `integrations/osiris/ForecastCalendar.tsx`
- [Forecast scorecard](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/ScorecardPanel.tsx): `integrations/osiris/ScorecardPanel.tsx`
- [What-if panel](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/WhatIfPanel.tsx): `integrations/osiris/WhatIfPanel.tsx`
- [TV kiosk](https://github.com/jangles-byte/pythia/blob/main/integrations/osiris/tv-page.tsx): `integrations/osiris/tv-page.tsx`

### Other components

- **Operator or agent**
- **Osiris feeds**

## Connections

- Operator or agent → Forecast panel: requests forecasts
- Osiris feeds → Feed API routes: serves live feeds
- Feed API routes → Event intake: provides event data (evidence: `engine/osiris_intake.py`)
- Event intake → Oracle pass: fetches events (evidence: `engine/pipeline.py`)
- Oracle pass → World brief: builds brief (evidence: `engine/pipeline.py`)
- Oracle pass → Live engine state: publishes world (evidence: `engine/pipeline.py`)
- Oracle pass → LLM oracle: requests forecasts
- Oracle pass → Council deliberation: deliberates forecasts (evidence: `engine/pipeline.py`)
- Council deliberation → LLM oracle: queries personas (evidence: `engine/swarm.py`)
- Council deliberation → Forecast ledger: reads track record (evidence: `engine/swarm.py`)
- Oracle pass → Webhook delivery: fires event hooks (evidence: `engine/pipeline.py`)
- Engine API → Scheduled loop: starts loop (evidence: `engine/server.py`)
- Scheduled loop → Oracle pass: runs oracle pass (evidence: `engine/loop.py`)
- Engine API → Live engine state: serves snapshots (evidence: `engine/server.py`)
- Oracle pass → Forecast ledger: records briefs (evidence: `engine/pipeline.py`)
- Live engine state → Domain models: stores domain data (evidence: `engine/state.py`)
- Event intake → Domain models: normalizes events (evidence: `engine/osiris_intake.py`)
- Signal rules → Webhook delivery: pushes fired alerts (evidence: `engine/alerts.py`)
- Scheduled loop → Signal rules: evaluates rules (evidence: `engine/loop.py`)
- Scheduled loop → Morning Brief: schedules digest (evidence: `engine/loop.py`)
- Morning Brief → Forecast ledger: reads forecasts (evidence: `engine/brief.py`)
- Global Health Score → Live engine state: reads world state (evidence: `engine/healthscore.py`)
- Operator or agent → Engine API: queries engine
- Engine API → Forecast panel: returns forecasts
- Forecast panel → Council view: opens deliberation (evidence: `integrations/osiris/PythiaPanel.tsx`)
- Forecast panel → Brief panel: shows digest (evidence: `integrations/osiris/PythiaPanel.tsx`)
- Operator or agent → Nearby cameras: opens nearby cameras
- Operator or agent → Live alerts: configures signals
- Operator or agent → Markets panel: views markets
- Operator or agent → Forecast calendar: views forecast dates
- Operator or agent → Forecast scorecard: reviews performance
- Operator or agent → What-if panel: explores scenarios
- Operator or agent → TV kiosk: opens kiosk
- Camera API → Nearby cameras: serves camera data
- Markets and odds → Markets panel: serves quotes
- Feed API routes → Event intake: supplies world signals