README.md

metadata

language: en
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
tags:
  - mistral
  - lora
  - merged
  - gguf
  - text-generation
base_model: mistralai/Mistral-7B-Instruct-v0.2

🌍 Geopolitical Analysis Agent

Advanced strategic forecasting and simulation engine combining RAG, SQLite, ChromaDB, and Claude AI

What Is This?

A production-ready geopolitical analysis system that:

• Answers complex "what-if" questions about world events
• Models quantitative scenarios (tank stocks, production rates, timelines)
• Combines structured data + unstructured knowledge via RAG
• Provides rigorous analysis like a think tank war games coordinator
• Prepares training data for fine-tuning specialized models

Key Features

🧠 Intelligent RAG Architecture

• Vector search with ChromaDB for semantic retrieval
• Structured database with SQLite for facts, metrics, inventories
• Hybrid retrieval combining both sources for comprehensive context

📊 Quantitative Modeling

• Project military inventories over time
• Calculate attrition rates and production capacities
• Model economic sustainability scenarios
• Compare alternative pathways

💾 Production-Ready Stack

• FastAPI backend with async support
• SQLAlchemy ORM for database management
• Sentence Transformers for embeddings
• Claude Sonnet 4 for analysis
• Clean HTML/JS frontend

🎯 Example Queries

"Where will Russia's tank stock be in 5 years with 15% annual 
losses and 200 tanks/year production?"

"What's China's timeline to semiconductor parity with Taiwan 
if sanctions continue vs. if they're lifted?"

"How long can Iran sustain its proxy network at $60/barrel 
vs $100/barrel oil prices?"

"Model European energy security in 2030 under three scenarios: 
diversified LNG, accelerated renewables, or partial Russian 
reconciliation"

Quick Start

1. Install

cd geopolitical-agent/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure

Create .env file:

ANTHROPIC_API_KEY=your_key_here

3. Initialize

python -c "from models.database import init_db; init_db()"

4. Run

python app.py

Server starts on http://localhost:8000

5. Open Frontend

Open frontend/index.html in browser or:

cd frontend
python -m http.server 8080

6. Load Sample Data

Click "Load Sample Data" button in UI or:

curl -X POST http://localhost:8000/api/data/load-sample-data

Architecture

┌─────────────────────────────────────────────────┐
│              Frontend (HTML/JS)                 │
└─────────────────┬───────────────────────────────┘
                  │ REST API
┌─────────────────┴───────────────────────────────┐
│           FastAPI Backend                       │
│                                                 │
│  ┌──────────────────────────────────────────┐  │
│  │      Analysis Service (Claude + RAG)     │  │
│  └─────────┬────────────────────┬───────────┘  │
│            │                    │               │
│   ┌────────┴────────┐   ┌──────┴───────────┐   │
│   │  RAG Service    │   │  Data Ingestion  │   │
│   └────────┬────────┘   └──────┬───────────┘   │
│            │                    │               │
│   ┌────────┴────────┐   ┌──────┴───────────┐   │
│   │   ChromaDB      │   │     SQLite       │   │
│   │  (Vectors)      │   │   (Structured)   │   │
│   └─────────────────┘   └──────────────────┘   │
└─────────────────────────────────────────────────┘

Project Structure

geopolitical-agent/
├── backend/
│   ├── app.py                    # Main FastAPI app
│   ├── config.py                 # Configuration
│   ├── requirements.txt          # Dependencies
│   ├── models/
│   │   ├── database.py          # SQLAlchemy models
│   │   └── embeddings.py        # ChromaDB manager
│   ├── services/
│   │   ├── rag_service.py       # RAG orchestration
│   │   ├── analysis_service.py  # Analysis engine
│   │   └── data_ingestion.py    # Data loading
│   ├── routes/
│   │   ├── query.py             # Query endpoints
│   │   └── data.py              # Data endpoints
│   └── data/
│       ├── geopolitical.db      # SQLite database
│       └── chroma_db/           # Vector store
├── frontend/
│   └── index.html               # Web interface
├── data/
│   ├── sample_data/             # Sample datasets
│   └── training/                # Fine-tuning prep
└── docs/
    ├── SETUP.md                 # Setup guide
    └── API.md                   # API documentation

Database Schema

Countries

• Basic country attributes
• GDP, population, military budget
• Regional categorization

Military Assets

• Equipment inventories (tanks, aircraft, etc.)
• Operational rates
• Production and attrition rates

Geopolitical Events

• Timeline of significant events
• Impact scoring
• Related countries tracking

Metrics Time Series

• Economic indicators
• Production statistics
• Any quantitative metric over time

Knowledge Sources

• Document provenance tracking
• Credibility scoring
• Source metadata

API Examples

Analyze Query

curl -X POST http://localhost:8000/api/query/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Your geopolitical question here",
    "use_cache": true
  }'

Add Knowledge

curl -X POST http://localhost:8000/api/data/add-document \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your geopolitical knowledge document",
    "metadata": {"type": "report", "country": "China"}
  }'

Full API documentation: docs/API.md

Fine-Tuning Preparation

Export Training Data

from models.database import SessionLocal, AnalysisCache
import json

db = SessionLocal()
analyses = db.query(AnalysisCache).all()

training_data = []
for analysis in analyses:
    training_data.append({
        "messages": [
            {
                "role": "system",
                "content": "You are a geopolitical analysis expert..."
            },
            {
                "role": "user",
                "content": analysis.query_text
            },
            {
                "role": "assistant",
                "content": analysis.analysis_result
            }
        ]
    })

with open("training_data.jsonl", "w") as f:
    for item in training_data:
        f.write(json.dumps(item) + "\n")

LoRA Training

Use the exported data to fine-tune a LoRA adapter on geopolitical data:

1. Export queries/responses from analysis_cache table
2. Format as JSONL for LoRA training
3. Train LoRA adapter on domain-specific data
4. Deploy fine-tuned model for specialized analysis

Extending the System

Add New Countries

from models.database import SessionLocal, Country

db = SessionLocal()
country = Country(
    name="Pakistan",
    iso_code="PAK",
    region="South Asia",
    population=235000000,
    gdp_usd=376000000000,
    military_budget_usd=11000000000
)
db.add(country)
db.commit()

Add Military Assets

from models.database import MilitaryAsset

asset = MilitaryAsset(
    country_id=country.id,
    asset_type="Fighter Aircraft",
    asset_name="JF-17 Thunder",
    quantity=150,
    operational_rate=0.75,
    production_rate_yearly=25,
    attrition_rate_yearly=0.05
)
db.add(asset)
db.commit()

Add Knowledge Documents

from services.data_ingestion import DataIngestionService

service = DataIngestionService()
service.add_knowledge_document(
    text="Your geopolitical analysis or fact...",
    metadata={
        "type": "intelligence_assessment",
        "country": "Iran",
        "classification": "open_source"
    }
)

Configuration

Edit backend/config.py:

# Embedding model (smaller = faster, larger = better)
EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"

# RAG retrieval settings
TOP_K_RESULTS = 5              # Number of relevant chunks
SIMILARITY_THRESHOLD = 0.7      # Minimum relevance score

# Claude settings
DEFAULT_MODEL = "claude-sonnet-4-20250514"
MAX_TOKENS = 4000
TEMPERATURE = 0.3               # Lower = more analytical

Performance Tips

1. Adjust retrieval: Tune TOP_K_RESULTS and SIMILARITY_THRESHOLD
2. Enable caching: Set use_cache=true for repeated queries
3. Batch document ingestion: Use bulk-add for multiple documents
4. Index optimization: Add SQLite indexes for frequent queries

Use Cases

Strategic Planning

• War games scenario modeling
• Resource sustainability analysis
• Timeline projections

Intelligence Analysis

• Capability gap assessments
• Economic constraint modeling
• Production capacity tracking

Academic Research

• Geopolitical trend analysis
• Historical pattern recognition
• Comparative case studies

Policy Analysis

• Sanction impact modeling
• Alliance dynamics assessment
• Economic leverage analysis

Roadmap

• Real-time data ingestion from news sources
• Multi-agent debate for competing analyses
• Temporal reasoning for historical patterns
• Export to PDF reports
• WebSocket streaming for long analyses
• Named Entity Recognition for auto-tagging
• Graph database for relationship modeling

Contributing

Areas for contribution:

1. Data: Add domain-specific geopolitical datasets
2. Models: Integrate specialized embedding models
3. Analysis: Enhance quantitative modeling functions
4. UI: Improve frontend visualization
5. Documentation: Add tutorials and examples

License

MIT License - See LICENSE file

Citation

If you use this system in research:

@software{geopolitical_analysis_agent,
  title={Geopolitical Analysis Agent: RAG-based Strategic Forecasting},
  author={[Your Name]},
  year={2025},
  url={https://github.com/yourusername/geopolitical-agent}
}

Support

• Documentation: docs/
• API Reference: docs/API.md
• Setup Guide: docs/SETUP.md
• Issues: GitHub Issues

Acknowledgments

Built with:

• FastAPI
• ChromaDB
• Anthropic Claude
• Sentence Transformers

---

Ready to analyze the world? Start with python app.py 🚀