Open-source alternate history engine. Multi-agent AI simulations of geopolitical scenarios on an interactive 3D globe.
| Layer | Tech |
|---|---|
| AI | OpenAI Agents SDK — structured output, input guardrails, Pydantic models |
| Backend | FastAPI, Shapely (polygon merging), Natural Earth GeoJSON |
| Frontend | Next.js, react-globe.gl, shadcn/ui, Motion |
| Dev | uv, Ruff, Pyright, Biome |
# Backend
cp .env.example .env # add your OPENAI_API_KEY
uv sync
uv run uvicorn src.backend.app:app --reload --port 8001
# Frontend
cd src/frontend
bun install
bun devOpen localhost:3000, type a question, and watch.
src/
backend/
agent.py # Historian + guardrail agents (OpenAI Agents SDK)
app.py # FastAPI endpoint, polygon merging pipeline
models.py # Pydantic models (input from AI, output with GeoJSON)
geo.py # Country polygon lookup + Shapely merge
data/ # Natural Earth provinces GeoJSON (10m)
frontend/
src/
app/ # Next.js app router
components/
globe.tsx # 3D globe viewer with animated playback
ui/ # shadcn components
public/data/ # Natural Earth countries GeoJSON (110m)
[User Input] [System Boundary: Bivium] [External Services]
┌──────────────┐ ┌───────────────┐
│ Browser │ │ OpenAI API │
│ (What-if Q) │ │ (Agents SDK) │
└──────┬───────┘ └───────┬───────┘
│ POST /api/timeline │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────────────────┐ │
│ FastAPI Backend │ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ Guardrail │ Reject │ Historian │ LLM │ Geo │ │ │
│ │ (nano) │────────▶│ Agent │◀────────│ Pipeline │ │◀─────────┘
│ │ Validate │ │(GPT-5.4) │ │ (Shapely) │ │
│ └────────────┘ └─────┬──────┘ └─────┬──────┘ │
│ │ │ │ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌─────────────┐ ┌────────────┐ │
│ │ │ Timeline │ │ GeoJSON │ │
│ │ │ (Pydantic) │───────▶│ Polygons │ │
│ │ └─────────────┘ └─────┬──────┘ │
│ │ │ │
└─────────┼───────────────────────────────────────────┼───────────────────────┘
│ │
│ 400 Bad Request │ 200 OK + GeoJSON
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Next.js Frontend │
│ ┌────────────┐ ┌────────────┐ │
│ │ Input │ │ Globe │ │
│ │ Card │ │react-globe │ │
│ │ │ │ .gl │ │
│ └────────────┘ │ │ │
│ │ • Polygons │ │
│ │ • Camera │ │
│ │ • Timeline │ │
│ └────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Data: Natural Earth GeoJSON (10m provinces, 110m countries)
MIT