--- 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 ```bash cd geopolitical-agent/backend python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ### 2. Configure Create `.env` file: ```bash ANTHROPIC_API_KEY=your_key_here ``` ### 3. Initialize ```bash python -c "from models.database import init_db; init_db()" ``` ### 4. Run ```bash python app.py ``` Server starts on http://localhost:8000 ### 5. Open Frontend Open `frontend/index.html` in browser or: ```bash cd frontend python -m http.server 8080 ``` ### 6. Load Sample Data Click "Load Sample Data" button in UI or: ```bash 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 ```bash 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 ```bash 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 ```python 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 ```python 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 ```python 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 ```python 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`: ```python # 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: ```bibtex @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](https://fastapi.tiangolo.com/) - [ChromaDB](https://www.trychroma.com/) - [Anthropic Claude](https://www.anthropic.com/) - [Sentence Transformers](https://www.sbert.net/) --- **Ready to analyze the world? Start with `python app.py`** 🚀