Where International Relations meets AI — Analyze. Simulate. Predict.

• Overview
• Why This Project
• Features
• Architecture
• Quick Start
• Screenshots
• Technology Stack
• API Reference
• Documentation
• Contributing
• License
• Acknowledgments

IR Intelligence Platform is an end-to-end AI-powered Geopolitical Intelligence Analysis & Simulation System. It ingests global news in real time, clusters related reports, abstracts them into structured international relations events using LLMs, applies IR theories for analysis, generates multi-directional scenario scripts with probabilistic forecasting, and continuously calibrates predictions against actual outcomes.

Think of it as an AI analyst that reads the world's news 24/7, builds structured geopolitical event graphs, simulates possible futures under different IR theoretical lenses, and learns from its mistakes through systematic calibration.

Traditional geopolitical analysis suffers from three problems:

1. Information overload — too many news sources to track manually
2. Cognitive bias — analysts anchor on familiar narratives
3. No feedback loop — predictions are made but rarely systematically evaluated

This platform addresses all three by:

1. Automated ingestion & abstraction of global news into structured event models
2. Multi-theory, multi-directional scenario generation to counter confirmation bias
3. Built-in calibration tracking with Brier scores, hit-rate dashboards, and automatic evaluation

• Multi-source RSS feed ingestion (Reuters, AP, regional sources)
• Semantic clustering of related news articles using LLM embeddings
• Automatic deduplication and story grouping

• LLM-powered extraction of structured IR events from news clusters
• Captures: actors, event type, crisis stage, strategic dimensions, rule-of-engagement triggers
• Produces clean, structured AbstractIRGEvent data models

Apply 6+ international relations theories to each event:

• Realism — power politics, security dilemmas
• Liberal Institutionalism — institutional constraints, norms
• Constructivism — identity, narrative, perception
• Geopolitics — geography, resources, strategic chokepoints
• International Political Economy — trade interdependence
• Power Transition Theory — hegemonic dynamics

For each event, generate scripted scenarios across three directions:

• 🔴 Escalation — conflict intensifies
• 🟡 Stalemate — status quo persists
• 🟢 De-escalation — tensions resolve

Each script includes:

• Step-by-step timelines with actor motivations
• Trigger conditions & invalidation conditions
• Probability distributions (low / central / high estimates)
• Supporting & counter evidence per step
• Confidence levels and uncertainty annotations

• Create branching "what-if" scenarios from any prediction run
• Simulate alternative actor moves, constraint changes, or external shocks
• Compare divergence points and new step paths

• Curated database of 100+ historical IR cases (Cuban Missile Crisis, Gulf War, South China Sea disputes, etc.)
• LLM-powered structural similarity matching
• Historical base-rate probabilities guide current forecasts
• Full CRUD for case library management

• Brier Score tracking (gold standard for probabilistic forecast accuracy)
• Calibration Grade (A–F) with quality benchmarks
• Step-level & script-level hit rate tracking
• By-direction, by-theory, by-event-type, by-crisis-stage breakdowns
• Calibration curve visualization (predicted vs. actual)
• Automated improvement suggestions

• Complete prediction run history with expandable detail views
• Record actual outcomes with form-based entry
• Auto-generate evaluations comparing predictions to reality
• Error type classification and accuracy rate computation

• Interactive 3D globe showing geopolitical events geographically
• Color-coded crisis stages and relationship types
• Map layer switching (satellite / dark / night)

• Generate structured PDF reports for events, scenarios, themes, and reviews
• Chinese font support (WenQuanYi / Noto CJK)

• Every user-facing string is internationalized
• Dynamic date/number formatting based on locale

                          ┌─────────────────────────────────────┐
                          │          React 18 + TypeScript        │
                          │         (Vite build + PWA)           │
                          │  ┌─────┐ ┌────┐ ┌───┐ ┌──────┐     │
                          │  │Globe│ │Pipe│ │Scn│ │Calib │ ...  │
                          │  └──┬──┘ └──┬─┘ └─┬─┘ └──┬───┘     │
                          └─────┼───────┼─────┼──────┼──────────┘
                                │       │     │      │
                          ┌─────┼───────┼─────┼──────┼──────────┐
                          │     ▼       ▼     ▼      ▼           │
                          │         REST API (FastAPI)            │
                          │  ┌─────────────────────────────────┐  │
                          │  │ Routers: events, scenarios,     │  │
                          │  │   pipeline, calibration,        │  │
                          │  │   analogies, reports, auth      │  │
                          │  └───────────┬─────────────────────┘  │
                          │              │                        │
                          │  ┌───────────┼─────────────────────┐  │
                          │  │ Services: (Business Logic)      │  │
                          │  │  • Ingestion (RSS + dedup)      │  │
                          │  │  • Clustering (LLM embedding)   │  │
                          │  │  • Event Abstraction (LLM)      │  │
                          │  │  • Theory Analysis (LLM)        │  │
                          │  │  • Scenario Engine (LLM)        │  │
                          │  │  • Branch Engine                │  │
                          │  │  • Analogy Engine               │  │
                          │  │  • Calibration Service          │  │
                          │  │  • PDF Export                   │  │
                          │  └───────────┬─────────────────────┘  │
                          │              │                        │
                          │  ┌───────────┼─────────────────────┐  │
                          │  │ Core:                           │  │
                          │  │  • LLM Router (Anthropic)       │  │
                          │  │  • Config Management            │  │
                          │  │  • Auth (JWT)                   │  │
                          │  │  • Rate Limiter                 │  │
                          │  └───────────┬─────────────────────┘  │
                          │              │                        │
                          │  ┌───────────▼─────────────────────┐  │
                          │  │ Database (SQLite / PostgreSQL)  │  │
                          │  │  + Alembic Migrations           │  │
                          │  └─────────────────────────────────┘  │
                          └───────────────────────────────────────┘

RSS Feeds → News Clusters → Abstract IR Events
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
              Theory         Scenario       Historical
              Analysis       Scripts        Analogies
                    │             │             │
                    └─────────────┼─────────────┘
                                  ▼
                          Prediction Runs
                                  │
                                  ▼
                     Actual Outcome Recording
                                  │
                                  ▼
                     Calibration & Evaluation
                                  │
                                  ▼
                          PDF Report Export

• Python 3.12+
• Node.js 18+
• Anthropic API key (Get one here)

Windows:

start.bat

Linux / macOS:

chmod +x start.sh && ./start.sh

The script will automatically:

1. Check Python & Node environments
2. Install missing dependencies
3. Run database migrations
4. Start backend (port 8000) & frontend (port 5173)
5. Open the app in your browser

# Build and start
docker compose up --build -d

# Check status
docker compose ps

# View logs
docker compose logs -f backend

# Access the app
open http://localhost:8000

# ── Backend ──
cd backend
python -m pip install -r requirements.txt
cp ../.env.example ../.env
# Edit .env to add your ANTHROPIC_API_KEY
python -m alembic upgrade head
python -m uvicorn backend.main:app --reload --port 8000

# ── Frontend ──
cd frontend
npm ci
npm run dev

Visit http://localhost:5173 in your browser.

Note: The platform requires a valid Anthropic API key for AI features (event abstraction, theory analysis, scenario generation, etc.). Without it, the ingestion and database features still work.

When the backend is running, visit:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

• Architecture Guide — system design, data models, service interactions
• User Guide — walkthrough of all features
• API Reference — interactive Swagger docs
• Contributing Guide — how to contribute
• Security Policy — vulnerability reporting

We welcome contributions! See CONTRIBUTING.md for:

• Development environment setup
• Code style guidelines
• Pull request process
• Testing requirements

git clone https://github.com/your-org/ir-intel-platform.git
cd ir-intel-platform
cp .env.example .env  # Add your ANTHROPIC_API_KEY
pip install -r backend/requirements.txt
cd frontend && npm ci && cd ..
# Start both services and start hacking!

This project is licensed under the MIT License — see the LICENSE file for details.

• Anthropic — for the Claude API that powers the LLM reasoning
• Three.js / Globe.GL — for the 3D globe visualization
• FastAPI — for the excellent Python web framework
• All open-source contributors whose libraries make this project possible

_{Built with ❤️ by the IR Intel Platform team
⭐ Star us on GitHub — it helps more people discover the platform!}