Initial GeoBot Forecasting Framework commit

.gitignore

@@ -0,0 +1,20 @@
+# Ignore Python virtual environments
+.venv/
+venv/
+.venv311/
+
+# Ignore compiled Python files
+__pycache__/
+*.pyc
+
+# Ignore OS metadata
+.DS_Store
+
+# Ignore local data
+*.sqlite
+*.db
+*.log
+
+# Ignore IDE settings
+.vscode/
+.idea/

GETTING_STARTED.md

@@ -0,0 +1,242 @@
+# Getting Started with GeoBotv1
+
+This guide will help you get up and running with GeoBotv1.
+
+## Installation
+
+### 1. Clone the repository
+```bash
+git clone https://github.com/yourusername/AIGEOPOLITICAL.git
+cd AIGEOPOLITICAL
+```
+
+### 2. Create a virtual environment (recommended)
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+### 3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+Or install in development mode:
+```bash
+pip install -e .
+```
+
+### 4. Install optional dependencies
+For full data ingestion capabilities:
+```bash
+pip install pypdf pdfplumber beautifulsoup4 newspaper3k trafilatura feedparser
+```
+
+## Quick Start
+
+### Example 1: Basic Scenario Analysis
+
+```python
+from geobot.core.scenario import Scenario
+from geobot.simulation.monte_carlo import MonteCarloEngine, SimulationConfig
+import numpy as np
+
+# Create a scenario
+scenario = Scenario(
+    name="tension_scenario",
+    features={
+        'military_tension': np.array([0.7]),
+        'diplomatic_relations': np.array([0.3]),
+    }
+)
+
+# Run Monte Carlo simulation
+config = SimulationConfig(n_simulations=1000, time_horizon=50)
+engine = MonteCarloEngine(config)
+
+# Define dynamics
+def transition_fn(state, t, noise):
+    new_state = {}
+    new_state['tension'] = state.get('tension', 0.5) + noise.get('tension', 0)
+    return new_state
+
+def noise_fn(t):
+    return {'tension': np.random.normal(0, 0.05)}
+
+initial_state = {'tension': 0.3}
+trajectories = engine.run_basic_simulation(initial_state, transition_fn, noise_fn)
+
+# Analyze results
+stats = engine.compute_statistics(trajectories)
+print(f"Mean tension at end: {stats['tension']['mean'][-1]:.3f}")
+```
+
+### Example 2: Causal Inference
+
+```python
+from geobot.models.causal_graph import CausalGraph
+
+# Build causal graph
+graph = CausalGraph(name="conflict_model")
+
+# Add variables
+graph.add_node('sanctions', node_type='policy')
+graph.add_node('tension', node_type='state')
+graph.add_node('conflict', node_type='outcome')
+
+# Define causal relationships
+graph.add_edge('sanctions', 'tension',
+              strength=0.7,
+              mechanism="Sanctions increase tension")
+graph.add_edge('tension', 'conflict',
+              strength=0.8,
+              mechanism="Tension leads to conflict")
+
+# Visualize
+graph.visualize('causal_graph.png')
+```
+
+### Example 3: Intervention Simulation
+
+```python
+from geobot.inference.do_calculus import InterventionSimulator
+from geobot.models.causal_graph import StructuralCausalModel
+
+# Create SCM with your causal graph
+scm = StructuralCausalModel(graph)
+
+# Define structural equations
+# (See examples/03_intervention_simulation.py for full details)
+
+# Create simulator
+simulator = InterventionSimulator(scm)
+
+# Simulate intervention
+result = simulator.simulate_intervention(
+    intervention={'sanctions': 0.8},
+    n_samples=1000,
+    outcomes=['conflict']
+)
+
+print(f"Expected conflict under sanctions: {result['conflict'].mean():.3f}")
+```
+
+### Example 4: Bayesian Belief Updating
+
+```python
+from geobot.inference.bayesian_engine import BeliefUpdater
+
+# Create updater
+updater = BeliefUpdater()
+
+# Initialize belief
+updater.initialize_belief(
+    name='conflict_risk',
+    prior_mean=0.3,
+    prior_std=0.1,
+    belief_type='probability'
+)
+
+# Update with new intelligence
+posterior = updater.update_from_intelligence(
+    belief='conflict_risk',
+    observation=0.6,
+    reliability=0.8
+)
+
+print(f"Updated risk: {posterior['mean']:.3f} ± {posterior['std']:.3f}")
+```
+
+### Example 5: PDF Processing
+
+```python
+from geobot.data_ingestion.pdf_reader import PDFProcessor
+
+# Create processor
+processor = PDFProcessor()
+
+# Process document
+result = processor.extract_intelligence('report.pdf')
+
+print(f"Risk Level: {result['intelligence']['risk_level']}")
+print(f"Countries: {result['intelligence']['mentioned_countries']}")
+print(f"Conflict Indicators: {result['intelligence']['conflict_indicators']}")
+```
+
+### Example 6: Web Scraping
+
+```python
+from geobot.data_ingestion.web_scraper import ArticleExtractor
+
+# Create extractor
+extractor = ArticleExtractor()
+
+# Extract article
+article = extractor.extract_article('https://example.com/article')
+
+print(f"Title: {article['title']}")
+print(f"Summary: {article['text'][:200]}...")
+```
+
+## Running Examples
+
+The `examples/` directory contains comprehensive demonstrations:
+
+```bash
+cd examples
+
+# Basic usage
+python 01_basic_usage.py
+
+# Data ingestion
+python 02_data_ingestion.py
+
+# Intervention simulation
+python 03_intervention_simulation.py
+```
+
+## Core Concepts
+
+### 1. Scenarios
+Scenarios represent geopolitical states with features and probabilities.
+
+### 2. Causal Graphs
+DAGs that model causal relationships between variables.
+
+### 3. Structural Causal Models
+Mathematical models with functional equations for each variable.
+
+### 4. Monte Carlo Simulation
+Stochastic simulation for uncertainty quantification.
+
+### 5. Bayesian Inference
+Principled belief updating as new evidence arrives.
+
+### 6. Do-Calculus
+Intervention reasoning for "what if" questions.
+
+### 7. Optimal Transport
+Measuring distances between probability distributions.
+
+## Next Steps
+
+1. Read the full README.md
+2. Explore the examples directory
+3. Check out the module documentation
+4. Build your own models!
+
+## Need Help?
+
+- Check the examples directory for detailed code
+- Review module docstrings for API documentation
+- Open an issue on GitHub
+
+## Tips
+
+1. Start with simple models and gradually add complexity
+2. Always validate your causal assumptions
+3. Use Monte Carlo for uncertainty quantification
+4. Combine multiple methods for robust forecasting
+5. Document your assumptions and data sources
+
+Happy forecasting!

README.md

@@ -0,0 +1,542 @@
+# GeoBotv1: Research-Grade Geopolitical Forecasting Framework
+
+[![Status](https://img.shields.io/badge/status-production-brightgreen)]() [![Python](https://img.shields.io/badge/python-3.9+-blue)]() [![License](https://img.shields.io/badge/license-MIT-blue)]()
+
+**GeoBotv1** is a complete, research-grade framework for geopolitical forecasting, conflict prediction, and causal policy analysis. Built on rigorous mathematical foundations, it combines optimal transport theory, structural causal inference, Bayesian reasoning, stochastic processes, econometric methods, and machine learning to provide actionable intelligence on regime shifts, conflict escalation, and intervention outcomes.
+
+**Status: ✅ 100% Complete** - All core mathematical frameworks implemented and production-ready.
+
+---
+
+## 🎯 Key Capabilities
+
+- **Causal Policy Analysis**: Simulate interventions (sanctions, deployments, regime changes) and estimate counterfactual outcomes
+- **Conflict Contagion Modeling**: Model self-exciting escalation dynamics and cross-country spillovers using Hawkes processes
+- **Multi-Country Forecasting**: Capture interdependencies and shock propagation with Vector Autoregression (VAR/SVAR)
+- **Quasi-Experimental Inference**: Estimate treatment effects from observational data (Synthetic Control, DiD, RDD, IV)
+- **Regime Detection**: Identify structural breaks and state transitions in real-time
+- **Scenario Comparison**: Measure distances between geopolitical futures using optimal transport geometry
+- **Intelligence Integration**: Bayesian belief updating from text, events, and structured data
+- **Nowcasting**: High-dimensional factor models for real-time situational awareness
+
+---
+
+## 📊 Complete Mathematical Framework
+
+### ✅ Implemented Core Components
+
+<table>
+<tr>
+<td width="50%">
+
+**1. Optimal Transport Theory**
+- Wasserstein distances (W1, W2, W∞)
+- Kantorovich duality (primal/dual formulations)
+- Sinkhorn algorithm (entropic regularization)
+- Unbalanced optimal transport
+- Gromov-Wasserstein for network comparison
+- Gradient-based OT optimization
+
+**2. Causal Inference**
+- Directed Acyclic Graphs (DAGs)
+- Structural Causal Models (SCMs)
+- Pearl's Do-Calculus for interventions
+- Backdoor/frontdoor adjustment
+- Counterfactual computation
+- Causal discovery algorithms
+
+**3. Bayesian Inference**
+- Markov Chain Monte Carlo (MCMC)
+- Sequential Monte Carlo (Particle Filters)
+  - Bootstrap, Auxiliary, Rao-Blackwellized
+- Variational Inference (ELBO, CAVI, ADVI)
+- Belief updating from intelligence
+- Posterior predictive distributions
+
+**4. Stochastic Processes**
+- Stochastic Differential Equations (SDEs)
+  - Euler-Maruyama, Milstein, Stochastic RK
+- Jump-diffusion processes (Merton model)
+- Ornstein-Uhlenbeck processes
+- GeopoliticalSDE framework
+- Continuous-time dynamics
+
+</td>
+<td width="50%">
+
+**5. Time-Series & Econometrics**
+- Kalman Filters (Linear & Extended)
+- Hidden Markov Models (HMM)
+- Regime-Switching Models
+- **Vector Autoregression (VAR)**
+- **Structural VAR (SVAR)**
+- **Dynamic Factor Models (DFM)**
+- **Granger Causality Testing**
+- Impulse Response Functions (IRF)
+- Forecast Error Variance Decomposition
+
+**6. Point Processes**
+- **Univariate Hawkes Processes**
+- **Multivariate Hawkes Processes**
+- **Conflict Contagion Models**
+- Branching ratio estimation
+- Self-excitation dynamics
+- Cross-country excitation matrices
+
+**7. Quasi-Experimental Methods**
+- **Synthetic Control Method (SCM)**
+- **Difference-in-Differences (DiD)**
+- **Regression Discontinuity Design (RDD)**
+- **Instrumental Variables (2SLS)**
+- Placebo tests and robustness checks
+- Treatment effect bounds
+
+**8. Machine Learning**
+- Graph Neural Networks (GNN, GAT)
+- CausalGNN for directed graphs
+- Risk scoring and classification
+- Feature discovery and embeddings
+- Transformer-based text encoding
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/AIGEOPOLITICAL.git
+cd AIGEOPOLITICAL
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Optional: Install Graph Neural Network support
+# (Requires matching torch version)
+pip install torch-geometric torch-scatter torch-sparse
+```
+
+### Basic Usage Example
+
+```python
+from geobot.core import Scenario, ScenarioComparator
+from geobot.models import CausalGraph
+from geobot.inference import DoCalculus
+from geobot.timeseries import VARModel
+import numpy as np
+
+# 1. Create geopolitical scenarios
+scenario_baseline = Scenario(
+    name="Baseline",
+    features={
+        "military_readiness": np.array([0.6, 0.4, 0.5]),
+        "economic_stability": np.array([0.7, 0.6, 0.5])
+    }
+)
+
+scenario_intervention = Scenario(
+    name="Post-Sanctions",
+    features={
+        "military_readiness": np.array([0.8, 0.4, 0.5]),
+        "economic_stability": np.array([0.3, 0.6, 0.5])
+    }
+)
+
+# 2. Compare scenarios using optimal transport
+comparator = ScenarioComparator()
+distance = comparator.compare(scenario_baseline, scenario_intervention)
+print(f"Wasserstein distance: {distance:.4f}")
+
+# 3. Build causal model
+causal_graph = CausalGraph()
+causal_graph.add_edge("sanctions", "economy", strength=0.8)
+causal_graph.add_edge("economy", "stability", strength=0.6)
+causal_graph.add_edge("stability", "conflict_risk", strength=-0.7)
+
+# 4. Simulate intervention
+do_calc = DoCalculus(causal_graph)
+intervention_effect = do_calc.compute_intervention_effect(
+    intervention={"sanctions": 1.0},
+    outcome="conflict_risk"
+)
+print(f"Estimated effect on conflict risk: {intervention_effect:.3f}")
+
+# 5. Multi-country VAR forecasting
+# (Simulated data for demonstration)
+data = np.random.randn(100, 3)  # 100 time periods, 3 countries
+var = VARModel(n_lags=2)
+results = var.fit(data, variable_names=['Country_A', 'Country_B', 'Country_C'])
+forecast = var.forecast(results, steps=10)
+print(f"10-step forecast:\n{forecast}")
+```
+
+### Conflict Contagion Example
+
+```python
+from geobot.timeseries import ConflictContagionModel
+
+# Model conflict spread between countries
+countries = ['Syria', 'Iraq', 'Lebanon', 'Turkey']
+model = ConflictContagionModel(countries=countries)
+
+# Historical conflict events (times when conflicts occurred)
+events = {
+    'Syria': [1.2, 5.3, 10.1, 15.2, 22.3],
+    'Iraq': [3.4, 8.9, 12.1, 18.5],
+    'Lebanon': [12.3, 19.8, 25.1],
+    'Turkey': [28.2, 30.5]
+}
+
+# Fit contagion model
+result = model.fit(events, T=365.0)  # 1 year of data
+
+print(f"Most contagious source: {result['most_contagious_source']}")
+print(f"Most vulnerable target: {result['most_vulnerable_target']}")
+
+# Assess future risk
+risks = model.contagion_risk(events, result, t=370.0, horizon=30.0)
+for country, risk in risks.items():
+    print(f"{country} conflict risk (next 30 days): {risk:.1%}")
+```
+
+### Synthetic Control for Policy Evaluation
+
+```python
+from geobot.models import SyntheticControlMethod
+import numpy as np
+
+# Evaluate impact of sanctions on target country
+scm = SyntheticControlMethod()
+
+# Data: treated country vs. control countries
+treated_outcome = gdp_growth_target_country  # Shape: (T,)
+control_outcomes = gdp_growth_other_countries  # Shape: (T, J)
+
+result = scm.fit(
+    treated_outcome=treated_outcome,
+    control_outcomes=control_outcomes,
+    treatment_time=50,  # Sanctions imposed at t=50
+    control_names=['Country_1', 'Country_2', ..., 'Country_J']
+)
+
+# Estimated treatment effect
+avg_effect = np.mean(result.treatment_effect[50:])
+print(f"Average treatment effect: {avg_effect:.3f}")
+
+# Statistical significance via placebo test
+p_value = scm.placebo_test(treated_outcome, control_outcomes,
+                           treatment_time=50, n_permutations=100)
+print(f"Placebo test p-value: {p_value:.3f}")
+```
+
+---
+
+## 📁 Project Structure
+
+```
+AIGEOPOLITICAL/
+├── geobot/                          # Main package
+│   ├── core/                        # Core mathematical primitives
+│   │   ├── optimal_transport.py     # Wasserstein distances
+│   │   ├── advanced_optimal_transport.py  # Kantorovich, Sinkhorn, Gromov-W
+│   │   └── scenario.py              # Scenario representations
+│   │
+│   ├── models/                      # Causal models
+│   │   ├── causal_graph.py          # DAGs and SCMs
+│   │   ├── causal_discovery.py      # Causal structure learning
+│   │   └── quasi_experimental.py    # SCM, DiD, RDD, IV methods
+│   │
+│   ├── inference/                   # Probabilistic inference
+│   │   ├── do_calculus.py           # Interventions and counterfactuals
+│   │   ├── bayesian_engine.py       # Bayesian belief updating
+│   │   ├── particle_filter.py       # Sequential Monte Carlo
+│   │   └── variational_inference.py # VI, ELBO, ADVI
+│   │
+│   ├── simulation/                  # Stochastic simulation
+│   │   ├── monte_carlo.py           # Basic Monte Carlo
+│   │   ├── sde_solver.py            # Stochastic differential equations
+│   │   └── agent_based.py           # Agent-based models
+│   │
+│   ├── timeseries/                  # Time-series models
+│   │   ├── kalman_filter.py         # Kalman filters
+│   │   ├── hmm.py                   # Hidden Markov Models
+│   │   ├── regime_switching.py      # Regime-switching models
+│   │   ├── var_models.py            # VAR, SVAR, DFM, Granger causality
+│   │   └── point_processes.py       # Hawkes processes, conflict contagion
+│   │
+│   ├── ml/                          # Machine learning
+│   │   ├── risk_models.py           # Risk scoring
+│   │   ├── graph_neural_networks.py # GNNs for causal/geopolitical networks
+│   │   └── embeddings.py            # Feature embeddings
+│   │
+│   ├── data_ingestion/              # Data processing
+│   │   ├── pdf_reader.py            # PDF intelligence extraction
+│   │   ├── web_scraper.py           # Web scraping
+│   │   ├── event_extraction.py      # NLP-based event structuring
+│   │   └── event_database.py        # Event storage and querying
+│   │
+│   ├── utils/                       # Utilities
+│   │   ├── data_processing.py       # Data preprocessing
+│   │   └── visualization.py         # Plotting and visualization
+│   │
+│   └── config/                      # Configuration
+│       └── settings.py              # System configuration
+│
+├── examples/                        # Comprehensive examples
+│   ├── 01_basic_usage.py            # Scenarios, causal graphs, Monte Carlo
+│   ├── 02_data_ingestion.py        # PDF/web scraping pipeline
+│   ├── 03_intervention_simulation.py # Do-calculus and counterfactuals
+│   ├── 04_advanced_features.py     # Particle filters, VI, SDEs, GNNs
+│   └── 05_complete_framework.py    # VAR, Hawkes, quasi-experimental
+│
+├── requirements.txt                 # Python dependencies
+└── README.md                        # This file
+```
+
+---
+
+## 🔬 Mathematical Foundations
+
+### Causality-First Principle
+
+GeoBotv1 grounds all forecasting in **explicit causal structure**. This prevents spurious correlations and enables simulation of interventions that have never been observed.
+
+**Structural Causal Model (SCM):**
+```
+X := f_X(Pa_X, U_X)
+Y := f_Y(Pa_Y, U_Y)
+```
+
+**Pearl's Do-Calculus** enables reasoning about interventions `do(X = x)` even when only observational data is available.
+
+### Optimal Transport for Scenario Comparison
+
+The Wasserstein distance measures the "cost" of transforming one probability distribution into another:
+
+```
+W_2(μ, ν) = inf_{π ∈ Π(μ,ν)} √(∫∫ ||x - y||² dπ(x,y))
+```
+
+**Kantorovich Duality** provides computational efficiency and geometric interpretation.
+
+### Hawkes Processes for Conflict Dynamics
+
+Self-exciting point processes capture escalation and contagion:
+
+```
+λ_k(t) = μ_k + ∑_{j=1}^K α_{kj} ∑_{t_i^j < t} exp(-β_{kj}(t - t_i^j))
+```
+
+**Branching ratio** `n = α/β` determines stability:
+- `n < 1`: Process is stable (subcritical)
+- `n ≥ 1`: Process is explosive (supercritical)
+
+### Stochastic Differential Equations
+
+Continuous-time geopolitical dynamics:
+
+```
+dX_t = μ(X_t, t) dt + σ(X_t, t) dW_t + dJ_t
+```
+
+Where:
+- `μ`: Drift (deterministic component)
+- `σ dW_t`: Diffusion (continuous shocks)
+- `dJ_t`: Jumps (discrete events)
+
+---
+
+## 💡 Use Cases
+
+### 1. Strategic Intelligence & Risk Assessment
+- **Multi-country risk dashboards** with VAR-based interdependency analysis
+- **Real-time belief updating** as intelligence arrives (Bayesian inference)
+- **Regime detection** using HMM and particle filters
+
+### 2. Conflict Prediction & Early Warning
+- **Hawkes process models** for escalation dynamics and contagion
+- **Structural break detection** in military/economic indicators
+- **Cross-country spillover analysis** with SVAR impulse responses
+
+### 3. Policy Impact Analysis
+- **Synthetic control** for sanctions/intervention evaluation
+- **Difference-in-differences** for regime change effects
+- **Regression discontinuity** for election outcome impacts
+- **Do-calculus** for counterfactual policy simulation
+
+### 4. Resource Allocation & Logistics
+- **Optimal transport** for supply chain optimization under uncertainty
+- **Monte Carlo simulation** for contingency planning
+- **Stochastic optimization** with SDE-based constraints
+
+### 5. Diplomatic Forecasting
+- **Game-theoretic extensions** (can be added via causal graphs)
+- **Network centrality** analysis with GNNs
+- **Alliance dynamics** using multivariate Hawkes processes
+
+---
+
+## 🛠️ Technical Requirements
+
+### Core Dependencies
+- **Python**: 3.9+
+- **NumPy**: 1.24+
+- **SciPy**: 1.10+
+- **Pandas**: 2.0+
+- **NetworkX**: 3.0+ (causal graphs)
+- **POT**: 0.9+ (optimal transport)
+- **PyMC**: 5.0+ (Bayesian inference)
+- **Statsmodels**: 0.14+ (econometrics)
+
+### Optional but Recommended
+- **PyTorch**: 2.0+ (for GNNs, deep learning)
+- **PyTorch Geometric**: 2.3+ (graph neural networks)
+- **spaCy**: 3.6+ (NLP for event extraction)
+- **Transformers**: 4.30+ (text embeddings)
+
+### Data Ingestion
+- **Beautiful Soup**: 4.12+ (web scraping)
+- **PDFPlumber**: 0.10+ (PDF extraction)
+- **Newspaper3k**: 0.2.8+ (article extraction)
+- **Feedparser**: 6.0+ (RSS feeds)
+
+See `requirements.txt` for complete dependency list.
+
+---
+
+## 📖 Documentation & Examples
+
+### Example Scripts
+All examples are fully functional and demonstrate end-to-end workflows:
+
+1. **`01_basic_usage.py`**: Scenarios, causal graphs, Monte Carlo basics, Bayesian updating
+2. **`02_data_ingestion.py`**: PDF extraction, web scraping, event databases
+3. **`03_intervention_simulation.py`**: Do-calculus, counterfactuals, policy simulation
+4. **`04_advanced_features.py`**: Particle filters, VI, SDEs, GNNs, event extraction
+5. **`05_complete_framework.py`**: VAR/SVAR/DFM, Hawkes processes, quasi-experimental methods
+
+### Running Examples
+
+```bash
+cd examples
+
+# Basic usage
+python 01_basic_usage.py
+
+# Data ingestion pipeline
+python 02_data_ingestion.py
+
+# Intervention simulation
+python 03_intervention_simulation.py
+
+# Advanced mathematical features
+python 04_advanced_features.py
+
+# Complete framework demonstration (VAR, Hawkes, quasi-experimental)
+python 05_complete_framework.py
+```
+
+---
+
+## 🎓 Theoretical Background
+
+GeoBotv1 synthesizes methods from multiple fields:
+
+### Economics & Econometrics
+- Vector Autoregression (Sims, 1980)
+- Structural VAR identification (Blanchard & Quah, 1989)
+- Synthetic Control Method (Abadie et al., 2010, 2015)
+- Difference-in-Differences (Card & Krueger, 1994)
+- Regression Discontinuity (Thistlethwaite & Campbell, 1960)
+
+### Statistics & Probability
+- Optimal Transport (Villani, 2003, 2009)
+- Hawkes Processes (Hawkes, 1971; Hawkes & Oakes, 1974)
+- Sequential Monte Carlo (Doucet et al., 2001)
+- Variational Inference (Jordan et al., 1999; Blei et al., 2017)
+
+### Computer Science & AI
+- Causal Inference (Pearl, 2000, 2009)
+- Do-Calculus (Pearl, 1995)
+- Graph Neural Networks (Kipf & Welling, 2017; Veličković et al., 2018)
+- Structural Causal Models (Pearl & Mackenzie, 2018)
+
+### Geopolitics & Conflict Studies
+- Conflict contagion (Gleditsch, 2007; Braithwaite, 2010)
+- Regime change dynamics (Acemoglu & Robinson, 2006)
+- Economic sanctions effects (Hufbauer et al., 2007)
+
+---
+
+## 🧪 Testing & Validation
+
+### Mathematical Correctness
+- Kantorovich duality: Verify primal-dual gap ≈ 0
+- Hawkes stability: Check branching ratio < 1 for subcritical processes
+- Causal identification: Validate backdoor/frontdoor criteria
+- Particle filter: Monitor Effective Sample Size (ESS)
+
+### Statistical Properties
+- VAR stationarity: Check eigenvalues of companion matrix
+- SVAR identification: Verify order conditions satisfied
+- Synthetic control: Pre-treatment fit quality (RMSPE)
+- RDD: Bandwidth sensitivity analysis
+
+### Reproducibility
+All examples include `np.random.seed()` for deterministic results.
+
+---
+
+## 🚧 Extensions & Future Work
+
+While GeoBotv1 is complete for core forecasting tasks, potential extensions include:
+
+- **Game-Theoretic Modules**: Strategic interaction between actors
+- **Spatial Statistics**: Geographic contagion with distance decay
+- **Network Effects**: Centrality measures, community detection
+- **Deep Learning**: Attention mechanisms for text-to-risk pipelines
+- **Real-Time Data Feeds**: API integrations for live intelligence
+- **Uncertainty Quantification**: Conformal prediction, calibration
+- **Ensemble Methods**: Model averaging across multiple frameworks
+
+---
+
+## 📄 License
+
+MIT License - See LICENSE file for details
+
+---
+
+## 🙏 Acknowledgments
+
+GeoBotv1 builds on decades of research in:
+- Causal inference (Judea Pearl, Donald Rubin)
+- Optimal transport theory (Cédric Villani, Leonid Kantorovich)
+- Econometrics (Christopher Sims, Alberto Abadie)
+- Point processes (Alan Hawkes, Daryl Daley)
+- Bayesian statistics (Andrew Gelman, Michael Jordan)
+- Stochastic calculus (Kiyosi Itô, Bernt Øksendal)
+
+---
+
+## 📧 Contact & Support
+
+For questions, issues, or collaboration:
+- **Issues**: [GitHub Issues](https://github.com/your-org/AIGEOPOLITICAL/issues)
+- **Documentation**: [Full documentation](https://your-org.github.io/AIGEOPOLITICAL)
+- **Citation**: If you use GeoBotv1 in research, please cite this repository
+
+---
+
+<div align="center">
+
+**GeoBotv1** - Where rigorous mathematics meets geopolitical forecasting
+
+*Built with causality, powered by probability, validated by theory*
+
+</div>

examples/01_basic_usage.py

@@ -0,0 +1,131 @@
+"""
+Example 1: Basic Usage of GeoBotv1
+
+This example demonstrates the core components of the framework:
+- Creating scenarios
+- Building causal graphs
+- Running Monte Carlo simulations
+- Bayesian belief updating
+"""
+
+import numpy as np
+import sys
+sys.path.append('..')
+
+from geobot.core.scenario import Scenario, ScenarioDistribution
+from geobot.models.causal_graph import CausalGraph, StructuralCausalModel
+from geobot.simulation.monte_carlo import MonteCarloEngine, SimulationConfig
+from geobot.inference.bayesian_engine import BayesianEngine, Prior, Evidence, BeliefUpdater
+from scipy import stats
+
+
+def main():
+    print("=" * 80)
+    print("GeoBotv1 - Basic Usage Example")
+    print("=" * 80)
+
+    # 1. Create a simple scenario
+    print("\n1. Creating a geopolitical scenario...")
+    scenario = Scenario(
+        name="baseline_scenario",
+        features={
+            'military_tension': np.array([0.5]),
+            'economic_sanctions': np.array([0.3]),
+            'diplomatic_relations': np.array([0.6]),
+        },
+        probability=1.0
+    )
+    print(f"   Created scenario: {scenario.name}")
+    print(f"   Features: {list(scenario.features.keys())}")
+
+    # 2. Build a causal graph
+    print("\n2. Building causal graph...")
+    causal_graph = CausalGraph(name="geopolitical_dag")
+
+    # Add nodes
+    causal_graph.add_node('sanctions', node_type='policy')
+    causal_graph.add_node('tension', node_type='state')
+    causal_graph.add_node('conflict_risk', node_type='outcome')
+
+    # Add causal edges
+    causal_graph.add_edge('sanctions', 'tension',
+                         strength=0.7,
+                         mechanism="Sanctions increase military tension")
+    causal_graph.add_edge('tension', 'conflict_risk',
+                         strength=0.8,
+                         mechanism="Tension increases conflict probability")
+
+    print(f"   Created graph with {len(causal_graph.graph.nodes)} nodes")
+    print(f"   Causal relationships: sanctions -> tension -> conflict_risk")
+
+    # 3. Run Monte Carlo simulation
+    print("\n3. Running Monte Carlo simulation...")
+    config = SimulationConfig(n_simulations=100, time_horizon=50)
+    mc_engine = MonteCarloEngine(config)
+
+    def transition_fn(state, t, noise):
+        # Simple dynamics
+        new_state = {}
+        new_state['tension'] = state.get('tension', 0.5) + \
+                              0.1 * state.get('sanctions', 0) + \
+                              noise.get('tension', 0)
+        new_state['conflict_risk'] = 0.5 * new_state['tension'] + \
+                                    noise.get('conflict_risk', 0)
+        # Clip values
+        new_state['tension'] = np.clip(new_state['tension'], 0, 1)
+        new_state['conflict_risk'] = np.clip(new_state['conflict_risk'], 0, 1)
+        return new_state
+
+    def noise_fn(t):
+        return {
+            'tension': np.random.normal(0, 0.05),
+            'conflict_risk': np.random.normal(0, 0.05)
+        }
+
+    initial_state = {'tension': 0.3, 'sanctions': 0.2, 'conflict_risk': 0.1}
+    trajectories = mc_engine.run_basic_simulation(initial_state, transition_fn, noise_fn)
+
+    # Compute statistics
+    stats = mc_engine.compute_statistics(trajectories)
+    print(f"   Ran {config.n_simulations} simulations")
+    print(f"   Final conflict risk (mean): {stats['conflict_risk']['mean'][-1]:.3f}")
+    print(f"   Final conflict risk (95% CI): [{stats['conflict_risk']['q5'][-1]:.3f}, {stats['conflict_risk']['q95'][-1]:.3f}]")
+
+    # 4. Bayesian belief updating
+    print("\n4. Bayesian belief updating...")
+    updater = BeliefUpdater()
+
+    # Initialize belief about conflict risk
+    updater.initialize_belief(
+        name='conflict_risk',
+        prior_mean=0.3,
+        prior_std=0.1,
+        belief_type='probability'
+    )
+
+    # Receive intelligence report suggesting higher risk
+    print("   Received intelligence: conflict risk = 0.6 (reliability: 0.7)")
+    posterior = updater.update_from_intelligence(
+        belief='conflict_risk',
+        observation=0.6,
+        reliability=0.7
+    )
+
+    print(f"   Updated belief - Mean: {posterior['mean']:.3f}, Std: {posterior['std']:.3f}")
+    print(f"   95% Credible Interval: [{posterior['q5']:.3f}, {posterior['q95']:.3f}]")
+
+    # 5. Probability of high risk
+    prob_high_risk = updater.get_belief_probability(
+        'conflict_risk',
+        threshold=0.5,
+        direction='greater'
+    )
+    print(f"   Probability of high risk (>0.5): {prob_high_risk:.3f}")
+
+    print("\n" + "=" * 80)
+    print("Example completed successfully!")
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

examples/02_data_ingestion.py

@@ -0,0 +1,202 @@
+"""
+Example 2: Data Ingestion - PDF and Web Scraping
+
+This example demonstrates:
+- PDF document reading and processing
+- Web article extraction
+- News aggregation
+- Intelligence extraction from documents
+"""
+
+import sys
+sys.path.append('..')
+
+from geobot.data_ingestion.pdf_reader import PDFReader, PDFProcessor
+from geobot.data_ingestion.web_scraper import WebScraper, ArticleExtractor, NewsAggregator
+
+
+def demo_pdf_processing():
+    """Demonstrate PDF processing capabilities."""
+    print("\n" + "=" * 80)
+    print("PDF Processing Demo")
+    print("=" * 80)
+
+    # Create PDF processor
+    processor = PDFProcessor()
+
+    print("\nPDF processing capabilities:")
+    print("- Text extraction from PDFs")
+    print("- Table extraction")
+    print("- Metadata extraction")
+    print("- Entity recognition (countries, organizations)")
+    print("- Keyword extraction")
+    print("- Risk assessment")
+    print("\nTo use: processor.process_document('path/to/document.pdf')")
+
+    # Example code structure
+    example_code = """
+    # Process a single PDF
+    result = processor.process_document('intelligence_report.pdf')
+
+    print(f"Title: {result['metadata'].get('title', 'Unknown')}")
+    print(f"Pages: {result['num_pages']}")
+    print(f"Keywords: {result['keywords']}")
+    print(f"Risk Level: {result['intelligence']['risk_level']}")
+
+    # Process multiple PDFs
+    results = processor.batch_process('reports_directory/', '*.pdf')
+    """
+
+    print("\nExample usage:")
+    print(example_code)
+
+
+def demo_web_scraping():
+    """Demonstrate web scraping capabilities."""
+    print("\n" + "=" * 80)
+    print("Web Scraping Demo")
+    print("=" * 80)
+
+    # Create article extractor
+    extractor = ArticleExtractor()
+
+    print("\nWeb scraping capabilities:")
+    print("- Extract articles from URLs")
+    print("- Clean HTML content")
+    print("- Extract metadata (author, date, etc.)")
+    print("- Multiple extraction methods (newspaper3k, trafilatura, BeautifulSoup)")
+
+    # Example with a well-known news site (without actually fetching)
+    example_url = "https://www.example.com/geopolitical-analysis"
+
+    print(f"\nExample: Extracting article from {example_url}")
+    print("(This is a demonstration - no actual web request is made)")
+
+    example_code = """
+    # Extract article
+    article = extractor.extract_article(url)
+
+    print(f"Title: {article['title']}")
+    print(f"Author: {article['authors']}")
+    print(f"Published: {article['publish_date']}")
+    print(f"Content length: {len(article['text'])} characters")
+
+    # Extract multiple articles
+    urls = ['url1', 'url2', 'url3']
+    articles = extractor.batch_extract(urls)
+    """
+
+    print("\nExample usage:")
+    print(example_code)
+
+
+def demo_news_aggregation():
+    """Demonstrate news aggregation capabilities."""
+    print("\n" + "=" * 80)
+    print("News Aggregation Demo")
+    print("=" * 80)
+
+    aggregator = NewsAggregator()
+
+    print("\nNews aggregation capabilities:")
+    print("- Aggregate from multiple sources")
+    print("- RSS feed support")
+    print("- Keyword filtering")
+    print("- Trending topic detection")
+    print("- Real-time monitoring")
+
+    # Example configuration
+    print("\nExample: Setting up news aggregation")
+
+    example_code = """
+    # Add news sources
+    aggregator.add_source(
+        name='Reuters',
+        url='https://www.reuters.com/news/world',
+        source_type='rss'
+    )
+
+    aggregator.add_source(
+        name='Al Jazeera',
+        url='https://www.aljazeera.com/xml/rss/all.xml',
+        source_type='rss'
+    )
+
+    # Fetch news with keywords
+    keywords = ['sanctions', 'conflict', 'diplomacy', 'military']
+    articles = aggregator.fetch_news(keywords)
+
+    print(f"Found {len(articles)} relevant articles")
+
+    # Get trending topics
+    topics = aggregator.get_trending_topics(articles, n_topics=10)
+    print("Trending topics:", topics)
+
+    # Monitor sources continuously
+    def alert_callback(new_articles):
+        print(f"ALERT: {len(new_articles)} new relevant articles found")
+        for article in new_articles:
+            print(f"  - {article['title']}")
+
+    # Monitor every hour
+    aggregator.monitor_sources(keywords, callback=alert_callback, interval=3600)
+    """
+
+    print(example_code)
+
+
+def demo_intelligence_extraction():
+    """Demonstrate intelligence extraction from documents."""
+    print("\n" + "=" * 80)
+    print("Intelligence Extraction Demo")
+    print("=" * 80)
+
+    print("\nIntelligence extraction capabilities:")
+    print("- Country and organization detection")
+    print("- Conflict indicator detection")
+    print("- Risk level assessment")
+    print("- Document classification")
+    print("- Key phrase extraction")
+
+    example_code = """
+    processor = PDFProcessor()
+
+    # Extract intelligence from PDF
+    intel = processor.extract_intelligence('report.pdf')
+
+    print("Intelligence Summary:")
+    print(f"Risk Level: {intel['intelligence']['risk_level']}")
+    print(f"Countries mentioned: {intel['intelligence']['mentioned_countries']}")
+    print(f"Conflict indicators: {intel['intelligence']['conflict_indicators']}")
+    print(f"Key topics: {intel['intelligence']['key_topics']}")
+    print(f"Document type: {intel['intelligence']['document_type']}")
+    """
+
+    print("\nExample usage:")
+    print(example_code)
+
+
+def main():
+    print("=" * 80)
+    print("GeoBotv1 - Data Ingestion Examples")
+    print("=" * 80)
+    print("\nThis module demonstrates the data ingestion capabilities of GeoBotv1:")
+    print("1. PDF document processing")
+    print("2. Web scraping and article extraction")
+    print("3. News aggregation from multiple sources")
+    print("4. Intelligence extraction from documents")
+
+    demo_pdf_processing()
+    demo_web_scraping()
+    demo_news_aggregation()
+    demo_intelligence_extraction()
+
+    print("\n" + "=" * 80)
+    print("Data Ingestion Demo Complete")
+    print("=" * 80)
+    print("\nNote: Install required packages for full functionality:")
+    print("  pip install pypdf pdfplumber beautifulsoup4 newspaper3k trafilatura")
+
+
+if __name__ == "__main__":
+    main()

examples/03_intervention_simulation.py

@@ -0,0 +1,237 @@
+"""
+Example 3: Intervention Simulation and Counterfactual Analysis
+
+This example demonstrates:
+- Policy intervention simulation
+- Counterfactual reasoning ("what if" scenarios)
+- Comparing multiple interventions
+- Optimal intervention finding
+"""
+
+import numpy as np
+import sys
+sys.path.append('..')
+
+from geobot.models.causal_graph import CausalGraph, StructuralCausalModel
+from geobot.inference.do_calculus import DoCalculus, InterventionSimulator
+
+
+def create_geopolitical_scm():
+    """Create a structural causal model for geopolitical scenarios."""
+    print("\n1. Creating Structural Causal Model...")
+
+    # Create causal graph
+    graph = CausalGraph(name="geopolitical_system")
+
+    # Add nodes
+    graph.add_node('economic_sanctions', node_type='policy')
+    graph.add_node('diplomatic_pressure', node_type='policy')
+    graph.add_node('domestic_stability', node_type='state')
+    graph.add_node('military_mobilization', node_type='state')
+    graph.add_node('conflict_probability', node_type='outcome')
+
+    # Add causal edges
+    graph.add_edge('economic_sanctions', 'domestic_stability',
+                  strength=-0.6, mechanism="Sanctions reduce stability")
+    graph.add_edge('diplomatic_pressure', 'domestic_stability',
+                  strength=-0.3, mechanism="Pressure affects stability")
+    graph.add_edge('domestic_stability', 'military_mobilization',
+                  strength=-0.7, mechanism="Instability drives mobilization")
+    graph.add_edge('military_mobilization', 'conflict_probability',
+                  strength=0.8, mechanism="Mobilization increases conflict risk")
+    graph.add_edge('economic_sanctions', 'conflict_probability',
+                  strength=0.4, mechanism="Direct deterrence effect")
+
+    print(f"   Created graph with {len(graph.graph.nodes)} nodes and {len(graph.edges)} edges")
+
+    # Create SCM
+    scm = StructuralCausalModel(graph)
+
+    # Define structural equations
+    def sanctions_fn(parents, noise):
+        return 0.5 + noise  # Baseline policy level
+
+    def pressure_fn(parents, noise):
+        return 0.3 + noise
+
+    def stability_fn(parents, noise):
+        sanctions = parents.get('economic_sanctions', np.zeros(1))[0]
+        pressure = parents.get('diplomatic_pressure', np.zeros(1))[0]
+        return np.clip(0.7 - 0.6 * sanctions - 0.3 * pressure + noise, 0, 1)
+
+    def mobilization_fn(parents, noise):
+        stability = parents.get('domestic_stability', np.zeros(1))[0]
+        return np.clip(0.3 - 0.7 * stability + noise, 0, 1)
+
+    def conflict_fn(parents, noise):
+        mobilization = parents.get('military_mobilization', np.zeros(1))[0]
+        sanctions = parents.get('economic_sanctions', np.zeros(1))[0]
+        return np.clip(0.8 * mobilization + 0.4 * sanctions + noise, 0, 1)
+
+    # Set functions
+    from scipy import stats
+    scm.set_function('economic_sanctions', sanctions_fn, stats.norm(0, 0.1))
+    scm.set_function('diplomatic_pressure', pressure_fn, stats.norm(0, 0.1))
+    scm.set_function('domestic_stability', stability_fn, stats.norm(0, 0.05))
+    scm.set_function('military_mobilization', mobilization_fn, stats.norm(0, 0.05))
+    scm.set_function('conflict_probability', conflict_fn, stats.norm(0, 0.05))
+
+    print("   Structural equations defined")
+
+    return scm
+
+
+def simulate_baseline(simulator):
+    """Simulate baseline (no intervention) scenario."""
+    print("\n2. Simulating Baseline Scenario...")
+
+    baseline = simulator.simulate_intervention(
+        intervention={},
+        n_samples=1000,
+        outcomes=['conflict_probability']
+    )
+
+    conflict_mean = np.mean(baseline['conflict_probability'])
+    conflict_std = np.std(baseline['conflict_probability'])
+
+    print(f"   Baseline conflict probability: {conflict_mean:.3f} ± {conflict_std:.3f}")
+
+    return baseline
+
+
+def simulate_interventions(simulator):
+    """Simulate different policy interventions."""
+    print("\n3. Simulating Policy Interventions...")
+
+    interventions = [
+        {'economic_sanctions': 0.8, 'diplomatic_pressure': 0.3},  # Heavy sanctions
+        {'economic_sanctions': 0.3, 'diplomatic_pressure': 0.8},  # Heavy diplomacy
+        {'economic_sanctions': 0.6, 'diplomatic_pressure': 0.6},  # Balanced approach
+    ]
+
+    intervention_names = [
+        "Heavy Sanctions",
+        "Heavy Diplomacy",
+        "Balanced Approach"
+    ]
+
+    results = simulator.compare_interventions(
+        interventions,
+        outcome='conflict_probability',
+        n_samples=1000
+    )
+
+    print("\n   Intervention Results:")
+    print("   " + "-" * 60)
+
+    for i, name in enumerate(intervention_names):
+        result = results[f'intervention_{i}']
+        print(f"\n   {name}:")
+        print(f"     Mean conflict probability: {result['mean']:.3f}")
+        print(f"     Std deviation: {result['std']:.3f}")
+        print(f"     95% CI: [{result['q25']:.3f}, {result['q75']:.3f}]")
+
+    return results
+
+
+def find_optimal_intervention(simulator):
+    """Find optimal intervention to minimize conflict."""
+    print("\n4. Finding Optimal Intervention...")
+
+    optimal = simulator.optimal_intervention(
+        target_var='conflict_probability',
+        intervention_vars=['economic_sanctions', 'diplomatic_pressure'],
+        intervention_ranges={
+            'economic_sanctions': (0.0, 1.0),
+            'diplomatic_pressure': (0.0, 1.0)
+        },
+        objective='minimize',
+        n_trials=50,
+        n_samples=1000
+    )
+
+    print(f"\n   Optimal intervention found:")
+    print(f"     Economic Sanctions: {optimal['optimal_intervention']['economic_sanctions']:.3f}")
+    print(f"     Diplomatic Pressure: {optimal['optimal_intervention']['diplomatic_pressure']:.3f}")
+    print(f"     Expected conflict probability: {optimal['optimal_value']:.3f}")
+
+    return optimal
+
+
+def counterfactual_analysis(simulator):
+    """Perform counterfactual analysis."""
+    print("\n5. Counterfactual Analysis...")
+
+    # Observed scenario
+    observed = {
+        'economic_sanctions': 0.7,
+        'diplomatic_pressure': 0.2,
+        'domestic_stability': 0.4,
+        'military_mobilization': 0.6,
+        'conflict_probability': 0.65
+    }
+
+    print("\n   Observed scenario:")
+    print(f"     Sanctions: {observed['economic_sanctions']}")
+    print(f"     Diplomacy: {observed['diplomatic_pressure']}")
+    print(f"     Conflict: {observed['conflict_probability']}")
+
+    # Counterfactual: What if we had used more diplomacy?
+    counterfactual_intervention = {
+        'diplomatic_pressure': 0.8,
+        'economic_sanctions': 0.3
+    }
+
+    result = simulator.counterfactual_analysis(
+        observed=observed,
+        intervention=counterfactual_intervention,
+        outcome='conflict_probability'
+    )
+
+    print("\n   Counterfactual: 'What if we had emphasized diplomacy?'")
+    print(f"     Counterfactual conflict: {result['counterfactual_outcome']:.3f}")
+    print(f"     Effect of intervention: {result['effect']:.3f}")
+
+    if result['effect'] < 0:
+        print(f"     Conclusion: Diplomacy would have REDUCED conflict by {abs(result['effect']):.3f}")
+    else:
+        print(f"     Conclusion: Diplomacy would have INCREASED conflict by {result['effect']:.3f}")
+
+
+def main():
+    print("=" * 80)
+    print("GeoBotv1 - Intervention Simulation & Counterfactual Analysis")
+    print("=" * 80)
+    print("\nThis example demonstrates answering 'what if' questions:")
+    print("- 'What if the U.S. increases sanctions?'")
+    print("- 'What if we emphasize diplomacy over sanctions?'")
+    print("- 'What is the optimal policy mix?'")
+    print("- 'What would have happened if we had acted differently?'")
+
+    # Create SCM
+    scm = create_geopolitical_scm()
+
+    # Create intervention simulator
+    simulator = InterventionSimulator(scm)
+
+    # Run analyses
+    baseline = simulate_baseline(simulator)
+    interventions = simulate_interventions(simulator)
+    optimal = find_optimal_intervention(simulator)
+    counterfactual_analysis(simulator)
+
+    print("\n" + "=" * 80)
+    print("Key Insights:")
+    print("=" * 80)
+    print("\n1. Different interventions have different effects on conflict probability")
+    print("2. Optimal policy can be discovered through systematic search")
+    print("3. Counterfactual reasoning enables learning from alternative scenarios")
+    print("4. Causal models enable principled 'what if' analysis")
+
+    print("\n" + "=" * 80)
+    print("Example completed successfully!")
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

examples/04_advanced_features.py

@@ -0,0 +1,348 @@
+"""
+Example 4: Advanced Mathematical Features
+
+This example demonstrates the research-grade advanced features:
+- Sequential Monte Carlo (particle filtering)
+- Variational Inference
+- Stochastic Differential Equations (SDEs)
+- Gradient-based Optimal Transport
+- Kantorovich Duality
+- Event Extraction and Database
+- Continuous-time dynamics
+
+These features enable measure-theoretic, rigorous forecasting.
+"""
+
+import numpy as np
+import sys
+sys.path.append('..')
+
+from datetime import datetime, timedelta
+from scipy import stats
+
+# Advanced inference
+from geobot.inference.particle_filter import SequentialMonteCarlo
+from geobot.inference.variational_inference import VariationalInference
+
+# SDE solvers
+from geobot.simulation.sde_solver import (
+    EulerMaruyama,
+    Milstein,
+    JumpDiffusionProcess,
+    GeopoliticalSDE
+)
+
+# Advanced optimal transport
+from geobot.core.advanced_optimal_transport import (
+    KantorovichDuality,
+    EntropicOT,
+    GradientBasedOT
+)
+
+# Event extraction
+from geobot.data_ingestion.event_extraction import EventExtractor, EventType
+from geobot.data_ingestion.event_database import EventDatabase
+
+
+def demo_particle_filter():
+    """Demonstrate Sequential Monte Carlo / Particle Filter."""
+    print("\n" + "="*80)
+    print("1. Sequential Monte Carlo (Particle Filter)")
+    print("="*80)
+
+    # Define nonlinear dynamics
+    def dynamics_fn(x, noise):
+        # Nonlinear geopolitical dynamics
+        # x[0] = tension, x[1] = stability
+        tension = x[0]
+        stability = x[1]
+
+        new_tension = tension + 0.1 * (1 - stability) + noise[0]
+        new_stability = stability - 0.05 * tension + noise[1]
+
+        return np.array([
+            np.clip(new_tension, 0, 1),
+            np.clip(new_stability, 0, 1)
+        ])
+
+    def observation_fn(y, x):
+        # Log-likelihood of observation given state
+        # Observe tension with noise
+        predicted = x[0]
+        return stats.norm.logpdf(y[0], loc=predicted, scale=0.1)
+
+    # Create particle filter
+    pf = SequentialMonteCarlo(
+        n_particles=500,
+        state_dim=2,
+        dynamics_fn=dynamics_fn,
+        observation_fn=observation_fn
+    )
+
+    # Initialize from prior
+    pf.initialize_from_prior(lambda: np.array([0.3, 0.7]))
+
+    # Generate synthetic observations
+    observations = np.array([
+        [0.35], [0.40], [0.45], [0.50], [0.55],
+        [0.60], [0.65], [0.70], [0.75], [0.80]
+    ])
+
+    print(f"\nRunning particle filter with {pf.n_particles} particles...")
+    print("Tracking hidden geopolitical state from noisy observations\n")
+
+    # Filter
+    states = pf.filter(observations)
+
+    # Show results
+    for i, state in enumerate(states[-5:]):  # Last 5 steps
+        mean, cov = pf.get_state_estimate()
+        print(f"Step {i+6}: Tension={mean[0]:.3f}±{np.sqrt(cov[0,0]):.3f}, "
+              f"Stability={mean[1]:.3f}±{np.sqrt(cov[1,1]):.3f}, "
+              f"ESS={state.ess:.1f}")
+
+    print("\n✓ Particle filter successfully tracked nonlinear hidden states!")
+
+
+def demo_sde_solver():
+    """Demonstrate Stochastic Differential Equations."""
+    print("\n" + "="*80)
+    print("2. Stochastic Differential Equations (Continuous-Time Dynamics)")
+    print("="*80)
+
+    # Define SDE: dx = f(x,t)dt + g(x,t)dW
+    def drift(x, t):
+        # Mean-reverting to 0.5 (long-term stability)
+        return 0.2 * (0.5 - x)
+
+    def diffusion(x, t):
+        # Volatility increases with tension
+        return 0.1 * (1 + x)
+
+    # Create SDE solver
+    solver = EulerMaruyama(
+        drift=drift,
+        diffusion=diffusion,
+        x0=np.array([0.7]),  # Start with high tension
+        t0=0.0
+    )
+
+    print("\nSimulating continuous-time geopolitical tension dynamics...")
+    print("SDE: dx = 0.2(0.5 - x)dt + 0.1(1 + x)dW\n")
+
+    # Integrate
+    solution = solver.integrate(T=10.0, dt=0.01, n_paths=5)
+
+    # Show statistics
+    final_values = solution.x[:, -1, 0]
+    print(f"After T=10.0 time units:")
+    print(f"  Mean tension: {np.mean(final_values):.3f}")
+    print(f"  Std deviation: {np.std(final_values):.3f}")
+    print(f"  Min/Max: [{np.min(final_values):.3f}, {np.max(final_values):.3f}]")
+
+    print("\n✓ SDE solver successfully simulated continuous-time dynamics!")
+
+
+def demo_jump_diffusion():
+    """Demonstrate Jump-Diffusion Process."""
+    print("\n" + "="*80)
+    print("3. Jump-Diffusion Process (Modeling Black Swan Events)")
+    print("="*80)
+
+    # Create jump-diffusion process
+    jdp = JumpDiffusionProcess(
+        drift=0.05,  # Slow drift
+        diffusion=0.1,  # Normal volatility
+        jump_intensity=0.5,  # 0.5 jumps per unit time (on average)
+        jump_mean=-0.2,  # Negative jumps (crises)
+        jump_std=0.1,
+        x0=np.array([0.5])
+    )
+
+    print("\nSimulating conflict escalation with discrete shock events...")
+    print("Model: Continuous diffusion + Poisson jumps (λ=0.5, μ=-0.2)\n")
+
+    # Simulate
+    solution = jdp.simulate(T=20.0, dt=0.1, n_paths=3)
+
+    # Count jumps (approximately)
+    for path in range(3):
+        # Detect jumps as large changes
+        diffs = np.diff(solution.x[path, :, 0])
+        n_jumps = np.sum(np.abs(diffs) > 0.15)
+        final_value = solution.x[path, -1, 0]
+        print(f"Path {path+1}: {n_jumps} jumps detected, Final value: {final_value:.3f}")
+
+    print("\n✓ Jump-diffusion successfully modeled rare shock events!")
+
+
+def demo_kantorovich_duality():
+    """Demonstrate Kantorovich Duality."""
+    print("\n" + "="*80)
+    print("4. Kantorovich Duality (Optimal Transport Theory)")
+    print("="*80)
+
+    # Create two distributions (scenarios)
+    n, m = 10, 10
+    mu = np.ones(n) / n  # Uniform source
+    nu = np.ones(m) / m  # Uniform target
+
+    # Cost matrix (Euclidean distance)
+    X_source = np.random.rand(n, 2)
+    X_target = np.random.rand(m, 2) + np.array([0.5, 0.5])  # Shifted
+    from scipy.spatial.distance import cdist
+    C = cdist(X_source, X_target, metric='sqeuclidean')
+
+    # Solve primal and dual
+    kantorovich = KantorovichDuality()
+
+    print("\nComputing optimal transport between two geopolitical scenarios...")
+    print(f"Source: {n} points, Target: {m} points\n")
+
+    # Primal solution
+    coupling, primal_cost = kantorovich.solve_primal(mu, nu, C, method='emd')
+    print(f"Primal optimal cost: {primal_cost:.6f}")
+
+    # Dual solution
+    f, g, dual_value = kantorovich.solve_dual(mu, nu, C, max_iter=100)
+    print(f"Dual optimal value: {dual_value:.6f}")
+
+    # Verify duality gap
+    gap = kantorovich.verify_duality_gap(mu, nu, C)
+    print(f"Duality gap: {gap:.8f} (should be ≈ 0)")
+
+    if abs(gap) < 1e-4:
+        print("\n✓ Strong duality verified! Primal = Dual")
+    else:
+        print("\n⚠ Duality gap present (numerical approximation)")
+
+
+def demo_entropic_ot():
+    """Demonstrate Entropic Optimal Transport (Sinkhorn)."""
+    print("\n" + "="*80)
+    print("5. Entropic Optimal Transport (Sinkhorn Algorithm)")
+    print("="*80)
+
+    # Create distributions
+    n, m = 20, 20
+    mu = np.random.dirichlet(np.ones(n))  # Random distribution
+    nu = np.random.dirichlet(np.ones(m))
+
+    # Cost matrix
+    X = np.random.rand(n, 2)
+    Y = np.random.rand(m, 2)
+    from scipy.spatial.distance import cdist
+    C = cdist(X, Y, metric='euclidean')
+
+    # Entropic OT with different regularization
+    epsilons = [0.01, 0.05, 0.1]
+
+    print("\nComparing regularization levels for Sinkhorn algorithm...\n")
+
+    for eps in epsilons:
+        eot = EntropicOT(epsilon=eps)
+        coupling, cost = eot.sinkhorn(mu, nu, C, max_iter=500)
+
+        print(f"ε = {eps:0.2f}: Cost = {cost:.6f}, "
+              f"Entropy = {-np.sum(coupling * np.log(coupling + 1e-10)):.4f}")
+
+    print("\n✓ Entropic OT computed with fast Sinkhorn iterations!")
+
+
+def demo_event_extraction():
+    """Demonstrate Event Extraction Pipeline."""
+    print("\n" + "="*80)
+    print("6. Structured Event Extraction from Intelligence")
+    print("="*80)
+
+    # Sample intelligence text
+    intelligence_text = """
+    On March 15, 2024, tensions escalated between the United States and China
+    following a major military mobilization in the Taiwan Strait. NATO issued
+    a statement expressing concern. Russia announced sanctions on European Union
+    member states. India maintained diplomatic neutrality while calling for
+    de-escalation talks.
+
+    The United Nations Security Council convened an emergency session on March 16,
+    2024. Economic sanctions were proposed against China by the United States,
+    but Russia exercised its veto power.
+    """
+
+    # Extract events
+    extractor = EventExtractor()
+
+    print("\nExtracting structured events from intelligence report...\n")
+    print("Input text:")
+    print("-" * 60)
+    print(intelligence_text[:200] + "...")
+    print("-" * 60)
+
+    events = extractor.extract_events(
+        intelligence_text,
+        source="intel_report_001",
+        default_timestamp=datetime(2024, 3, 15)
+    )
+
+    print(f"\n✓ Extracted {len(events)} geopolitical events:")
+    print()
+
+    for i, event in enumerate(events):
+        print(f"Event {i+1}:")
+        print(f"  Type: {event.event_type.value}")
+        print(f"  Actors: {', '.join(event.actors)}")
+        print(f"  Magnitude: {event.magnitude:.2f}")
+        print(f"  Timestamp: {event.timestamp.date()}")
+        print()
+
+    # Store in database
+    print("Storing events in database...")
+    with EventDatabase("demo_events.db") as db:
+        db.insert_events(events)
+
+        # Query back
+        conflict_events = db.query_events(
+            event_types=[EventType.CONFLICT, EventType.MILITARY_MOBILIZATION]
+        )
+
+        print(f"✓ Database contains {len(conflict_events)} conflict-related events")
+
+    print("\n✓ Event extraction and storage pipeline operational!")
+
+
+def main():
+    """Run all advanced feature demonstrations."""
+    print("=" * 80)
+    print("GeoBotv1 - Advanced Mathematical Features Demonstration")
+    print("=" * 80)
+    print("\nThis example showcases research-grade capabilities:")
+    print("• Sequential Monte Carlo (particle filtering)")
+    print("• Stochastic Differential Equations")
+    print("• Jump-Diffusion Processes")
+    print("• Kantorovich Duality in Optimal Transport")
+    print("• Entropic OT with Sinkhorn")
+    print("• Structured Event Extraction")
+
+    # Run demonstrations
+    demo_particle_filter()
+    demo_sde_solver()
+    demo_jump_diffusion()
+    demo_kantorovich_duality()
+    demo_entropic_ot()
+    demo_event_extraction()
+
+    print("\n" + "=" * 80)
+    print("All Advanced Features Demonstrated Successfully!")
+    print("=" * 80)
+    print("\nKey Insights:")
+    print("1. Particle filters handle nonlinear/non-Gaussian state estimation")
+    print("2. SDEs model continuous-time geopolitical dynamics rigorously")
+    print("3. Jump-diffusion captures both gradual change and sudden shocks")
+    print("4. Kantorovich duality provides theoretical foundation for OT")
+    print("5. Entropic OT enables fast computation via Sinkhorn")
+    print("6. Event extraction creates structured data for causal modeling")
+
+    print("\n" + "="*80)
+
+
+if __name__ == "__main__":
+    main()

examples/05_complete_framework.py

@@ -0,0 +1,542 @@
+"""
+Example 5: Complete GeoBotv1 Framework - Final Features
+
+This example demonstrates the final critical components that complete GeoBotv1
+to 100% research-grade capability:
+
+1. Vector Autoregression (VAR/SVAR/DFM) - Econometric time-series analysis
+2. Hawkes Processes - Conflict contagion and self-exciting dynamics
+3. Quasi-Experimental Methods - Causal inference without randomization
+   - Synthetic Control Method (SCM)
+   - Difference-in-Differences (DiD)
+   - Regression Discontinuity Design (RDD)
+   - Instrumental Variables (IV)
+
+These methods are essential for:
+- Multi-country forecasting with spillovers (VAR)
+- Modeling conflict escalation and contagion (Hawkes)
+- Estimating policy effects and counterfactuals (quasi-experimental)
+
+GeoBotv1 is now COMPLETE with all research-grade mathematical components!
+"""
+
+import numpy as np
+import sys
+sys.path.append('..')
+
+from datetime import datetime, timedelta
+
+# Time-series models
+from geobot.timeseries import (
+    VARModel,
+    SVARModel,
+    DynamicFactorModel,
+    GrangerCausality,
+    UnivariateHawkesProcess,
+    MultivariateHawkesProcess,
+    ConflictContagionModel
+)
+
+# Quasi-experimental methods
+from geobot.models import (
+    SyntheticControlMethod,
+    DifferenceinDifferences,
+    RegressionDiscontinuity,
+    InstrumentalVariables
+)
+
+
+def demo_var_model():
+    """Demonstrate Vector Autoregression for multi-country forecasting."""
+    print("\n" + "="*80)
+    print("1. Vector Autoregression (VAR) - Multi-Country Spillovers")
+    print("="*80)
+
+    # Simulate data for 3 countries
+    # Country dynamics with interdependencies
+    np.random.seed(42)
+    T = 100
+    n_vars = 3
+
+    # Generate VAR(2) data
+    # Y_t = A_1 Y_{t-1} + A_2 Y_{t-2} + noise
+    A1 = np.array([
+        [0.5, 0.2, 0.1],   # Country 1: affected by all
+        [0.1, 0.6, 0.15],  # Country 2: strong self-dependence
+        [0.05, 0.1, 0.55]  # Country 3: weak spillovers
+    ])
+    A2 = np.array([
+        [0.2, 0.05, 0.0],
+        [0.1, 0.1, 0.05],
+        [0.0, 0.05, 0.2]
+    ])
+
+    # Simulate
+    data = np.zeros((T, n_vars))
+    data[0] = np.random.randn(n_vars) * 0.1
+    data[1] = np.random.randn(n_vars) * 0.1
+
+    for t in range(2, T):
+        data[t] = (A1 @ data[t-1] + A2 @ data[t-2] +
+                   np.random.randn(n_vars) * 0.1)
+
+    print(f"\nSimulated {T} time periods for {n_vars} countries")
+    print(f"Variables: GDP growth, Military spending, Stability index\n")
+
+    # Fit VAR model
+    var = VARModel(n_lags=2)
+    variable_names = ['GDP_growth', 'Military_spend', 'Stability']
+    results = var.fit(data, variable_names)
+
+    print(f"VAR({results.n_lags}) Estimation Results:")
+    print(f"  Log-likelihood: {results.log_likelihood:.2f}")
+    print(f"  AIC: {results.aic:.2f}")
+    print(f"  BIC: {results.bic:.2f}")
+
+    # Forecast
+    forecast = var.forecast(results, steps=10)
+    print(f"\n10-step ahead forecast:")
+    print(f"  GDP growth: {forecast[-1, 0]:.3f}")
+    print(f"  Military spending: {forecast[-1, 1]:.3f}")
+    print(f"  Stability: {forecast[-1, 2]:.3f}")
+
+    # Granger causality
+    print("\nGranger Causality Tests:")
+    for i in range(n_vars):
+        for j in range(n_vars):
+            if i != j:
+                gc_result = var.granger_causality(results, i, j)
+                if gc_result['p_value'] < 0.05:
+                    print(f"  {variable_names[j]} → {variable_names[i]}: "
+                          f"F={gc_result['f_statistic']:.2f}, p={gc_result['p_value']:.3f} ✓")
+
+    # Impulse response functions
+    irf_result = var.impulse_response(results, steps=10)
+    print("\nImpulse Response Functions computed (10 steps)")
+    print(f"  Shock to Military spending → GDP growth at t=5: {irf_result.irf[0, 1, 5]:.4f}")
+
+    # Forecast error variance decomposition
+    fevd = var.forecast_error_variance_decomposition(results, steps=10)
+    print("\nForecast Error Variance Decomposition (horizon=10):")
+    for i, var_name in enumerate(variable_names):
+        contributions = fevd[i, :, -1]
+        print(f"  {var_name} variance explained by:")
+        for j, source_name in enumerate(variable_names):
+            print(f"    {source_name}: {contributions[j]:.1%}")
+
+    print("\n✓ VAR model demonstrates multi-country interdependencies!")
+
+
+def demo_hawkes_process():
+    """Demonstrate Hawkes processes for conflict contagion."""
+    print("\n" + "="*80)
+    print("2. Hawkes Processes - Conflict Escalation and Contagion")
+    print("="*80)
+
+    # Simulate conflict events
+    print("\nSimulating conflict events with self-excitation...")
+    hawkes = UnivariateHawkesProcess()
+
+    # Parameters: baseline=0.3, excitation=0.6, decay=1.2
+    # Branching ratio = 0.6/1.2 = 0.5 (stable, subcritical)
+    events = hawkes.simulate(mu=0.3, alpha=0.6, beta=1.2, T=100.0)
+
+    print(f"Generated {len(events)} conflict events over 100 time units")
+    print(f"Average rate: {len(events) / 100.0:.2f} events/unit\n")
+
+    # Fit model
+    result = hawkes.fit(events, T=100.0)
+
+    print("Estimated Hawkes Parameters:")
+    print(f"  Baseline intensity (μ): {result.params.mu:.3f}")
+    print(f"  Excitation (α): {result.params.alpha:.3f}")
+    print(f"  Decay rate (β): {result.params.beta:.3f}")
+    print(f"  Branching ratio: {result.params.branching_ratio:.3f}")
+    print(f"  Process is {'STABLE' if result.params.is_stable else 'EXPLOSIVE'}")
+
+    # Predict intensity
+    t_future = 105.0
+    intensity = hawkes.predict_intensity(events, result.params, t_future)
+    print(f"\nPredicted conflict intensity at t={t_future}: {intensity:.3f}")
+
+    # Multivariate: conflict contagion between countries
+    print("\n" + "-"*80)
+    print("Multivariate Hawkes: Cross-Country Conflict Contagion")
+    print("-"*80)
+
+    countries = ['Syria', 'Iraq', 'Lebanon']
+    contagion_model = ConflictContagionModel(countries=countries)
+
+    # Simulate with cross-excitation
+    mu = np.array([0.5, 0.3, 0.2])  # Different baseline rates
+    alpha = np.array([
+        [0.3, 0.15, 0.1],   # Syria: high self-excitation, moderate contagion
+        [0.2, 0.25, 0.1],   # Iraq: affected by Syria
+        [0.15, 0.1, 0.2]    # Lebanon: affected by both
+    ])
+    beta = np.ones((3, 3)) * 1.5
+
+    multi_hawkes = MultivariateHawkesProcess(n_dimensions=3)
+    events_multi = multi_hawkes.simulate(mu=mu, alpha=alpha, beta=beta, T=100.0)
+
+    print(f"\nSimulated events:")
+    for i, country in enumerate(countries):
+        print(f"  {country}: {len(events_multi[i])} events")
+
+    # Fit multivariate model
+    events_dict = {country: events_multi[i] for i, country in enumerate(countries)}
+    fit_result = contagion_model.fit(events_dict, T=100.0)
+
+    print(f"\nFitted contagion model:")
+    print(f"  Spectral radius: {fit_result['spectral_radius']:.3f} (< 1 = stable)")
+    print(f"  Most contagious source: {fit_result['most_contagious_source']}")
+    print(f"  Most vulnerable target: {fit_result['most_vulnerable_target']}")
+
+    # Identify contagion pathways
+    pathways = contagion_model.identify_contagion_pathways(fit_result, threshold=0.1)
+    print("\nSignificant contagion pathways (branching ratio > 0.1):")
+    for source, target, strength in pathways[:5]:
+        print(f"  {source} → {target}: {strength:.3f}")
+
+    # Risk assessment
+    risks = contagion_model.contagion_risk(events_dict, fit_result, t=105.0, horizon=5.0)
+    print("\nConflict risk over next 5 time units:")
+    for country, risk in risks.items():
+        print(f"  {country}: {risk:.1%}")
+
+    print("\n✓ Hawkes processes capture conflict escalation dynamics!")
+
+
+def demo_synthetic_control():
+    """Demonstrate Synthetic Control Method."""
+    print("\n" + "="*80)
+    print("3. Synthetic Control Method - Policy Impact Estimation")
+    print("="*80)
+
+    # Scenario: Estimate effect of sanctions on target country's GDP
+    print("\nScenario: Economic sanctions imposed on Country A at t=50")
+    print("Question: What is the causal effect on GDP growth?\n")
+
+    # Generate data
+    np.random.seed(42)
+    T = 100
+    J = 10  # 10 control countries
+
+    # Pre-treatment: all countries follow similar trends
+    time = np.arange(T)
+    trend = 0.02 * time + np.random.randn(T) * 0.1
+
+    # Control countries
+    control_outcomes = np.zeros((T, J))
+    for j in range(J):
+        control_outcomes[:, j] = trend + np.random.randn(T) * 0.15 + np.random.randn() * 0.5
+
+    # Treated country (matches controls pre-treatment)
+    treated_outcome = trend + np.random.randn(T) * 0.15
+
+    # Treatment effect: negative shock starting at t=50
+    treatment_time = 50
+    true_effect = -0.8
+    treated_outcome[treatment_time:] += true_effect + np.random.randn(T - treatment_time) * 0.1
+
+    # Fit SCM
+    scm = SyntheticControlMethod()
+    result = scm.fit(
+        treated_outcome=treated_outcome,
+        control_outcomes=control_outcomes,
+        treatment_time=treatment_time,
+        control_names=[f"Country_{j+1}" for j in range(J)]
+    )
+
+    print("Synthetic Control Results:")
+    print(f"  Pre-treatment fit (RMSPE): {result.pre_treatment_fit:.4f}")
+    print(f"\nSynthetic Country A is weighted combination of:")
+    for j, weight in enumerate(result.weights):
+        if weight > 0.01:  # Only show significant weights
+            print(f"    {result.control_units[j]}: {weight:.1%}")
+
+    # Treatment effects
+    avg_effect = np.mean(result.treatment_effect[treatment_time:])
+    print(f"\nEstimated treatment effect (post-sanctions):")
+    print(f"  Average: {avg_effect:.3f} (true effect: {true_effect:.3f})")
+    print(f"  Final period: {result.treatment_effect[-1]:.3f}")
+
+    # Placebo test
+    p_value = scm.placebo_test(treated_outcome, control_outcomes, treatment_time, n_permutations=J)
+    print(f"\nPlacebo test p-value: {p_value:.3f}")
+    if p_value < 0.05:
+        print("  ✓ Effect is statistically significant (unusual compared to placebos)")
+    else:
+        print("  ✗ Effect not significant (could be random)")
+
+    print("\n✓ Synthetic control provides credible counterfactual!")
+
+
+def demo_difference_in_differences():
+    """Demonstrate Difference-in-Differences."""
+    print("\n" + "="*80)
+    print("4. Difference-in-Differences (DiD) - Regime Change Analysis")
+    print("="*80)
+
+    # Scenario: Regime change in treated country
+    print("\nScenario: Regime change in Country T at t=50")
+    print("Compare to similar countries without regime change\n")
+
+    np.random.seed(42)
+
+    # Pre-treatment (similar trends)
+    treated_pre = 3.0 + np.random.randn(50) * 0.5
+    control_pre = 3.2 + np.random.randn(50) * 0.5
+
+    # Post-treatment (treatment effect = +1.5 on outcome)
+    true_effect = 1.5
+    treated_post = 3.0 + true_effect + np.random.randn(50) * 0.5
+    control_post = 3.2 + np.random.randn(50) * 0.5  # No effect
+
+    # Estimate DiD
+    did = DifferenceinDifferences()
+    result = did.estimate(treated_pre, treated_post, control_pre, control_post)
+
+    print("Difference-in-Differences Results:")
+    print(f"\n  Pre-treatment difference: {result.pre_treatment_diff:.3f}")
+    print(f"  Post-treatment difference: {result.post_treatment_diff:.3f}")
+    print(f"\n  Average Treatment Effect (ATT): {result.att:.3f}")
+    print(f"  Standard error: {result.se:.3f}")
+    print(f"  t-statistic: {result.t_stat:.3f}")
+    print(f"  p-value: {result.p_value:.4f}")
+
+    if result.p_value < 0.05:
+        print(f"\n  ✓ Regime change had significant effect (true effect: {true_effect:.3f})")
+    else:
+        print("\n  ✗ Effect not statistically significant")
+
+    # Assumption check
+    if abs(result.pre_treatment_diff) < 0.5:
+        print("\n  ✓ Parallel trends assumption plausible (small pre-treatment diff)")
+    else:
+        print("\n  ⚠ Parallel trends questionable (large pre-treatment diff)")
+
+    print("\n✓ DiD isolates causal effect of regime change!")
+
+
+def demo_regression_discontinuity():
+    """Demonstrate Regression Discontinuity Design."""
+    print("\n" + "="*80)
+    print("5. Regression Discontinuity Design (RDD) - Election Effects")
+    print("="*80)
+
+    # Scenario: Effect of winning election on military policy
+    print("\nScenario: Effect of hawkish candidate winning election")
+    print("Running variable: Vote share (cutoff = 50%)")
+    print("Outcome: Military spending increase\n")
+
+    np.random.seed(42)
+    n = 500
+
+    # Vote share (running variable)
+    vote_share = np.random.uniform(0.3, 0.7, n)
+
+    # Outcome: military spending
+    # Smooth function of vote share + discontinuity at 50%
+    outcome = 2.0 + 1.5 * vote_share + np.random.randn(n) * 0.3
+
+    # Treatment effect: +0.8 if vote > 50%
+    true_effect = 0.8
+    outcome[vote_share >= 0.5] += true_effect
+
+    # Estimate RDD
+    rdd = RegressionDiscontinuity(cutoff=0.5)
+    result = rdd.estimate_sharp(
+        running_var=vote_share,
+        outcome=outcome,
+        bandwidth=0.15,  # 15% bandwidth
+        kernel='triangular'
+    )
+
+    print("Regression Discontinuity Results:")
+    print(f"\n  Bandwidth: {result.bandwidth:.3f}")
+    print(f"  Observations below cutoff: {result.n_left}")
+    print(f"  Observations above cutoff: {result.n_right}")
+    print(f"\n  Treatment effect (LATE): {result.treatment_effect:.3f}")
+    print(f"  Standard error: {result.se:.3f}")
+    print(f"  t-statistic: {result.t_stat:.3f}")
+    print(f"  p-value: {result.p_value:.4f}")
+
+    if result.p_value < 0.05:
+        print(f"\n  ✓ Winning election causes increase in military spending")
+        print(f"    (true effect: {true_effect:.3f})")
+    else:
+        print("\n  ✗ Effect not statistically significant")
+
+    print("\n✓ RDD exploits threshold-based treatment assignment!")
+
+
+def demo_instrumental_variables():
+    """Demonstrate Instrumental Variables."""
+    print("\n" + "="*80)
+    print("6. Instrumental Variables (IV) - Trade and Conflict")
+    print("="*80)
+
+    # Scenario: Effect of trade on conflict (trade is endogenous)
+    print("\nScenario: Does trade reduce conflict?")
+    print("Problem: Trade is endogenous (reverse causality, omitted variables)")
+    print("Instrument: Geographic distance to major trade routes\n")
+
+    np.random.seed(42)
+    n = 300
+
+    # Instrument: distance (exogenous)
+    distance = np.random.uniform(100, 1000, n)
+
+    # Unobserved confounders
+    unobserved = np.random.randn(n)
+
+    # Trade (endogenous): affected by distance and confounders
+    trade = 50 - 0.03 * distance + 2.0 * unobserved + np.random.randn(n) * 5
+
+    # Conflict: true effect of trade = -0.15, but also affected by confounders
+    true_effect = -0.15
+    conflict = 10 + true_effect * trade - 1.5 * unobserved + np.random.randn(n) * 2
+
+    # Estimate with IV
+    iv = InstrumentalVariables()
+    result = iv.estimate_2sls(
+        outcome=conflict,
+        endogenous=trade,
+        instrument=distance
+    )
+
+    print("Instrumental Variables (2SLS) Results:")
+    print(f"\n  First stage F-statistic: {result.first_stage_f:.2f}")
+    if result.weak_instrument:
+        print("  ⚠ Warning: Weak instrument (F < 10)")
+    else:
+        print("  ✓ Strong instrument (F > 10)")
+
+    print(f"\n  OLS estimate (biased): {result.beta_ols[0]:.4f}")
+    print(f"  IV estimate (consistent): {result.beta_iv[0]:.4f}")
+    print(f"  IV standard error: {result.se_iv[0]:.4f}")
+    print(f"\n  True causal effect: {true_effect:.4f}")
+
+    # Hausman test (informal)
+    if abs(result.beta_ols[0] - result.beta_iv[0]) > 0.05:
+        print("\n  ✓ OLS and IV differ substantially → endogeneity present")
+        print("    IV corrects for bias!")
+    else:
+        print("\n  OLS and IV similar → endogeneity may be small")
+
+    print("\n✓ IV isolates causal effect using exogenous variation!")
+
+
+def demo_dynamic_factor_model():
+    """Demonstrate Dynamic Factor Model for nowcasting."""
+    print("\n" + "="*80)
+    print("7. Dynamic Factor Model (DFM) - High-Dimensional Nowcasting")
+    print("="*80)
+
+    # Scenario: Nowcast geopolitical tension from many indicators
+    print("\nScenario: Nowcast regional tension from 50 economic/political indicators")
+    print("DFM extracts common latent factors driving all indicators\n")
+
+    np.random.seed(42)
+    T = 200
+    n_indicators = 50
+    n_factors = 3
+
+    # True factors (latent tensions)
+    true_factors = np.zeros((T, n_factors))
+    for k in range(n_factors):
+        # AR(1) dynamics
+        for t in range(1, T):
+            true_factors[t, k] = 0.8 * true_factors[t-1, k] + np.random.randn() * 0.5
+
+    # Factor loadings (how indicators load on factors)
+    true_loadings = np.random.randn(n_indicators, n_factors)
+
+    # Observed indicators = factors * loadings + idiosyncratic noise
+    data = true_factors @ true_loadings.T + np.random.randn(T, n_indicators) * 0.5
+
+    # Fit DFM
+    dfm = DynamicFactorModel(n_factors=3, n_lags=1)
+    model = dfm.fit(data)
+
+    print(f"Dynamic Factor Model Results:")
+    print(f"\n  Number of indicators: {n_indicators}")
+    print(f"  Number of factors: {n_factors}")
+    print(f"  Explained variance: {model['explained_variance_ratio']:.1%}")
+
+    # Extracted factors
+    factors = model['factors']
+    print(f"\n  Extracted factor dimensions: {factors.shape}")
+    print(f"  Factor 1 final value: {factors[-1, 0]:.3f}")
+    print(f"  Factor 2 final value: {factors[-1, 1]:.3f}")
+    print(f"  Factor 3 final value: {factors[-1, 2]:.3f}")
+
+    # Forecast
+    forecast = dfm.forecast(model, steps=10)
+    print(f"\n  10-step ahead forecast dimensions: {forecast.shape}")
+    print(f"  Average forecasted indicator value: {np.mean(forecast[-1]):.3f}")
+
+    # Correlation with true factors
+    corr_0 = np.corrcoef(true_factors[:, 0], factors[:, 0])[0, 1]
+    print(f"\n  Factor recovery (correlation with true): {abs(corr_0):.3f}")
+
+    print("\n✓ DFM reduces dimensionality while preserving information!")
+
+
+def main():
+    """Run all demonstrations of final features."""
+    print("=" * 80)
+    print("GeoBotv1 - COMPLETE FRAMEWORK DEMONSTRATION")
+    print("=" * 80)
+    print("\nThis example showcases the final components that complete GeoBotv1:")
+    print("• Vector Autoregression (VAR/SVAR/DFM)")
+    print("• Hawkes Processes for conflict contagion")
+    print("• Quasi-Experimental Causal Inference")
+    print("  - Synthetic Control Method")
+    print("  - Difference-in-Differences")
+    print("  - Regression Discontinuity Design")
+    print("  - Instrumental Variables")
+
+    # Run all demonstrations
+    demo_var_model()
+    demo_hawkes_process()
+    demo_synthetic_control()
+    demo_difference_in_differences()
+    demo_regression_discontinuity()
+    demo_instrumental_variables()
+    demo_dynamic_factor_model()
+
+    print("\n" + "=" * 80)
+    print("GeoBotv1 Framework is NOW 100% COMPLETE!")
+    print("=" * 80)
+    print("\n🎉 All Research-Grade Mathematical Components Implemented:")
+    print("\n📊 CORE FRAMEWORKS:")
+    print("  ✓ Optimal Transport (Wasserstein, Kantorovich, Sinkhorn)")
+    print("  ✓ Causal Inference (DAGs, SCMs, Do-Calculus)")
+    print("  ✓ Bayesian Inference (MCMC, Particle Filters, VI)")
+    print("  ✓ Stochastic Processes (SDEs, Jump-Diffusion)")
+    print("  ✓ Time-Series Models (Kalman, HMM, VAR, Hawkes)")
+    print("  ✓ Quasi-Experimental Methods (SCM, DiD, RDD, IV)")
+    print("  ✓ Machine Learning (GNNs, Risk Scoring, Embeddings)")
+    print("\n📈 SPECIALIZED CAPABILITIES:")
+    print("  ✓ Multi-country interdependency modeling (VAR)")
+    print("  ✓ Conflict contagion and escalation (Hawkes)")
+    print("  ✓ Policy counterfactuals (Synthetic Control)")
+    print("  ✓ Regime change effects (Difference-in-Differences)")
+    print("  ✓ Election outcomes impact (Regression Discontinuity)")
+    print("  ✓ Trade-conflict nexus (Instrumental Variables)")
+    print("  ✓ High-dimensional nowcasting (Dynamic Factor Models)")
+    print("\n🔬 MATHEMATICAL RIGOR:")
+    print("  ✓ Measure-theoretic probability foundations")
+    print("  ✓ Continuous-time dynamics (SDEs)")
+    print("  ✓ Causal identification strategies")
+    print("  ✓ Structural econometric methods")
+    print("  ✓ Point process theory")
+    print("  ✓ Optimal transport geometry")
+    print("\n💡 GeoBotv1 is ready for production geopolitical forecasting!")
+    print("=" * 80 + "\n")
+
+
+if __name__ == "__main__":
+    main()

examples/06_geobot2_analytical_framework.py

@@ -0,0 +1,318 @@
+"""
+GeoBot 2.0 Analytical Framework Example
+
+Demonstrates the complete GeoBot 2.0 framework for clinical systems analysis
+with geopolitical nuance. Includes:
+
+1. Framework overview
+2. Analytical lenses demonstration
+3. China Rocket Force purge analysis (example from specification)
+4. Governance system comparison
+5. Corruption type analysis
+6. Non-Western military assessment
+"""
+
+import sys
+sys.path.insert(0, '..')
+
+from geobot.analysis import (
+    AnalyticalEngine,
+    GeoBotFramework,
+    AnalyticalLenses,
+    GovernanceType,
+    CorruptionType
+)
+
+
+def print_section(title):
+    """Print formatted section header."""
+    print("\n" + "=" * 80)
+    print(f"  {title}")
+    print("=" * 80 + "\n")
+
+
+def example_1_framework_overview():
+    """Demonstrate GeoBot 2.0 framework overview."""
+    print_section("Example 1: GeoBot 2.0 Framework Overview")
+
+    framework = GeoBotFramework()
+    summary = framework.get_framework_summary()
+
+    print(f"Version: {summary['version']}")
+    print(f"Description: {summary['description']}\n")
+
+    print("Core Identity:")
+    print(f"  Focus: {summary['identity']['focus']}")
+    print(f"  Key Shift: {summary['identity']['key_shift']}\n")
+
+    print("Integration Elements:")
+    for element in summary['identity']['integration_elements']:
+        print(f"  - {element}")
+
+    print("\nTone:")
+    print(summary['tone'])
+
+    print("\nAnalytical Principles:")
+    for i, principle in enumerate(summary['principles'], 1):
+        print(f"  {i}. {principle}")
+
+
+def example_2_china_rocket_force_analysis():
+    """
+    Demonstrate complete analysis using China Rocket Force purge example
+    from the GeoBot 2.0 specification.
+    """
+    print_section("Example 2: China Rocket Force Purge Analysis")
+
+    engine = AnalyticalEngine()
+
+    query = "China removed several top Rocket Force generals. What does this mean?"
+
+    context = {
+        'governance_type': GovernanceType.AUTHORITARIAN_CENTRALIZED,
+        'corruption_type': CorruptionType.MANAGED_BOUNDED,
+        'military_system': 'Chinese PLA',
+        'scenario_description': 'Leadership purge in strategic forces',
+        'operational_context': 'Strategic nuclear forces readiness',
+
+        'summary': """The purge indicates internal accountability enforcement within strategic forces
+command, with mixed implications for near-term readiness and decision coherence.""",
+
+        'logistics_assessment': """Rocket Force maintenance, silo integration, and inventory control
+are likely under audit. Purges typically follow discovery of procurement irregularities or
+readiness misreporting. However, unlike Russian corruption patterns, Chinese anti-corruption
+campaigns since 2012 have successfully constrained (though not eliminated) defense sector
+embezzlement. The PLA's civil-military logistics integration provides redundancy that mitigates
+some supply chain risks.""",
+
+        'scenarios': [
+            {
+                'name': 'Routine institutional maintenance',
+                'probability': 0.50,
+                'description': 'Temporary disruption, return to baseline within 6-12 months'
+            },
+            {
+                'name': 'Deeper procurement crisis',
+                'probability': 0.30,
+                'description': 'Extended degradation of readiness reporting reliability'
+            },
+            {
+                'name': 'Factional conflict',
+                'probability': 0.15,
+                'description': 'Prolonged command instability'
+            },
+            {
+                'name': 'Major reorganization',
+                'probability': 0.05,
+                'description': 'Strategic forces restructure'
+            }
+        ],
+
+        'uncertainty_factors': [
+            'Limited visibility into CCP internal dynamics and audit findings'
+        ],
+
+        'signals_to_watch': [
+            'Promotion patterns (meritocratic vs. factional indicators)',
+            'Training tempo changes (satellite observable)',
+            'Procurement contract patterns',
+            'Whether purges expand beyond Rocket Force'
+        ],
+
+        'comparative_notes': """Russia's similar aerospace purges (2015-2017) resulted in sustained
+degradation because underlying corruption was never addressed—only individuals were replaced.
+China's systemic anti-corruption infrastructure suggests different trajectory is possible."""
+    }
+
+    # Add governance context
+    context['governance_context'] = {
+        'trade_off': """China gains long-term institutional integrity at the cost of
+short-term command continuity.""",
+        'context_specific_advantage': """Authoritarian systems can execute rapid leadership
+replacement without legislative constraints, allowing faster course correction than
+consensus-based systems. However, this creates temporary communication disruption and
+institutional memory loss."""
+    }
+
+    # Add corruption details
+    context['corruption_details'] = {
+        'evidence': """Evidence suggests managed corruption model rather than parasitic:
+purges indicate the system detected and acted on problems, rather than tolerating systemic decay.
+This is structurally different from militaries where corruption goes unaddressed.""",
+        'risk_assessment': """Purge-induced fear may cause temporary over-reporting conservatism,
+slowing mobilization responses."""
+    }
+
+    # Add non-Western context
+    context['non_western_context'] = {
+        'analysis_framework': """Western analysis often treats purges as pure weakness signals.
+In Chinese institutional context, periodic purges are a maintenance mechanism for regime stability.
+The question is whether this specific purge reflects routine enforcement or deeper structural crisis.""",
+        'key_distinction': """Indicators distinguishing routine vs. crisis:
+  - Scope: limited to RF or expanding to other services?
+  - Timing: related to specific audit cycle or sudden?
+  - Replacements: technocratic or factional?"""
+    }
+
+    # Perform analysis
+    analysis = engine.analyze(query, context)
+    print(analysis)
+
+
+def example_3_governance_comparison():
+    """Demonstrate governance system comparison."""
+    print_section("Example 3: Governance System Comparison")
+
+    engine = AnalyticalEngine()
+
+    scenario = "Rapid military mobilization in response to regional crisis"
+
+    comparison = engine.compare_governance_systems(
+        scenario=scenario,
+        authoritarian_context={},
+        democratic_context={}
+    )
+
+    print(comparison)
+
+
+def example_4_corruption_assessment():
+    """Demonstrate corruption type assessment."""
+    print_section("Example 4: Corruption Type Assessment")
+
+    lenses = AnalyticalLenses()
+
+    print("Corruption Type Analysis:\n")
+
+    # Assess different corruption types
+    corruption_types = [
+        (CorruptionType.PARASITIC, "Russia"),
+        (CorruptionType.MANAGED_BOUNDED, "China"),
+        (CorruptionType.INSTITUTIONALIZED_PATRONAGE, "Iran IRGC"),
+        (CorruptionType.LOW_CORRUPTION, "NATO countries")
+    ]
+
+    for corr_type, example in corruption_types:
+        analysis = lenses.corruption.analyze(
+            corr_type,
+            operational_context="Sustained high-intensity conventional operations"
+        )
+
+        print(f"\n{corr_type.value.upper()} ({example}):")
+        print(f"  Operational Impact: {analysis['operational_impact']}")
+        print(f"  Characteristics:")
+        for char in analysis['characteristics']:
+            print(f"    - {char}")
+
+
+def example_5_non_western_military_assessment():
+    """Demonstrate non-Western military analysis."""
+    print_section("Example 5: Non-Western Military Assessment")
+
+    lenses = AnalyticalLenses()
+
+    militaries = ["Chinese PLA", "Russian Military", "Iranian Systems"]
+
+    for military in militaries:
+        analysis = lenses.non_western.analyze(military)
+
+        print(f"\n{military.upper()}:")
+        print(f"\nOperational Culture: {analysis['operational_culture']}")
+
+        print("\nStrengths:")
+        for strength in analysis['strengths']:
+            print(f"  - {strength}")
+
+        print("\nWeaknesses:")
+        for weakness in analysis['weaknesses']:
+            print(f"  - {weakness}")
+
+        print(f"\nKey Insight: {analysis['key_insight']}")
+
+
+def example_6_all_lenses_integration():
+    """Demonstrate integration of all four lenses."""
+    print_section("Example 6: All Lenses Integration")
+
+    engine = AnalyticalEngine()
+
+    print("Analytical Priorities:\n")
+    priorities = engine.get_analytical_priorities()
+    for i, priority in enumerate(priorities, 1):
+        print(f"{i}. {priority}")
+
+    print("\n" + "-" * 80)
+
+    # Quick analysis example
+    print("\nQuick Analysis Example:")
+    print("Query: 'Iran's ability to sustain proxy operations in Syria'\n")
+
+    analysis = engine.quick_analysis(
+        query="Iran's ability to sustain proxy operations in Syria",
+        governance_type=GovernanceType.AUTHORITARIAN_CENTRALIZED,
+        corruption_type=CorruptionType.INSTITUTIONALIZED_PATRONAGE,
+        military_system="Iranian Systems",
+        summary="""Iran demonstrates structural advantages in proxy coordination despite
+conventional military limitations. IRGC Quds Force maintains effective command and control
+through patronage networks that double as operational infrastructure.""",
+        logistics_assessment="""Supply lines to Syria rely on air bridge through Iraq and
+maritime routes. Vulnerable to interdiction but demonstrated resilience through redundancy.
+Sanctions impact advanced systems but not basic sustainment.""",
+        scenarios=[
+            {
+                'name': 'Sustained proxy presence',
+                'probability': 0.60,
+                'description': 'Current operational tempo maintained'
+            },
+            {
+                'name': 'Degraded operations',
+                'probability': 0.30,
+                'description': 'Israeli interdiction reduces capability'
+            },
+            {
+                'name': 'Expansion',
+                'probability': 0.10,
+                'description': 'Regional instability creates opportunities'
+            }
+        ]
+    )
+
+    print(analysis)
+
+
+def main():
+    """Run all examples."""
+    print("\n" + "=" * 80)
+    print("  GeoBot 2.0: Cold Systems Analysis with Geopolitical Nuance")
+    print("=" * 80)
+
+    examples = [
+        ("Framework Overview", example_1_framework_overview),
+        ("China Rocket Force Analysis", example_2_china_rocket_force_analysis),
+        ("Governance Comparison", example_3_governance_comparison),
+        ("Corruption Assessment", example_4_corruption_assessment),
+        ("Non-Western Military Assessment", example_5_non_western_military_assessment),
+        ("All Lenses Integration", example_6_all_lenses_integration),
+    ]
+
+    print("\nAvailable Examples:")
+    for i, (name, _) in enumerate(examples, 1):
+        print(f"  {i}. {name}")
+
+    print("\nRunning all examples...\n")
+
+    for name, example_func in examples:
+        try:
+            example_func()
+        except Exception as e:
+            print(f"Error in {name}: {e}")
+            import traceback
+            traceback.print_exc()
+
+    print("\n" + "=" * 80)
+    print("  All examples completed")
+    print("=" * 80 + "\n")
+
+
+if __name__ == "__main__":
+    main()

examples/EXAMPLES_STATUS.md

@@ -0,0 +1 @@
+[PASTE MARKDOWN ABOVE]

examples/README.md

@@ -0,0 +1,132 @@
+# GeoBotv1 Examples
+
+This directory contains example scripts demonstrating the capabilities of GeoBotv1.
+
+## Examples Overview
+
+### 01_basic_usage.py
+Basic introduction to GeoBotv1 core components:
+- Creating geopolitical scenarios
+- Building causal graphs
+- Running Monte Carlo simulations
+- Bayesian belief updating
+- Uncertainty quantification
+
+**Run it:**
+```bash
+python 01_basic_usage.py
+```
+
+### 02_data_ingestion.py
+Demonstrates data ingestion capabilities:
+- PDF document processing
+- Web scraping and article extraction
+- News aggregation from multiple sources
+- Intelligence extraction from documents
+- Entity and keyword extraction
+
+**Run it:**
+```bash
+python 02_data_ingestion.py
+```
+
+**Note:** For full functionality, install optional dependencies:
+```bash
+pip install pypdf pdfplumber beautifulsoup4 newspaper3k trafilatura feedparser
+```
+
+### 03_intervention_simulation.py
+Advanced intervention and counterfactual analysis:
+- Policy intervention simulation
+- Comparing multiple policy options
+- Finding optimal interventions
+- Counterfactual reasoning ("what if" scenarios)
+- Causal effect estimation
+
+**Run it:**
+```bash
+python 03_intervention_simulation.py
+```
+
+### 04_advanced_features.py
+Research-grade advanced mathematical features:
+- Sequential Monte Carlo (particle filtering) for nonlinear state estimation
+- Stochastic Differential Equations (Euler-Maruyama, Milstein, Jump-Diffusion)
+- Gradient-based Optimal Transport with Kantorovich duality
+- Entropic OT with Sinkhorn algorithm
+- Structured event extraction from intelligence text
+- Event database with temporal normalization
+
+**Run it:**
+```bash
+python 04_advanced_features.py
+```
+
+**Note:** Some features require additional dependencies:
+```bash
+pip install torch  # For advanced features
+```
+
+## Additional Resources
+
+### Creating Custom Scenarios
+```python
+from geobot.core.scenario import Scenario
+import numpy as np
+
+scenario = Scenario(
+    name="custom_scenario",
+    features={
+        'tension': np.array([0.7]),
+        'stability': np.array([0.4]),
+    },
+    probability=1.0
+)
+```
+
+### Building Causal Models
+```python
+from geobot.models.causal_graph import CausalGraph
+
+graph = CausalGraph(name="my_model")
+graph.add_node('cause')
+graph.add_node('effect')
+graph.add_edge('cause', 'effect', strength=0.8)
+```
+
+### Monte Carlo Simulation
+```python
+from geobot.simulation.monte_carlo import MonteCarloEngine, SimulationConfig
+
+config = SimulationConfig(n_simulations=1000, time_horizon=100)
+engine = MonteCarloEngine(config)
+```
+
+### Web Scraping
+```python
+from geobot.data_ingestion.web_scraper import ArticleExtractor
+
+extractor = ArticleExtractor()
+article = extractor.extract_article('https://example.com/article')
+print(article['title'])
+print(article['text'])
+```
+
+### PDF Processing
+```python
+from geobot.data_ingestion.pdf_reader import PDFProcessor
+
+processor = PDFProcessor()
+result = processor.extract_intelligence('report.pdf')
+print(f"Risk Level: {result['intelligence']['risk_level']}")
+```
+
+## Need Help?
+
+- Check the main README.md in the project root
+- Review the module documentation in each package
+- Examine the source code for detailed implementation
+
+## Contributing
+
+Have an interesting use case? Create a new example script and submit a PR!

examples/taiwan_situation_room.py

@@ -0,0 +1,610 @@
+"""
+Taiwan Situation Room - GeoBot 2.0 Analytical Framework Demo
+
+Comprehensive demonstration of GeoBot 2.0 analytical capabilities applied
+to Taiwan Strait scenario analysis. Integrates:
+
+- GeoBot 2.0 analytical lenses (Governance, Logistics, Corruption, Non-Western)
+- Bayesian forecasting and belief updating
+- Structural causal models for intervention analysis
+- Hawkes processes for escalation dynamics
+
+Scenario: Rising tensions in Taiwan Strait with potential for
+military escalation. Analysis evaluates PRC capabilities, deterrence
+credibility, and intervention outcomes.
+"""
+
+import sys
+sys.path.insert(0, '..')
+
+import numpy as np
+from datetime import datetime
+
+# GeoBot 2.0 Analytical Framework
+from geobot.analysis import (
+    AnalyticalEngine,
+    GovernanceType,
+    CorruptionType,
+    AnalyticalLenses
+)
+
+# Bayesian Forecasting (if numpy available)
+try:
+    from geobot.bayes import (
+        BayesianForecaster,
+        GeopoliticalPrior,
+        PriorType,
+        EvidenceUpdate,
+        EvidenceType
+    )
+    BAYES_AVAILABLE = True
+except ImportError:
+    BAYES_AVAILABLE = False
+    print("Note: Bayesian forecasting requires numpy - skipping Bayesian analysis")
+
+# Causal Models (if numpy/networkx available)
+try:
+    from geobot.causal import (
+        StructuralCausalModel,
+        StructuralEquation,
+        Intervention,
+        Counterfactual
+    )
+    CAUSAL_AVAILABLE = True
+except ImportError:
+    CAUSAL_AVAILABLE = False
+    print("Note: Causal models require numpy/networkx - skipping causal analysis")
+
+# Hawkes processes (if scipy available)
+try:
+    from geobot.simulation.hawkes import (
+        HawkesSimulator,
+        quick_conflict_contagion_analysis
+    )
+    HAWKES_AVAILABLE = True
+except ImportError:
+    HAWKES_AVAILABLE = False
+    print("Note: Hawkes processes require scipy - skipping escalation dynamics")
+
+
+def print_header(title):
+    """Print formatted section header."""
+    print("\n" + "=" * 80)
+    print(f"  {title}")
+    print("=" * 80 + "\n")
+
+
+def print_subheader(title):
+    """Print formatted subsection header."""
+    print("\n" + "-" * 80)
+    print(f"  {title}")
+    print("-" * 80 + "\n")
+
+
+# ============================================================================
+# Part 1: GeoBot 2.0 Core Analysis
+# ============================================================================
+
+def part1_geobot_core_analysis():
+    """
+    Apply GeoBot 2.0 analytical framework to Taiwan scenario.
+    """
+    print_header("Part 1: GeoBot 2.0 Analytical Framework - Taiwan Scenario")
+
+    engine = AnalyticalEngine()
+
+    # Scenario context
+    query = """PRC conducts large-scale military exercises around Taiwan,
+including live-fire drills and simulated blockade operations. US conducts
+freedom of navigation operations in Taiwan Strait. What are the escalation
+risks and intervention outcomes?"""
+
+    print(f"QUERY: {query}\n")
+
+    # Build comprehensive context
+    context = {
+        'governance_type': GovernanceType.AUTHORITARIAN_CENTRALIZED,
+        'corruption_type': CorruptionType.MANAGED_BOUNDED,
+        'military_system': 'Chinese PLA',
+        'scenario_description': 'PRC military exercises and potential Taiwan contingency',
+        'operational_context': 'High-intensity joint operations in near-seas environment',
+
+        'summary': """PRC demonstrates improving capability for joint operations in Taiwan
+Strait, but faces significant logistical and operational challenges for sustained
+high-intensity operations. Authoritarian governance enables rapid mobilization but
+information flow problems could create coordination failures under stress.""",
+
+        'logistics_assessment': """PRC Eastern Theater Command has concentrated logistics
+infrastructure supporting Taiwan contingency. Civil-military fusion enables rapid resource
+mobilization. However, sustained amphibious/air assault operations would stress logistics
+systems untested in combat. Key constraints: sealift capacity, contested logistics under
+US/allied interdiction, ammunition sustainment for high-intensity operations.""",
+
+        # Scenarios with probabilities
+        'scenarios': [
+            {
+                'name': 'Coercive demonstration without escalation',
+                'probability': 0.55,
+                'description': 'Exercises conclude after demonstrating capability and resolve'
+            },
+            {
+                'name': 'Graduated escalation (quarantine/blockade)',
+                'probability': 0.30,
+                'description': 'PRC implements quarantine, testing US/allied response'
+            },
+            {
+                'name': 'Limited kinetic action',
+                'probability': 0.10,
+                'description': 'Strikes on Taiwan military targets, no invasion'
+            },
+            {
+                'name': 'Full-scale invasion attempt',
+                'probability': 0.05,
+                'description': 'Amphibious/airborne assault on Taiwan'
+            }
+        ],
+
+        # Uncertainty factors
+        'uncertainty_factors': [
+            'PRC leadership risk tolerance and decision calculus',
+            'Taiwan domestic political response and resolve',
+            'US extended deterrence credibility perception',
+            'PLA actual readiness vs. reported readiness (information distortion risk)',
+            'Third-party actions (Japan, Australia, regional states)',
+            'Economic interdependence constraints on escalation'
+        ],
+
+        # Signals to watch
+        'signals_to_watch': [
+            'PLA logistics mobilization (satellite-observable sealift, air transport concentration)',
+            'Rocket Force alert status and deployment patterns',
+            'PLAN submarine deployments',
+            'Civilian shipping disruptions (clearance of civilian vessels from exercise areas)',
+            'PRC domestic propaganda shifts (priming for kinetic action vs. victorious conclusion)',
+            'US carrier strike group deployments and readiness status',
+            'Taiwan reserve mobilization signals',
+            'Japanese Self-Defense Force posture changes'
+        ],
+
+        # Comparative notes
+        'comparative_notes': """Unlike Russia-Ukraine, PRC faces amphibious/air assault across
+defended strait with peer/near-peer opposition (US, Japan, Australia). PLA has not conducted
+combat operations since 1979, vs. Russia's experience in Syria, Georgia, Ukraine. However,
+PRC has advantage of proximity, massive firepower overmatch against Taiwan alone, and
+authoritarian ability to sustain economic costs."""
+    }
+
+    # Add governance-specific analysis
+    context['governance_context'] = {
+        'trade_off': """Authoritarian governance enables PRC to:
+        - Rapidly mobilize resources without legislative approval
+        - Sustain operations despite economic costs and casualties
+        - Conduct strategic surprise without public debate
+
+        But creates risks:
+        - Information distortion about PLA readiness/capabilities
+        - Over-confidence in leadership due to filtered reporting
+        - Inflexible response to unexpected battlefield developments""",
+
+        'context_specific_advantage': """In crisis initiation and short, sharp operations,
+authoritarian system has decision-speed advantage. In sustained operations requiring
+adaptation, democratic information flow advantages become more important. Key question:
+Can PRC achieve fait accompli before US/allied decision-making concludes?"""
+    }
+
+    # Add corruption context
+    context['corruption_details'] = {
+        'evidence': """Post-2012 anti-corruption campaigns have reduced parasitic corruption
+in PLA, especially after 2017 Rocket Force purges. However, managed corruption model means:
+        - Procurement still involves kickbacks, but constrained to avoid readiness impact
+        - Promotion decisions still involve patronage, affecting command quality
+        - Readiness reporting still subject to careerism incentives""",
+
+        'risk_assessment': """Corruption less likely to cause catastrophic equipment failures
+(cf. Russian logistics in Ukraine), but could create:
+        - Over-estimation of PLA capabilities by leadership
+        - Coordination problems from patronage-based command appointments
+        - Supply chain inefficiencies under stress"""
+    }
+
+    # Add non-Western analysis
+    context['non_western_context'] = {
+        'analysis_framework': """PLA operational culture emphasizes:
+        - Centralized planning with detailed pre-scripted operations
+        - Heavy firepower preparation before maneuver
+        - Political control through party committee system
+        - Joint operations still developing (improving but not NATO-level)
+
+        This creates both capabilities and constraints different from Western assumptions.""",
+
+        'key_distinction': """Western analysis often assumes PLA would operate like NATO forces.
+In reality, PLA would likely emphasize:
+        - Overwhelming initial firepower (missiles, air strikes) to create shock
+        - Rapid fait accompli before US can intervene
+        - Accepting higher casualties than Western forces
+        - Using information operations and political warfare alongside kinetic
+
+        These reflect Chinese strategic culture and organizational strengths, not deficiencies."""
+    }
+
+    # Perform analysis
+    print_subheader("GeoBot 2.0 Analytical Output")
+    analysis = engine.analyze(query, context)
+    print(analysis)
+
+
+# ============================================================================
+# Part 2: Bayesian Belief Updating
+# ============================================================================
+
+def part2_bayesian_analysis():
+    """
+    Bayesian belief updating as new intelligence arrives.
+    """
+    if not BAYES_AVAILABLE:
+        print_header("Part 2: Bayesian Analysis - SKIPPED (numpy not available)")
+        return
+
+    print_header("Part 2: Bayesian Belief Updating - Intelligence Integration")
+
+    forecaster = BayesianForecaster()
+
+    # Set prior on PRC invasion probability within 12 months
+    invasion_prior = GeopoliticalPrior(
+        parameter_name="invasion_probability_12mo",
+        prior_type=PriorType.BETA,
+        parameters={'alpha': 2.0, 'beta': 18.0},  # Prior mean ~0.10
+        description="Probability of PRC invasion attempt within 12 months"
+    )
+
+    forecaster.set_prior(invasion_prior)
+
+    print("PRIOR BELIEF:")
+    print(f"  Distribution: Beta(α=2.0, β=18.0)")
+    print(f"  Prior mean: ~0.10 (10% chance)")
+    print(f"  This reflects baseline assessment before current crisis\n")
+
+    # Evidence 1: Satellite imagery shows sealift mobilization
+    print_subheader("Evidence Update 1: Satellite Imagery")
+    print("Satellite imagery shows increased sealift concentration in Fujian ports")
+    print("Assessing impact on invasion probability...\n")
+
+    def sealift_likelihood(p):
+        # If invasion likely, sealift mobilization is very likely
+        # If invasion unlikely, some mobilization still possible (exercises)
+        return p * 0.9 + (1 - p) * 0.2
+
+    evidence1 = EvidenceUpdate(
+        evidence_type=EvidenceType.SATELLITE_IMAGERY,
+        observation="sealift_mobilization",
+        likelihood_function=sealift_likelihood,
+        reliability=0.95,
+        source="Commercial satellite analysis"
+    )
+
+    belief1 = forecaster.update_belief(
+        "invasion_probability_12mo",
+        evidence1,
+        n_samples=10000
+    )
+
+    print(f"Updated belief after satellite evidence:")
+    print(f"  Mean: {belief1.mean():.3f}")
+    print(f"  Median: {belief1.median():.3f}")
+    print(f"  95% CI: {belief1.credible_interval(0.05)}")
+    print(f"  P(invasion > 0.20): {belief1.probability_greater_than(0.20):.2f}\n")
+
+    # Evidence 2: HUMINT reports purges in Taiwan Affairs Office
+    print_subheader("Evidence Update 2: HUMINT Report")
+    print("HUMINT reports internal purges in Taiwan Affairs Office leadership")
+    print("Interpretation: Could indicate pre-operation security tightening OR internal dysfunction\n")
+
+    def purge_likelihood(p):
+        # Purges could indicate either preparation or problems
+        # Moderate signal
+        return p * 0.6 + (1 - p) * 0.4
+
+    evidence2 = EvidenceUpdate(
+        evidence_type=EvidenceType.INTELLIGENCE_REPORT,
+        observation="tao_purges",
+        likelihood_function=purge_likelihood,
+        reliability=0.70,  # HUMINT less reliable than satellite
+        source="HUMINT Taiwan Affairs Office"
+    )
+
+    belief2 = forecaster.update_belief(
+        "invasion_probability_12mo",
+        evidence2,
+        n_samples=10000
+    )
+
+    print(f"Updated belief after HUMINT evidence:")
+    print(f"  Mean: {belief2.mean():.3f}")
+    print(f"  Median: {belief2.median():.3f}")
+    print(f"  95% CI: {belief2.credible_interval(0.05)}")
+    print(f"  P(invasion > 0.20): {belief2.probability_greater_than(0.20):.2f}\n")
+
+    # Evidence 3: Economic data shows continued deep integration
+    print_subheader("Evidence Update 3: Economic Data")
+    print("Economic data shows continued deep PRC-Taiwan trade integration, no decoupling")
+    print("Interpretation: Reduces likelihood of near-term kinetic action\n")
+
+    def economic_likelihood(p):
+        # Continued integration suggests not preparing for war
+        return p * 0.3 + (1 - p) * 0.8
+
+    evidence3 = EvidenceUpdate(
+        evidence_type=EvidenceType.ECONOMIC_DATA,
+        observation="continued_integration",
+        likelihood_function=economic_likelihood,
+        reliability=1.0,  # Economic data highly reliable
+        source="Trade statistics"
+    )
+
+    belief3 = forecaster.update_belief(
+        "invasion_probability_12mo",
+        evidence3,
+        n_samples=10000
+    )
+
+    print(f"Final belief after all evidence:")
+    print(f"  Mean: {belief3.mean():.3f}")
+    print(f"  Median: {belief3.median():.3f}")
+    print(f"  95% CI: {belief3.credible_interval(0.05)}")
+    print(f"  P(invasion > 0.20): {belief3.probability_greater_than(0.20):.2f}")
+    print(f"  P(invasion > 0.30): {belief3.probability_greater_than(0.30):.2f}")
+
+    # Summary
+    summary = forecaster.get_belief_summary("invasion_probability_12mo")
+    print(f"\nBelief Summary:")
+    print(f"  Evidence updates: {summary['n_evidence_updates']}")
+    print(f"  Evidence types: {summary['evidence_types']}")
+    print(f"  Final assessment: {summary['mean']:.1%} probability within 12 months")
+
+
+# ============================================================================
+# Part 3: Causal Intervention Analysis
+# ============================================================================
+
+def part3_causal_intervention_analysis():
+    """
+    Use structural causal models to evaluate intervention outcomes.
+    """
+    if not CAUSAL_AVAILABLE:
+        print_header("Part 3: Causal Analysis - SKIPPED (dependencies not available)")
+        return
+
+    print_header("Part 3: Causal Intervention Analysis - Policy Counterfactuals")
+
+    # Build SCM for Taiwan deterrence
+    print("Building Structural Causal Model for Taiwan deterrence dynamics...\n")
+
+    scm = StructuralCausalModel(name="TaiwanDeterrenceSCM")
+
+    noise_dist = lambda n: np.random.randn(n) * 0.05
+
+    # US military presence -> PRC perception of US resolve
+    scm.add_equation(StructuralEquation(
+        variable="prc_perceived_us_resolve",
+        parents=["us_military_presence"],
+        function=lambda p: 0.3 + 0.6 * p["us_military_presence"],
+        noise_dist=noise_dist,
+        description="US military presence increases PRC perception of US resolve"
+    ))
+
+    # Taiwan defense spending -> Taiwan military capability
+    scm.add_equation(StructuralEquation(
+        variable="taiwan_military_capability",
+        parents=["taiwan_defense_spending"],
+        function=lambda p: 0.4 + 0.5 * p["taiwan_defense_spending"],
+        noise_dist=noise_dist,
+        description="Taiwan defense spending improves military capability"
+    ))
+
+    # PRC perceived costs = f(US resolve, Taiwan capability)
+    scm.add_equation(StructuralEquation(
+        variable="prc_perceived_costs",
+        parents=["prc_perceived_us_resolve", "taiwan_military_capability"],
+        function=lambda p: (0.4 * p["prc_perceived_us_resolve"] +
+                          0.3 * p["taiwan_military_capability"]),
+        noise_dist=noise_dist,
+        description="Perceived costs depend on US resolve and Taiwan capability"
+    ))
+
+    # Conflict risk = f(perceived costs, prc_domestic_pressure)
+    scm.add_equation(StructuralEquation(
+        variable="conflict_risk",
+        parents=["prc_perceived_costs", "prc_domestic_pressure"],
+        function=lambda p: (0.5 + 0.3 * p["prc_domestic_pressure"] -
+                          0.4 * p["prc_perceived_costs"]),
+        noise_dist=noise_dist,
+        description="Conflict risk increases with domestic pressure, decreases with perceived costs"
+    ))
+
+    # Baseline scenario
+    print_subheader("Baseline Scenario")
+    baseline_data = scm.simulate(n_samples=10000, random_state=42)
+    print(f"Baseline conflict risk: Mean = {np.mean(baseline_data['conflict_risk']):.3f}, "
+          f"Std = {np.std(baseline_data['conflict_risk']):.3f}\n")
+
+    # Intervention 1: Increase US military presence
+    print_subheader("Intervention 1: Increase US Military Presence")
+    print("do(us_military_presence = 0.8)  # High presence\n")
+
+    intervention1 = Intervention(
+        variable="us_military_presence",
+        value=0.8,
+        description="Sustained US carrier presence + forward-deployed assets"
+    )
+
+    post_intervention1 = scm.intervene([intervention1], n_samples=10000, random_state=42)
+    print(f"Post-intervention conflict risk: Mean = {np.mean(post_intervention1['conflict_risk']):.3f}")
+    print(f"Effect of intervention: {np.mean(baseline_data['conflict_risk']) - np.mean(post_intervention1['conflict_risk']):.3f} reduction")
+    print(f"Interpretation: Increasing US presence reduces conflict risk by ~{100*(np.mean(baseline_data['conflict_risk']) - np.mean(post_intervention1['conflict_risk'])):.1f} percentage points\n")
+
+    # Intervention 2: Increase Taiwan defense spending
+    print_subheader("Intervention 2: Increase Taiwan Defense Spending")
+    print("do(taiwan_defense_spending = 0.9)  # Major defense investment\n")
+
+    intervention2 = Intervention(
+        variable="taiwan_defense_spending",
+        value=0.9,
+        description="Major asymmetric defense investments"
+    )
+
+    post_intervention2 = scm.intervene([intervention2], n_samples=10000, random_state=42)
+    print(f"Post-intervention conflict risk: Mean = {np.mean(post_intervention2['conflict_risk']):.3f}")
+    print(f"Effect of intervention: {np.mean(baseline_data['conflict_risk']) - np.mean(post_intervention2['conflict_risk']):.3f} reduction\n")
+
+    # Combined intervention
+    print_subheader("Intervention 3: Combined Strategy")
+    print("do(us_military_presence = 0.8, taiwan_defense_spending = 0.9)\n")
+
+    combined_data = scm.intervene([intervention1, intervention2], n_samples=10000, random_state=42)
+    print(f"Post-intervention conflict risk: Mean = {np.mean(combined_data['conflict_risk']):.3f}")
+    print(f"Effect of combined intervention: {np.mean(baseline_data['conflict_risk']) - np.mean(combined_data['conflict_risk']):.3f} reduction")
+    print(f"Interpretation: Combined strategy most effective for reducing conflict risk\n")
+
+    # Counterfactual query
+    print_subheader("Counterfactual Query")
+    print("Question: What would conflict risk be if we had maintained high US presence,")
+    print("given that we currently observe moderate US presence?\n")
+
+    counterfactual = Counterfactual(
+        query_variable="conflict_risk",
+        intervention=Intervention("us_military_presence", 0.8),
+        observations={"us_military_presence": 0.5}
+    )
+
+    cf_result = scm.counterfactual_query(counterfactual, n_samples=10000)
+    print(f"Counterfactual conflict risk: {cf_result['expected_value']:.3f}")
+    print(f"95% CI: ({cf_result['quantiles']['5%']:.3f}, {cf_result['quantiles']['95%']:.3f})")
+
+
+# ============================================================================
+# Part 4: Escalation Dynamics (Hawkes Processes)
+# ============================================================================
+
+def part4_escalation_dynamics():
+    """
+    Model escalation dynamics using Hawkes processes.
+    """
+    if not HAWKES_AVAILABLE:
+        print_header("Part 4: Escalation Dynamics - SKIPPED (scipy not available)")
+        return
+
+    print_header("Part 4: Escalation Dynamics - Self-Exciting Processes")
+
+    from geobot.simulation.hawkes import HawkesParameters
+
+    print("Modeling crisis escalation as self-exciting point process...")
+    print("Events cluster in time and trigger subsequent events (escalatory spiral)\n")
+
+    # Simulate escalation scenario
+    print_subheader("Scenario: Incremental Escalation with Contagion")
+
+    # Three actors: PRC, Taiwan, US
+    baseline_rates = [0.5, 0.3, 0.2]  # PRC initiates more, US responds
+    countries = ['PRC', 'Taiwan', 'US']
+
+    # Contagion: PRC action triggers Taiwan/US response
+    alpha_matrix = np.array([
+        [0.3, 0.2, 0.15],  # PRC actions trigger more PRC, Taiwan, US actions
+        [0.4, 0.2, 0.3],   # Taiwan actions strongly trigger PRC and US
+        [0.5, 0.2, 0.1],   # US actions strongly trigger PRC responses
+    ])
+
+    beta_matrix = np.ones((3, 3)) * 1.5  # Decay rate
+
+    params = HawkesParameters(
+        mu=np.array(baseline_rates),
+        alpha=alpha_matrix,
+        beta=beta_matrix
+    )
+
+    # Simulate 30-day crisis
+    simulator = HawkesSimulator(n_dimensions=3)
+    events = simulator.simulate(T=30.0, params=params, random_state=42)
+
+    print(f"Simulated 30-day crisis escalation:")
+    for i, country in enumerate(countries):
+        print(f"  {country}: {len(events[i])} escalatory events")
+
+    # Assess stability
+    stability = simulator.assess_stability(params)
+    print(f"\nEscalation dynamics stability assessment:")
+    print(f"  Branching ratio: {stability['branching_ratio']:.3f}")
+    print(f"  Regime: {stability['regime']}")
+    print(f"  Interpretation: {stability['interpretation']}\n")
+
+    if stability['is_explosive']:
+        print("⚠️  WARNING: Process is supercritical - escalation could spiral out of control")
+    else:
+        print("✓ Process is subcritical - escalation will stabilize")
+
+
+# ============================================================================
+# Main Execution
+# ============================================================================
+
+def main():
+    """Run complete Taiwan situation room analysis."""
+
+    print("\n" + "=" * 80)
+    print("  TAIWAN SITUATION ROOM")
+    print("  GeoBot 2.0 Integrated Geopolitical Analysis")
+    print("  " + datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
+    print("=" * 80)
+
+    # Run all parts
+    part1_geobot_core_analysis()
+    part2_bayesian_analysis()
+    part3_causal_intervention_analysis()
+    part4_escalation_dynamics()
+
+    # Summary
+    print_header("Summary and Recommendations")
+
+    print("""
+INTEGRATED ASSESSMENT:
+
+1. GEOBOT 2.0 ANALYTICAL FRAMEWORK
+   - PRC has improving joint operations capability but faces significant logistical
+     constraints for sustained high-intensity operations
+   - Authoritarian governance enables rapid mobilization but creates information
+     flow risks
+   - Managed corruption likely constrained enough to maintain basic functionality
+   - Non-Western analysis reveals PRC emphasis on firepower and fait accompli
+
+2. BAYESIAN BELIEF UPDATING
+   - Posterior probability of invasion within 12 months: ~15-20% (up from 10% prior)
+   - Satellite evidence of sealift mobilization raises concern
+   - Economic integration evidence reduces near-term kinetic risk
+   - Continued monitoring required as new intelligence arrives
+
+3. CAUSAL INTERVENTION ANALYSIS
+   - Combined strategy (US presence + Taiwan defense) most effective
+   - US military presence has direct deterrent effect
+   - Taiwan capabilities create operational costs for PRC
+   - Counterfactual analysis supports sustained presence policy
+
+4. ESCALATION DYNAMICS
+   - Current contagion parameters suggest subcritical regime (stable)
+   - However, parameter changes could shift to explosive regime
+   - Escalation management critical to prevent spiral
+
+POLICY RECOMMENDATIONS:
+   - Maintain credible US extended deterrence
+   - Support Taiwan asymmetric defense capabilities
+   - Engage in crisis management mechanisms to prevent escalation spirals
+   - Continue intelligence collection on PLA readiness and mobilization
+   - Monitor for signals of PRC leadership decision to use force
+    """)
+
+    print("=" * 80)
+    print("  Analysis Complete")
+    print("=" * 80 + "\n")
+
+
+if __name__ == "__main__":
+    main()

geobot/__init__.py

@@ -0,0 +1,43 @@
+"""
+GeoBotv1: Geopolitical Forecasting Framework
+
+A comprehensive framework for geopolitical risk analysis, conflict prediction,
+and intervention simulation using advanced mathematical and statistical methods.
+
+Version 2.0 includes the GeoBot analytical framework for clinical systems analysis
+with geopolitical nuance.
+"""
+
+__version__ = "2.0.0"
+__author__ = "GeoBotv1 Team"
+
+# Core modules
+from . import core
+from . import models
+from . import inference
+from . import simulation
+from . import timeseries
+from . import ml
+from . import data_ingestion
+from . import utils
+from . import config
+from . import analysis
+
+# New modules in v2.0
+from . import bayes
+from . import causal
+
+__all__ = [
+    "core",
+    "models",
+    "inference",
+    "simulation",
+    "timeseries",
+    "ml",
+    "data_ingestion",
+    "utils",
+    "config",
+    "analysis",
+    "bayes",
+    "causal",
+]

geobot/analysis/__init__.py

@@ -0,0 +1,30 @@
+"""
+GeoBot 2.0 Analytical Framework
+
+A clinical, logistics-focused analytical framework for geopolitical analysis
+with institutional agility assessment and cultural-operational context.
+"""
+
+from .framework import GeoBotFramework, AnalyticalPrinciples, CoreIdentity
+from .lenses import (
+    LogisticsLens,
+    GovernanceLens,
+    CorruptionLens,
+    NonWesternLens,
+    AnalyticalLenses
+)
+from .engine import AnalyticalEngine
+from .formatter import AnalysisFormatter
+
+__all__ = [
+    "GeoBotFramework",
+    "AnalyticalPrinciples",
+    "CoreIdentity",
+    "LogisticsLens",
+    "GovernanceLens",
+    "CorruptionLens",
+    "NonWesternLens",
+    "AnalyticalLenses",
+    "AnalyticalEngine",
+    "AnalysisFormatter",
+]

geobot/analysis/engine.py

@@ -0,0 +1,393 @@
+"""
+GeoBot 2.0 Analytical Engine
+
+Main interface for conducting GeoBot 2.0 analysis. Integrates all lenses,
+applies analytical priorities, and generates formatted output.
+"""
+
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+
+from .framework import GeoBotFramework
+from .lenses import (
+    AnalyticalLenses,
+    GovernanceType,
+    CorruptionType,
+    MilitaryProfile
+)
+from .formatter import AnalysisFormatter, AnalysisOutput, Scenario
+
+
+@dataclass
+class AnalyticalPriorities:
+    """
+    Analytical priorities for GeoBot 2.0.
+
+    Every analysis checks:
+    1. Governance structure impact
+    2. Logistics coherence
+    3. Corruption type and impact
+    4. Institutional context
+    5. Communication networks
+    6. Organizational cohesion
+    """
+
+    priorities: List[str] = field(default_factory=lambda: [
+        "Governance structure impact - Does this scenario favor centralized decision-making or distributed adaptation?",
+        "Logistics coherence - Supply chains, maintenance, communications",
+        "Corruption type and impact - What kind of corruption exists? Does it critically impair this specific operation?",
+        "Institutional context - Are we analyzing this military using appropriate cultural/organizational frameworks?",
+        "Communication networks - Information flow and coordination",
+        "Organizational cohesion - Unit cohesion and morale"
+    ])
+
+    def check_all(self, context: Dict[str, Any]) -> Dict[str, bool]:
+        """
+        Check which priorities have been addressed in analysis.
+
+        Parameters
+        ----------
+        context : Dict[str, Any]
+            Analysis context
+
+        Returns
+        -------
+        Dict[str, bool]
+            Priority checklist
+        """
+        return {
+            'governance_structure': 'governance_type' in context,
+            'logistics': 'logistics_assessment' in context,
+            'corruption': 'corruption_type' in context,
+            'institutional_context': 'military_system' in context,
+            'communications': 'communications_status' in context,
+            'cohesion': 'cohesion_assessment' in context
+        }
+
+
+class AnalyticalEngine:
+    """
+    Main analytical engine for GeoBot 2.0.
+
+    Integrates framework, lenses, priorities, and formatter to provide
+    comprehensive geopolitical analysis.
+    """
+
+    def __init__(self):
+        """Initialize the analytical engine."""
+        self.framework = GeoBotFramework()
+        self.lenses = AnalyticalLenses()
+        self.priorities = AnalyticalPriorities()
+        self.formatter = AnalysisFormatter()
+
+    def analyze(
+        self,
+        query: str,
+        context: Dict[str, Any]
+    ) -> str:
+        """
+        Conduct complete GeoBot 2.0 analysis.
+
+        Parameters
+        ----------
+        query : str
+            Analytical query or question
+        context : Dict[str, Any]
+            Context for analysis including:
+            - governance_type: GovernanceType
+            - corruption_type: CorruptionType
+            - military_system: str
+            - logistics_data: Dict
+            - scenario_description: str
+
+        Returns
+        -------
+        str
+            Formatted analysis
+        """
+        # Apply all lenses
+        analysis_components = self._apply_lenses(context)
+
+        # Create structured output
+        output = self._create_output(query, context, analysis_components)
+
+        # Validate against framework
+        if not self.framework.validate_analysis(output.__dict__):
+            raise ValueError("Analysis does not adhere to GeoBot 2.0 framework")
+
+        # Format and return
+        return self.formatter.format_analysis(output)
+
+    def _apply_lenses(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Apply all analytical lenses to context.
+
+        Parameters
+        ----------
+        context : Dict[str, Any]
+            Analysis context
+
+        Returns
+        -------
+        Dict[str, Any]
+            Lens analyses
+        """
+        components = {}
+
+        # Lens A: Logistics
+        components['logistics'] = self.lenses.logistics.analyze(context)
+
+        # Lens B: Governance
+        if 'governance_type' in context:
+            gov_type = context['governance_type']
+            scenario = context.get('scenario_description', 'General scenario')
+            components['governance'] = self.lenses.governance.analyze(
+                gov_type, scenario
+            )
+        else:
+            components['governance'] = {
+                'note': 'Governance type not specified'
+            }
+
+        # Lens C: Corruption
+        if 'corruption_type' in context:
+            corr_type = context['corruption_type']
+            operational_context = context.get('operational_context', 'General operations')
+            components['corruption'] = self.lenses.corruption.analyze(
+                corr_type, operational_context
+            )
+        else:
+            components['corruption'] = {
+                'note': 'Corruption type not specified'
+            }
+
+        # Lens D: Non-Western
+        if 'military_system' in context:
+            military = context['military_system']
+            components['non_western'] = self.lenses.non_western.analyze(military)
+        else:
+            components['non_western'] = {
+                'note': 'Military system not specified'
+            }
+
+        return components
+
+    def _create_output(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        components: Dict[str, Any]
+    ) -> AnalysisOutput:
+        """
+        Create structured analysis output.
+
+        Parameters
+        ----------
+        query : str
+            Original query
+        context : Dict[str, Any]
+            Analysis context
+        components : Dict[str, Any]
+            Lens analysis components
+
+        Returns
+        -------
+        AnalysisOutput
+            Structured output
+        """
+        # Extract or create summary
+        summary = context.get('summary', f"Analysis of: {query}")
+
+        # Governance analysis
+        governance_analysis = {
+            'system_type': context.get('governance_type', 'Not specified'),
+            **components.get('governance', {})
+        }
+
+        # Logistics analysis
+        logistics_analysis = {
+            'assessment': context.get('logistics_assessment', 'Requires detailed logistics data'),
+            **components.get('logistics', {})
+        }
+
+        # Corruption assessment
+        corruption_assessment = {
+            'corruption_type': context.get('corruption_type', 'Not specified'),
+            **components.get('corruption', {})
+        }
+
+        # Non-Western perspective
+        non_western_perspective = {
+            'military_system': context.get('military_system', 'Not specified'),
+            **components.get('non_western', {})
+        }
+
+        # Scenarios
+        scenarios = context.get('scenarios', [])
+
+        # Uncertainty
+        uncertainty = context.get('uncertainty_factors', [
+            "Limited visibility into internal decision-making",
+            "Intelligence gaps in operational readiness",
+            "Uncertainty in actor intentions"
+        ])
+
+        # Signals
+        signals = context.get('signals_to_watch', [
+            "Changes in leadership or command structure",
+            "Shifts in training tempo or deployment patterns",
+            "Procurement and supply chain activity"
+        ])
+
+        # Comparative notes
+        comparative = context.get('comparative_notes')
+
+        return self.formatter.create_structured_output(
+            summary=summary,
+            governance=governance_analysis,
+            logistics=logistics_analysis,
+            corruption=corruption_assessment,
+            non_western=non_western_perspective,
+            scenarios=scenarios,
+            uncertainty=uncertainty,
+            signals=signals,
+            comparative=comparative
+        )
+
+    def quick_analysis(
+        self,
+        query: str,
+        governance_type: GovernanceType,
+        corruption_type: CorruptionType,
+        military_system: str,
+        summary: str,
+        **kwargs
+    ) -> str:
+        """
+        Quick analysis with minimal context.
+
+        Parameters
+        ----------
+        query : str
+            Analysis query
+        governance_type : GovernanceType
+            Type of governance system
+        corruption_type : CorruptionType
+            Type of corruption present
+        military_system : str
+            Military system being analyzed
+        summary : str
+            Assessment summary
+        **kwargs
+            Additional context
+
+        Returns
+        -------
+        str
+            Formatted analysis
+        """
+        context = {
+            'governance_type': governance_type,
+            'corruption_type': corruption_type,
+            'military_system': military_system,
+            'summary': summary,
+            **kwargs
+        }
+
+        return self.analyze(query, context)
+
+    def compare_governance_systems(
+        self,
+        scenario: str,
+        authoritarian_context: Dict[str, Any],
+        democratic_context: Dict[str, Any]
+    ) -> str:
+        """
+        Compare authoritarian vs democratic systems for a scenario.
+
+        Parameters
+        ----------
+        scenario : str
+            Scenario description
+        authoritarian_context : Dict[str, Any]
+            Context for authoritarian system
+        democratic_context : Dict[str, Any]
+            Context for democratic system
+
+        Returns
+        -------
+        str
+            Comparative analysis
+        """
+        comparison = self.lenses.governance.compare_systems(scenario)
+
+        output = [
+            f"COMPARATIVE ANALYSIS: {scenario}",
+            "",
+            "AUTHORITARIAN/CENTRALIZED SYSTEMS:",
+            "Advantages:"
+        ]
+
+        for adv in comparison['authoritarian']['advantages']:
+            output.append(f"  - {adv}")
+
+        output.append("\nDisadvantages:")
+        for dis in comparison['authoritarian']['disadvantages']:
+            output.append(f"  - {dis}")
+
+        output.append("\nDEMOCRATIC/CONSENSUS SYSTEMS:")
+        output.append("Advantages:")
+        for adv in comparison['democratic']['advantages']:
+            output.append(f"  - {adv}")
+
+        output.append("\nDisadvantages:")
+        for dis in comparison['democratic']['disadvantages']:
+            output.append(f"  - {dis}")
+
+        output.append(f"\nKEY INSIGHT: {comparison['key_insight']}")
+
+        return "\n".join(output)
+
+    def assess_corruption_impact(
+        self,
+        corruption_type: CorruptionType,
+        operation_type: str
+    ) -> str:
+        """
+        Assess corruption impact on specific operation type.
+
+        Parameters
+        ----------
+        corruption_type : CorruptionType
+            Type of corruption
+        operation_type : str
+            Type of operation
+
+        Returns
+        -------
+        str
+            Impact assessment
+        """
+        return self.lenses.corruption.assess_impact(corruption_type, operation_type)
+
+    def get_framework_summary(self) -> Dict[str, Any]:
+        """
+        Get summary of GeoBot 2.0 framework.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Framework summary
+        """
+        return self.framework.get_framework_summary()
+
+    def get_analytical_priorities(self) -> List[str]:
+        """
+        Get list of analytical priorities.
+
+        Returns
+        -------
+        List[str]
+            Analytical priorities
+        """
+        return self.priorities.priorities

geobot/analysis/formatter.py

@@ -0,0 +1,318 @@
+"""
+GeoBot 2.0 Analysis Formatter
+
+Formats analytical outputs according to GeoBot 2.0 specifications:
+1. Summary conclusion
+2. Governance structure analysis
+3. Logistical interpretation
+4. Corruption impact
+5. Non-Western perspective integration
+6. Scenarios (with probabilities)
+7. Uncertainty factors
+8. Signals to watch
+"""
+
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Scenario:
+    """A scenario with probability estimate."""
+    name: str
+    probability: float
+    description: str
+
+
+@dataclass
+class AnalysisOutput:
+    """Structured analysis output."""
+    summary: str
+    governance_analysis: Dict[str, Any]
+    logistics_analysis: Dict[str, Any]
+    corruption_assessment: Dict[str, Any]
+    non_western_perspective: Dict[str, Any]
+    scenarios: List[Scenario] = field(default_factory=list)
+    uncertainty_factors: List[str] = field(default_factory=list)
+    signals_to_watch: List[str] = field(default_factory=list)
+    comparative_notes: Optional[str] = None
+
+
+class AnalysisFormatter:
+    """
+    Formatter for GeoBot 2.0 analytical outputs.
+
+    Formats analysis according to the default output formula:
+    1. Summary conclusion
+    2. Governance structure analysis
+    3. Logistical interpretation
+    4. Corruption impact
+    5. Non-Western perspective integration
+    6. Scenarios (with probabilities)
+    7. Uncertainty factors
+    8. Signals to watch
+    """
+
+    def __init__(self):
+        """Initialize the formatter."""
+        self.section_separator = "\n" + "=" * 60 + "\n"
+        self.subsection_separator = "\n" + "-" * 60 + "\n"
+
+    def format_analysis(self, analysis: AnalysisOutput) -> str:
+        """
+        Format complete analysis output.
+
+        Parameters
+        ----------
+        analysis : AnalysisOutput
+            Analysis to format
+
+        Returns
+        -------
+        str
+            Formatted analysis
+        """
+        sections = []
+
+        # 1. Summary
+        sections.append(self._format_summary(analysis.summary))
+
+        # 2. Governance Structure Analysis
+        sections.append(self._format_governance(analysis.governance_analysis))
+
+        # 3. Logistics
+        sections.append(self._format_logistics(analysis.logistics_analysis))
+
+        # 4. Corruption Dynamics
+        sections.append(self._format_corruption(analysis.corruption_assessment))
+
+        # 5. Non-Western Context
+        sections.append(self._format_non_western(analysis.non_western_perspective))
+
+        # 6. Scenarios
+        sections.append(self._format_scenarios(analysis.scenarios))
+
+        # 7. Uncertainty
+        sections.append(self._format_uncertainty(analysis.uncertainty_factors))
+
+        # 8. Signals to Watch
+        sections.append(self._format_signals(analysis.signals_to_watch))
+
+        # 9. Comparative Note (if present)
+        if analysis.comparative_notes:
+            sections.append(self._format_comparative(analysis.comparative_notes))
+
+        return self.section_separator.join(sections)
+
+    def _format_summary(self, summary: str) -> str:
+        """Format assessment summary."""
+        return f"""ASSESSMENT:
+{summary}"""
+
+    def _format_governance(self, governance: Dict[str, Any]) -> str:
+        """Format governance structure analysis."""
+        output = ["GOVERNANCE STRUCTURE CONTEXT:"]
+
+        if 'system_type' in governance:
+            output.append(f"\nSystem Type: {governance['system_type']}")
+
+        if 'advantages' in governance:
+            output.append("\nAdvantages:")
+            for adv in governance['advantages']:
+                output.append(f"  - {adv}")
+
+        if 'disadvantages' in governance:
+            output.append("\nDisadvantages:")
+            for dis in governance['disadvantages']:
+                output.append(f"  - {dis}")
+
+        if 'trade_off' in governance:
+            output.append(f"\nTrade-off: {governance['trade_off']}")
+
+        if 'context_specific_advantage' in governance:
+            output.append(f"\nContextual Advantage: {governance['context_specific_advantage']}")
+
+        return "\n".join(output)
+
+    def _format_logistics(self, logistics: Dict[str, Any]) -> str:
+        """Format logistics analysis."""
+        output = ["LOGISTICS:"]
+
+        if 'assessment' in logistics:
+            output.append(f"\n{logistics['assessment']}")
+
+        if 'supply_chain_status' in logistics:
+            output.append(f"\nSupply Chain Status: {logistics['supply_chain_status']}")
+
+        if 'maintenance_capacity' in logistics:
+            output.append(f"Maintenance Capacity: {logistics['maintenance_capacity']}")
+
+        if 'key_constraints' in logistics:
+            output.append("\nKey Constraints:")
+            for constraint in logistics['key_constraints']:
+                output.append(f"  - {constraint}")
+
+        if 'mitigating_factors' in logistics:
+            output.append("\nMitigating Factors:")
+            for factor in logistics['mitigating_factors']:
+                output.append(f"  - {factor}")
+
+        return "\n".join(output)
+
+    def _format_corruption(self, corruption: Dict[str, Any]) -> str:
+        """Format corruption assessment."""
+        output = ["CORRUPTION DYNAMICS:"]
+
+        if 'corruption_type' in corruption:
+            output.append(f"\nCorruption Type: {corruption['corruption_type']}")
+
+        if 'evidence' in corruption:
+            output.append(f"\nEvidence: {corruption['evidence']}")
+
+        if 'operational_impact' in corruption:
+            output.append(f"\nOperational Impact: {corruption['operational_impact']}")
+
+        if 'comparison' in corruption:
+            output.append(f"\nComparative Context: {corruption['comparison']}")
+
+        if 'risk_assessment' in corruption:
+            output.append(f"\nRisk: {corruption['risk_assessment']}")
+
+        return "\n".join(output)
+
+    def _format_non_western(self, non_western: Dict[str, Any]) -> str:
+        """Format non-Western perspective."""
+        output = ["NON-WESTERN CONTEXT:"]
+
+        if 'analysis_framework' in non_western:
+            output.append(f"\n{non_western['analysis_framework']}")
+
+        if 'indigenous_strengths' in non_western:
+            output.append("\nIndigenous Strengths:")
+            for strength in non_western['indigenous_strengths']:
+                output.append(f"  - {strength}")
+
+        if 'structural_constraints' in non_western:
+            output.append("\nStructural Constraints:")
+            for constraint in non_western['structural_constraints']:
+                output.append(f"  - {constraint}")
+
+        if 'institutional_context' in non_western:
+            output.append(f"\nInstitutional Context: {non_western['institutional_context']}")
+
+        if 'key_distinction' in non_western:
+            output.append(f"\nKey Distinction: {non_western['key_distinction']}")
+
+        return "\n".join(output)
+
+    def _format_scenarios(self, scenarios: List[Scenario]) -> str:
+        """Format scenario probabilities."""
+        output = ["SCENARIOS:"]
+
+        if not scenarios:
+            output.append("\n(Scenarios require additional context)")
+            return "\n".join(output)
+
+        # Sort by probability descending
+        sorted_scenarios = sorted(scenarios, key=lambda s: s.probability, reverse=True)
+
+        for scenario in sorted_scenarios:
+            output.append(f"\n• {scenario.name} ({scenario.probability:.2f})")
+            output.append(f"  {scenario.description}")
+
+        return "\n".join(output)
+
+    def _format_uncertainty(self, uncertainty_factors: List[str]) -> str:
+        """Format uncertainty factors."""
+        output = ["UNCERTAINTY:"]
+
+        if not uncertainty_factors:
+            output.append("\n(Standard intelligence limitations apply)")
+            return "\n".join(output)
+
+        for factor in uncertainty_factors:
+            output.append(f"  - {factor}")
+
+        return "\n".join(output)
+
+    def _format_signals(self, signals: List[str]) -> str:
+        """Format signals to watch."""
+        output = ["SIGNALS TO WATCH:"]
+
+        if not signals:
+            output.append("\n(Ongoing monitoring required)")
+            return "\n".join(output)
+
+        for signal in signals:
+            output.append(f"  - {signal}")
+
+        return "\n".join(output)
+
+    def _format_comparative(self, comparative_note: str) -> str:
+        """Format comparative note."""
+        return f"""COMPARATIVE NOTE:
+{comparative_note}"""
+
+    def create_structured_output(
+        self,
+        summary: str,
+        governance: Dict[str, Any],
+        logistics: Dict[str, Any],
+        corruption: Dict[str, Any],
+        non_western: Dict[str, Any],
+        scenarios: Optional[List[Dict[str, Any]]] = None,
+        uncertainty: Optional[List[str]] = None,
+        signals: Optional[List[str]] = None,
+        comparative: Optional[str] = None
+    ) -> AnalysisOutput:
+        """
+        Create structured analysis output.
+
+        Parameters
+        ----------
+        summary : str
+            Assessment summary
+        governance : Dict[str, Any]
+            Governance structure analysis
+        logistics : Dict[str, Any]
+            Logistics analysis
+        corruption : Dict[str, Any]
+            Corruption assessment
+        non_western : Dict[str, Any]
+            Non-Western perspective
+        scenarios : Optional[List[Dict[str, Any]]]
+            List of scenarios with probabilities
+        uncertainty : Optional[List[str]]
+            Uncertainty factors
+        signals : Optional[List[str]]
+            Signals to watch
+        comparative : Optional[str]
+            Comparative note
+
+        Returns
+        -------
+        AnalysisOutput
+            Structured output
+        """
+        scenario_objects = []
+        if scenarios:
+            scenario_objects = [
+                Scenario(
+                    name=s['name'],
+                    probability=s['probability'],
+                    description=s['description']
+                )
+                for s in scenarios
+            ]
+
+        return AnalysisOutput(
+            summary=summary,
+            governance_analysis=governance,
+            logistics_analysis=logistics,
+            corruption_assessment=corruption,
+            non_western_perspective=non_western,
+            scenarios=scenario_objects,
+            uncertainty_factors=uncertainty or [],
+            signals_to_watch=signals or [],
+            comparative_notes=comparative
+        )

geobot/analysis/framework.py

@@ -0,0 +1,155 @@
+"""
+GeoBot 2.0 Core Framework
+
+Defines the core identity, tone, and analytical principles for GeoBot 2.0,
+a clinical systems analyst with geopolitical nuance.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any
+from enum import Enum
+
+
+class ToneElement(Enum):
+    """Tone elements for GeoBot 2.0 analysis."""
+    NEUTRAL = "neutral and clinical"
+    ANALYTIC = "analytic, not poetic"
+    SKEPTICAL = "cautiously skeptical of all systems, including Western ones"
+    SYSTEMS_ORIENTED = "systems-oriented - analyzes structural trade-offs"
+    CAVEATED = "heavily caveated"
+    RISK_REPORT = "risk-report style"
+
+
+@dataclass
+class CoreIdentity:
+    """
+    Core identity of GeoBot 2.0.
+
+    GeoBot remains a clinical, logistics-focused analyst, but now integrates:
+    - Institutional agility assessment
+    - Cultural-operational context
+    - Adaptive capacity modeling
+    - Non-Western institutional logic
+
+    Key shift: Analyzes structural trade-offs rather than assuming
+    Western organizational models are superior.
+    """
+
+    focus: str = "clinical, logistics-focused analyst"
+
+    integration_elements: List[str] = field(default_factory=lambda: [
+        "Institutional agility assessment (authoritarian vs. consensus-based decision structures)",
+        "Cultural-operational context (how different militaries actually function, not just Western assumptions)",
+        "Adaptive capacity modeling (who can pivot quickly under stress, and why)",
+        "Non-Western institutional logic (understanding Chinese, Russian, Iranian, etc. systems on their own terms)"
+    ])
+
+    key_shift: str = "Analyzes structural trade-offs rather than assuming Western organizational models are superior"
+
+    tone_elements: List[ToneElement] = field(default_factory=lambda: [
+        ToneElement.NEUTRAL,
+        ToneElement.ANALYTIC,
+        ToneElement.SKEPTICAL,
+        ToneElement.SYSTEMS_ORIENTED,
+        ToneElement.CAVEATED,
+        ToneElement.RISK_REPORT
+    ])
+
+    def get_tone_description(self) -> str:
+        """Get description of analytical tone."""
+        return "\n".join([f"- {tone.value}" for tone in self.tone_elements])
+
+
+@dataclass
+class AnalyticalPrinciples:
+    """
+    Embedded analytical principles that GeoBot 2.0 believes and operates by.
+    """
+
+    principles: List[str] = field(default_factory=lambda: [
+        "Governance structure creates operational trade-offs, not just advantages/disadvantages",
+        "Authoritarian systems have real agility advantages in strategic pivots and crisis mobilization",
+        "Corruption impact depends on type and context, not just existence",
+        "Non-Western militaries must be analyzed using their own organizational logic",
+        "Logistics remain the ultimate constraint, but cultural factors shape how logistics are managed",
+        "Western military assumptions often miss indigenous capabilities",
+        "Purges can signal both weakness AND functional institutional enforcement"
+    ])
+
+    def get_principles_list(self) -> List[str]:
+        """Get list of analytical principles."""
+        return self.principles
+
+    def validate_analysis(self, analysis: Dict[str, Any]) -> bool:
+        """
+        Validate that an analysis adheres to analytical principles.
+
+        Parameters
+        ----------
+        analysis : Dict[str, Any]
+            Analysis to validate
+
+        Returns
+        -------
+        bool
+            True if analysis adheres to principles
+        """
+        # Check for required elements
+        required_elements = [
+            'governance_context',
+            'logistics_analysis',
+            'corruption_assessment',
+            'non_western_perspective'
+        ]
+
+        return all(element in analysis for element in required_elements)
+
+
+@dataclass
+class GeoBotFramework:
+    """
+    Complete GeoBot 2.0 framework combining identity, tone, and principles.
+    """
+
+    core_identity: CoreIdentity = field(default_factory=CoreIdentity)
+    analytical_principles: AnalyticalPrinciples = field(default_factory=AnalyticalPrinciples)
+
+    version: str = "2.0"
+    description: str = "Cold Systems Analysis with Geopolitical Nuance"
+
+    def get_framework_summary(self) -> Dict[str, Any]:
+        """
+        Get summary of the complete framework.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Framework summary
+        """
+        return {
+            'version': self.version,
+            'description': self.description,
+            'identity': {
+                'focus': self.core_identity.focus,
+                'key_shift': self.core_identity.key_shift,
+                'integration_elements': self.core_identity.integration_elements
+            },
+            'tone': self.core_identity.get_tone_description(),
+            'principles': self.analytical_principles.get_principles_list()
+        }
+
+    def validate_analysis(self, analysis: Dict[str, Any]) -> bool:
+        """
+        Validate that an analysis adheres to GeoBot 2.0 framework.
+
+        Parameters
+        ----------
+        analysis : Dict[str, Any]
+            Analysis to validate
+
+        Returns
+        -------
+        bool
+            True if analysis adheres to framework
+        """
+        return self.analytical_principles.validate_analysis(analysis)

geobot/analysis/lenses.py

@@ -0,0 +1,477 @@
+"""
+GeoBot 2.0 Analytical Lenses
+
+Four complementary analytical lenses for geopolitical analysis:
+- Lens A: Logistics as Power
+- Lens B: Governance Structure & Decision Speed
+- Lens C: Corruption as Context-Dependent Variable
+- Lens D: Non-Western Military Logic
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional
+from enum import Enum
+
+
+# ============================================================================
+# Lens A: Logistics as Power
+# ============================================================================
+
+@dataclass
+class LogisticsLens:
+    """
+    Lens A: Logistics as Power (Unchanged from GeoBot v1)
+
+    Prioritizes supply chains, throughput, maintenance, communications infrastructure.
+    Logistics remain the ultimate constraint.
+    """
+
+    name: str = "Logistics as Power"
+    priority_areas: List[str] = field(default_factory=lambda: [
+        "Supply chains and throughput",
+        "Maintenance capacity",
+        "Communications infrastructure",
+        "Resource mobilization speed",
+        "Sustainment capacity"
+    ])
+
+    def analyze(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Analyze situation through logistics lens.
+
+        Parameters
+        ----------
+        context : Dict[str, Any]
+            Situational context
+
+        Returns
+        -------
+        Dict[str, Any]
+            Logistics analysis
+        """
+        return {
+            'lens': self.name,
+            'priority_areas': self.priority_areas,
+            'assessment': "Logistics coherence analysis required",
+            'context': context
+        }
+
+
+# ============================================================================
+# Lens B: Governance Structure & Decision Speed
+# ============================================================================
+
+class GovernanceType(Enum):
+    """Types of governance structures."""
+    AUTHORITARIAN_CENTRALIZED = "authoritarian/centralized"
+    DEMOCRATIC_CONSENSUS = "democratic/consensus"
+    HYBRID = "hybrid"
+
+
+@dataclass
+class GovernanceAdvantages:
+    """Advantages of a governance type."""
+    advantages: List[str] = field(default_factory=list)
+    disadvantages: List[str] = field(default_factory=list)
+
+
+@dataclass
+class GovernanceLens:
+    """
+    Lens B: Governance Structure & Decision Speed
+
+    Evaluates institutional agility and decision-making structures.
+    Recognizes that different governance structures create different
+    operational capabilities, not just deficits.
+    """
+
+    name: str = "Governance Structure & Decision Speed"
+
+    authoritarian_profile: GovernanceAdvantages = field(default_factory=lambda: GovernanceAdvantages(
+        advantages=[
+            "Faster strategic pivots (no legislative/consensus delays)",
+            "Rapid resource mobilization during crises",
+            "Unified command structures (fewer veto points)",
+            "Ability to absorb short-term costs for long-term positioning",
+            "Less vulnerable to public opinion shifts"
+        ],
+        disadvantages=[
+            "Higher corruption risk (less accountability)",
+            "Information distortion (fear of reporting bad news upward)",
+            "Brittleness under sustained stress (rigid hierarchies)",
+            "Lower tactical initiative at junior levels",
+            "Purge-induced institutional memory loss"
+        ]
+    ))
+
+    democratic_profile: GovernanceAdvantages = field(default_factory=lambda: GovernanceAdvantages(
+        advantages=[
+            "Better information flow (less fear-based reporting)",
+            "Higher tactical flexibility (NCO empowerment)",
+            "More resilient under prolonged strain",
+            "Transparent procurement (lower corruption)",
+            "Adaptive learning cultures"
+        ],
+        disadvantages=[
+            "Slower strategic decision-making (multiple approval layers)",
+            "Political constraints on deployment/escalation",
+            "Public opinion as operational constraint",
+            "Bureaucratic friction in mobilization",
+            "Difficulty sustaining unpopular policies"
+        ]
+    ))
+
+    def analyze(self, governance_type: GovernanceType, scenario_context: str) -> Dict[str, Any]:
+        """
+        Analyze which governance type has structural advantage for specific scenario.
+
+        Parameters
+        ----------
+        governance_type : GovernanceType
+            Type of governance structure
+        scenario_context : str
+            Description of scenario requiring analysis
+
+        Returns
+        -------
+        Dict[str, Any]
+            Governance structure analysis
+        """
+        profile = None
+        if governance_type == GovernanceType.AUTHORITARIAN_CENTRALIZED:
+            profile = self.authoritarian_profile
+        elif governance_type == GovernanceType.DEMOCRATIC_CONSENSUS:
+            profile = self.democratic_profile
+
+        return {
+            'lens': self.name,
+            'governance_type': governance_type.value,
+            'advantages': profile.advantages if profile else [],
+            'disadvantages': profile.disadvantages if profile else [],
+            'scenario_context': scenario_context,
+            'key_question': "Which governance type advantages matter for this specific scenario?"
+        }
+
+    def compare_systems(self, scenario_context: str) -> Dict[str, Any]:
+        """
+        Compare authoritarian vs democratic systems for a scenario.
+
+        Parameters
+        ----------
+        scenario_context : str
+            Description of scenario
+
+        Returns
+        -------
+        Dict[str, Any]
+            Comparative analysis
+        """
+        return {
+            'lens': self.name,
+            'scenario': scenario_context,
+            'authoritarian': {
+                'advantages': self.authoritarian_profile.advantages,
+                'disadvantages': self.authoritarian_profile.disadvantages
+            },
+            'democratic': {
+                'advantages': self.democratic_profile.advantages,
+                'disadvantages': self.democratic_profile.disadvantages
+            },
+            'key_insight': "Governance structure creates operational trade-offs, not universal superiority"
+        }
+
+
+# ============================================================================
+# Lens C: Corruption as Context-Dependent Variable
+# ============================================================================
+
+class CorruptionType(Enum):
+    """Types of corruption and their operational impacts."""
+    PARASITIC = "parasitic"  # Hollows readiness, predictably degrades performance
+    MANAGED_BOUNDED = "managed/bounded"  # Limited by periodic purges
+    INSTITUTIONALIZED_PATRONAGE = "institutionalized patronage"  # Loyalty networks
+    LOW_CORRUPTION = "low corruption"  # Western militaries, Singapore
+
+
+@dataclass
+class CorruptionProfile:
+    """Profile of corruption type and its impacts."""
+    corruption_type: CorruptionType
+    characteristics: List[str] = field(default_factory=list)
+    operational_impact: str = ""
+    examples: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CorruptionLens:
+    """
+    Lens C: Corruption as Context-Dependent Variable
+
+    Corruption is no longer assumed to be universally crippling.
+    Instead, analyzes corruption type and its context-specific impacts.
+    """
+
+    name: str = "Corruption as Context-Dependent Variable"
+
+    corruption_profiles: Dict[CorruptionType, CorruptionProfile] = field(default_factory=lambda: {
+        CorruptionType.PARASITIC: CorruptionProfile(
+            corruption_type=CorruptionType.PARASITIC,
+            characteristics=[
+                "Hollows readiness",
+                "Steals from supply chains",
+                "Predictably degrades performance"
+            ],
+            operational_impact="Severe degradation of operational capability",
+            examples=["Russia (extensive)", "Many Global South militaries"]
+        ),
+        CorruptionType.MANAGED_BOUNDED: CorruptionProfile(
+            corruption_type=CorruptionType.MANAGED_BOUNDED,
+            characteristics=[
+                "Limited by periodic purges and surveillance",
+                "Still present, but constrained enough to maintain basic functionality",
+                "Risk: purges themselves create instability"
+            ],
+            operational_impact="Moderate impact, mitigated by enforcement",
+            examples=["China post-Xi purges"]
+        ),
+        CorruptionType.INSTITUTIONALIZED_PATRONAGE: CorruptionProfile(
+            corruption_type=CorruptionType.INSTITUTIONALIZED_PATRONAGE,
+            characteristics=[
+                "Loyalty networks provide cohesion",
+                "Can coexist with effectiveness if tied to performance"
+            ],
+            operational_impact="Variable - depends on performance accountability",
+            examples=["Iran IRGC", "Some Gulf states"]
+        ),
+        CorruptionType.LOW_CORRUPTION: CorruptionProfile(
+            corruption_type=CorruptionType.LOW_CORRUPTION,
+            characteristics=[
+                "Advantage in sustained operations",
+                "Can be slower to mobilize"
+            ],
+            operational_impact="Minimal negative impact, enables sustained operations",
+            examples=["Western militaries", "Singapore"]
+        )
+    })
+
+    def analyze(self, corruption_type: CorruptionType, operational_context: str) -> Dict[str, Any]:
+        """
+        Analyze corruption impact in specific operational context.
+
+        Parameters
+        ----------
+        corruption_type : CorruptionType
+            Type of corruption present
+        operational_context : str
+            Operational context for assessment
+
+        Returns
+        -------
+        Dict[str, Any]
+            Corruption impact analysis
+        """
+        profile = self.corruption_profiles[corruption_type]
+
+        return {
+            'lens': self.name,
+            'corruption_type': corruption_type.value,
+            'characteristics': profile.characteristics,
+            'operational_impact': profile.operational_impact,
+            'examples': profile.examples,
+            'operational_context': operational_context,
+            'key_question': "What type of corruption, and how does it interact with operational demands?"
+        }
+
+    def assess_impact(self, corruption_type: CorruptionType, operation_type: str) -> str:
+        """
+        Assess whether corruption critically impairs specific operation.
+
+        Parameters
+        ----------
+        corruption_type : CorruptionType
+            Type of corruption
+        operation_type : str
+            Type of military operation
+
+        Returns
+        -------
+        str
+            Impact assessment
+        """
+        profile = self.corruption_profiles[corruption_type]
+        return f"For {operation_type}: {profile.operational_impact}"
+
+
+# ============================================================================
+# Lens D: Non-Western Military Logic
+# ============================================================================
+
+@dataclass
+class MilitaryProfile:
+    """Profile of a military system's strengths and weaknesses."""
+    strengths: List[str] = field(default_factory=list)
+    weaknesses: List[str] = field(default_factory=list)
+    operational_culture: str = ""
+
+
+@dataclass
+class NonWesternLens:
+    """
+    Lens D: Non-Western Military Logic
+
+    Incorporates indigenous operational cultures rather than measuring
+    everything against NATO standards. Analyzes non-Western militaries
+    using appropriate cultural/organizational frameworks.
+    """
+
+    name: str = "Non-Western Military Logic"
+
+    military_profiles: Dict[str, MilitaryProfile] = field(default_factory=lambda: {
+        "Chinese PLA": MilitaryProfile(
+            strengths=[
+                "Rapid infrastructure mobilization (civil-military fusion)",
+                "Industrial base integration",
+                "Coastal defense asymmetric advantages",
+                "Improving joint operations capability",
+                "Long-term strategic patience"
+            ],
+            weaknesses=[
+                "Limited expeditionary experience",
+                "Unproven complex joint operations",
+                "NCO corps still developing",
+                "Logistics for sustained high-intensity operations"
+            ],
+            operational_culture="Centralized strategic planning with improving tactical adaptation"
+        ),
+        "Russian Military": MilitaryProfile(
+            strengths=[
+                "Artillery coordination",
+                "Tactical adaptation under fire (demonstrated in Ukraine)",
+                "Willingness to accept casualties",
+                "Deep fires integration"
+            ],
+            weaknesses=[
+                "Logistics corruption (confirmed)",
+                "Poor junior leadership initiative",
+                "Industrial base constraints under sanctions"
+            ],
+            operational_culture="Heavy firepower doctrine with rigid tactical execution"
+        ),
+        "Iranian Systems": MilitaryProfile(
+            strengths=[
+                "Proxy warfare coordination",
+                "Missile/drone saturation tactics",
+                "Strategic patience",
+                "Asymmetric warfare effectiveness"
+            ],
+            weaknesses=[
+                "Air force decay",
+                "Sanctions-induced technology gaps",
+                "Conventional forces limitations"
+            ],
+            operational_culture="Asymmetric focus with strategic depth through proxies"
+        )
+    })
+
+    def analyze(self, military: str) -> Dict[str, Any]:
+        """
+        Analyze military using appropriate cultural/organizational framework.
+
+        Parameters
+        ----------
+        military : str
+            Military system to analyze
+
+        Returns
+        -------
+        Dict[str, Any]
+            Non-Western perspective analysis
+        """
+        if military not in self.military_profiles:
+            return {
+                'lens': self.name,
+                'military': military,
+                'warning': "Military profile not defined - analysis requires custom framework",
+                'key_question': "What are we missing if we only use Western assumptions?"
+            }
+
+        profile = self.military_profiles[military]
+
+        return {
+            'lens': self.name,
+            'military': military,
+            'strengths': profile.strengths,
+            'weaknesses': profile.weaknesses,
+            'operational_culture': profile.operational_culture,
+            'key_insight': "Non-obvious strengths often missed by Western-centric analysis",
+            'key_question': "Are we analyzing this military using appropriate cultural/organizational frameworks?"
+        }
+
+    def add_military_profile(self, military: str, profile: MilitaryProfile) -> None:
+        """
+        Add new military profile to the lens.
+
+        Parameters
+        ----------
+        military : str
+            Name of military system
+        profile : MilitaryProfile
+            Profile of the military system
+        """
+        self.military_profiles[military] = profile
+
+
+# ============================================================================
+# Combined Analytical Lenses
+# ============================================================================
+
+@dataclass
+class AnalyticalLenses:
+    """
+    Combined analytical lenses for comprehensive GeoBot 2.0 analysis.
+    """
+
+    logistics: LogisticsLens = field(default_factory=LogisticsLens)
+    governance: GovernanceLens = field(default_factory=GovernanceLens)
+    corruption: CorruptionLens = field(default_factory=CorruptionLens)
+    non_western: NonWesternLens = field(default_factory=NonWesternLens)
+
+    def get_all_lenses(self) -> Dict[str, Any]:
+        """
+        Get all analytical lenses.
+
+        Returns
+        -------
+        Dict[str, Any]
+            All lenses
+        """
+        return {
+            'Lens A': self.logistics,
+            'Lens B': self.governance,
+            'Lens C': self.corruption,
+            'Lens D': self.non_western
+        }
+
+    def apply_all_lenses(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Apply all lenses to a given context.
+
+        Parameters
+        ----------
+        context : Dict[str, Any]
+            Context to analyze
+
+        Returns
+        -------
+        Dict[str, Any]
+            Multi-lens analysis
+        """
+        return {
+            'logistics_analysis': self.logistics.analyze(context),
+            'governance_analysis': self.governance.compare_systems(
+                context.get('scenario', 'General scenario')
+            ),
+            'corruption_analysis': "Requires corruption type specification",
+            'non_western_analysis': "Requires military system specification",
+            'integrated_assessment': "Apply all lenses for comprehensive analysis"
+        }

geobot/bayes/__init__.py

@@ -0,0 +1,21 @@
+"""
+Bayesian forecasting and belief updating for GeoBotv1
+"""
+
+from .forecasting import (
+    BayesianForecaster,
+    BeliefState,
+    GeopoliticalPrior,
+    EvidenceUpdate,
+    ForecastDistribution,
+    CredibleInterval
+)
+
+__all__ = [
+    "BayesianForecaster",
+    "BeliefState",
+    "GeopoliticalPrior",
+    "EvidenceUpdate",
+    "ForecastDistribution",
+    "CredibleInterval",
+]

geobot/bayes/forecasting.py

@@ -0,0 +1,659 @@
+"""
+Bayesian Forecasting Module for GeoBotv1
+
+Provides Bayesian belief updating, prior construction, and probabilistic forecasting
+for geopolitical scenarios. Integrates with GeoBot 2.0 analytical framework.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional, Callable, Tuple
+from enum import Enum
+import numpy as np
+from scipy import stats
+from scipy.optimize import minimize
+
+
+class PriorType(Enum):
+    """Types of prior distributions."""
+    UNIFORM = "uniform"
+    NORMAL = "normal"
+    BETA = "beta"
+    GAMMA = "gamma"
+    EXPERT_INFORMED = "expert_informed"
+    HISTORICAL = "historical"
+
+
+class EvidenceType(Enum):
+    """Types of evidence for belief updating."""
+    INTELLIGENCE_REPORT = "intelligence_report"
+    SATELLITE_IMAGERY = "satellite_imagery"
+    ECONOMIC_DATA = "economic_data"
+    MILITARY_MOVEMENT = "military_movement"
+    DIPLOMATIC_SIGNAL = "diplomatic_signal"
+    OPEN_SOURCE = "open_source"
+
+
+@dataclass
+class GeopoliticalPrior:
+    """
+    Prior distribution for geopolitical parameter.
+
+    Attributes
+    ----------
+    parameter_name : str
+        Name of the parameter
+    prior_type : PriorType
+        Type of prior distribution
+    parameters : Dict[str, float]
+        Distribution parameters
+    description : str
+        Description of what this parameter represents
+    """
+    parameter_name: str
+    prior_type: PriorType
+    parameters: Dict[str, float]
+    description: str = ""
+
+    def sample(self, n_samples: int = 1000, random_state: Optional[int] = None) -> np.ndarray:
+        """
+        Sample from prior distribution.
+
+        Parameters
+        ----------
+        n_samples : int
+            Number of samples
+        random_state : Optional[int]
+            Random seed
+
+        Returns
+        -------
+        np.ndarray
+            Samples from prior
+        """
+        if random_state is not None:
+            np.random.seed(random_state)
+
+        if self.prior_type == PriorType.UNIFORM:
+            low = self.parameters['low']
+            high = self.parameters['high']
+            return np.random.uniform(low, high, n_samples)
+
+        elif self.prior_type == PriorType.NORMAL:
+            mean = self.parameters['mean']
+            std = self.parameters['std']
+            return np.random.normal(mean, std, n_samples)
+
+        elif self.prior_type == PriorType.BETA:
+            alpha = self.parameters['alpha']
+            beta = self.parameters['beta']
+            return np.random.beta(alpha, beta, n_samples)
+
+        elif self.prior_type == PriorType.GAMMA:
+            shape = self.parameters['shape']
+            scale = self.parameters['scale']
+            return np.random.gamma(shape, scale, n_samples)
+
+        else:
+            raise ValueError(f"Sampling not implemented for {self.prior_type}")
+
+    def pdf(self, x: np.ndarray) -> np.ndarray:
+        """
+        Compute probability density function.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Points at which to evaluate PDF
+
+        Returns
+        -------
+        np.ndarray
+            PDF values
+        """
+        if self.prior_type == PriorType.UNIFORM:
+            low = self.parameters['low']
+            high = self.parameters['high']
+            return stats.uniform.pdf(x, loc=low, scale=high-low)
+
+        elif self.prior_type == PriorType.NORMAL:
+            mean = self.parameters['mean']
+            std = self.parameters['std']
+            return stats.norm.pdf(x, loc=mean, scale=std)
+
+        elif self.prior_type == PriorType.BETA:
+            alpha = self.parameters['alpha']
+            beta = self.parameters['beta']
+            return stats.beta.pdf(x, alpha, beta)
+
+        elif self.prior_type == PriorType.GAMMA:
+            shape = self.parameters['shape']
+            scale = self.parameters['scale']
+            return stats.gamma.pdf(x, shape, scale=scale)
+
+        else:
+            raise ValueError(f"PDF not implemented for {self.prior_type}")
+
+
+@dataclass
+class EvidenceUpdate:
+    """
+    Evidence for Bayesian belief updating.
+
+    Attributes
+    ----------
+    evidence_type : EvidenceType
+        Type of evidence
+    observation : Any
+        Observed value or data
+    likelihood_function : Callable
+        Function mapping parameters to likelihood of observation
+    reliability : float
+        Reliability score [0, 1]
+    source : str
+        Source of evidence
+    timestamp : Optional[str]
+        When evidence was collected
+    """
+    evidence_type: EvidenceType
+    observation: Any
+    likelihood_function: Callable[[np.ndarray], np.ndarray]
+    reliability: float = 1.0
+    source: str = ""
+    timestamp: Optional[str] = None
+
+    def compute_likelihood(self, parameter_values: np.ndarray) -> np.ndarray:
+        """
+        Compute likelihood of observation given parameter values.
+
+        Parameters
+        ----------
+        parameter_values : np.ndarray
+            Parameter values
+
+        Returns
+        -------
+        np.ndarray
+            Likelihood values
+        """
+        base_likelihood = self.likelihood_function(parameter_values)
+        # Adjust for reliability
+        return base_likelihood ** self.reliability
+
+
+@dataclass
+class BeliefState:
+    """
+    Current belief state (posterior distribution).
+
+    Attributes
+    ----------
+    parameter_name : str
+        Name of parameter
+    posterior_samples : np.ndarray
+        Samples from posterior distribution
+    prior : GeopoliticalPrior
+        Original prior
+    evidence_history : List[EvidenceUpdate]
+        Evidence used to update beliefs
+    """
+    parameter_name: str
+    posterior_samples: np.ndarray
+    prior: GeopoliticalPrior
+    evidence_history: List[EvidenceUpdate] = field(default_factory=list)
+
+    def mean(self) -> float:
+        """Posterior mean."""
+        return float(np.mean(self.posterior_samples))
+
+    def median(self) -> float:
+        """Posterior median."""
+        return float(np.median(self.posterior_samples))
+
+    def std(self) -> float:
+        """Posterior standard deviation."""
+        return float(np.std(self.posterior_samples))
+
+    def quantile(self, q: float) -> float:
+        """
+        Posterior quantile.
+
+        Parameters
+        ----------
+        q : float
+            Quantile in [0, 1]
+
+        Returns
+        -------
+        float
+            Quantile value
+        """
+        return float(np.quantile(self.posterior_samples, q))
+
+    def credible_interval(self, alpha: float = 0.05) -> Tuple[float, float]:
+        """
+        Compute credible interval.
+
+        Parameters
+        ----------
+        alpha : float
+            Significance level (default 0.05 for 95% CI)
+
+        Returns
+        -------
+        Tuple[float, float]
+            Lower and upper bounds
+        """
+        lower = self.quantile(alpha / 2)
+        upper = self.quantile(1 - alpha / 2)
+        return (lower, upper)
+
+    def probability_greater_than(self, threshold: float) -> float:
+        """
+        Compute P(parameter > threshold | evidence).
+
+        Parameters
+        ----------
+        threshold : float
+            Threshold value
+
+        Returns
+        -------
+        float
+            Probability
+        """
+        return float(np.mean(self.posterior_samples > threshold))
+
+    def probability_in_range(self, low: float, high: float) -> float:
+        """
+        Compute P(low < parameter < high | evidence).
+
+        Parameters
+        ----------
+        low : float
+            Lower bound
+        high : float
+            Upper bound
+
+        Returns
+        -------
+        float
+            Probability
+        """
+        return float(np.mean((self.posterior_samples > low) &
+                           (self.posterior_samples < high)))
+
+
+@dataclass
+class CredibleInterval:
+    """Credible interval for forecast."""
+    lower: float
+    upper: float
+    alpha: float  # Significance level
+
+    @property
+    def width(self) -> float:
+        """Interval width."""
+        return self.upper - self.lower
+
+    @property
+    def credibility(self) -> float:
+        """Credibility level (e.g., 0.95 for 95% CI)."""
+        return 1 - self.alpha
+
+
+@dataclass
+class ForecastDistribution:
+    """
+    Predictive distribution for geopolitical forecast.
+
+    Attributes
+    ----------
+    variable_name : str
+        Name of forecasted variable
+    samples : np.ndarray
+        Samples from predictive distribution
+    time_horizon : int
+        Forecast horizon (days, months, etc.)
+    conditioning_info : Dict[str, Any]
+        Information conditioned on
+    """
+    variable_name: str
+    samples: np.ndarray
+    time_horizon: int
+    conditioning_info: Dict[str, Any] = field(default_factory=dict)
+
+    def point_forecast(self, method: str = 'mean') -> float:
+        """
+        Point forecast.
+
+        Parameters
+        ----------
+        method : str
+            'mean', 'median', or 'mode'
+
+        Returns
+        -------
+        float
+            Point forecast
+        """
+        if method == 'mean':
+            return float(np.mean(self.samples))
+        elif method == 'median':
+            return float(np.median(self.samples))
+        elif method == 'mode':
+            # Use kernel density estimation for mode
+            from scipy.stats import gaussian_kde
+            kde = gaussian_kde(self.samples)
+            x = np.linspace(self.samples.min(), self.samples.max(), 1000)
+            return float(x[np.argmax(kde(x))])
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+    def credible_interval(self, alpha: float = 0.05) -> CredibleInterval:
+        """
+        Compute credible interval.
+
+        Parameters
+        ----------
+        alpha : float
+            Significance level
+
+        Returns
+        -------
+        CredibleInterval
+            Credible interval
+        """
+        lower = float(np.quantile(self.samples, alpha / 2))
+        upper = float(np.quantile(self.samples, 1 - alpha / 2))
+        return CredibleInterval(lower=lower, upper=upper, alpha=alpha)
+
+    def probability_of_event(self, condition: Callable[[np.ndarray], np.ndarray]) -> float:
+        """
+        Probability of event defined by condition.
+
+        Parameters
+        ----------
+        condition : Callable
+            Function that returns True/False for each sample
+
+        Returns
+        -------
+        float
+            Probability
+        """
+        return float(np.mean(condition(self.samples)))
+
+
+class BayesianForecaster:
+    """
+    Bayesian forecasting engine for geopolitical analysis.
+
+    Integrates with GeoBot 2.0 analytical framework to provide
+    probabilistic forecasts with explicit uncertainty quantification.
+    """
+
+    def __init__(self):
+        """Initialize Bayesian forecaster."""
+        self.priors: Dict[str, GeopoliticalPrior] = {}
+        self.beliefs: Dict[str, BeliefState] = {}
+
+    def set_prior(self, prior: GeopoliticalPrior) -> None:
+        """
+        Set prior distribution for parameter.
+
+        Parameters
+        ----------
+        prior : GeopoliticalPrior
+            Prior distribution
+        """
+        self.priors[prior.parameter_name] = prior
+
+    def update_belief(
+        self,
+        parameter_name: str,
+        evidence: EvidenceUpdate,
+        n_samples: int = 10000,
+        method: str = 'importance_sampling'
+    ) -> BeliefState:
+        """
+        Update beliefs using Bayes' rule.
+
+        Parameters
+        ----------
+        parameter_name : str
+            Parameter to update
+        evidence : EvidenceUpdate
+            New evidence
+        n_samples : int
+            Number of samples for approximation
+        method : str
+            'importance_sampling' or 'rejection_sampling'
+
+        Returns
+        -------
+        BeliefState
+            Updated belief state
+        """
+        if parameter_name not in self.priors:
+            raise ValueError(f"No prior set for {parameter_name}")
+
+        # Get current prior or posterior
+        if parameter_name in self.beliefs:
+            # Use previous posterior as new prior
+            prior_samples = self.beliefs[parameter_name].posterior_samples
+        else:
+            # Use original prior
+            prior_samples = self.priors[parameter_name].sample(n_samples)
+
+        # Compute likelihoods
+        likelihoods = evidence.compute_likelihood(prior_samples)
+
+        if method == 'importance_sampling':
+            # Importance sampling with resampling
+            weights = likelihoods / np.sum(likelihoods)
+
+            # Resample according to weights
+            indices = np.random.choice(
+                len(prior_samples),
+                size=n_samples,
+                replace=True,
+                p=weights
+            )
+            posterior_samples = prior_samples[indices]
+
+        elif method == 'rejection_sampling':
+            # Rejection sampling
+            max_likelihood = np.max(likelihoods)
+            accepted = []
+
+            for sample, likelihood in zip(prior_samples, likelihoods):
+                if np.random.uniform(0, max_likelihood) < likelihood:
+                    accepted.append(sample)
+
+            if len(accepted) < 100:
+                raise ValueError("Rejection sampling failed - too few accepted samples")
+
+            posterior_samples = np.array(accepted)
+
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+        # Create or update belief state
+        if parameter_name in self.beliefs:
+            belief = self.beliefs[parameter_name]
+            belief.posterior_samples = posterior_samples
+            belief.evidence_history.append(evidence)
+        else:
+            belief = BeliefState(
+                parameter_name=parameter_name,
+                posterior_samples=posterior_samples,
+                prior=self.priors[parameter_name],
+                evidence_history=[evidence]
+            )
+
+        self.beliefs[parameter_name] = belief
+        return belief
+
+    def sequential_update(
+        self,
+        parameter_name: str,
+        evidence_sequence: List[EvidenceUpdate],
+        n_samples: int = 10000
+    ) -> BeliefState:
+        """
+        Sequential belief updating with multiple pieces of evidence.
+
+        Parameters
+        ----------
+        parameter_name : str
+            Parameter to update
+        evidence_sequence : List[EvidenceUpdate]
+            Sequence of evidence
+        n_samples : int
+            Number of samples
+
+        Returns
+        -------
+        BeliefState
+            Final belief state
+        """
+        for evidence in evidence_sequence:
+            self.update_belief(parameter_name, evidence, n_samples)
+
+        return self.beliefs[parameter_name]
+
+    def forecast(
+        self,
+        variable_name: str,
+        predictive_function: Callable[[Dict[str, float]], float],
+        time_horizon: int,
+        n_samples: int = 10000,
+        conditioning_info: Optional[Dict[str, Any]] = None
+    ) -> ForecastDistribution:
+        """
+        Generate probabilistic forecast.
+
+        Parameters
+        ----------
+        variable_name : str
+            Variable to forecast
+        predictive_function : Callable
+            Function mapping parameter values to prediction
+        time_horizon : int
+            Forecast horizon
+        n_samples : int
+            Number of forecast samples
+        conditioning_info : Optional[Dict[str, Any]]
+            Additional conditioning information
+
+        Returns
+        -------
+        ForecastDistribution
+            Forecast distribution
+        """
+        # Sample parameters from beliefs
+        parameter_samples = {}
+        for param_name, belief in self.beliefs.items():
+            indices = np.random.choice(len(belief.posterior_samples), size=n_samples)
+            parameter_samples[param_name] = belief.posterior_samples[indices]
+
+        # Generate forecasts
+        forecast_samples = np.zeros(n_samples)
+        for i in range(n_samples):
+            params = {name: samples[i] for name, samples in parameter_samples.items()}
+            forecast_samples[i] = predictive_function(params)
+
+        return ForecastDistribution(
+            variable_name=variable_name,
+            samples=forecast_samples,
+            time_horizon=time_horizon,
+            conditioning_info=conditioning_info or {}
+        )
+
+    def model_comparison(
+        self,
+        models: Dict[str, Callable],
+        evidence: List[EvidenceUpdate],
+        prior_model_probs: Optional[Dict[str, float]] = None
+    ) -> Dict[str, float]:
+        """
+        Bayesian model comparison using evidence.
+
+        Parameters
+        ----------
+        models : Dict[str, Callable]
+            Dictionary of models (name -> likelihood function)
+        evidence : List[EvidenceUpdate]
+            Evidence for comparison
+        prior_model_probs : Optional[Dict[str, float]]
+            Prior model probabilities
+
+        Returns
+        -------
+        Dict[str, float]
+            Posterior model probabilities
+        """
+        if prior_model_probs is None:
+            # Uniform prior over models
+            prior_model_probs = {name: 1.0 / len(models) for name in models}
+
+        # Compute marginal likelihoods (evidence)
+        marginal_likelihoods = {}
+
+        for model_name, model_fn in models.items():
+            # This is a simplified version - full implementation would
+            # integrate over parameter space
+            likelihood = 1.0
+            for ev in evidence:
+                # Assuming model_fn can compute likelihood
+                likelihood *= np.mean(ev.compute_likelihood(model_fn))
+
+            marginal_likelihoods[model_name] = likelihood
+
+        # Compute posterior model probabilities
+        posterior_probs = {}
+        total = 0.0
+
+        for model_name in models:
+            unnormalized = (prior_model_probs[model_name] *
+                          marginal_likelihoods[model_name])
+            posterior_probs[model_name] = unnormalized
+            total += unnormalized
+
+        # Normalize
+        for model_name in posterior_probs:
+            posterior_probs[model_name] /= total
+
+        return posterior_probs
+
+    def get_belief_summary(self, parameter_name: str) -> Dict[str, Any]:
+        """
+        Get summary statistics for belief state.
+
+        Parameters
+        ----------
+        parameter_name : str
+            Parameter name
+
+        Returns
+        -------
+        Dict[str, Any]
+            Summary statistics
+        """
+        if parameter_name not in self.beliefs:
+            raise ValueError(f"No beliefs for {parameter_name}")
+
+        belief = self.beliefs[parameter_name]
+        ci_95 = belief.credible_interval(alpha=0.05)
+        ci_90 = belief.credible_interval(alpha=0.10)
+
+        return {
+            'parameter': parameter_name,
+            'mean': belief.mean(),
+            'median': belief.median(),
+            'std': belief.std(),
+            '95%_CI': ci_95,
+            '90%_CI': ci_90,
+            'n_evidence_updates': len(belief.evidence_history),
+            'evidence_types': [ev.evidence_type.value for ev in belief.evidence_history]
+        }

geobot/causal/__init__.py

@@ -0,0 +1,23 @@
+"""
+Causal inference and structural causal models for GeoBotv1
+"""
+
+from .structural_model import (
+    StructuralCausalModel,
+    StructuralEquation,
+    Intervention,
+    Counterfactual,
+    CausalEffect,
+    IdentificationStrategy,
+    estimate_causal_effect
+)
+
+__all__ = [
+    "StructuralCausalModel",
+    "StructuralEquation",
+    "Intervention",
+    "Counterfactual",
+    "CausalEffect",
+    "IdentificationStrategy",
+    "estimate_causal_effect",
+]

geobot/causal/structural_model.py

@@ -0,0 +1,664 @@
+"""
+Structural Causal Models for GeoBotv1
+
+Implements Structural Causal Models (SCMs) for geopolitical analysis,
+intervention simulation, and counterfactual reasoning. Integrates with
+GeoBot 2.0 analytical framework.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional, Callable, Set, Tuple
+from enum import Enum
+import numpy as np
+import networkx as nx
+
+
+class IdentificationStrategy(Enum):
+    """Strategies for identifying causal effects."""
+    BACKDOOR_ADJUSTMENT = "backdoor"
+    FRONTDOOR_ADJUSTMENT = "frontdoor"
+    INSTRUMENTAL_VARIABLES = "iv"
+    DO_CALCULUS = "do_calculus"
+    STRUCTURAL_EQUATIONS = "structural"
+
+
+@dataclass
+class StructuralEquation:
+    """
+    Structural equation for a variable in SCM.
+
+    X := f(Pa_X, U_X)
+
+    Attributes
+    ----------
+    variable : str
+        Variable name
+    parents : List[str]
+        Parent variables in causal graph
+    function : Callable
+        Structural function f
+    noise_dist : Callable
+        Distribution of exogenous noise U_X
+    description : str
+        Description of equation
+    """
+    variable: str
+    parents: List[str]
+    function: Callable[[Dict[str, float]], float]
+    noise_dist: Callable[[int], np.ndarray]
+    description: str = ""
+
+    def evaluate(self, parent_values: Dict[str, float], noise: Optional[float] = None) -> float:
+        """
+        Evaluate structural equation.
+
+        Parameters
+        ----------
+        parent_values : Dict[str, float]
+            Values of parent variables
+        noise : Optional[float]
+            Noise value (if None, sample from distribution)
+
+        Returns
+        -------
+        float
+            Value of variable
+        """
+        if noise is None:
+            noise = self.noise_dist(1)[0]
+
+        return self.function(parent_values) + noise
+
+
+@dataclass
+class Intervention:
+    """
+    Causal intervention do(X = x).
+
+    Attributes
+    ----------
+    variable : str
+        Variable being intervened on
+    value : float
+        Value set by intervention
+    description : str
+        Description of intervention
+    """
+    variable: str
+    value: float
+    description: str = ""
+
+    def __repr__(self) -> str:
+        return f"do({self.variable} = {self.value})"
+
+
+@dataclass
+class Counterfactual:
+    """
+    Counterfactual query.
+
+    "What would Y be if we had done X = x, given that we observed Z = z?"
+
+    Attributes
+    ----------
+    query_variable : str
+        Variable being queried
+    intervention : Intervention
+        Counterfactual intervention
+    observations : Dict[str, float]
+        Observed values
+    """
+    query_variable: str
+    intervention: Intervention
+    observations: Dict[str, float] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        obs_str = ", ".join([f"{k}={v}" for k, v in self.observations.items()])
+        return f"{self.query_variable}_{{{self.intervention}}} | {obs_str}"
+
+
+@dataclass
+class CausalEffect:
+    """
+    Estimated causal effect.
+
+    Attributes
+    ----------
+    treatment : str
+        Treatment variable
+    outcome : str
+        Outcome variable
+    effect : float
+        Estimated average causal effect
+    std_error : Optional[float]
+        Standard error of estimate
+    confidence_interval : Optional[Tuple[float, float]]
+        Confidence interval
+    identification_strategy : IdentificationStrategy
+        How effect was identified
+    """
+    treatment: str
+    outcome: str
+    effect: float
+    std_error: Optional[float] = None
+    confidence_interval: Optional[Tuple[float, float]] = None
+    identification_strategy: Optional[IdentificationStrategy] = None
+
+    def __repr__(self) -> str:
+        ci_str = ""
+        if self.confidence_interval:
+            ci_str = f", 95% CI: {self.confidence_interval}"
+        return f"ACE({self.treatment} → {self.outcome}) = {self.effect:.3f}{ci_str}"
+
+
+class StructuralCausalModel:
+    """
+    Structural Causal Model for geopolitical analysis.
+
+    An SCM consists of:
+    1. Causal graph G (DAG)
+    2. Structural equations for each variable
+    3. Exogenous noise distributions
+
+    Enables:
+    - Intervention simulation (do-operator)
+    - Counterfactual reasoning
+    - Causal effect identification
+    """
+
+    def __init__(self, name: str = "GeopoliticalSCM"):
+        """
+        Initialize SCM.
+
+        Parameters
+        ----------
+        name : str
+            Name of SCM
+        """
+        self.name = name
+        self.graph = nx.DiGraph()
+        self.equations: Dict[str, StructuralEquation] = {}
+        self.exogenous_variables: Set[str] = set()
+
+    def add_equation(self, equation: StructuralEquation) -> None:
+        """
+        Add structural equation to model.
+
+        Parameters
+        ----------
+        equation : StructuralEquation
+            Structural equation
+        """
+        self.equations[equation.variable] = equation
+
+        # Add to graph
+        self.graph.add_node(equation.variable)
+        for parent in equation.parents:
+            self.graph.add_edge(parent, equation.variable)
+
+    def add_exogenous(self, variable: str, distribution: Callable[[int], np.ndarray]) -> None:
+        """
+        Add exogenous variable.
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+        distribution : Callable
+            Distribution for sampling
+        """
+        self.exogenous_variables.add(variable)
+        self.graph.add_node(variable)
+
+    def topological_order(self) -> List[str]:
+        """
+        Get topological ordering of variables.
+
+        Returns
+        -------
+        List[str]
+            Topologically sorted variables
+        """
+        try:
+            return list(nx.topological_sort(self.graph))
+        except nx.NetworkXError:
+            raise ValueError("Graph contains cycles - not a valid DAG")
+
+    def simulate(
+        self,
+        n_samples: int = 1000,
+        interventions: Optional[List[Intervention]] = None,
+        random_state: Optional[int] = None
+    ) -> Dict[str, np.ndarray]:
+        """
+        Simulate from SCM.
+
+        Parameters
+        ----------
+        n_samples : int
+            Number of samples
+        interventions : Optional[List[Intervention]]
+            Interventions to apply
+        random_state : Optional[int]
+            Random seed
+
+        Returns
+        -------
+        Dict[str, np.ndarray]
+            Simulated data for each variable
+        """
+        if random_state is not None:
+            np.random.seed(random_state)
+
+        # Intervention variables
+        intervention_dict = {}
+        if interventions:
+            intervention_dict = {iv.variable: iv.value for iv in interventions}
+
+        # Initialize data
+        data = {}
+
+        # Topological order
+        order = self.topological_order()
+
+        # Simulate each variable in order
+        for var in order:
+            if var in intervention_dict:
+                # Variable is intervened on - set to intervention value
+                data[var] = np.full(n_samples, intervention_dict[var])
+
+            elif var in self.exogenous_variables:
+                # Exogenous variable - sample from distribution
+                # For now, assume standard normal if not specified
+                data[var] = np.random.randn(n_samples)
+
+            elif var in self.equations:
+                # Endogenous variable - evaluate structural equation
+                eq = self.equations[var]
+                values = np.zeros(n_samples)
+
+                for i in range(n_samples):
+                    parent_vals = {p: data[p][i] for p in eq.parents}
+                    values[i] = eq.evaluate(parent_vals)
+
+                data[var] = values
+
+            else:
+                raise ValueError(f"No equation for variable {var}")
+
+        return data
+
+    def intervene(
+        self,
+        interventions: List[Intervention],
+        n_samples: int = 1000,
+        random_state: Optional[int] = None
+    ) -> Dict[str, np.ndarray]:
+        """
+        Simulate interventions using do-operator.
+
+        Parameters
+        ----------
+        interventions : List[Intervention]
+            Interventions to apply
+        n_samples : int
+            Number of samples
+        random_state : Optional[int]
+            Random seed
+
+        Returns
+        -------
+        Dict[str, np.ndarray]
+            Post-intervention data
+        """
+        return self.simulate(n_samples, interventions, random_state)
+
+    def estimate_causal_effect(
+        self,
+        treatment: str,
+        outcome: str,
+        n_samples: int = 10000,
+        treatment_values: Optional[List[float]] = None
+    ) -> CausalEffect:
+        """
+        Estimate average causal effect of treatment on outcome.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+        n_samples : int
+            Number of simulation samples
+        treatment_values : Optional[List[float]]
+            Treatment values to compare (default [0, 1])
+
+        Returns
+        -------
+        CausalEffect
+            Estimated causal effect
+        """
+        if treatment_values is None:
+            treatment_values = [0.0, 1.0]
+
+        # Simulate under different treatment values
+        outcomes = []
+        for t_val in treatment_values:
+            intervention = Intervention(variable=treatment, value=t_val)
+            data = self.intervene([intervention], n_samples)
+            outcomes.append(np.mean(data[outcome]))
+
+        # Average causal effect
+        ace = outcomes[1] - outcomes[0]
+
+        # Bootstrap for standard error
+        bootstrap_effects = []
+        for _ in range(100):
+            boot_outcomes = []
+            for t_val in treatment_values:
+                intervention = Intervention(variable=treatment, value=t_val)
+                data = self.intervene([intervention], n_samples=1000)
+                boot_outcomes.append(np.mean(data[outcome]))
+            bootstrap_effects.append(boot_outcomes[1] - boot_outcomes[0])
+
+        std_error = np.std(bootstrap_effects)
+        ci = (
+            ace - 1.96 * std_error,
+            ace + 1.96 * std_error
+        )
+
+        return CausalEffect(
+            treatment=treatment,
+            outcome=outcome,
+            effect=ace,
+            std_error=std_error,
+            confidence_interval=ci,
+            identification_strategy=IdentificationStrategy.STRUCTURAL_EQUATIONS
+        )
+
+    def counterfactual_query(
+        self,
+        query: Counterfactual,
+        n_samples: int = 10000
+    ) -> Dict[str, Any]:
+        """
+        Answer counterfactual query.
+
+        Three-step process:
+        1. Abduction: Infer exogenous variables from observations
+        2. Action: Apply intervention
+        3. Prediction: Compute outcome
+
+        Parameters
+        ----------
+        query : Counterfactual
+            Counterfactual query
+        n_samples : int
+            Number of samples for approximation
+
+        Returns
+        -------
+        Dict[str, Any]
+            Counterfactual results
+        """
+        # Simplified counterfactual reasoning
+        # Full implementation would do proper abduction step
+
+        # For now, simulate with intervention
+        data = self.intervene([query.intervention], n_samples)
+
+        return {
+            'query': str(query),
+            'expected_value': float(np.mean(data[query.query_variable])),
+            'std': float(np.std(data[query.query_variable])),
+            'median': float(np.median(data[query.query_variable])),
+            'quantiles': {
+                '5%': float(np.quantile(data[query.query_variable], 0.05)),
+                '25%': float(np.quantile(data[query.query_variable], 0.25)),
+                '75%': float(np.quantile(data[query.query_variable], 0.75)),
+                '95%': float(np.quantile(data[query.query_variable], 0.95)),
+            }
+        }
+
+    def find_backdoor_paths(self, treatment: str, outcome: str) -> List[List[str]]:
+        """
+        Find backdoor paths from treatment to outcome.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+
+        Returns
+        -------
+        List[List[str]]
+            List of backdoor paths
+        """
+        # Create undirected version of graph
+        undirected = self.graph.to_undirected()
+
+        # Find all paths
+        try:
+            all_paths = list(nx.all_simple_paths(undirected, treatment, outcome))
+        except nx.NodeNotFound:
+            return []
+
+        # Filter for backdoor paths (paths that go through parent of treatment)
+        backdoor_paths = []
+        treatment_parents = set(self.graph.predecessors(treatment))
+
+        for path in all_paths:
+            # Check if path starts with an edge into treatment
+            if len(path) > 1 and path[1] in treatment_parents:
+                backdoor_paths.append(path)
+
+        return backdoor_paths
+
+    def find_backdoor_adjustment_set(
+        self,
+        treatment: str,
+        outcome: str
+    ) -> Optional[Set[str]]:
+        """
+        Find minimal backdoor adjustment set.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+
+        Returns
+        -------
+        Optional[Set[str]]
+            Backdoor adjustment set, or None if no valid set exists
+        """
+        backdoor_paths = self.find_backdoor_paths(treatment, outcome)
+
+        if not backdoor_paths:
+            return set()  # No backdoor paths, empty set suffices
+
+        # Find minimal set that blocks all backdoor paths
+        # This is simplified - full implementation would use
+        # proper d-separation testing
+
+        # Collect all variables in backdoor paths
+        candidates = set()
+        for path in backdoor_paths:
+            candidates.update(path[1:-1])  # Exclude treatment and outcome
+
+        # Remove descendants of treatment (would create bias)
+        treatment_descendants = nx.descendants(self.graph, treatment)
+        candidates -= treatment_descendants
+
+        return candidates
+
+    def plot_graph(self, filename: Optional[str] = None) -> None:
+        """
+        Plot causal graph.
+
+        Parameters
+        ----------
+        filename : Optional[str]
+            File to save plot to
+        """
+        try:
+            import matplotlib.pyplot as plt
+
+            pos = nx.spring_layout(self.graph)
+            nx.draw(
+                self.graph,
+                pos,
+                with_labels=True,
+                node_color='lightblue',
+                node_size=1500,
+                font_size=10,
+                font_weight='bold',
+                arrows=True,
+                arrowsize=20
+            )
+
+            if filename:
+                plt.savefig(filename)
+            else:
+                plt.show()
+
+        except ImportError:
+            print("matplotlib not available for plotting")
+
+
+def estimate_causal_effect(
+    scm: StructuralCausalModel,
+    treatment: str,
+    outcome: str,
+    adjustment_set: Optional[Set[str]] = None,
+    n_samples: int = 10000
+) -> CausalEffect:
+    """
+    Estimate causal effect using appropriate identification strategy.
+
+    Parameters
+    ----------
+    scm : StructuralCausalModel
+        Structural causal model
+    treatment : str
+        Treatment variable
+    outcome : str
+        Outcome variable
+    adjustment_set : Optional[Set[str]]
+        Variables to adjust for (if None, use backdoor criterion)
+    n_samples : int
+        Number of samples
+
+    Returns
+    -------
+    CausalEffect
+        Estimated causal effect
+    """
+    # Find adjustment set if not provided
+    if adjustment_set is None:
+        adjustment_set = scm.find_backdoor_adjustment_set(treatment, outcome)
+
+        if adjustment_set is None:
+            # Try frontdoor or IV
+            raise ValueError("Cannot identify causal effect - no valid adjustment set")
+
+    # Use structural equations for direct estimation
+    return scm.estimate_causal_effect(treatment, outcome, n_samples)
+
+
+# ============================================================================
+# Predefined SCMs for Geopolitical Analysis
+# ============================================================================
+
+def create_sanctions_scm() -> StructuralCausalModel:
+    """
+    Create SCM for sanctions analysis.
+
+    Variables:
+    - sanctions: Binary sanctions imposed
+    - trade_disruption: Trade flow disruption
+    - economic_growth: Economic growth rate
+    - regime_stability: Regime stability score
+
+    Returns
+    -------
+    StructuralCausalModel
+        Sanctions SCM
+    """
+    scm = StructuralCausalModel(name="SanctionsSCM")
+
+    # Exogenous noise (simplified as standard normal)
+    noise_dist = lambda n: np.random.randn(n) * 0.1
+
+    # Trade disruption = f(sanctions) + noise
+    scm.add_equation(StructuralEquation(
+        variable="trade_disruption",
+        parents=["sanctions"],
+        function=lambda p: 0.7 * p["sanctions"],
+        noise_dist=noise_dist,
+        description="Sanctions directly reduce trade"
+    ))
+
+    # Economic growth = f(trade_disruption) + noise
+    scm.add_equation(StructuralEquation(
+        variable="economic_growth",
+        parents=["trade_disruption"],
+        function=lambda p: 0.05 - 0.4 * p["trade_disruption"],
+        noise_dist=noise_dist,
+        description="Trade disruption reduces growth"
+    ))
+
+    # Regime stability = f(economic_growth) + noise
+    scm.add_equation(StructuralEquation(
+        variable="regime_stability",
+        parents=["economic_growth"],
+        function=lambda p: 0.7 + 0.5 * p["economic_growth"],
+        noise_dist=noise_dist,
+        description="Economic growth affects regime stability"
+    ))
+
+    return scm
+
+
+def create_conflict_escalation_scm() -> StructuralCausalModel:
+    """
+    Create SCM for conflict escalation.
+
+    Variables:
+    - military_buildup: Military force buildup
+    - diplomatic_tension: Diplomatic relations tension
+    - conflict_risk: Risk of armed conflict
+
+    Returns
+    -------
+    StructuralCausalModel
+        Conflict escalation SCM
+    """
+    scm = StructuralCausalModel(name="ConflictEscalationSCM")
+
+    noise_dist = lambda n: np.random.randn(n) * 0.05
+
+    # Diplomatic tension = f(military_buildup) + noise
+    scm.add_equation(StructuralEquation(
+        variable="diplomatic_tension",
+        parents=["military_buildup"],
+        function=lambda p: 0.3 + 0.6 * p["military_buildup"],
+        noise_dist=noise_dist,
+        description="Military buildup increases diplomatic tension"
+    ))
+
+    # Conflict risk = f(military_buildup, diplomatic_tension) + noise
+    scm.add_equation(StructuralEquation(
+        variable="conflict_risk",
+        parents=["military_buildup", "diplomatic_tension"],
+        function=lambda p: 0.1 + 0.4 * p["military_buildup"] + 0.3 * p["diplomatic_tension"],
+        noise_dist=noise_dist,
+        description="Both military buildup and tension increase conflict risk"
+    ))
+
+    return scm

geobot/cli.py

@@ -0,0 +1,6 @@
+def main():
+    """
+    Temporary CLI stub for GeoBotv1.
+    This just proves the package and entry point are wired up correctly.
+    """
+    print("GeoBotv1 CLI is installed and reachable. (Stub CLI for now.)")

geobot/config/__init__.py

@@ -0,0 +1,11 @@
+"""
+Configuration management for GeoBotv1
+"""
+
+from .settings import Settings, get_settings, update_settings
+
+__all__ = [
+    "Settings",
+    "get_settings",
+    "update_settings",
+]

geobot/config/settings.py

@@ -0,0 +1,183 @@
+"""
+Settings and configuration for GeoBotv1
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional
+import yaml
+from pathlib import Path
+
+
+@dataclass
+class Settings:
+    """
+    Global settings for GeoBotv1.
+    """
+    # Simulation settings
+    default_n_simulations: int = 1000
+    default_time_horizon: int = 100
+    random_seed: Optional[int] = None
+
+    # Data ingestion settings
+    pdf_extraction_method: str = 'auto'
+    web_scraping_timeout: int = 30
+    article_extraction_method: str = 'auto'
+
+    # ML settings
+    risk_scoring_method: str = 'gradient_boosting'
+    embedding_model: str = 'sentence-transformers/all-MiniLM-L6-v2'
+
+    # Bayesian inference settings
+    bayesian_method: str = 'grid'
+    n_mcmc_samples: int = 10000
+
+    # Causal inference settings
+    causal_discovery_method: str = 'pc'
+    causal_discovery_alpha: float = 0.05
+
+    # Data directories
+    data_dir: str = 'data'
+    cache_dir: str = '.cache'
+    output_dir: str = 'output'
+
+    # Logging
+    log_level: str = 'INFO'
+    log_file: Optional[str] = None
+
+    # Custom settings
+    custom: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert settings to dictionary."""
+        return {
+            'simulation': {
+                'default_n_simulations': self.default_n_simulations,
+                'default_time_horizon': self.default_time_horizon,
+                'random_seed': self.random_seed
+            },
+            'data_ingestion': {
+                'pdf_extraction_method': self.pdf_extraction_method,
+                'web_scraping_timeout': self.web_scraping_timeout,
+                'article_extraction_method': self.article_extraction_method
+            },
+            'ml': {
+                'risk_scoring_method': self.risk_scoring_method,
+                'embedding_model': self.embedding_model
+            },
+            'bayesian': {
+                'method': self.bayesian_method,
+                'n_mcmc_samples': self.n_mcmc_samples
+            },
+            'causal': {
+                'discovery_method': self.causal_discovery_method,
+                'discovery_alpha': self.causal_discovery_alpha
+            },
+            'directories': {
+                'data_dir': self.data_dir,
+                'cache_dir': self.cache_dir,
+                'output_dir': self.output_dir
+            },
+            'logging': {
+                'log_level': self.log_level,
+                'log_file': self.log_file
+            },
+            'custom': self.custom
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Settings':
+        """Load settings from dictionary."""
+        settings = cls()
+
+        if 'simulation' in data:
+            settings.default_n_simulations = data['simulation'].get('default_n_simulations', 1000)
+            settings.default_time_horizon = data['simulation'].get('default_time_horizon', 100)
+            settings.random_seed = data['simulation'].get('random_seed')
+
+        if 'data_ingestion' in data:
+            settings.pdf_extraction_method = data['data_ingestion'].get('pdf_extraction_method', 'auto')
+            settings.web_scraping_timeout = data['data_ingestion'].get('web_scraping_timeout', 30)
+            settings.article_extraction_method = data['data_ingestion'].get('article_extraction_method', 'auto')
+
+        if 'ml' in data:
+            settings.risk_scoring_method = data['ml'].get('risk_scoring_method', 'gradient_boosting')
+            settings.embedding_model = data['ml'].get('embedding_model', 'sentence-transformers/all-MiniLM-L6-v2')
+
+        if 'bayesian' in data:
+            settings.bayesian_method = data['bayesian'].get('method', 'grid')
+            settings.n_mcmc_samples = data['bayesian'].get('n_mcmc_samples', 10000)
+
+        if 'causal' in data:
+            settings.causal_discovery_method = data['causal'].get('discovery_method', 'pc')
+            settings.causal_discovery_alpha = data['causal'].get('discovery_alpha', 0.05)
+
+        if 'directories' in data:
+            settings.data_dir = data['directories'].get('data_dir', 'data')
+            settings.cache_dir = data['directories'].get('cache_dir', '.cache')
+            settings.output_dir = data['directories'].get('output_dir', 'output')
+
+        if 'logging' in data:
+            settings.log_level = data['logging'].get('log_level', 'INFO')
+            settings.log_file = data['logging'].get('log_file')
+
+        if 'custom' in data:
+            settings.custom = data['custom']
+
+        return settings
+
+    def save(self, path: str) -> None:
+        """Save settings to YAML file."""
+        with open(path, 'w') as f:
+            yaml.dump(self.to_dict(), f, default_flow_style=False)
+
+    @classmethod
+    def load(cls, path: str) -> 'Settings':
+        """Load settings from YAML file."""
+        with open(path, 'r') as f:
+            data = yaml.safe_load(f)
+        return cls.from_dict(data)
+
+
+# Global settings instance
+_global_settings: Optional[Settings] = None
+
+
+def get_settings() -> Settings:
+    """
+    Get global settings instance.
+
+    Returns
+    -------
+    Settings
+        Global settings
+    """
+    global _global_settings
+    if _global_settings is None:
+        _global_settings = Settings()
+    return _global_settings
+
+
+def update_settings(settings: Settings) -> None:
+    """
+    Update global settings.
+
+    Parameters
+    ----------
+    settings : Settings
+        New settings
+    """
+    global _global_settings
+    _global_settings = settings
+
+
+def load_settings_from_file(path: str) -> None:
+    """
+    Load settings from file and update global settings.
+
+    Parameters
+    ----------
+    path : str
+        Path to settings file
+    """
+    settings = Settings.load(path)
+    update_settings(settings)

geobot/core/__init__.py

@@ -0,0 +1,25 @@
+"""
+Core mathematical frameworks for GeoBotv1
+"""
+
+from .optimal_transport import WassersteinDistance, ScenarioComparator
+from .scenario import Scenario, ScenarioDistribution
+from .advanced_optimal_transport import (
+    GradientBasedOT,
+    KantorovichDuality,
+    EntropicOT,
+    UnbalancedOT,
+    GromovWassersteinDistance
+)
+
+__all__ = [
+    "WassersteinDistance",
+    "ScenarioComparator",
+    "Scenario",
+    "ScenarioDistribution",
+    "GradientBasedOT",
+    "KantorovichDuality",
+    "EntropicOT",
+    "UnbalancedOT",
+    "GromovWassersteinDistance",
+]

geobot/core/advanced_optimal_transport.py

@@ -0,0 +1,653 @@
+"""
+Advanced Optimal Transport with Gradient-Based Methods
+
+Implements sophisticated optimal transport algorithms:
+- Gradient-based OT with automatic differentiation
+- Kantorovich duality formulation
+- Sinkhorn with entropic regularization (tunable ε)
+- Wasserstein barycenters
+- Gromov-Wasserstein distance
+- Unbalanced optimal transport
+
+Provides geometric insights on the space of probability measures
+and leverages gradient flows for OT computations.
+"""
+
+import numpy as np
+from typing import Tuple, Optional, Callable, List
+from scipy.optimize import minimize
+from scipy.spatial.distance import cdist
+
+try:
+    import ot as pot
+    HAS_POT = True
+except ImportError:
+    HAS_POT = False
+
+
+class GradientBasedOT:
+    """
+    Gradient-based optimal transport using automatic differentiation.
+
+    Solves the Monge-Kantorovich problem:
+    min_γ ∈ Π(μ,ν) ⟨γ, C⟩
+
+    using gradient-based optimization on the dual problem or
+    on parametric transport maps.
+    """
+
+    def __init__(self, cost_fn: Optional[Callable] = None):
+        """
+        Initialize gradient-based OT.
+
+        Parameters
+        ----------
+        cost_fn : callable, optional
+            Cost function c(x, y). Defaults to squared Euclidean distance.
+        """
+        self.cost_fn = cost_fn or (lambda x, y: np.sum((x - y)**2))
+
+    def compute_transport_map(
+        self,
+        X_source: np.ndarray,
+        X_target: np.ndarray,
+        method: str = 'gradient',
+        reg: float = 0.1,
+        n_iter: int = 100
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Compute optimal transport map via gradient descent.
+
+        For Monge formulation: min_T E[c(x, T(x))]
+
+        Parameters
+        ----------
+        X_source : np.ndarray, shape (n, d)
+            Source samples
+        X_target : np.ndarray, shape (m, d)
+            Target samples
+        method : str
+            Method ('gradient', 'dual')
+        reg : float
+            Regularization parameter
+        n_iter : int
+            Number of iterations
+
+        Returns
+        -------
+        tuple
+            (transport_map, cost)
+        """
+        n_source, d = X_source.shape
+        n_target = X_target.shape[0]
+
+        if method == 'gradient':
+            # Parametrize transport map as T(x) = x + displacement
+            displacement = np.zeros_like(X_source)
+
+            learning_rate = 0.01
+
+            for iteration in range(n_iter):
+                # Compute transported points
+                X_transported = X_source + displacement
+
+                # Find nearest neighbors in target (assignment)
+                distances = cdist(X_transported, X_target)
+                assignments = np.argmin(distances, axis=1)
+
+                # Compute cost
+                cost = np.mean([
+                    self.cost_fn(X_transported[i], X_target[assignments[i]])
+                    for i in range(n_source)
+                ])
+
+                # Gradient (simplified - would use autograd)
+                gradient = np.zeros_like(displacement)
+                for i in range(n_source):
+                    gradient[i] = 2 * (X_transported[i] - X_target[assignments[i]])
+
+                # Regularization
+                gradient += reg * displacement
+
+                # Update
+                displacement -= learning_rate * gradient
+
+                if iteration % 20 == 0:
+                    print(f"Iteration {iteration}, Cost: {cost:.6f}")
+
+            return displacement, cost
+
+        elif method == 'dual':
+            return self._solve_dual_problem(X_source, X_target, reg)
+
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+    def _solve_dual_problem(
+        self,
+        X_source: np.ndarray,
+        X_target: np.ndarray,
+        reg: float
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Solve dual OT problem.
+
+        Dual formulation (Kantorovich):
+        max_{f,g} E_μ[f(x)] + E_ν[g(y)]
+        s.t. f(x) + g(y) ≤ c(x,y)
+
+        Parameters
+        ----------
+        X_source : np.ndarray
+            Source points
+        X_target : np.ndarray
+            Target points
+        reg : float
+            Regularization
+
+        Returns
+        -------
+        tuple
+            (potentials, cost)
+        """
+        n_source = len(X_source)
+        n_target = len(X_target)
+
+        # Cost matrix
+        C = cdist(X_source, X_target, metric='sqeuclidean')
+
+        # Solve via constrained optimization
+        # Variables: [f (n_source), g (n_target)]
+        n_vars = n_source + n_target
+
+        def objective(x):
+            f = x[:n_source]
+            g = x[n_source:]
+            return -(np.mean(f) + np.mean(g))  # Negative for minimization
+
+        def constraint(x):
+            f = x[:n_source]
+            g = x[n_source:]
+            # f(x_i) + g(y_j) - c(x_i, y_j) ≤ 0
+            return C - (f[:, np.newaxis] + g[np.newaxis, :])
+
+        from scipy.optimize import NonlinearConstraint
+        nlc = NonlinearConstraint(
+            lambda x: constraint(x).flatten(),
+            -np.inf,
+            0
+        )
+
+        x0 = np.zeros(n_vars)
+        result = minimize(objective, x0, constraints=nlc, method='SLSQP')
+
+        f_opt = result.x[:n_source]
+        g_opt = result.x[n_source:]
+
+        cost = -result.fun
+
+        return np.column_stack([f_opt, g_opt]), cost
+
+
+class KantorovichDuality:
+    """
+    Kantorovich duality formulation for optimal transport.
+
+    Primal: min_γ ∈ Π(μ,ν) ∫∫ c(x,y) dγ(x,y)
+
+    Dual: max_{f,g} ∫ f dμ + ∫ g dν
+          s.t. f(x) + g(y) ≤ c(x,y)
+
+    Strong duality holds under mild conditions.
+    """
+
+    def __init__(self):
+        """Initialize Kantorovich duality solver."""
+        pass
+
+    def solve_primal(
+        self,
+        mu: np.ndarray,
+        nu: np.ndarray,
+        C: np.ndarray,
+        method: str = 'emd'
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Solve primal OT problem.
+
+        Parameters
+        ----------
+        mu : np.ndarray
+            Source distribution weights
+        nu : np.ndarray
+            Target distribution weights
+        C : np.ndarray
+            Cost matrix
+        method : str
+            Method ('emd', 'sinkhorn')
+
+        Returns
+        -------
+        tuple
+            (coupling, cost)
+        """
+        if not HAS_POT:
+            raise ImportError("POT library required")
+
+        if method == 'emd':
+            coupling = pot.emd(mu, nu, C)
+        elif method == 'sinkhorn':
+            coupling = pot.sinkhorn(mu, nu, C, reg=0.1)
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+        cost = np.sum(coupling * C)
+        return coupling, cost
+
+    def solve_dual(
+        self,
+        mu: np.ndarray,
+        nu: np.ndarray,
+        C: np.ndarray,
+        max_iter: int = 1000,
+        tol: float = 1e-6
+    ) -> Tuple[np.ndarray, np.ndarray, float]:
+        """
+        Solve dual OT problem via iterative Bregman projections.
+
+        Parameters
+        ----------
+        mu : np.ndarray
+            Source weights
+        nu : np.ndarray
+            Target weights
+        C : np.ndarray
+            Cost matrix
+        max_iter : int
+            Maximum iterations
+        tol : float
+            Convergence tolerance
+
+        Returns
+        -------
+        tuple
+            (f, g, dual_value) where f, g are dual potentials
+        """
+        n = len(mu)
+        m = len(nu)
+
+        # Initialize dual variables (Kantorovich potentials)
+        f = np.zeros(n)
+        g = np.zeros(m)
+
+        for iteration in range(max_iter):
+            # Update g (c-transform of f)
+            # g(y) = min_x [c(x,y) - f(x)]
+            g_new = np.min(C - f[:, np.newaxis], axis=0)
+
+            # Update f (c-transform of g)
+            # f(x) = min_y [c(x,y) - g(y)]
+            f_new = np.min(C - g_new[np.newaxis, :], axis=1)
+
+            # Check convergence
+            if np.max(np.abs(f_new - f)) < tol and np.max(np.abs(g_new - g)) < tol:
+                break
+
+            f, g = f_new, g_new
+
+        # Dual value
+        dual_value = np.dot(f, mu) + np.dot(g, nu)
+
+        return f, g, dual_value
+
+    def verify_duality_gap(
+        self,
+        mu: np.ndarray,
+        nu: np.ndarray,
+        C: np.ndarray
+    ) -> float:
+        """
+        Verify strong duality: primal_cost - dual_cost ≈ 0.
+
+        Parameters
+        ----------
+        mu : np.ndarray
+            Source weights
+        nu : np.ndarray
+            Target weights
+        C : np.ndarray
+            Cost matrix
+
+        Returns
+        -------
+        float
+            Duality gap
+        """
+        # Solve primal
+        coupling, primal_cost = self.solve_primal(mu, nu, C)
+
+        # Solve dual
+        f, g, dual_value = self.solve_dual(mu, nu, C)
+
+        gap = primal_cost - dual_value
+        return gap
+
+
+class EntropicOT:
+    """
+    Entropic optimal transport with Sinkhorn algorithm.
+
+    Regularized OT:
+    min_γ ∈ Π(μ,ν) ⟨γ, C⟩ + ε H(γ)
+
+    where H(γ) = - ∑_ij γ_ij log γ_ij is entropy.
+
+    Sinkhorn iterations converge geometrically fast.
+    """
+
+    def __init__(self, epsilon: float = 0.1):
+        """
+        Initialize entropic OT.
+
+        Parameters
+        ----------
+        epsilon : float
+            Entropic regularization parameter
+        """
+        self.epsilon = epsilon
+
+    def sinkhorn(
+        self,
+        mu: np.ndarray,
+        nu: np.ndarray,
+        C: np.ndarray,
+        max_iter: int = 1000,
+        tol: float = 1e-6
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Sinkhorn algorithm for entropic OT.
+
+        Parameters
+        ----------
+        mu : np.ndarray
+            Source distribution
+        nu : np.ndarray
+            Target distribution
+        C : np.ndarray
+            Cost matrix
+        max_iter : int
+            Maximum iterations
+        tol : float
+            Convergence tolerance
+
+        Returns
+        -------
+        tuple
+            (coupling, cost)
+        """
+        n, m = C.shape
+
+        # Kernel matrix
+        K = np.exp(-C / self.epsilon)
+
+        # Initialize scaling vectors
+        u = np.ones(n) / n
+        v = np.ones(m) / m
+
+        for iteration in range(max_iter):
+            u_prev = u.copy()
+
+            # Update u
+            u = mu / (K @ v)
+
+            # Update v
+            v = nu / (K.T @ u)
+
+            # Check convergence
+            if np.max(np.abs(u - u_prev)) < tol:
+                break
+
+        # Compute coupling
+        coupling = u[:, np.newaxis] * K * v[np.newaxis, :]
+
+        # Compute cost
+        cost = np.sum(coupling * C)
+
+        return coupling, cost
+
+    def sinkhorn_log_stabilized(
+        self,
+        mu: np.ndarray,
+        nu: np.ndarray,
+        C: np.ndarray,
+        max_iter: int = 1000,
+        tol: float = 1e-6
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Log-stabilized Sinkhorn algorithm (more numerically stable).
+
+        Works in log-domain to avoid overflow/underflow.
+
+        Parameters
+        ----------
+        mu : np.ndarray
+            Source distribution
+        nu : np.ndarray
+            Target distribution
+        C : np.ndarray
+            Cost matrix
+        max_iter : int
+            Maximum iterations
+        tol : float
+            Tolerance
+
+        Returns
+        -------
+        tuple
+            (coupling, cost)
+        """
+        n, m = C.shape
+
+        # Log-domain variables
+        log_mu = np.log(mu)
+        log_nu = np.log(nu)
+
+        # Initialize
+        f = np.zeros(n)
+        g = np.zeros(m)
+
+        for iteration in range(max_iter):
+            f_prev = f.copy()
+
+            # Update f
+            f = -self.epsilon * self._log_sum_exp(
+                (g[np.newaxis, :] - C) / self.epsilon,
+                axis=1
+            ) + log_mu + self.epsilon * np.log(n)
+
+            # Update g
+            g = -self.epsilon * self._log_sum_exp(
+                (f[:, np.newaxis] - C) / self.epsilon,
+                axis=0
+            ) + log_nu + self.epsilon * np.log(m)
+
+            # Check convergence
+            if np.max(np.abs(f - f_prev)) < tol:
+                break
+
+        # Compute coupling (in log domain, then exp)
+        log_coupling = (f[:, np.newaxis] + g[np.newaxis, :] - C) / self.epsilon
+        coupling = np.exp(log_coupling)
+
+        # Normalize
+        coupling = coupling / np.sum(coupling)
+
+        cost = np.sum(coupling * C)
+
+        return coupling, cost
+
+    def _log_sum_exp(self, X: np.ndarray, axis: int) -> np.ndarray:
+        """
+        Numerically stable log-sum-exp.
+
+        log(∑ exp(X_i)) computed stably.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Input array
+        axis : int
+            Axis to sum over
+
+        Returns
+        -------
+        np.ndarray
+            log-sum-exp result
+        """
+        max_X = np.max(X, axis=axis, keepdims=True)
+        return np.log(np.sum(np.exp(X - max_X), axis=axis)) + np.squeeze(max_X, axis=axis)
+
+
+class UnbalancedOT:
+    """
+    Unbalanced optimal transport.
+
+    Relaxes the marginal constraints, allowing mass creation/destruction.
+    Useful when distributions don't have same total mass.
+
+    Formulation:
+    min_γ ⟨γ, C⟩ + ε H(γ) + τ KL(γ1_m | μ) + τ KL(γ^T1_n | ν)
+
+    where KL is Kullback-Leibler divergence.
+    """
+
+    def __init__(self, epsilon: float = 0.1, tau: float = 0.1):
+        """
+        Initialize unbalanced OT.
+
+        Parameters
+        ----------
+        epsilon : float
+            Entropic regularization
+        tau : float
+            Marginal relaxation parameter
+        """
+        self.epsilon = epsilon
+        self.tau = tau
+
+    def solve(
+        self,
+        mu: np.ndarray,
+        nu: np.ndarray,
+        C: np.ndarray,
+        max_iter: int = 1000
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Solve unbalanced OT via Sinkhorn-Knopp algorithm.
+
+        Parameters
+        ----------
+        mu : np.ndarray
+            Source (unbalanced) distribution
+        nu : np.ndarray
+            Target (unbalanced) distribution
+        C : np.ndarray
+            Cost matrix
+        max_iter : int
+            Maximum iterations
+
+        Returns
+        -------
+        tuple
+            (coupling, cost)
+        """
+        if not HAS_POT:
+            raise ImportError("POT library required for unbalanced OT")
+
+        # Use POT's unbalanced solver
+        coupling = pot.unbalanced.sinkhorn_unbalanced(
+            mu, nu, C,
+            reg=self.epsilon,
+            reg_m=self.tau,
+            numItermax=max_iter
+        )
+
+        cost = np.sum(coupling * C)
+
+        return coupling, cost
+
+
+class GromovWassersteinDistance:
+    """
+    Gromov-Wasserstein distance for comparing metric spaces.
+
+    Useful when we want to compare structures (graphs, networks)
+    rather than points in a common space.
+    """
+
+    def __init__(self, epsilon: float = 0.1):
+        """
+        Initialize Gromov-Wasserstein.
+
+        Parameters
+        ----------
+        epsilon : float
+            Entropic regularization
+        """
+        self.epsilon = epsilon
+
+    def compute(
+        self,
+        C1: np.ndarray,
+        C2: np.ndarray,
+        p: Optional[np.ndarray] = None,
+        q: Optional[np.ndarray] = None,
+        loss_fun: str = 'square_loss',
+        max_iter: int = 100
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Compute Gromov-Wasserstein distance.
+
+        Parameters
+        ----------
+        C1 : np.ndarray
+            Intra-space cost matrix for space 1
+        C2 : np.ndarray
+            Intra-space cost matrix for space 2
+        p : np.ndarray, optional
+            Distribution on space 1
+        q : np.ndarray, optional
+            Distribution on space 2
+        loss_fun : str
+            Loss function
+        max_iter : int
+            Maximum iterations
+
+        Returns
+        -------
+        tuple
+            (coupling, GW_distance)
+        """
+        if not HAS_POT:
+            raise ImportError("POT library required for Gromov-Wasserstein")
+
+        n1, n2 = C1.shape[0], C2.shape[0]
+
+        # Default uniform distributions
+        if p is None:
+            p = np.ones(n1) / n1
+        if q is None:
+            q = np.ones(n2) / n2
+
+        # Compute Gromov-Wasserstein
+        gw_dist, log = pot.gromov.entropic_gromov_wasserstein(
+            C1, C2, p, q,
+            loss_fun=loss_fun,
+            epsilon=self.epsilon,
+            max_iter=max_iter,
+            log=True
+        )
+
+        coupling = log['T']
+
+        return coupling, gw_dist

geobot/core/optimal_transport.py

@@ -0,0 +1,360 @@
+"""
+Optimal Transport Module - Wasserstein Distances
+
+Provides geometric measures of how much "effort" is needed to move from
+one geopolitical scenario to another using optimal transport theory.
+
+Applications:
+- Measure regime shifts
+- Compare distributions of Monte Carlo futures
+- Quantify shock impact
+- Measure closeness of geopolitical scenarios
+- Detect structural change
+- Logistics modeling
+"""
+
+import numpy as np
+from typing import Union, Tuple, Optional, List
+from scipy.spatial.distance import cdist
+from scipy.stats import wasserstein_distance
+
+try:
+    import ot  # Python Optimal Transport library
+    HAS_POT = True
+except ImportError:
+    HAS_POT = False
+    print("Warning: POT library not available. Some features will be limited.")
+
+
+class WassersteinDistance:
+    """
+    Compute Wasserstein distances between probability distributions.
+
+    The Wasserstein distance (also known as Earth Mover's Distance) provides
+    a principled way to measure the distance between probability distributions,
+    accounting for the geometry of the underlying space.
+    """
+
+    def __init__(self, metric: str = 'euclidean', p: int = 2):
+        """
+        Initialize Wasserstein distance calculator.
+
+        Parameters
+        ----------
+        metric : str
+            Distance metric to use for ground distance ('euclidean', 'cityblock', etc.)
+        p : int
+            Order of Wasserstein distance (1 or 2)
+        """
+        self.metric = metric
+        self.p = p
+
+    def compute_1d(
+        self,
+        u_values: np.ndarray,
+        v_values: np.ndarray,
+        u_weights: Optional[np.ndarray] = None,
+        v_weights: Optional[np.ndarray] = None
+    ) -> float:
+        """
+        Compute 1D Wasserstein distance between two distributions.
+
+        Parameters
+        ----------
+        u_values : np.ndarray
+            Values for first distribution
+        v_values : np.ndarray
+            Values for second distribution
+        u_weights : np.ndarray, optional
+            Weights for first distribution (defaults to uniform)
+        v_weights : np.ndarray, optional
+            Weights for second distribution (defaults to uniform)
+
+        Returns
+        -------
+        float
+            Wasserstein distance
+        """
+        return wasserstein_distance(u_values, v_values, u_weights, v_weights)
+
+    def compute_nd(
+        self,
+        X_source: np.ndarray,
+        X_target: np.ndarray,
+        a: Optional[np.ndarray] = None,
+        b: Optional[np.ndarray] = None,
+        method: str = 'sinkhorn'
+    ) -> float:
+        """
+        Compute n-dimensional Wasserstein distance.
+
+        Parameters
+        ----------
+        X_source : np.ndarray, shape (n_samples_source, n_features)
+            Source distribution samples
+        X_target : np.ndarray, shape (n_samples_target, n_features)
+            Target distribution samples
+        a : np.ndarray, optional
+            Weights for source distribution (defaults to uniform)
+        b : np.ndarray, optional
+            Weights for target distribution (defaults to uniform)
+        method : str
+            Method to use ('sinkhorn', 'emd', 'emd2')
+
+        Returns
+        -------
+        float
+            Wasserstein distance
+        """
+        if not HAS_POT:
+            raise ImportError("POT library required for n-dimensional distances")
+
+        n_source = X_source.shape[0]
+        n_target = X_target.shape[0]
+
+        # Default to uniform distributions
+        if a is None:
+            a = np.ones(n_source) / n_source
+        if b is None:
+            b = np.ones(n_target) / n_target
+
+        # Compute cost matrix
+        M = cdist(X_source, X_target, metric=self.metric)
+
+        # Compute optimal transport
+        if method == 'sinkhorn':
+            # Sinkhorn algorithm (faster, approximate)
+            distance = ot.sinkhorn2(a, b, M, reg=0.1)
+        elif method == 'emd':
+            # Exact EMD
+            distance = ot.emd2(a, b, M)
+        elif method == 'emd2':
+            # Squared EMD
+            distance = ot.emd2(a, b, M**2)
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+        return float(distance)
+
+    def compute_barycenter(
+        self,
+        distributions: List[np.ndarray],
+        weights: Optional[np.ndarray] = None,
+        method: str = 'sinkhorn'
+    ) -> np.ndarray:
+        """
+        Compute Wasserstein barycenter of multiple distributions.
+
+        This finds the "average" distribution in Wasserstein space.
+
+        Parameters
+        ----------
+        distributions : list of np.ndarray
+            List of distributions to average
+        weights : np.ndarray, optional
+            Weights for each distribution
+        method : str
+            Method to use ('sinkhorn')
+
+        Returns
+        -------
+        np.ndarray
+            Wasserstein barycenter
+        """
+        if not HAS_POT:
+            raise ImportError("POT library required for barycenter computation")
+
+        n_distributions = len(distributions)
+
+        if weights is None:
+            weights = np.ones(n_distributions) / n_distributions
+
+        # Stack distributions
+        A = np.column_stack(distributions)
+
+        # Compute barycenter
+        if method == 'sinkhorn':
+            barycenter = ot.bregman.barycenter(A, M=None, reg=0.1, weights=weights)
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+        return barycenter
+
+
+class ScenarioComparator:
+    """
+    Compare geopolitical scenarios using optimal transport.
+
+    This class provides high-level methods for comparing scenarios,
+    detecting regime shifts, and quantifying shock impacts.
+    """
+
+    def __init__(self, metric: str = 'euclidean'):
+        """
+        Initialize scenario comparator.
+
+        Parameters
+        ----------
+        metric : str
+            Distance metric for ground distance
+        """
+        self.wasserstein = WassersteinDistance(metric=metric)
+
+    def compare_scenarios(
+        self,
+        scenario1: np.ndarray,
+        scenario2: np.ndarray,
+        weights1: Optional[np.ndarray] = None,
+        weights2: Optional[np.ndarray] = None
+    ) -> float:
+        """
+        Compare two geopolitical scenarios.
+
+        Parameters
+        ----------
+        scenario1 : np.ndarray
+            First scenario (features x samples)
+        scenario2 : np.ndarray
+            Second scenario (features x samples)
+        weights1 : np.ndarray, optional
+            Weights for first scenario
+        weights2 : np.ndarray, optional
+            Weights for second scenario
+
+        Returns
+        -------
+        float
+            Distance between scenarios
+        """
+        return self.wasserstein.compute_nd(scenario1, scenario2, weights1, weights2)
+
+    def detect_regime_shift(
+        self,
+        baseline: np.ndarray,
+        current: np.ndarray,
+        threshold: float = 0.1
+    ) -> Tuple[bool, float]:
+        """
+        Detect if a regime shift has occurred.
+
+        Parameters
+        ----------
+        baseline : np.ndarray
+            Baseline scenario distribution
+        current : np.ndarray
+            Current scenario distribution
+        threshold : float
+            Threshold for detecting shift
+
+        Returns
+        -------
+        tuple
+            (shift_detected, distance)
+        """
+        distance = self.compare_scenarios(baseline, current)
+        shift_detected = distance > threshold
+
+        return shift_detected, distance
+
+    def quantify_shock_impact(
+        self,
+        pre_shock: np.ndarray,
+        post_shock: np.ndarray
+    ) -> dict:
+        """
+        Quantify the impact of a shock event.
+
+        Parameters
+        ----------
+        pre_shock : np.ndarray
+            Pre-shock scenario distribution
+        post_shock : np.ndarray
+            Post-shock scenario distribution
+
+        Returns
+        -------
+        dict
+            Dictionary with impact metrics
+        """
+        distance = self.compare_scenarios(pre_shock, post_shock)
+
+        # Compute additional metrics
+        mean_shift = np.linalg.norm(np.mean(post_shock, axis=0) - np.mean(pre_shock, axis=0))
+        variance_change = np.abs(np.var(post_shock) - np.var(pre_shock))
+
+        return {
+            'wasserstein_distance': distance,
+            'mean_shift': mean_shift,
+            'variance_change': variance_change,
+            'impact_magnitude': distance * mean_shift
+        }
+
+    def compute_scenario_trajectory(
+        self,
+        scenarios: List[np.ndarray]
+    ) -> np.ndarray:
+        """
+        Compute trajectory of scenarios over time.
+
+        Parameters
+        ----------
+        scenarios : list of np.ndarray
+            Time series of scenarios
+
+        Returns
+        -------
+        np.ndarray
+            Array of distances between consecutive scenarios
+        """
+        n_scenarios = len(scenarios)
+        distances = np.zeros(n_scenarios - 1)
+
+        for i in range(n_scenarios - 1):
+            distances[i] = self.compare_scenarios(scenarios[i], scenarios[i + 1])
+
+        return distances
+
+    def logistics_optimal_transport(
+        self,
+        supply: np.ndarray,
+        demand: np.ndarray,
+        supply_locations: np.ndarray,
+        demand_locations: np.ndarray
+    ) -> Tuple[np.ndarray, float]:
+        """
+        Solve logistics problem using optimal transport.
+
+        Parameters
+        ----------
+        supply : np.ndarray
+            Supply amounts at each location
+        demand : np.ndarray
+            Demand amounts at each location
+        supply_locations : np.ndarray
+            Coordinates of supply locations
+        demand_locations : np.ndarray
+            Coordinates of demand locations
+
+        Returns
+        -------
+        tuple
+            (transport_plan, total_cost)
+        """
+        if not HAS_POT:
+            raise ImportError("POT library required for logistics optimization")
+
+        # Normalize supply and demand
+        supply_norm = supply / supply.sum()
+        demand_norm = demand / demand.sum()
+
+        # Compute cost matrix (distances)
+        M = cdist(supply_locations, demand_locations, metric=self.wasserstein.metric)
+
+        # Compute optimal transport plan
+        transport_plan = ot.emd(supply_norm, demand_norm, M)
+        total_cost = np.sum(transport_plan * M)
+
+        # Scale back to original quantities
+        transport_plan *= supply.sum()
+
+        return transport_plan, total_cost

geobot/core/scenario.py

@@ -0,0 +1,285 @@
+"""
+Scenario representation and management for geopolitical modeling.
+"""
+
+import numpy as np
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Scenario:
+    """
+    Represents a geopolitical scenario with multiple features and metadata.
+
+    Attributes
+    ----------
+    name : str
+        Name or identifier for the scenario
+    features : Dict[str, np.ndarray]
+        Dictionary of feature names to values
+    timestamp : datetime
+        Timestamp of the scenario
+    metadata : Dict[str, Any]
+        Additional metadata
+    probability : float
+        Probability or weight of this scenario (for ensembles)
+    """
+    name: str
+    features: Dict[str, np.ndarray]
+    timestamp: datetime = field(default_factory=datetime.now)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    probability: float = 1.0
+
+    def get_feature_vector(self, feature_names: Optional[List[str]] = None) -> np.ndarray:
+        """
+        Get features as a vector.
+
+        Parameters
+        ----------
+        feature_names : List[str], optional
+            List of feature names to include (if None, use all)
+
+        Returns
+        -------
+        np.ndarray
+            Feature vector
+        """
+        if feature_names is None:
+            feature_names = list(self.features.keys())
+
+        vectors = [self.features[name].flatten() for name in feature_names if name in self.features]
+        return np.concatenate(vectors)
+
+    def get_feature_matrix(self) -> np.ndarray:
+        """
+        Get all features as a matrix.
+
+        Returns
+        -------
+        np.ndarray
+            Feature matrix (n_features, ...)
+        """
+        return np.array([v for v in self.features.values()])
+
+    def add_feature(self, name: str, values: np.ndarray) -> None:
+        """
+        Add a new feature to the scenario.
+
+        Parameters
+        ----------
+        name : str
+            Feature name
+        values : np.ndarray
+            Feature values
+        """
+        self.features[name] = values
+
+    def remove_feature(self, name: str) -> None:
+        """
+        Remove a feature from the scenario.
+
+        Parameters
+        ----------
+        name : str
+            Feature name to remove
+        """
+        if name in self.features:
+            del self.features[name]
+
+    def clone(self) -> 'Scenario':
+        """
+        Create a deep copy of the scenario.
+
+        Returns
+        -------
+        Scenario
+            Cloned scenario
+        """
+        return Scenario(
+            name=self.name,
+            features={k: v.copy() for k, v in self.features.items()},
+            timestamp=self.timestamp,
+            metadata=self.metadata.copy(),
+            probability=self.probability
+        )
+
+
+class ScenarioDistribution:
+    """
+    Represents a distribution over multiple scenarios.
+
+    This is useful for Monte Carlo simulations, ensemble forecasting,
+    and probabilistic reasoning.
+    """
+
+    def __init__(self, scenarios: Optional[List[Scenario]] = None):
+        """
+        Initialize scenario distribution.
+
+        Parameters
+        ----------
+        scenarios : List[Scenario], optional
+            Initial list of scenarios
+        """
+        self.scenarios: List[Scenario] = scenarios if scenarios is not None else []
+
+    def add_scenario(self, scenario: Scenario) -> None:
+        """
+        Add a scenario to the distribution.
+
+        Parameters
+        ----------
+        scenario : Scenario
+            Scenario to add
+        """
+        self.scenarios.append(scenario)
+
+    def get_probabilities(self) -> np.ndarray:
+        """
+        Get probabilities of all scenarios.
+
+        Returns
+        -------
+        np.ndarray
+            Array of probabilities
+        """
+        probs = np.array([s.probability for s in self.scenarios])
+        # Normalize
+        return probs / probs.sum()
+
+    def normalize_probabilities(self) -> None:
+        """
+        Normalize scenario probabilities to sum to 1.
+        """
+        total_prob = sum(s.probability for s in self.scenarios)
+        for scenario in self.scenarios:
+            scenario.probability /= total_prob
+
+    def get_feature_samples(self, feature_names: Optional[List[str]] = None) -> np.ndarray:
+        """
+        Get feature samples from all scenarios.
+
+        Parameters
+        ----------
+        feature_names : List[str], optional
+            List of feature names to include
+
+        Returns
+        -------
+        np.ndarray
+            Feature samples (n_scenarios, n_features)
+        """
+        samples = [s.get_feature_vector(feature_names) for s in self.scenarios]
+        return np.array(samples)
+
+    def get_weighted_mean(self, feature_names: Optional[List[str]] = None) -> np.ndarray:
+        """
+        Compute weighted mean of features.
+
+        Parameters
+        ----------
+        feature_names : List[str], optional
+            List of feature names to include
+
+        Returns
+        -------
+        np.ndarray
+            Weighted mean feature vector
+        """
+        samples = self.get_feature_samples(feature_names)
+        probs = self.get_probabilities()
+        return np.average(samples, axis=0, weights=probs)
+
+    def get_variance(self, feature_names: Optional[List[str]] = None) -> np.ndarray:
+        """
+        Compute variance of features.
+
+        Parameters
+        ----------
+        feature_names : List[str], optional
+            List of feature names to include
+
+        Returns
+        -------
+        np.ndarray
+            Variance of features
+        """
+        samples = self.get_feature_samples(feature_names)
+        probs = self.get_probabilities()
+        mean = self.get_weighted_mean(feature_names)
+
+        variance = np.average((samples - mean) ** 2, axis=0, weights=probs)
+        return variance
+
+    def sample(self, n_samples: int = 1, replace: bool = True) -> List[Scenario]:
+        """
+        Sample scenarios from the distribution.
+
+        Parameters
+        ----------
+        n_samples : int
+            Number of samples to draw
+        replace : bool
+            Whether to sample with replacement
+
+        Returns
+        -------
+        List[Scenario]
+            Sampled scenarios
+        """
+        probs = self.get_probabilities()
+        indices = np.random.choice(
+            len(self.scenarios),
+            size=n_samples,
+            replace=replace,
+            p=probs
+        )
+        return [self.scenarios[i] for i in indices]
+
+    def filter_by_probability(self, threshold: float) -> 'ScenarioDistribution':
+        """
+        Filter scenarios by probability threshold.
+
+        Parameters
+        ----------
+        threshold : float
+            Minimum probability threshold
+
+        Returns
+        -------
+        ScenarioDistribution
+            New distribution with filtered scenarios
+        """
+        filtered_scenarios = [s for s in self.scenarios if s.probability >= threshold]
+        return ScenarioDistribution(filtered_scenarios)
+
+    def get_top_k(self, k: int) -> 'ScenarioDistribution':
+        """
+        Get top k scenarios by probability.
+
+        Parameters
+        ----------
+        k : int
+            Number of scenarios to return
+
+        Returns
+        -------
+        ScenarioDistribution
+            Distribution with top k scenarios
+        """
+        sorted_scenarios = sorted(self.scenarios, key=lambda s: s.probability, reverse=True)
+        return ScenarioDistribution(sorted_scenarios[:k])
+
+    def __len__(self) -> int:
+        """Return number of scenarios."""
+        return len(self.scenarios)
+
+    def __getitem__(self, idx: int) -> Scenario:
+        """Get scenario by index."""
+        return self.scenarios[idx]
+
+    def __iter__(self):
+        """Iterate over scenarios."""
+        return iter(self.scenarios)

geobot/data_ingestion/__init__.py

@@ -0,0 +1,36 @@
+"""
+Data ingestion modules for GeoBotv1
+
+Support for:
+- PDF document reading and processing
+- Web scraping and article extraction
+- News feed ingestion
+- Structured event extraction
+- Event database and temporal normalization
+"""
+
+from .pdf_reader import PDFReader, PDFProcessor
+from .web_scraper import WebScraper, ArticleExtractor, NewsAggregator
+from .event_extraction import (
+    EventExtractor,
+    GeopoliticalEvent,
+    EventType,
+    TemporalNormalizer,
+    CausalFeatureExtractor
+)
+from .event_database import EventDatabase, EventStream
+
+__all__ = [
+    "PDFReader",
+    "PDFProcessor",
+    "WebScraper",
+    "ArticleExtractor",
+    "NewsAggregator",
+    "EventExtractor",
+    "GeopoliticalEvent",
+    "EventType",
+    "TemporalNormalizer",
+    "CausalFeatureExtractor",
+    "EventDatabase",
+    "EventStream",
+]

geobot/data_ingestion/event_database.py

@@ -0,0 +1,574 @@
+"""
+Event Database for Geopolitical Intelligence
+
+Persistent storage and querying for structured events.
+
+Features:
+- Efficient time-range queries
+- Actor-based filtering
+- Event type filtering
+- Temporal aggregation
+- Causal graph construction from events
+- Export to panel data formats
+"""
+
+import json
+import sqlite3
+from datetime import datetime, timedelta
+from typing import List, Dict, Optional, Tuple, Any
+from pathlib import Path
+import pandas as pd
+
+from .event_extraction import GeopoliticalEvent, EventType, TemporalNormalizer
+
+
+class EventDatabase:
+    """
+    SQLite-based event database with efficient querying.
+    """
+
+    def __init__(self, db_path: str = "events.db"):
+        """
+        Initialize event database.
+
+        Parameters
+        ----------
+        db_path : str
+            Path to SQLite database file
+        """
+        self.db_path = db_path
+        self.conn = None
+        self._connect()
+        self._create_tables()
+
+    def _connect(self):
+        """Connect to database."""
+        self.conn = sqlite3.connect(self.db_path)
+        self.conn.row_factory = sqlite3.Row
+
+    def _create_tables(self):
+        """Create database schema."""
+        cursor = self.conn.cursor()
+
+        # Events table
+        cursor.execute('''
+            CREATE TABLE IF NOT EXISTS events (
+                event_id TEXT PRIMARY KEY,
+                timestamp TEXT NOT NULL,
+                event_type TEXT NOT NULL,
+                location TEXT,
+                magnitude REAL,
+                confidence REAL,
+                source TEXT,
+                text TEXT,
+                metadata TEXT
+            )
+        ''')
+
+        # Actors table (many-to-many with events)
+        cursor.execute('''
+            CREATE TABLE IF NOT EXISTS event_actors (
+                event_id TEXT,
+                actor TEXT,
+                role TEXT,
+                FOREIGN KEY (event_id) REFERENCES events(event_id),
+                PRIMARY KEY (event_id, actor)
+            )
+        ''')
+
+        # Causal relationships
+        cursor.execute('''
+            CREATE TABLE IF NOT EXISTS causal_links (
+                cause_event_id TEXT,
+                effect_event_id TEXT,
+                strength REAL,
+                confidence REAL,
+                FOREIGN KEY (cause_event_id) REFERENCES events(event_id),
+                FOREIGN KEY (effect_event_id) REFERENCES events(event_id),
+                PRIMARY KEY (cause_event_id, effect_event_id)
+            )
+        ''')
+
+        # Create indices for fast queries
+        cursor.execute('CREATE INDEX IF NOT EXISTS idx_timestamp ON events(timestamp)')
+        cursor.execute('CREATE INDEX IF NOT EXISTS idx_event_type ON events(event_type)')
+        cursor.execute('CREATE INDEX IF NOT EXISTS idx_actor ON event_actors(actor)')
+
+        self.conn.commit()
+
+    def insert_event(self, event: GeopoliticalEvent) -> None:
+        """
+        Insert event into database.
+
+        Parameters
+        ----------
+        event : GeopoliticalEvent
+            Event to insert
+        """
+        cursor = self.conn.cursor()
+
+        # Normalize timestamp
+        timestamp_str = TemporalNormalizer.normalize_to_utc(event.timestamp).isoformat()
+
+        # Insert main event
+        cursor.execute('''
+            INSERT OR REPLACE INTO events
+            (event_id, timestamp, event_type, location, magnitude, confidence, source, text, metadata)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ''', (
+            event.event_id,
+            timestamp_str,
+            event.event_type.value,
+            event.location,
+            event.magnitude,
+            event.confidence,
+            event.source,
+            event.text,
+            json.dumps(event.metadata)
+        ))
+
+        # Insert actors
+        for actor in event.actors:
+            cursor.execute('''
+                INSERT OR REPLACE INTO event_actors (event_id, actor, role)
+                VALUES (?, ?, ?)
+            ''', (event.event_id, actor, 'participant'))
+
+        # Insert target as actor with different role
+        if event.target:
+            cursor.execute('''
+                INSERT OR REPLACE INTO event_actors (event_id, actor, role)
+                VALUES (?, ?, ?)
+            ''', (event.event_id, event.target, 'target'))
+
+        self.conn.commit()
+
+    def insert_events(self, events: List[GeopoliticalEvent]) -> None:
+        """
+        Bulk insert events.
+
+        Parameters
+        ----------
+        events : list
+            List of events to insert
+        """
+        for event in events:
+            self.insert_event(event)
+
+    def query_events(
+        self,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        event_types: Optional[List[EventType]] = None,
+        actors: Optional[List[str]] = None,
+        min_magnitude: Optional[float] = None,
+        limit: Optional[int] = None
+    ) -> List[GeopoliticalEvent]:
+        """
+        Query events with filters.
+
+        Parameters
+        ----------
+        start_time : datetime, optional
+            Start of time range
+        end_time : datetime, optional
+            End of time range
+        event_types : list, optional
+            Filter by event types
+        actors : list, optional
+            Filter by actors
+        min_magnitude : float, optional
+            Minimum magnitude
+        limit : int, optional
+            Maximum number of results
+
+        Returns
+        -------
+        list
+            List of matching events
+        """
+        cursor = self.conn.cursor()
+
+        query = "SELECT DISTINCT e.* FROM events e"
+        conditions = []
+        params = []
+
+        # Join with actors if needed
+        if actors:
+            query += " JOIN event_actors ea ON e.event_id = ea.event_id"
+
+        # Time range
+        if start_time:
+            conditions.append("e.timestamp >= ?")
+            params.append(start_time.isoformat())
+        if end_time:
+            conditions.append("e.timestamp <= ?")
+            params.append(end_time.isoformat())
+
+        # Event types
+        if event_types:
+            placeholders = ','.join('?' * len(event_types))
+            conditions.append(f"e.event_type IN ({placeholders})")
+            params.extend([et.value for et in event_types])
+
+        # Actors
+        if actors:
+            placeholders = ','.join('?' * len(actors))
+            conditions.append(f"ea.actor IN ({placeholders})")
+            params.extend(actors)
+
+        # Magnitude
+        if min_magnitude is not None:
+            conditions.append("e.magnitude >= ?")
+            params.append(min_magnitude)
+
+        # Build query
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+
+        query += " ORDER BY e.timestamp DESC"
+
+        if limit:
+            query += f" LIMIT {limit}"
+
+        # Execute
+        cursor.execute(query, params)
+        rows = cursor.fetchall()
+
+        # Convert to GeopoliticalEvent objects
+        events = []
+        for row in rows:
+            # Get actors
+            cursor.execute(
+                "SELECT actor FROM event_actors WHERE event_id = ?",
+                (row['event_id'],)
+            )
+            actors_rows = cursor.fetchall()
+            event_actors = [r['actor'] for r in actors_rows]
+
+            # Reconstruct event
+            event = GeopoliticalEvent(
+                event_id=row['event_id'],
+                timestamp=datetime.fromisoformat(row['timestamp']),
+                event_type=EventType(row['event_type']),
+                actors=event_actors,
+                location=row['location'],
+                magnitude=row['magnitude'],
+                confidence=row['confidence'],
+                source=row['source'],
+                text=row['text'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else {}
+            )
+            events.append(event)
+
+        return events
+
+    def get_actor_timeline(
+        self,
+        actor: str,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None
+    ) -> List[GeopoliticalEvent]:
+        """
+        Get timeline of events for a specific actor.
+
+        Parameters
+        ----------
+        actor : str
+            Actor name
+        start_time : datetime, optional
+            Start time
+        end_time : datetime, optional
+            End time
+
+        Returns
+        -------
+        list
+            Events involving actor
+        """
+        return self.query_events(
+            start_time=start_time,
+            end_time=end_time,
+            actors=[actor]
+        )
+
+    def get_event_counts_by_type(
+        self,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None
+    ) -> Dict[str, int]:
+        """
+        Get event counts by type.
+
+        Parameters
+        ----------
+        start_time : datetime, optional
+            Start time
+        end_time : datetime, optional
+            End time
+
+        Returns
+        -------
+        dict
+            Counts by event type
+        """
+        cursor = self.conn.cursor()
+
+        query = "SELECT event_type, COUNT(*) as count FROM events"
+        conditions = []
+        params = []
+
+        if start_time:
+            conditions.append("timestamp >= ?")
+            params.append(start_time.isoformat())
+        if end_time:
+            conditions.append("timestamp <= ?")
+            params.append(end_time.isoformat())
+
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+
+        query += " GROUP BY event_type"
+
+        cursor.execute(query, params)
+        rows = cursor.fetchall()
+
+        return {row['event_type']: row['count'] for row in rows}
+
+    def aggregate_by_time(
+        self,
+        granularity: str = 'day',
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        event_types: Optional[List[EventType]] = None
+    ) -> pd.DataFrame:
+        """
+        Aggregate events by time period.
+
+        Parameters
+        ----------
+        granularity : str
+            Time granularity ('day', 'week', 'month')
+        start_time : datetime, optional
+            Start time
+        end_time : datetime, optional
+            End time
+        event_types : list, optional
+            Filter by event types
+
+        Returns
+        -------
+        pd.DataFrame
+            Time series of event counts
+        """
+        events = self.query_events(
+            start_time=start_time,
+            end_time=end_time,
+            event_types=event_types
+        )
+
+        if not events:
+            return pd.DataFrame()
+
+        # Convert to DataFrame
+        df = pd.DataFrame([
+            {
+                'timestamp': e.timestamp,
+                'event_type': e.event_type.value,
+                'magnitude': e.magnitude
+            }
+            for e in events
+        ])
+
+        df['timestamp'] = pd.to_datetime(df['timestamp'])
+        df = df.set_index('timestamp')
+
+        # Resample
+        if granularity == 'day':
+            freq = 'D'
+        elif granularity == 'week':
+            freq = 'W'
+        elif granularity == 'month':
+            freq = 'M'
+        else:
+            raise ValueError(f"Unknown granularity: {granularity}")
+
+        # Aggregate
+        aggregated = df.resample(freq).agg({
+            'magnitude': ['count', 'mean', 'sum']
+        })
+
+        return aggregated
+
+    def export_to_panel_data(
+        self,
+        actors: List[str],
+        start_time: datetime,
+        end_time: datetime,
+        granularity: str = 'day'
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Export to panel data format.
+
+        Parameters
+        ----------
+        actors : list
+            List of actors
+        start_time : datetime
+            Start time
+        end_time : datetime
+            End time
+        granularity : str
+            Time granularity
+
+        Returns
+        -------
+        dict
+            Panel data {actor: DataFrame}
+        """
+        from .event_extraction import CausalFeatureExtractor
+
+        # Get events for each actor
+        panel = {}
+        for actor in actors:
+            events = self.get_actor_timeline(actor, start_time, end_time)
+
+            # Extract features
+            extractor = CausalFeatureExtractor()
+            panel_data = extractor.construct_panel_data([events], [actor], granularity)
+
+            if actor in panel_data:
+                panel[actor] = panel_data[actor]
+
+        return panel
+
+    def add_causal_link(
+        self,
+        cause_event_id: str,
+        effect_event_id: str,
+        strength: float = 1.0,
+        confidence: float = 0.5
+    ) -> None:
+        """
+        Add causal link between events.
+
+        Parameters
+        ----------
+        cause_event_id : str
+            ID of cause event
+        effect_event_id : str
+            ID of effect event
+        strength : float
+            Causal strength
+        confidence : float
+            Confidence in link
+        """
+        cursor = self.conn.cursor()
+
+        cursor.execute('''
+            INSERT OR REPLACE INTO causal_links
+            (cause_event_id, effect_event_id, strength, confidence)
+            VALUES (?, ?, ?, ?)
+        ''', (cause_event_id, effect_event_id, strength, confidence))
+
+        self.conn.commit()
+
+    def get_causal_graph(self) -> Dict[str, List[str]]:
+        """
+        Get causal graph from event links.
+
+        Returns
+        -------
+        dict
+            Adjacency list representation
+        """
+        cursor = self.conn.cursor()
+
+        cursor.execute("SELECT cause_event_id, effect_event_id FROM causal_links")
+        rows = cursor.fetchall()
+
+        graph = {}
+        for row in rows:
+            cause = row['cause_event_id']
+            effect = row['effect_event_id']
+
+            if cause not in graph:
+                graph[cause] = []
+            graph[cause].append(effect)
+
+        return graph
+
+    def close(self):
+        """Close database connection."""
+        if self.conn:
+            self.conn.close()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+
+
+class EventStream:
+    """
+    Real-time event stream processor.
+
+    Monitors and processes incoming events in real-time.
+    """
+
+    def __init__(self, db: EventDatabase):
+        """
+        Initialize event stream.
+
+        Parameters
+        ----------
+        db : EventDatabase
+            Event database
+        """
+        self.db = db
+        self.subscribers = []
+
+    def subscribe(self, callback: callable) -> None:
+        """
+        Subscribe to event stream.
+
+        Parameters
+        ----------
+        callback : callable
+            Function to call on new events
+        """
+        self.subscribers.append(callback)
+
+    def process_event(self, event: GeopoliticalEvent) -> None:
+        """
+        Process and store new event.
+
+        Parameters
+        ----------
+        event : GeopoliticalEvent
+            New event
+        """
+        # Store in database
+        self.db.insert_event(event)
+
+        # Notify subscribers
+        for callback in self.subscribers:
+            callback(event)
+
+    def process_batch(self, events: List[GeopoliticalEvent]) -> None:
+        """
+        Process batch of events.
+
+        Parameters
+        ----------
+        events : list
+            List of events
+        """
+        self.db.insert_events(events)
+
+        for event in events:
+            for callback in self.subscribers:
+                callback(event)

geobot/data_ingestion/event_extraction.py

@@ -0,0 +1,539 @@
+"""
+Structured Event Extraction Pipeline
+
+Converts unstructured intelligence (PDFs, articles, reports) into structured,
+timestamped events suitable for:
+- Causal graph construction and updates
+- Time-series analysis
+- Panel data modeling
+- Temporal feature engineering
+
+Event schema:
+- Timestamp (normalized to UTC)
+- Event type (conflict, diplomacy, economic, etc.)
+- Actors (countries, organizations)
+- Location (geospatial)
+- Magnitude/severity
+- Source and confidence
+- Causal attributes (preconditions, effects)
+"""
+
+import re
+from datetime import datetime, timezone
+from typing import List, Dict, Optional, Tuple, Any
+import numpy as np
+from dataclasses import dataclass, field
+from enum import Enum
+import json
+
+
+class EventType(Enum):
+    """Event taxonomy."""
+    CONFLICT = "conflict"
+    DIPLOMACY = "diplomacy"
+    ECONOMIC = "economic"
+    MILITARY_MOBILIZATION = "military_mobilization"
+    SANCTIONS = "sanctions"
+    ALLIANCE_FORMATION = "alliance_formation"
+    TREATY_SIGNING = "treaty_signing"
+    PROTEST = "protest"
+    ELECTION = "election"
+    COUP = "coup"
+    TERROR_ATTACK = "terror_attack"
+    CYBER_ATTACK = "cyber_attack"
+    TRADE_AGREEMENT = "trade_agreement"
+    ARMS_DEAL = "arms_deal"
+    HUMANITARIAN_CRISIS = "humanitarian_crisis"
+    OTHER = "other"
+
+
+@dataclass
+class GeopoliticalEvent:
+    """
+    Structured geopolitical event.
+
+    Attributes
+    ----------
+    event_id : str
+        Unique event identifier
+    timestamp : datetime
+        Event timestamp (normalized to UTC)
+    event_type : EventType
+        Type of event
+    actors : List[str]
+        Involved actors (countries, organizations)
+    target : Optional[str]
+        Target of action (if applicable)
+    location : Optional[str]
+        Geographic location
+    magnitude : float
+        Event magnitude/severity (0-1)
+    confidence : float
+        Extraction confidence (0-1)
+    source : str
+        Source document/article
+    text : str
+        Original text describing event
+    causal_preconditions : List[str]
+        Identified preconditions
+    causal_effects : List[str]
+        Identified effects
+    metadata : Dict[str, Any]
+        Additional metadata
+    """
+    event_id: str
+    timestamp: datetime
+    event_type: EventType
+    actors: List[str]
+    target: Optional[str] = None
+    location: Optional[str] = None
+    magnitude: float = 0.5
+    confidence: float = 0.5
+    source: str = ""
+    text: str = ""
+    causal_preconditions: List[str] = field(default_factory=list)
+    causal_effects: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            'event_id': self.event_id,
+            'timestamp': self.timestamp.isoformat(),
+            'event_type': self.event_type.value,
+            'actors': self.actors,
+            'target': self.target,
+            'location': self.location,
+            'magnitude': self.magnitude,
+            'confidence': self.confidence,
+            'source': self.source,
+            'text': self.text,
+            'causal_preconditions': self.causal_preconditions,
+            'causal_effects': self.causal_effects,
+            'metadata': self.metadata
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'GeopoliticalEvent':
+        """Load from dictionary."""
+        data['timestamp'] = datetime.fromisoformat(data['timestamp'])
+        data['event_type'] = EventType(data['event_type'])
+        return cls(**data)
+
+
+class EventExtractor:
+    """
+    Extract structured events from unstructured text.
+
+    Uses rule-based patterns and NLP to identify:
+    - Event mentions
+    - Temporal expressions
+    - Actor identification
+    - Event type classification
+    """
+
+    def __init__(self):
+        """Initialize event extractor."""
+        self.country_names = self._load_country_names()
+        self.organization_names = self._load_organization_names()
+        self.event_patterns = self._compile_event_patterns()
+
+    def _load_country_names(self) -> List[str]:
+        """Load list of country names."""
+        # Extended list of countries
+        return [
+            'United States', 'USA', 'China', 'Russia', 'India', 'Pakistan',
+            'Iran', 'North Korea', 'South Korea', 'Japan', 'Germany', 'France',
+            'United Kingdom', 'UK', 'Israel', 'Saudi Arabia', 'Turkey', 'Egypt',
+            'Syria', 'Iraq', 'Afghanistan', 'Ukraine', 'Poland', 'Italy', 'Spain',
+            'Canada', 'Australia', 'Brazil', 'Mexico', 'South Africa', 'Nigeria'
+        ]
+
+    def _load_organization_names(self) -> List[str]:
+        """Load list of international organizations."""
+        return [
+            'NATO', 'UN', 'United Nations', 'EU', 'European Union',
+            'OPEC', 'ASEAN', 'African Union', 'Arab League', 'G7', 'G20',
+            'IMF', 'World Bank', 'WTO', 'WHO', 'ICC'
+        ]
+
+    def _compile_event_patterns(self) -> Dict[EventType, List[re.Pattern]]:
+        """Compile regex patterns for event types."""
+        patterns = {
+            EventType.CONFLICT: [
+                re.compile(r'\b(attack|strike|bomb|missile|war|combat|clash|battle)\b', re.I),
+                re.compile(r'\b(invasion|offensive|assault|raid)\b', re.I)
+            ],
+            EventType.DIPLOMACY: [
+                re.compile(r'\b(negotiation|talk|summit|meeting|dialogue)\b', re.I),
+                re.compile(r'\b(diplomatic|embassy|ambassador)\b', re.I)
+            ],
+            EventType.SANCTIONS: [
+                re.compile(r'\b(sanction|embargo|restriction|ban)\b', re.I)
+            ],
+            EventType.MILITARY_MOBILIZATION: [
+                re.compile(r'\b(mobiliz|deploy|troop|force|military)\b', re.I)
+            ],
+            EventType.ALLIANCE_FORMATION: [
+                re.compile(r'\b(alliance|partnership|coalition|pact)\b', re.I)
+            ],
+            EventType.TREATY_SIGNING: [
+                re.compile(r'\b(treaty|agreement|accord|convention)\b', re.I)
+            ],
+            EventType.ELECTION: [
+                re.compile(r'\b(election|vote|ballot|referendum)\b', re.I)
+            ],
+            EventType.COUP: [
+                re.compile(r'\b(coup|overthrow|takeover|regime change)\b', re.I)
+            ],
+            EventType.TERROR_ATTACK: [
+                re.compile(r'\b(terror|terrorist|extremist|bombing)\b', re.I)
+            ],
+            EventType.CYBER_ATTACK: [
+                re.compile(r'\b(cyber|hack|breach|malware|ransomware)\b', re.I)
+            ]
+        }
+        return patterns
+
+    def extract_events(
+        self,
+        text: str,
+        source: str = "",
+        default_timestamp: Optional[datetime] = None
+    ) -> List[GeopoliticalEvent]:
+        """
+        Extract events from text.
+
+        Parameters
+        ----------
+        text : str
+            Input text
+        source : str
+            Source identifier
+        default_timestamp : datetime, optional
+            Default timestamp if none found
+
+        Returns
+        -------
+        list
+            List of extracted events
+        """
+        events = []
+
+        # Split into sentences
+        sentences = self._split_sentences(text)
+
+        for i, sentence in enumerate(sentences):
+            # Detect event type
+            event_type = self._classify_event_type(sentence)
+
+            if event_type != EventType.OTHER:
+                # Extract actors
+                actors = self._extract_actors(sentence)
+
+                # Extract timestamp
+                timestamp = self._extract_timestamp(sentence, default_timestamp)
+
+                # Extract location
+                location = self._extract_location(sentence)
+
+                # Compute magnitude
+                magnitude = self._estimate_magnitude(sentence, event_type)
+
+                # Create event
+                event = GeopoliticalEvent(
+                    event_id=f"{source}_{i}",
+                    timestamp=timestamp,
+                    event_type=event_type,
+                    actors=actors,
+                    location=location,
+                    magnitude=magnitude,
+                    confidence=0.7,  # Rule-based confidence
+                    source=source,
+                    text=sentence
+                )
+
+                events.append(event)
+
+        return events
+
+    def _split_sentences(self, text: str) -> List[str]:
+        """Split text into sentences."""
+        # Simple sentence splitting
+        sentences = re.split(r'[.!?]+', text)
+        return [s.strip() for s in sentences if len(s.strip()) > 20]
+
+    def _classify_event_type(self, text: str) -> EventType:
+        """Classify event type using patterns."""
+        for event_type, patterns in self.event_patterns.items():
+            for pattern in patterns:
+                if pattern.search(text):
+                    return event_type
+        return EventType.OTHER
+
+    def _extract_actors(self, text: str) -> List[str]:
+        """Extract actor entities."""
+        actors = []
+
+        # Check for countries
+        for country in self.country_names:
+            if country.lower() in text.lower():
+                actors.append(country)
+
+        # Check for organizations
+        for org in self.organization_names:
+            if org.lower() in text.lower():
+                actors.append(org)
+
+        return list(set(actors))  # Remove duplicates
+
+    def _extract_timestamp(
+        self,
+        text: str,
+        default: Optional[datetime] = None
+    ) -> datetime:
+        """Extract timestamp from text."""
+        # Try to find date patterns
+        date_patterns = [
+            r'(\d{4})-(\d{2})-(\d{2})',  # YYYY-MM-DD
+            r'(\d{1,2})/(\d{1,2})/(\d{4})',  # MM/DD/YYYY
+            r'(January|February|March|April|May|June|July|August|September|October|November|December)\s+(\d{1,2}),?\s+(\d{4})'
+        ]
+
+        for pattern in date_patterns:
+            match = re.search(pattern, text)
+            if match:
+                # Parse date (simplified)
+                try:
+                    date_str = match.group(0)
+                    # Try multiple formats
+                    for fmt in ['%Y-%m-%d', '%m/%d/%Y']:
+                        try:
+                            return datetime.strptime(date_str, fmt).replace(tzinfo=timezone.utc)
+                        except:
+                            continue
+                except:
+                    pass
+
+        # Default to current time or provided default
+        return default or datetime.now(timezone.utc)
+
+    def _extract_location(self, text: str) -> Optional[str]:
+        """Extract location from text."""
+        # Check for country names as locations
+        for country in self.country_names:
+            if country.lower() in text.lower():
+                return country
+
+        return None
+
+    def _estimate_magnitude(self, text: str, event_type: EventType) -> float:
+        """Estimate event magnitude/severity."""
+        # Keywords indicating severity
+        high_severity_words = ['major', 'massive', 'large-scale', 'significant', 'devastating']
+        low_severity_words = ['minor', 'small', 'limited', 'isolated']
+
+        text_lower = text.lower()
+
+        if any(word in text_lower for word in high_severity_words):
+            return 0.8
+        elif any(word in text_lower for word in low_severity_words):
+            return 0.3
+        else:
+            return 0.5  # Default
+
+
+class TemporalNormalizer:
+    """
+    Normalize timestamps to consistent format (UTC).
+
+    Handles:
+    - Time zone conversion
+    - Temporal granularity (day, week, month)
+    - Missing timestamps (imputation)
+    """
+
+    @staticmethod
+    def normalize_to_utc(dt: datetime) -> datetime:
+        """
+        Normalize datetime to UTC.
+
+        Parameters
+        ----------
+        dt : datetime
+            Input datetime
+
+        Returns
+        -------
+        datetime
+            UTC datetime
+        """
+        if dt.tzinfo is None:
+            # Assume local time
+            return dt.replace(tzinfo=timezone.utc)
+        else:
+            return dt.astimezone(timezone.utc)
+
+    @staticmethod
+    def round_to_day(dt: datetime) -> datetime:
+        """Round to start of day."""
+        return dt.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    @staticmethod
+    def round_to_week(dt: datetime) -> datetime:
+        """Round to start of week (Monday)."""
+        day_of_week = dt.weekday()
+        days_to_subtract = day_of_week
+        week_start = dt - datetime.timedelta(days=days_to_subtract)
+        return TemporalNormalizer.round_to_day(week_start)
+
+
+class CausalFeatureExtractor:
+    """
+    Extract causal features from events for modeling.
+
+    Constructs features suitable for:
+    - Causal graph learning
+    - Structural equation modeling
+    - Time-series forecasting
+    """
+
+    def __init__(self):
+        """Initialize causal feature extractor."""
+        pass
+
+    def extract_features(
+        self,
+        events: List[GeopoliticalEvent],
+        time_window: int = 30
+    ) -> Dict[str, np.ndarray]:
+        """
+        Extract causal features from event sequence.
+
+        Parameters
+        ----------
+        events : list
+            List of events
+        time_window : int
+            Time window in days
+
+        Returns
+        -------
+        dict
+            Feature dictionary
+        """
+        import numpy as np
+
+        # Sort events by timestamp
+        sorted_events = sorted(events, key=lambda e: e.timestamp)
+
+        # Count events by type
+        event_counts = {}
+        for event_type in EventType:
+            event_counts[event_type.value] = sum(
+                1 for e in sorted_events if e.event_type == event_type
+            )
+
+        # Actor involvement matrix
+        all_actors = list(set(actor for e in sorted_events for actor in e.actors))
+        actor_indices = {actor: i for i, actor in enumerate(all_actors)}
+
+        # Event-actor matrix
+        n_events = len(sorted_events)
+        n_actors = len(all_actors)
+        actor_matrix = np.zeros((n_events, n_actors))
+
+        for i, event in enumerate(sorted_events):
+            for actor in event.actors:
+                if actor in actor_indices:
+                    actor_matrix[i, actor_indices[actor]] = 1
+
+        # Temporal features
+        if sorted_events:
+            time_deltas = []
+            for i in range(1, len(sorted_events)):
+                delta = (sorted_events[i].timestamp - sorted_events[i-1].timestamp).total_seconds() / 86400  # days
+                time_deltas.append(delta)
+            mean_time_delta = np.mean(time_deltas) if time_deltas else 0
+        else:
+            mean_time_delta = 0
+
+        features = {
+            'event_counts': np.array([event_counts[et.value] for et in EventType]),
+            'actor_matrix': actor_matrix,
+            'mean_time_delta': mean_time_delta,
+            'total_events': n_events,
+            'unique_actors': n_actors
+        }
+
+        return features
+
+    def construct_panel_data(
+        self,
+        events: List[GeopoliticalEvent],
+        actors: List[str],
+        time_granularity: str = 'day'
+    ) -> Dict[str, Any]:
+        """
+        Construct panel data structure from events.
+
+        Panel data format: (actor, time) -> features
+
+        Parameters
+        ----------
+        events : list
+            List of events
+        actors : list
+            List of actors
+        time_granularity : str
+            Time granularity ('day', 'week', 'month')
+
+        Returns
+        -------
+        dict
+            Panel data structure
+        """
+        import pandas as pd
+        import numpy as np
+
+        # Create time index
+        if not events:
+            return {}
+
+        sorted_events = sorted(events, key=lambda e: e.timestamp)
+        start_time = sorted_events[0].timestamp
+        end_time = sorted_events[-1].timestamp
+
+        # Generate time grid
+        if time_granularity == 'day':
+            time_index = pd.date_range(start_time, end_time, freq='D')
+        elif time_granularity == 'week':
+            time_index = pd.date_range(start_time, end_time, freq='W')
+        elif time_granularity == 'month':
+            time_index = pd.date_range(start_time, end_time, freq='M')
+        else:
+            raise ValueError(f"Unknown granularity: {time_granularity}")
+
+        # Initialize panel
+        panel = {}
+        for actor in actors:
+            panel[actor] = pd.DataFrame(index=time_index, columns=['event_count', 'avg_magnitude'])
+            panel[actor] = panel[actor].fillna(0)
+
+        # Fill panel with events
+        for event in sorted_events:
+            for actor in event.actors:
+                if actor in panel:
+                    # Find closest time point
+                    event_date = pd.Timestamp(event.timestamp)
+                    closest_idx = time_index[np.argmin(np.abs(time_index - event_date))]
+
+                    panel[actor].loc[closest_idx, 'event_count'] += 1
+                    panel[actor].loc[closest_idx, 'avg_magnitude'] += event.magnitude
+
+        # Normalize magnitudes
+        for actor in actors:
+            mask = panel[actor]['event_count'] > 0
+            panel[actor].loc[mask, 'avg_magnitude'] /= panel[actor].loc[mask, 'event_count']
+
+        return panel

geobot/data_ingestion/pdf_reader.py

@@ -0,0 +1,493 @@
+"""
+PDF Reading and Processing Module
+
+Comprehensive PDF ingestion capabilities for geopolitical intelligence documents,
+reports, briefings, and analysis.
+
+Supports:
+- Text extraction from PDFs
+- Table extraction
+- Metadata extraction
+- Multi-format PDF handling
+- Batch processing
+"""
+
+import os
+from typing import Dict, List, Optional, Any, Tuple
+from pathlib import Path
+import re
+
+
+class PDFReader:
+    """
+    Read and extract text from PDF documents.
+
+    Supports multiple PDF libraries for robust extraction.
+    """
+
+    def __init__(self, method: str = 'auto'):
+        """
+        Initialize PDF reader.
+
+        Parameters
+        ----------
+        method : str
+            Extraction method ('pypdf', 'pdfplumber', 'pdfminer', 'auto')
+        """
+        self.method = method
+        self._check_dependencies()
+
+    def _check_dependencies(self) -> None:
+        """Check which PDF libraries are available."""
+        self.has_pypdf = False
+        self.has_pdfplumber = False
+        self.has_pdfminer = False
+
+        try:
+            import pypdf
+            self.has_pypdf = True
+        except ImportError:
+            pass
+
+        try:
+            import pdfplumber
+            self.has_pdfplumber = True
+        except ImportError:
+            pass
+
+        try:
+            from pdfminer.high_level import extract_text as pdfminer_extract
+            self.has_pdfminer = True
+        except ImportError:
+            pass
+
+        if not any([self.has_pypdf, self.has_pdfplumber, self.has_pdfminer]):
+            print("Warning: No PDF libraries available. Please install pypdf, pdfplumber, or pdfminer.six")
+
+    def read_pdf(self, pdf_path: str) -> Dict[str, Any]:
+        """
+        Read PDF and extract all information.
+
+        Parameters
+        ----------
+        pdf_path : str
+            Path to PDF file
+
+        Returns
+        -------
+        dict
+            Extracted information including text, metadata, pages
+        """
+        if not os.path.exists(pdf_path):
+            raise FileNotFoundError(f"PDF not found: {pdf_path}")
+
+        method = self.method
+        if method == 'auto':
+            # Choose best available method
+            if self.has_pdfplumber:
+                method = 'pdfplumber'
+            elif self.has_pypdf:
+                method = 'pypdf'
+            elif self.has_pdfminer:
+                method = 'pdfminer'
+            else:
+                raise ImportError("No PDF library available")
+
+        if method == 'pypdf':
+            return self._read_with_pypdf(pdf_path)
+        elif method == 'pdfplumber':
+            return self._read_with_pdfplumber(pdf_path)
+        elif method == 'pdfminer':
+            return self._read_with_pdfminer(pdf_path)
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+    def _read_with_pypdf(self, pdf_path: str) -> Dict[str, Any]:
+        """Read PDF using pypdf."""
+        import pypdf
+
+        result = {
+            'text': '',
+            'pages': [],
+            'metadata': {},
+            'num_pages': 0
+        }
+
+        with open(pdf_path, 'rb') as file:
+            reader = pypdf.PdfReader(file)
+            result['num_pages'] = len(reader.pages)
+
+            # Extract metadata
+            if reader.metadata:
+                result['metadata'] = {
+                    'title': reader.metadata.get('/Title', ''),
+                    'author': reader.metadata.get('/Author', ''),
+                    'subject': reader.metadata.get('/Subject', ''),
+                    'creator': reader.metadata.get('/Creator', ''),
+                }
+
+            # Extract text from each page
+            for page_num, page in enumerate(reader.pages):
+                page_text = page.extract_text()
+                result['pages'].append({
+                    'page_number': page_num + 1,
+                    'text': page_text
+                })
+                result['text'] += page_text + '\n'
+
+        return result
+
+    def _read_with_pdfplumber(self, pdf_path: str) -> Dict[str, Any]:
+        """Read PDF using pdfplumber (best for tables)."""
+        import pdfplumber
+
+        result = {
+            'text': '',
+            'pages': [],
+            'tables': [],
+            'metadata': {},
+            'num_pages': 0
+        }
+
+        with pdfplumber.open(pdf_path) as pdf:
+            result['num_pages'] = len(pdf.pages)
+            result['metadata'] = pdf.metadata
+
+            for page_num, page in enumerate(pdf.pages):
+                page_text = page.extract_text()
+                page_tables = page.extract_tables()
+
+                result['pages'].append({
+                    'page_number': page_num + 1,
+                    'text': page_text,
+                    'tables': page_tables
+                })
+
+                result['text'] += page_text + '\n' if page_text else ''
+
+                if page_tables:
+                    result['tables'].extend([{
+                        'page': page_num + 1,
+                        'data': table
+                    } for table in page_tables])
+
+        return result
+
+    def _read_with_pdfminer(self, pdf_path: str) -> Dict[str, Any]:
+        """Read PDF using pdfminer."""
+        from pdfminer.high_level import extract_text, extract_pages
+        from pdfminer.layout import LTTextContainer
+
+        result = {
+            'text': '',
+            'pages': [],
+            'metadata': {},
+            'num_pages': 0
+        }
+
+        # Extract all text
+        result['text'] = extract_text(pdf_path)
+
+        # Extract page by page
+        pages = list(extract_pages(pdf_path))
+        result['num_pages'] = len(pages)
+
+        for page_num, page_layout in enumerate(pages):
+            page_text = ''
+            for element in page_layout:
+                if isinstance(element, LTTextContainer):
+                    page_text += element.get_text()
+
+            result['pages'].append({
+                'page_number': page_num + 1,
+                'text': page_text
+            })
+
+        return result
+
+    def extract_text(self, pdf_path: str) -> str:
+        """
+        Extract text from PDF (simple interface).
+
+        Parameters
+        ----------
+        pdf_path : str
+            Path to PDF
+
+        Returns
+        -------
+        str
+            Extracted text
+        """
+        result = self.read_pdf(pdf_path)
+        return result['text']
+
+    def extract_tables(self, pdf_path: str) -> List[List[List[str]]]:
+        """
+        Extract tables from PDF.
+
+        Parameters
+        ----------
+        pdf_path : str
+            Path to PDF
+
+        Returns
+        -------
+        list
+            List of tables
+        """
+        if not self.has_pdfplumber:
+            print("Warning: pdfplumber required for table extraction")
+            return []
+
+        result = self._read_with_pdfplumber(pdf_path)
+        return [table['data'] for table in result.get('tables', [])]
+
+
+class PDFProcessor:
+    """
+    Process and analyze PDF documents for geopolitical intelligence.
+
+    Provides high-level processing capabilities including:
+    - Entity extraction
+    - Topic extraction
+    - Sentiment analysis
+    - Key phrase extraction
+    """
+
+    def __init__(self, pdf_reader: Optional[PDFReader] = None):
+        """
+        Initialize PDF processor.
+
+        Parameters
+        ----------
+        pdf_reader : PDFReader, optional
+            PDF reader to use
+        """
+        self.reader = pdf_reader or PDFReader()
+
+    def process_document(self, pdf_path: str) -> Dict[str, Any]:
+        """
+        Process PDF document and extract intelligence.
+
+        Parameters
+        ----------
+        pdf_path : str
+            Path to PDF
+
+        Returns
+        -------
+        dict
+            Processed document with analysis
+        """
+        # Extract content
+        content = self.reader.read_pdf(pdf_path)
+
+        # Basic processing
+        processed = {
+            'file_path': pdf_path,
+            'file_name': Path(pdf_path).name,
+            'text': content['text'],
+            'num_pages': content['num_pages'],
+            'metadata': content.get('metadata', {}),
+            'word_count': len(content['text'].split()),
+            'char_count': len(content['text']),
+        }
+
+        # Extract key information
+        processed['entities'] = self._extract_entities(content['text'])
+        processed['keywords'] = self._extract_keywords(content['text'])
+        processed['summary'] = self._generate_summary(content['text'])
+
+        return processed
+
+    def _extract_entities(self, text: str) -> Dict[str, List[str]]:
+        """
+        Extract named entities (countries, organizations, people).
+
+        Parameters
+        ----------
+        text : str
+            Text to analyze
+
+        Returns
+        -------
+        dict
+            Extracted entities by type
+        """
+        entities = {
+            'countries': [],
+            'organizations': [],
+            'people': [],
+            'locations': []
+        }
+
+        # Simple pattern-based extraction (can be enhanced with NER)
+        # Common country names
+        countries = ['United States', 'China', 'Russia', 'Iran', 'North Korea',
+                    'India', 'Pakistan', 'Israel', 'Saudi Arabia', 'Turkey',
+                    'France', 'Germany', 'United Kingdom', 'Japan', 'South Korea']
+
+        for country in countries:
+            if country in text:
+                entities['countries'].append(country)
+
+        # Organizations (simple patterns)
+        org_patterns = [r'\b([A-Z][A-Za-z]+(?:\s+[A-Z][A-Za-z]+)*)\s+(?:Organization|Agency|Ministry|Department|Council)\b']
+        for pattern in org_patterns:
+            matches = re.findall(pattern, text)
+            entities['organizations'].extend(matches)
+
+        return entities
+
+    def _extract_keywords(self, text: str, n_keywords: int = 10) -> List[Tuple[str, float]]:
+        """
+        Extract keywords from text.
+
+        Parameters
+        ----------
+        text : str
+            Text to analyze
+        n_keywords : int
+            Number of keywords to extract
+
+        Returns
+        -------
+        list
+            List of (keyword, score) tuples
+        """
+        # Simple frequency-based extraction
+        words = text.lower().split()
+
+        # Remove common words
+        stopwords = {'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at',
+                    'to', 'for', 'of', 'with', 'by', 'from', 'as', 'is', 'was',
+                    'are', 'were', 'been', 'be', 'have', 'has', 'had', 'do',
+                    'does', 'did', 'will', 'would', 'should', 'could', 'may',
+                    'might', 'can', 'this', 'that', 'these', 'those'}
+
+        words = [w for w in words if w not in stopwords and len(w) > 3]
+
+        # Count frequencies
+        from collections import Counter
+        word_freq = Counter(words)
+
+        # Return top keywords
+        return word_freq.most_common(n_keywords)
+
+    def _generate_summary(self, text: str, num_sentences: int = 3) -> str:
+        """
+        Generate simple extractive summary.
+
+        Parameters
+        ----------
+        text : str
+            Text to summarize
+        num_sentences : int
+            Number of sentences in summary
+
+        Returns
+        -------
+        str
+            Summary
+        """
+        # Split into sentences
+        sentences = re.split(r'[.!?]+', text)
+        sentences = [s.strip() for s in sentences if len(s.strip()) > 20]
+
+        # Take first few sentences as summary (simple approach)
+        summary_sentences = sentences[:num_sentences]
+
+        return '. '.join(summary_sentences) + '.'
+
+    def batch_process(self, pdf_directory: str, pattern: str = '*.pdf') -> List[Dict[str, Any]]:
+        """
+        Process multiple PDFs in a directory.
+
+        Parameters
+        ----------
+        pdf_directory : str
+            Directory containing PDFs
+        pattern : str
+            File pattern to match
+
+        Returns
+        -------
+        list
+            List of processed documents
+        """
+        pdf_dir = Path(pdf_directory)
+        pdf_files = list(pdf_dir.glob(pattern))
+
+        results = []
+        for pdf_file in pdf_files:
+            try:
+                processed = self.process_document(str(pdf_file))
+                results.append(processed)
+            except Exception as e:
+                print(f"Error processing {pdf_file}: {e}")
+
+        return results
+
+    def extract_intelligence(self, pdf_path: str) -> Dict[str, Any]:
+        """
+        Extract geopolitical intelligence from PDF.
+
+        Parameters
+        ----------
+        pdf_path : str
+            Path to PDF
+
+        Returns
+        -------
+        dict
+            Intelligence summary
+        """
+        processed = self.process_document(pdf_path)
+
+        # Analyze for geopolitical indicators
+        text = processed['text'].lower()
+
+        indicators = {
+            'conflict_indicators': self._detect_conflict_indicators(text),
+            'risk_level': self._assess_risk_level(text),
+            'mentioned_countries': processed['entities'].get('countries', []),
+            'key_topics': [kw[0] for kw in processed['keywords'][:5]],
+            'document_type': self._classify_document_type(text)
+        }
+
+        return {**processed, 'intelligence': indicators}
+
+    def _detect_conflict_indicators(self, text: str) -> List[str]:
+        """Detect conflict-related keywords."""
+        conflict_keywords = ['war', 'conflict', 'military', 'attack', 'invasion',
+                            'sanctions', 'escalation', 'tension', 'threat', 'crisis']
+
+        detected = [kw for kw in conflict_keywords if kw in text]
+        return detected
+
+    def _assess_risk_level(self, text: str) -> str:
+        """Simple risk level assessment."""
+        high_risk_terms = ['imminent', 'urgent', 'critical', 'severe', 'escalating']
+        medium_risk_terms = ['concern', 'monitoring', 'potential', 'emerging']
+
+        high_count = sum(1 for term in high_risk_terms if term in text)
+        medium_count = sum(1 for term in medium_risk_terms if term in text)
+
+        if high_count > 2:
+            return 'HIGH'
+        elif medium_count > 2:
+            return 'MEDIUM'
+        else:
+            return 'LOW'
+
+    def _classify_document_type(self, text: str) -> str:
+        """Classify document type."""
+        if 'intelligence report' in text or 'classified' in text:
+            return 'Intelligence Report'
+        elif 'analysis' in text or 'assessment' in text:
+            return 'Analysis'
+        elif 'briefing' in text:
+            return 'Briefing'
+        else:
+            return 'General Document'

geobot/data_ingestion/web_scraper.py

@@ -0,0 +1,365 @@
+"""
+Web Scraping and Article Extraction Module
+
+Comprehensive web scraping capabilities for:
+- News articles
+- Analysis pieces
+- Intelligence reports
+- Research papers
+- Real-time news feeds
+
+Supports multiple extraction methods for robustness.
+"""
+
+import re
+import requests
+from datetime import datetime
+from urllib.parse import urlparse
+from typing import (
+    List,
+    Dict,
+    Any,
+    Tuple,
+    Optional,
+    Callable,
+)
+
+# -----------------------------------------------------
+#                     WEB SCRAPER
+# -----------------------------------------------------
+
+class WebScraper:
+    """
+    General-purpose web scraper for geopolitical content.
+    Handles various website structures and content types.
+    """
+
+    def __init__(self, user_agent: Optional[str] = None):
+        self.user_agent = user_agent or "GeoBotv1/1.0 (Geopolitical Analysis)"
+        self.session = requests.Session()
+        self.session.headers.update({"User-Agent": self.user_agent})
+
+    def fetch_url(self, url: str, timeout: int = 30) -> Dict[str, Any]:
+        """Fetch raw HTML from a URL."""
+        try:
+            response = self.session.get(url, timeout=timeout)
+            response.raise_for_status()
+            return {
+                "url": url,
+                "status_code": response.status_code,
+                "content": response.text,
+                "headers": dict(response.headers),
+                "encoding": response.encoding,
+                "timestamp": datetime.now().isoformat(),
+            }
+
+        except requests.RequestException as e:
+            return {
+                "url": url,
+                "error": str(e),
+                "status_code": None,
+                "content": None,
+                "timestamp": datetime.now().isoformat(),
+            }
+
+    def parse_html(self, html_content: str) -> Dict[str, Any]:
+        """Parse HTML using BeautifulSoup if available."""
+        try:
+            from bs4 import BeautifulSoup
+
+            soup = BeautifulSoup(html_content, "html.parser")
+
+            parsed = {
+                "title": soup.title.string if soup.title else "",
+                "text": soup.get_text(),
+                "links": [a.get("href") for a in soup.find_all("a", href=True)],
+                "images": [img.get("src") for img in soup.find_all("img", src=True)],
+                "meta": {},
+            }
+
+            for meta in soup.find_all("meta"):
+                name = meta.get("name") or meta.get("property")
+                content = meta.get("content")
+                if name and content:
+                    parsed["meta"][name] = content
+
+            return parsed
+
+        except ImportError:
+            # Fallback if soup is missing
+            return {
+                "title": "",
+                "text": self._simple_html_strip(html_content),
+                "links": [],
+                "images": [],
+                "meta": {},
+            }
+
+    def _simple_html_strip(self, html: str) -> str:
+        """Simple fallback for removing HTML tags."""
+        return re.sub(r"<[^>]+>", "", html)
+
+    def scrape_url(self, url: str) -> Dict[str, Any]:
+        """Fetch + parse a URL."""
+        response = self.fetch_url(url)
+        if response.get("error"):
+            return response
+
+        parsed = self.parse_html(response["content"])
+
+        return {
+            "url": url,
+            "domain": urlparse(url).netloc,
+            "title": parsed["title"],
+            "text": parsed["text"],
+            "meta": parsed["meta"],
+            "links": parsed["links"],
+            "images": parsed["images"],
+            "timestamp": response["timestamp"],
+            "status_code": response["status_code"],
+        }
+
+
+# -----------------------------------------------------
+#                 ARTICLE EXTRACTION
+# -----------------------------------------------------
+
+class ArticleExtractor:
+    """
+    Wrapper for newspaper3k / trafilatura / fallback extraction.
+    """
+
+    def __init__(self, method: str = "auto"):
+        self.method = method
+        self._check_dependencies()
+
+    def _check_dependencies(self) -> None:
+        self.has_newspaper = False
+        self.has_trafilatura = False
+
+        try:
+            import newspaper  # noqa
+            self.has_newspaper = True
+        except ImportError:
+            pass
+
+        try:
+            import trafilatura  # noqa
+            self.has_trafilatura = True
+        except ImportError:
+            pass
+
+    def extract_article(self, url: str) -> Dict[str, Any]:
+        """Choose extraction method based on dependencies."""
+        method = self.method
+
+        if method == "auto":
+            if self.has_newspaper:
+                method = "newspaper"
+            elif self.has_trafilatura:
+                method = "trafilatura"
+            else:
+                method = "basic"
+
+        if method == "newspaper":
+            return self._extract_with_newspaper(url)
+        elif method == "trafilatura":
+            return self._extract_with_trafilatura(url)
+        else:
+            return self._extract_basic(url)
+
+    def _extract_with_newspaper(self, url: str) -> Dict[str, Any]:
+        """Extract article using newspaper3k."""
+        try:
+            from newspaper import Article
+
+            article = Article(url)
+            article.download()
+            article.parse()
+
+            try:
+                article.nlp()
+                keywords = article.keywords
+                summary = article.summary
+            except Exception:
+                keywords = []
+                summary = ""
+
+            return {
+                "url": url,
+                "title": article.title,
+                "text": article.text,
+                "authors": article.authors,
+                "publish_date": article.publish_date.isoformat() if article.publish_date else None,
+                "keywords": keywords,
+                "summary": summary,
+                "top_image": article.top_image,
+                "images": list(article.images),
+                "method": "newspaper",
+                "timestamp": datetime.now().isoformat(),
+            }
+
+        except Exception as e:
+            return {"url": url, "error": str(e), "method": "newspaper"}
+
+    def _extract_with_trafilatura(self, url: str) -> Dict[str, Any]:
+        """Extract article using trafilatura."""
+        try:
+            import trafilatura
+
+            downloaded = trafilatura.fetch_url(url)
+            text = trafilatura.extract(downloaded)
+            metadata = trafilatura.extract_metadata(downloaded)
+
+            return {
+                "url": url,
+                "title": metadata.title if metadata else "",
+                "text": text or "",
+                "authors": [metadata.author] if metadata and metadata.author else [],
+                "publish_date": metadata.date if metadata else None,
+                "description": metadata.description if metadata else "",
+                "method": "trafilatura",
+                "timestamp": datetime.now().isoformat(),
+            }
+
+        except Exception as e:
+            return {"url": url, "error": str(e), "method": "trafilatura"}
+
+    def _extract_basic(self, url: str) -> Dict[str, Any]:
+        scraper = WebScraper()
+        content = scraper.scrape_url(url)
+
+        return {
+            "url": url,
+            "title": content.get("title", ""),
+            "text": content.get("text", ""),
+            "meta": content.get("meta", {}),
+            "method": "basic",
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    def batch_extract(self, urls: List[str]) -> List[Dict[str, Any]]:
+        articles = []
+        for url in urls:
+            try:
+                articles.append(self.extract_article(url))
+            except Exception as e:
+                print(f"Error extracting {url}: {e}")
+        return articles
+
+
+# -----------------------------------------------------
+#                NEWS AGGREGATOR
+# -----------------------------------------------------
+
+class NewsAggregator:
+    """Aggregate RSS feeds + websites into normalized article objects."""
+
+    def __init__(self):
+        self.extractor = ArticleExtractor()
+        self.sources: List[Dict[str, Any]] = []
+
+    def add_source(self, name: str, url: str, source_type: str = "rss") -> None:
+        self.sources.append({"name": name, "url": url, "type": source_type})
+
+    def fetch_news(self, keywords: Optional[List[str]] = None) -> List[Dict[str, Any]]:
+        articles = []
+
+        for source in self.sources:
+            try:
+                if source["type"] == "rss":
+                    pulled = self._fetch_rss(source["url"])
+                else:
+                    pulled = self._fetch_website(source["url"])
+
+                for a in pulled:
+                    a["source"] = source["name"]
+                    if keywords:
+                        txt = a.get("text", "").lower()
+                        if any(kw.lower() in txt for kw in keywords):
+                            articles.append(a)
+                    else:
+                        articles.append(a)
+
+            except Exception as e:
+                print(f"Error fetching from {source['name']}: {e}")
+
+        return articles
+
+    def _fetch_rss(self, rss_url: str) -> List[Dict[str, Any]]:
+        try:
+            import feedparser
+
+            feed = feedparser.parse(rss_url)
+            articles = []
+
+            for entry in feed.entries:
+                base = {
+                    "title": entry.get("title", ""),
+                    "url": entry.get("link", ""),
+                    "summary": entry.get("summary", ""),
+                    "publish_date": entry.get("published", ""),
+                    "authors": [a.get("name") for a in entry.get("authors", [])],
+                }
+
+                if base["url"]:
+                    try:
+                        full = self.extractor.extract_article(base["url"])
+                        base["text"] = full.get("text", base["summary"])
+                    except Exception:
+                        base["text"] = base["summary"]
+
+                articles.append(base)
+
+            return articles
+
+        except ImportError:
+            print("feedparser not installed: pip install feedparser")
+            return []
+
+    def _fetch_website(self, url: str) -> List[Dict[str, Any]]:
+        article = self.extractor.extract_article(url)
+        return [article] if not article.get("error") else []
+
+    def monitor_sources(
+        self,
+        keywords: List[str],
+        callback: Optional[Callable[[List[Dict[str, Any]]], None]] = None,
+        interval: int = 3600,
+    ) -> None:
+        """Continuously monitor sources for new articles."""
+        import time
+
+        seen: set = set()
+
+        while True:
+            articles = self.fetch_news(keywords)
+            new_articles = [a for a in articles if a["url"] not in seen]
+
+            if new_articles and callback:
+                callback(new_articles)
+
+            seen.update(a["url"] for a in new_articles)
+
+            time.sleep(interval)
+
+    def get_trending_topics(
+        self,
+        articles: List[Dict[str, Any]],
+        n_topics: int = 10
+    ) -> List[Tuple[str, int]]:
+        """Compute most common keywords."""
+        from collections import Counter
+
+        words = []
+        stop = {
+            "the", "a", "an", "and", "or", "but", "in", "on", "at",
+            "to", "for", "of", "with", "by", "from"
+        }
+
+        for art in articles:
+            text = (art.get("text", "") + " " + art.get("title", "")).lower()
+            ws = [w for w in text.split() if len(w) > 3 and w not in stop]
+            words.extend(ws)
+
+        return Counter(words).most_common(n_topics)

geobot/inference/__init__.py

@@ -0,0 +1,21 @@
+"""
+Inference engines for GeoBotv1
+"""
+
+from .do_calculus import DoCalculus, InterventionSimulator
+from .bayesian_engine import BayesianEngine, BeliefUpdater
+from .particle_filter import SequentialMonteCarlo, AuxiliaryParticleFilter, RaoBlackwellizedParticleFilter
+from .variational_inference import VariationalInference, MeanFieldVI, ADVI
+
+__all__ = [
+    "DoCalculus",
+    "InterventionSimulator",
+    "BayesianEngine",
+    "BeliefUpdater",
+    "SequentialMonteCarlo",
+    "AuxiliaryParticleFilter",
+    "RaoBlackwellizedParticleFilter",
+    "VariationalInference",
+    "MeanFieldVI",
+    "ADVI",
+]

geobot/inference/bayesian_engine.py

@@ -0,0 +1,606 @@
+"""
+Bayesian Inference Engine
+
+Provides principled way to update beliefs as new intelligence, rumors,
+events, or data arrive.
+
+Components:
+- Priors: Baseline beliefs
+- Likelihood: Evidence
+- Posteriors: Updated beliefs
+
+Necessary for:
+- Real-time updates
+- Intelligence feeds
+- Event-driven recalibration
+- Uncertainty tracking
+
+Monte Carlo + Bayesian updating = elite forecasting
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Optional, Callable, Any, Tuple
+from dataclasses import dataclass
+from scipy import stats
+
+
+@dataclass
+class Prior:
+    """
+    Represents a prior distribution.
+
+    Attributes
+    ----------
+    name : str
+        Name of the variable
+    distribution : Any
+        Prior distribution (scipy.stats distribution)
+    parameters : dict
+        Distribution parameters
+    """
+    name: str
+    distribution: Any
+    parameters: Dict[str, float]
+
+    def sample(self, n_samples: int = 1) -> np.ndarray:
+        """
+        Sample from prior.
+
+        Parameters
+        ----------
+        n_samples : int
+            Number of samples
+
+        Returns
+        -------
+        np.ndarray
+            Samples from prior
+        """
+        return self.distribution.rvs(size=n_samples, **self.parameters)
+
+    def pdf(self, x: np.ndarray) -> np.ndarray:
+        """
+        Evaluate prior probability density.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Points to evaluate
+
+        Returns
+        -------
+        np.ndarray
+            Probability densities
+        """
+        return self.distribution.pdf(x, **self.parameters)
+
+    def log_pdf(self, x: np.ndarray) -> np.ndarray:
+        """
+        Evaluate log prior probability density.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Points to evaluate
+
+        Returns
+        -------
+        np.ndarray
+            Log probability densities
+        """
+        return self.distribution.logpdf(x, **self.parameters)
+
+
+@dataclass
+class Evidence:
+    """
+    Represents evidence/observation.
+
+    Attributes
+    ----------
+    observation : Any
+        Observed data
+    likelihood_fn : Callable
+        Likelihood function
+    timestamp : float
+        Time of observation
+    confidence : float
+        Confidence in observation (0-1)
+    """
+    observation: Any
+    likelihood_fn: Callable
+    timestamp: float
+    confidence: float = 1.0
+
+
+class BayesianEngine:
+    """
+    Bayesian inference engine for belief updating.
+
+    This engine maintains and updates probability distributions
+    as new evidence arrives, enabling real-time forecasting with
+    uncertainty quantification.
+    """
+
+    def __init__(self):
+        """Initialize Bayesian engine."""
+        self.priors: Dict[str, Prior] = {}
+        self.posteriors: Dict[str, np.ndarray] = {}
+        self.evidence_history: List[Evidence] = []
+
+    def set_prior(self, prior: Prior) -> None:
+        """
+        Set prior distribution for a variable.
+
+        Parameters
+        ----------
+        prior : Prior
+            Prior distribution
+        """
+        self.priors[prior.name] = prior
+
+    def update(
+        self,
+        variable: str,
+        evidence: Evidence,
+        method: str = 'grid'
+    ) -> np.ndarray:
+        """
+        Update beliefs given evidence.
+
+        Parameters
+        ----------
+        variable : str
+            Variable to update
+        evidence : Evidence
+            New evidence
+        method : str
+            Update method ('grid', 'mcmc', 'analytical')
+
+        Returns
+        -------
+        np.ndarray
+            Posterior samples
+        """
+        if variable not in self.priors:
+            raise ValueError(f"No prior set for {variable}")
+
+        self.evidence_history.append(evidence)
+
+        if method == 'grid':
+            posterior = self._grid_update(variable, evidence)
+        elif method == 'mcmc':
+            posterior = self._mcmc_update(variable, evidence)
+        elif method == 'analytical':
+            posterior = self._analytical_update(variable, evidence)
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+        self.posteriors[variable] = posterior
+        return posterior
+
+    def _grid_update(self, variable: str, evidence: Evidence) -> np.ndarray:
+        """
+        Grid approximation for Bayesian update.
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+        evidence : Evidence
+            Evidence
+
+        Returns
+        -------
+        np.ndarray
+            Posterior samples
+        """
+        prior = self.priors[variable]
+
+        # Create grid
+        n_grid = 1000
+        if hasattr(prior.distribution, 'support'):
+            support = prior.distribution.support()
+            grid = np.linspace(support[0], support[1], n_grid)
+        else:
+            # Default grid
+            mean = prior.parameters.get('loc', 0)
+            std = prior.parameters.get('scale', 1)
+            grid = np.linspace(mean - 4*std, mean + 4*std, n_grid)
+
+        # Compute prior * likelihood
+        prior_vals = prior.pdf(grid)
+        likelihood_vals = evidence.likelihood_fn(grid, evidence.observation)
+
+        # Weight by evidence confidence
+        likelihood_vals = likelihood_vals ** evidence.confidence
+
+        # Compute posterior (unnormalized)
+        posterior_vals = prior_vals * likelihood_vals
+
+        # Normalize
+        posterior_vals /= posterior_vals.sum()
+
+        # Sample from posterior
+        n_samples = 10000
+        posterior_samples = np.random.choice(grid, size=n_samples, p=posterior_vals)
+
+        return posterior_samples
+
+    def _mcmc_update(
+        self,
+        variable: str,
+        evidence: Evidence,
+        n_samples: int = 10000
+    ) -> np.ndarray:
+        """
+        MCMC-based Bayesian update.
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+        evidence : Evidence
+            Evidence
+        n_samples : int
+            Number of MCMC samples
+
+        Returns
+        -------
+        np.ndarray
+            Posterior samples
+        """
+        prior = self.priors[variable]
+
+        def log_posterior(x):
+            log_prior = prior.log_pdf(np.array([x]))[0]
+            log_likelihood = np.log(evidence.likelihood_fn(np.array([x]), evidence.observation)[0] + 1e-10)
+            return log_prior + evidence.confidence * log_likelihood
+
+        # Simple Metropolis-Hastings
+        samples = []
+        current = prior.sample(1)[0]
+        current_log_p = log_posterior(current)
+
+        for _ in range(n_samples):
+            # Propose
+            proposal = current + np.random.normal(0, 0.1)
+            proposal_log_p = log_posterior(proposal)
+
+            # Accept/reject
+            log_alpha = proposal_log_p - current_log_p
+            if np.log(np.random.uniform()) < log_alpha:
+                current = proposal
+                current_log_p = proposal_log_p
+
+            samples.append(current)
+
+        return np.array(samples)
+
+    def _analytical_update(self, variable: str, evidence: Evidence) -> np.ndarray:
+        """
+        Analytical Bayesian update (for conjugate priors).
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+        evidence : Evidence
+            Evidence
+
+        Returns
+        -------
+        np.ndarray
+            Posterior samples
+        """
+        # Placeholder - would implement conjugate updates
+        # For now, fall back to grid
+        return self._grid_update(variable, evidence)
+
+    def get_posterior_summary(self, variable: str) -> Dict[str, float]:
+        """
+        Get summary statistics of posterior.
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+
+        Returns
+        -------
+        dict
+            Summary statistics
+        """
+        if variable not in self.posteriors:
+            raise ValueError(f"No posterior for {variable}")
+
+        samples = self.posteriors[variable]
+
+        return {
+            'mean': np.mean(samples),
+            'median': np.median(samples),
+            'std': np.std(samples),
+            'q5': np.percentile(samples, 5),
+            'q25': np.percentile(samples, 25),
+            'q75': np.percentile(samples, 75),
+            'q95': np.percentile(samples, 95)
+        }
+
+    def get_credible_interval(
+        self,
+        variable: str,
+        alpha: float = 0.05
+    ) -> Tuple[float, float]:
+        """
+        Get credible interval for posterior.
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+        alpha : float
+            Significance level
+
+        Returns
+        -------
+        tuple
+            (lower, upper) bounds of credible interval
+        """
+        if variable not in self.posteriors:
+            raise ValueError(f"No posterior for {variable}")
+
+        samples = self.posteriors[variable]
+        lower = np.percentile(samples, 100 * alpha / 2)
+        upper = np.percentile(samples, 100 * (1 - alpha / 2))
+
+        return lower, upper
+
+    def compute_bayes_factor(
+        self,
+        variable: str,
+        hypothesis1: Callable,
+        hypothesis2: Callable
+    ) -> float:
+        """
+        Compute Bayes factor for two hypotheses.
+
+        Parameters
+        ----------
+        variable : str
+            Variable name
+        hypothesis1 : callable
+            First hypothesis (returns bool)
+        hypothesis2 : callable
+            Second hypothesis (returns bool)
+
+        Returns
+        -------
+        float
+            Bayes factor (BF > 1 favors hypothesis1)
+        """
+        if variable not in self.posteriors:
+            raise ValueError(f"No posterior for {variable}")
+
+        samples = self.posteriors[variable]
+
+        p1 = np.mean([hypothesis1(x) for x in samples])
+        p2 = np.mean([hypothesis2(x) for x in samples])
+
+        if p2 == 0:
+            return np.inf
+        return p1 / p2
+
+
+class BeliefUpdater:
+    """
+    High-level interface for updating geopolitical beliefs.
+
+    This class provides domain-specific methods for updating
+    beliefs based on intelligence, events, and rumors.
+    """
+
+    def __init__(self):
+        """Initialize belief updater."""
+        self.engine = BayesianEngine()
+        self.beliefs: Dict[str, Dict[str, Any]] = {}
+
+    def initialize_belief(
+        self,
+        name: str,
+        prior_mean: float,
+        prior_std: float,
+        belief_type: str = 'continuous'
+    ) -> None:
+        """
+        Initialize a belief with prior.
+
+        Parameters
+        ----------
+        name : str
+            Belief name
+        prior_mean : float
+            Prior mean
+        prior_std : float
+            Prior standard deviation
+        belief_type : str
+            Type of belief ('continuous', 'probability')
+        """
+        if belief_type == 'continuous':
+            distribution = stats.norm
+        elif belief_type == 'probability':
+            # Use beta distribution for probabilities
+            # Convert mean/std to alpha/beta parameters
+            mean = np.clip(prior_mean, 0.01, 0.99)
+            var = prior_std ** 2
+            alpha = mean * (mean * (1 - mean) / var - 1)
+            beta = (1 - mean) * (mean * (1 - mean) / var - 1)
+            distribution = stats.beta
+            prior_mean = alpha
+            prior_std = beta
+        else:
+            distribution = stats.norm
+
+        prior = Prior(
+            name=name,
+            distribution=distribution,
+            parameters={'loc': prior_mean, 'scale': prior_std}
+        )
+
+        self.engine.set_prior(prior)
+        self.beliefs[name] = {
+            'type': belief_type,
+            'initialized': True
+        }
+
+    def update_from_intelligence(
+        self,
+        belief: str,
+        observation: float,
+        reliability: float = 0.8
+    ) -> Dict[str, float]:
+        """
+        Update belief from intelligence report.
+
+        Parameters
+        ----------
+        belief : str
+            Belief name
+        observation : float
+            Observed value from intelligence
+        reliability : float
+            Reliability of intelligence source (0-1)
+
+        Returns
+        -------
+        dict
+            Posterior summary
+        """
+        def likelihood_fn(x, obs):
+            # Gaussian likelihood centered at observation
+            # Width depends on reliability
+            std = 1.0 / reliability
+            return stats.norm.pdf(x, loc=obs, scale=std)
+
+        evidence = Evidence(
+            observation=observation,
+            likelihood_fn=likelihood_fn,
+            timestamp=pd.Timestamp.now().timestamp(),
+            confidence=reliability
+        )
+
+        self.engine.update(belief, evidence, method='grid')
+        return self.engine.get_posterior_summary(belief)
+
+    def update_from_event(
+        self,
+        belief: str,
+        event_impact: float,
+        event_certainty: float = 1.0
+    ) -> Dict[str, float]:
+        """
+        Update belief from observed event.
+
+        Parameters
+        ----------
+        belief : str
+            Belief name
+        event_impact : float
+            Impact of event (shift in belief)
+        event_certainty : float
+            Certainty that event occurred (0-1)
+
+        Returns
+        -------
+        dict
+            Posterior summary
+        """
+        # Get current belief
+        if belief not in self.engine.posteriors:
+            # Use prior
+            current_samples = self.engine.priors[belief].sample(10000)
+        else:
+            current_samples = self.engine.posteriors[belief]
+
+        current_mean = np.mean(current_samples)
+
+        # Create shifted observation
+        observation = current_mean + event_impact
+
+        def likelihood_fn(x, obs):
+            return stats.norm.pdf(x, loc=obs, scale=abs(event_impact) * 0.1)
+
+        evidence = Evidence(
+            observation=observation,
+            likelihood_fn=likelihood_fn,
+            timestamp=pd.Timestamp.now().timestamp(),
+            confidence=event_certainty
+        )
+
+        self.engine.update(belief, evidence, method='grid')
+        return self.engine.get_posterior_summary(belief)
+
+    def get_belief_probability(
+        self,
+        belief: str,
+        threshold: float,
+        direction: str = 'greater'
+    ) -> float:
+        """
+        Get probability that belief exceeds threshold.
+
+        Parameters
+        ----------
+        belief : str
+            Belief name
+        threshold : float
+            Threshold value
+        direction : str
+            'greater' or 'less'
+
+        Returns
+        -------
+        float
+            Probability
+        """
+        if belief not in self.engine.posteriors:
+            samples = self.engine.priors[belief].sample(10000)
+        else:
+            samples = self.engine.posteriors[belief]
+
+        if direction == 'greater':
+            return np.mean(samples > threshold)
+        else:
+            return np.mean(samples < threshold)
+
+    def compare_beliefs(self, belief1: str, belief2: str) -> Dict[str, float]:
+        """
+        Compare two beliefs.
+
+        Parameters
+        ----------
+        belief1 : str
+            First belief
+        belief2 : str
+            Second belief
+
+        Returns
+        -------
+        dict
+            Comparison results
+        """
+        if belief1 not in self.engine.posteriors:
+            samples1 = self.engine.priors[belief1].sample(10000)
+        else:
+            samples1 = self.engine.posteriors[belief1]
+
+        if belief2 not in self.engine.posteriors:
+            samples2 = self.engine.priors[belief2].sample(10000)
+        else:
+            samples2 = self.engine.posteriors[belief2]
+
+        return {
+            'p_belief1_greater': np.mean(samples1 > samples2),
+            'mean_difference': np.mean(samples1 - samples2),
+            'correlation': np.corrcoef(samples1, samples2)[0, 1]
+        }

geobot/inference/do_calculus.py

@@ -0,0 +1,510 @@
+"""
+Do-Calculus Module - Intervention Reasoning
+
+Implements Pearl's do-calculus for counterfactual analysis and policy simulation.
+
+Instead of just forecasting "what will happen," this module enables:
+- "What if the U.S. sanctions X?"
+- "What if China mobilizes?"
+- "What if NATO deploys troops?"
+- "What if an election is rigged?"
+
+This is the foundation for counterfactual geopolitics.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Set, Optional, Tuple, Any
+from ..models.causal_graph import CausalGraph, StructuralCausalModel
+
+
+class DoCalculus:
+    """
+    Implement Pearl's do-calculus for causal inference.
+
+    The do-calculus provides rules for transforming interventional
+    distributions into observational ones, enabling causal effect
+    estimation from observational data.
+    """
+
+    def __init__(self, causal_graph: CausalGraph):
+        """
+        Initialize do-calculus engine.
+
+        Parameters
+        ----------
+        causal_graph : CausalGraph
+            Causal graph structure
+        """
+        self.graph = causal_graph
+
+    def is_identifiable(
+        self,
+        treatment: str,
+        outcome: str,
+        confounders: Optional[Set[str]] = None
+    ) -> bool:
+        """
+        Check if causal effect is identifiable.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+        confounders : Set[str], optional
+            Known confounders
+
+        Returns
+        -------
+        bool
+            True if effect is identifiable
+        """
+        # Basic check: are treatment and outcome d-separated after intervention?
+        # This is a simplified version
+
+        # Get all backdoor paths
+        backdoor_paths = self._get_backdoor_paths(treatment, outcome)
+
+        if len(backdoor_paths) == 0:
+            # No backdoor paths, effect is identifiable
+            return True
+
+        if confounders is not None:
+            # Check if confounders block all backdoor paths
+            return self._blocks_backdoor_paths(backdoor_paths, confounders)
+
+        return False
+
+    def _get_backdoor_paths(self, treatment: str, outcome: str) -> List[List[str]]:
+        """
+        Get all backdoor paths from treatment to outcome.
+
+        A backdoor path is a path from treatment to outcome that
+        starts with an arrow into the treatment.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+
+        Returns
+        -------
+        List[List[str]]
+            List of backdoor paths
+        """
+        import networkx as nx
+
+        backdoor_paths = []
+
+        # Get all simple paths from treatment to outcome
+        try:
+            all_paths = list(nx.all_simple_paths(
+                self.graph.graph.to_undirected(),
+                treatment,
+                outcome
+            ))
+        except nx.NetworkXNoPath:
+            return []
+
+        # Filter for backdoor paths
+        for path in all_paths:
+            if len(path) > 2:  # Must have intermediate nodes
+                # Check if first edge goes into treatment
+                second_node = path[1]
+                if self.graph.graph.has_edge(second_node, treatment):
+                    backdoor_paths.append(path)
+
+        return backdoor_paths
+
+    def _blocks_backdoor_paths(
+        self,
+        paths: List[List[str]],
+        conditioning_set: Set[str]
+    ) -> bool:
+        """
+        Check if conditioning set blocks all backdoor paths.
+
+        Parameters
+        ----------
+        paths : List[List[str]]
+            Backdoor paths
+        conditioning_set : Set[str]
+            Variables to condition on
+
+        Returns
+        -------
+        bool
+            True if all paths are blocked
+        """
+        for path in paths:
+            if not self._is_path_blocked(path, conditioning_set):
+                return False
+        return True
+
+    def _is_path_blocked(self, path: List[str], conditioning_set: Set[str]) -> bool:
+        """
+        Check if a path is blocked by conditioning set.
+
+        Parameters
+        ----------
+        path : List[str]
+            Path to check
+        conditioning_set : Set[str]
+            Conditioning set
+
+        Returns
+        -------
+        bool
+            True if path is blocked
+        """
+        # Simplified version: check if any non-collider in path is in conditioning set
+        for node in path[1:-1]:  # Exclude endpoints
+            if node in conditioning_set:
+                # Check if it's a collider
+                idx = path.index(node)
+                prev_node = path[idx - 1]
+                next_node = path[idx + 1]
+
+                # It's a collider if both edges point to it
+                is_collider = (
+                    self.graph.graph.has_edge(prev_node, node) and
+                    self.graph.graph.has_edge(next_node, node)
+                )
+
+                if not is_collider:
+                    return True
+
+        return False
+
+    def find_adjustment_set(
+        self,
+        treatment: str,
+        outcome: str,
+        method: str = 'backdoor'
+    ) -> Set[str]:
+        """
+        Find valid adjustment set for identifying causal effect.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+        method : str
+            Method to use ('backdoor', 'minimal')
+
+        Returns
+        -------
+        Set[str]
+            Valid adjustment set
+        """
+        if method == 'backdoor':
+            return self._backdoor_adjustment_set(treatment, outcome)
+        elif method == 'minimal':
+            return self._minimal_adjustment_set(treatment, outcome)
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+    def _backdoor_adjustment_set(self, treatment: str, outcome: str) -> Set[str]:
+        """
+        Find backdoor adjustment set.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+
+        Returns
+        -------
+        Set[str]
+            Backdoor adjustment set
+        """
+        # Get all parents of treatment (excluding outcome's descendants)
+        parents = set(self.graph.get_parents(treatment))
+
+        # Remove outcome and its descendants
+        outcome_descendants = self.graph.get_descendants(outcome)
+        adjustment_set = parents - outcome_descendants - {outcome}
+
+        return adjustment_set
+
+    def _minimal_adjustment_set(self, treatment: str, outcome: str) -> Set[str]:
+        """
+        Find minimal adjustment set.
+
+        Parameters
+        ----------
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+
+        Returns
+        -------
+        Set[str]
+            Minimal adjustment set
+        """
+        # Start with backdoor set
+        backdoor_set = self._backdoor_adjustment_set(treatment, outcome)
+
+        # Try removing variables one by one
+        minimal_set = backdoor_set.copy()
+
+        for var in backdoor_set:
+            candidate_set = minimal_set - {var}
+            backdoor_paths = self._get_backdoor_paths(treatment, outcome)
+
+            if self._blocks_backdoor_paths(backdoor_paths, candidate_set):
+                minimal_set = candidate_set
+
+        return minimal_set
+
+    def compute_ate(
+        self,
+        data: pd.DataFrame,
+        treatment: str,
+        outcome: str,
+        adjustment_set: Optional[Set[str]] = None
+    ) -> float:
+        """
+        Compute Average Treatment Effect (ATE).
+
+        ATE = E[Y | do(X=1)] - E[Y | do(X=0)]
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Observational data
+        treatment : str
+            Treatment variable
+        outcome : str
+            Outcome variable
+        adjustment_set : Set[str], optional
+            Variables to adjust for
+
+        Returns
+        -------
+        float
+            Average Treatment Effect
+        """
+        if adjustment_set is None:
+            adjustment_set = self.find_adjustment_set(treatment, outcome)
+
+        # Stratification estimator
+        if len(adjustment_set) == 0:
+            # No confounding
+            treated = data[data[treatment] == 1][outcome].mean()
+            control = data[data[treatment] == 0][outcome].mean()
+            return treated - control
+
+        # With adjustment
+        # Group by adjustment variables
+        adjustment_vars = list(adjustment_set)
+
+        ate = 0.0
+        for strata, group in data.groupby(adjustment_vars):
+            if len(group) > 0:
+                # Compute effect in this stratum
+                treated = group[group[treatment] == 1][outcome].mean()
+                control = group[group[treatment] == 0][outcome].mean()
+
+                if not np.isnan(treated) and not np.isnan(control):
+                    strata_effect = treated - control
+                    strata_weight = len(group) / len(data)
+                    ate += strata_effect * strata_weight
+
+        return ate
+
+
+class InterventionSimulator:
+    """
+    Simulate policy interventions using structural causal models.
+
+    This class provides high-level interface for testing
+    "what if" scenarios in geopolitical contexts.
+    """
+
+    def __init__(self, scm: StructuralCausalModel):
+        """
+        Initialize intervention simulator.
+
+        Parameters
+        ----------
+        scm : StructuralCausalModel
+            Structural causal model
+        """
+        self.scm = scm
+        self.do_calculus = DoCalculus(scm.graph)
+
+    def simulate_intervention(
+        self,
+        intervention: Dict[str, float],
+        n_samples: int = 1000,
+        outcomes: Optional[List[str]] = None
+    ) -> Dict[str, np.ndarray]:
+        """
+        Simulate an intervention.
+
+        Parameters
+        ----------
+        intervention : dict
+            Intervention specification {variable: value}
+        n_samples : int
+            Number of Monte Carlo samples
+        outcomes : List[str], optional
+            Outcome variables to track
+
+        Returns
+        -------
+        dict
+            Simulated outcomes
+        """
+        # Sample from intervened distribution
+        samples = self.scm.sample(n_samples=n_samples, interventions=intervention)
+
+        if outcomes is not None:
+            samples = {k: v for k, v in samples.items() if k in outcomes}
+
+        return samples
+
+    def compare_interventions(
+        self,
+        interventions: List[Dict[str, float]],
+        outcome: str,
+        n_samples: int = 1000
+    ) -> Dict[str, Dict[str, float]]:
+        """
+        Compare multiple interventions.
+
+        Parameters
+        ----------
+        interventions : List[dict]
+            List of interventions to compare
+        outcome : str
+            Outcome variable to compare
+        n_samples : int
+            Number of samples per intervention
+
+        Returns
+        -------
+        dict
+            Comparison results
+        """
+        results = {}
+
+        for i, intervention in enumerate(interventions):
+            samples = self.simulate_intervention(intervention, n_samples, [outcome])
+            outcome_samples = samples[outcome]
+
+            results[f"intervention_{i}"] = {
+                'intervention': intervention,
+                'mean': np.mean(outcome_samples),
+                'std': np.std(outcome_samples),
+                'median': np.median(outcome_samples),
+                'q25': np.percentile(outcome_samples, 25),
+                'q75': np.percentile(outcome_samples, 75)
+            }
+
+        return results
+
+    def optimal_intervention(
+        self,
+        target_var: str,
+        intervention_vars: List[str],
+        intervention_ranges: Dict[str, Tuple[float, float]],
+        objective: str = 'maximize',
+        n_trials: int = 100,
+        n_samples: int = 1000
+    ) -> Dict[str, Any]:
+        """
+        Find optimal intervention to achieve target.
+
+        Parameters
+        ----------
+        target_var : str
+            Target variable to optimize
+        intervention_vars : List[str]
+            Variables that can be intervened on
+        intervention_ranges : dict
+            Ranges for each intervention variable
+        objective : str
+            'maximize' or 'minimize'
+        n_trials : int
+            Number of random trials
+        n_samples : int
+            Samples per trial
+
+        Returns
+        -------
+        dict
+            Optimal intervention and results
+        """
+        best_intervention = None
+        best_value = float('-inf') if objective == 'maximize' else float('inf')
+
+        for _ in range(n_trials):
+            # Sample random intervention
+            intervention = {}
+            for var in intervention_vars:
+                low, high = intervention_ranges[var]
+                intervention[var] = np.random.uniform(low, high)
+
+            # Simulate
+            samples = self.simulate_intervention(intervention, n_samples, [target_var])
+            mean_value = np.mean(samples[target_var])
+
+            # Update best
+            if objective == 'maximize':
+                if mean_value > best_value:
+                    best_value = mean_value
+                    best_intervention = intervention
+            else:
+                if mean_value < best_value:
+                    best_value = mean_value
+                    best_intervention = intervention
+
+        return {
+            'optimal_intervention': best_intervention,
+            'optimal_value': best_value,
+            'objective': objective
+        }
+
+    def counterfactual_analysis(
+        self,
+        observed: Dict[str, float],
+        intervention: Dict[str, float],
+        outcome: str
+    ) -> Dict[str, float]:
+        """
+        Perform counterfactual analysis.
+
+        "Given that we observed X, what would have happened if we had done Y?"
+
+        Parameters
+        ----------
+        observed : dict
+            Observed values
+        intervention : dict
+            Counterfactual intervention
+        outcome : str
+            Outcome variable
+
+        Returns
+        -------
+        dict
+            Counterfactual results
+        """
+        counterfactual = self.scm.compute_counterfactual(observed, intervention)
+
+        return {
+            'observed_outcome': observed.get(outcome, None),
+            'counterfactual_outcome': counterfactual.get(outcome, None),
+            'effect': counterfactual.get(outcome, 0) - observed.get(outcome, 0)
+        }

geobot/inference/particle_filter.py

@@ -0,0 +1,557 @@
+"""
+Sequential Monte Carlo (SMC) and Particle Filtering
+
+Implements advanced particle filtering algorithms for:
+- Recursive Bayesian inference on latent states
+- High-dimensional posterior computation
+- Nonlinear/non-Gaussian state estimation
+- Degeneracy handling through resampling
+
+Methods:
+- Bootstrap particle filter
+- Auxiliary particle filter
+- Rao-Blackwellized particle filter
+- Systematic resampling, stratified resampling
+"""
+
+import numpy as np
+from typing import Callable, Optional, Tuple, Dict, Any
+from dataclasses import dataclass
+from scipy.stats import multivariate_normal
+
+
+@dataclass
+class ParticleState:
+    """
+    Represents a particle filter state.
+
+    Attributes
+    ----------
+    particles : np.ndarray, shape (n_particles, state_dim)
+        Particle positions
+    weights : np.ndarray, shape (n_particles,)
+        Normalized particle weights
+    log_weights : np.ndarray, shape (n_particles,)
+        Log weights (for numerical stability)
+    ess : float
+        Effective sample size
+    """
+    particles: np.ndarray
+    weights: np.ndarray
+    log_weights: np.ndarray
+    ess: float
+
+
+class SequentialMonteCarlo:
+    """
+    Sequential Monte Carlo (particle filter) for recursive Bayesian inference.
+
+    Performs filtering on nonlinear/non-Gaussian state-space models:
+    x_t ~ p(x_t | x_{t-1})  (dynamics)
+    y_t ~ p(y_t | x_t)      (observation)
+
+    Maintains posterior approximation p(x_t | y_{1:t}) via weighted particles.
+    """
+
+    def __init__(
+        self,
+        n_particles: int,
+        state_dim: int,
+        dynamics_fn: Callable,
+        observation_fn: Callable,
+        dynamics_noise_fn: Optional[Callable] = None,
+        observation_noise_fn: Optional[Callable] = None,
+        resample_threshold: float = 0.5
+    ):
+        """
+        Initialize Sequential Monte Carlo filter.
+
+        Parameters
+        ----------
+        n_particles : int
+            Number of particles
+        state_dim : int
+            Dimension of state space
+        dynamics_fn : callable
+            State transition function: x_t = f(x_{t-1}, noise)
+        observation_fn : callable
+            Observation likelihood: p(y_t | x_t)
+        dynamics_noise_fn : callable, optional
+            Dynamics noise sampler
+        observation_noise_fn : callable, optional
+            Observation noise sampler
+        resample_threshold : float
+            ESS threshold for resampling (as fraction of n_particles)
+        """
+        self.n_particles = n_particles
+        self.state_dim = state_dim
+        self.dynamics_fn = dynamics_fn
+        self.observation_fn = observation_fn
+        self.dynamics_noise_fn = dynamics_noise_fn
+        self.observation_noise_fn = observation_noise_fn
+        self.resample_threshold = resample_threshold
+
+        # Initialize particles uniformly (or from prior)
+        self.particles = np.random.randn(n_particles, state_dim)
+        self.weights = np.ones(n_particles) / n_particles
+        self.log_weights = np.log(self.weights)
+
+        # History
+        self.history = []
+
+    def initialize_from_prior(self, prior_sampler: Callable) -> None:
+        """
+        Initialize particles from prior distribution.
+
+        Parameters
+        ----------
+        prior_sampler : callable
+            Function that samples from prior: x ~ p(x_0)
+        """
+        self.particles = np.array([prior_sampler() for _ in range(self.n_particles)])
+        self.weights = np.ones(self.n_particles) / self.n_particles
+        self.log_weights = np.log(self.weights)
+
+    def predict(self) -> None:
+        """
+        Prediction step: propagate particles through dynamics.
+
+        x_t^i ~ p(x_t | x_{t-1}^i)
+        """
+        new_particles = np.zeros_like(self.particles)
+
+        for i in range(self.n_particles):
+            # Sample noise
+            if self.dynamics_noise_fn:
+                noise = self.dynamics_noise_fn()
+            else:
+                noise = np.random.randn(self.state_dim) * 0.1
+
+            # Propagate particle
+            new_particles[i] = self.dynamics_fn(self.particles[i], noise)
+
+        self.particles = new_particles
+
+    def update(self, observation: np.ndarray) -> None:
+        """
+        Update step: reweight particles based on observation likelihood.
+
+        w_t^i ∝ p(y_t | x_t^i) w_{t-1}^i
+
+        Parameters
+        ----------
+        observation : np.ndarray
+            Observation y_t
+        """
+        # Compute log-likelihoods
+        log_likelihoods = np.zeros(self.n_particles)
+
+        for i in range(self.n_particles):
+            log_likelihoods[i] = self.observation_fn(observation, self.particles[i])
+
+        # Update log-weights
+        self.log_weights = self.log_weights + log_likelihoods
+
+        # Normalize weights (in log space for stability)
+        max_log_weight = np.max(self.log_weights)
+        self.log_weights = self.log_weights - max_log_weight
+        self.weights = np.exp(self.log_weights)
+        self.weights = self.weights / np.sum(self.weights)
+        self.log_weights = np.log(self.weights)
+
+    def compute_ess(self) -> float:
+        """
+        Compute effective sample size (ESS).
+
+        ESS = 1 / sum(w_i^2)
+
+        Returns
+        -------
+        float
+            Effective sample size
+        """
+        return 1.0 / np.sum(self.weights ** 2)
+
+    def resample(self, method: str = 'systematic') -> None:
+        """
+        Resample particles to combat degeneracy.
+
+        Parameters
+        ----------
+        method : str
+            Resampling method ('systematic', 'stratified', 'multinomial')
+        """
+        if method == 'systematic':
+            indices = self._systematic_resample()
+        elif method == 'stratified':
+            indices = self._stratified_resample()
+        elif method == 'multinomial':
+            indices = np.random.choice(
+                self.n_particles,
+                size=self.n_particles,
+                p=self.weights
+            )
+        else:
+            raise ValueError(f"Unknown resampling method: {method}")
+
+        # Resample particles
+        self.particles = self.particles[indices]
+
+        # Reset weights to uniform
+        self.weights = np.ones(self.n_particles) / self.n_particles
+        self.log_weights = np.log(self.weights)
+
+    def _systematic_resample(self) -> np.ndarray:
+        """
+        Systematic resampling (low variance).
+
+        Returns
+        -------
+        np.ndarray
+            Resampled indices
+        """
+        positions = (np.arange(self.n_particles) + np.random.uniform()) / self.n_particles
+        indices = np.zeros(self.n_particles, dtype=int)
+        cumulative_sum = np.cumsum(self.weights)
+
+        i, j = 0, 0
+        while i < self.n_particles:
+            if positions[i] < cumulative_sum[j]:
+                indices[i] = j
+                i += 1
+            else:
+                j += 1
+
+        return indices
+
+    def _stratified_resample(self) -> np.ndarray:
+        """
+        Stratified resampling.
+
+        Returns
+        -------
+        np.ndarray
+            Resampled indices
+        """
+        positions = (np.arange(self.n_particles) + np.random.uniform(size=self.n_particles)) / self.n_particles
+        indices = np.zeros(self.n_particles, dtype=int)
+        cumulative_sum = np.cumsum(self.weights)
+
+        i, j = 0, 0
+        while i < self.n_particles:
+            if positions[i] < cumulative_sum[j]:
+                indices[i] = j
+                i += 1
+            else:
+                j += 1
+
+        return indices
+
+    def filter_step(self, observation: np.ndarray, resample: bool = True) -> ParticleState:
+        """
+        Single filtering step: predict + update + (optional) resample.
+
+        Parameters
+        ----------
+        observation : np.ndarray
+            Observation at current time
+        resample : bool
+            Whether to check ESS and resample if needed
+
+        Returns
+        -------
+        ParticleState
+            Current particle filter state
+        """
+        # Predict
+        self.predict()
+
+        # Update
+        self.update(observation)
+
+        # Compute ESS
+        ess = self.compute_ess()
+
+        # Resample if ESS too low
+        if resample and ess < self.resample_threshold * self.n_particles:
+            self.resample(method='systematic')
+            ess = self.n_particles  # After resampling, ESS = N
+
+        # Save state
+        state = ParticleState(
+            particles=self.particles.copy(),
+            weights=self.weights.copy(),
+            log_weights=self.log_weights.copy(),
+            ess=ess
+        )
+        self.history.append(state)
+
+        return state
+
+    def filter(self, observations: np.ndarray) -> list:
+        """
+        Run particle filter on sequence of observations.
+
+        Parameters
+        ----------
+        observations : np.ndarray, shape (n_timesteps, obs_dim)
+            Sequence of observations
+
+        Returns
+        -------
+        list
+            List of ParticleState objects
+        """
+        states = []
+        for obs in observations:
+            state = self.filter_step(obs)
+            states.append(state)
+        return states
+
+    def get_state_estimate(self) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Get posterior mean and covariance estimate.
+
+        Returns
+        -------
+        tuple
+            (mean, covariance)
+        """
+        mean = np.average(self.particles, weights=self.weights, axis=0)
+
+        # Weighted covariance
+        diff = self.particles - mean
+        cov = np.dot(self.weights * diff.T, diff)
+
+        return mean, cov
+
+
+class AuxiliaryParticleFilter(SequentialMonteCarlo):
+    """
+    Auxiliary Particle Filter.
+
+    Improves importance distribution by looking ahead at next observation.
+    Uses auxiliary variables to guide particle propagation.
+    """
+
+    def __init__(self, *args, look_ahead_fn: Optional[Callable] = None, **kwargs):
+        """
+        Initialize auxiliary particle filter.
+
+        Parameters
+        ----------
+        look_ahead_fn : callable, optional
+            Function to compute look-ahead weights: μ_t^i = p(y_t | m_t^i)
+            where m_t^i is a prediction of x_t from x_{t-1}^i
+        """
+        super().__init__(*args, **kwargs)
+        self.look_ahead_fn = look_ahead_fn
+
+    def filter_step(self, observation: np.ndarray, resample: bool = True) -> ParticleState:
+        """
+        Auxiliary particle filter step.
+
+        Parameters
+        ----------
+        observation : np.ndarray
+            Current observation
+        resample : bool
+            Whether to resample
+
+        Returns
+        -------
+        ParticleState
+            Filter state
+        """
+        # Step 1: Compute auxiliary weights (look-ahead)
+        if self.look_ahead_fn:
+            aux_weights = np.zeros(self.n_particles)
+            for i in range(self.n_particles):
+                # Predict particle position
+                predicted = self.dynamics_fn(self.particles[i], np.zeros(self.state_dim))
+                # Compute look-ahead likelihood
+                aux_weights[i] = np.exp(self.observation_fn(observation, predicted))
+
+            # Combine with current weights
+            aux_weights = self.weights * aux_weights
+            aux_weights = aux_weights / np.sum(aux_weights)
+        else:
+            aux_weights = self.weights
+
+        # Step 2: Resample using auxiliary weights
+        indices = np.random.choice(self.n_particles, size=self.n_particles, p=aux_weights)
+        self.particles = self.particles[indices]
+        selected_weights = self.weights[indices]
+        selected_aux_weights = aux_weights[indices]
+
+        # Step 3: Propagate
+        self.predict()
+
+        # Step 4: Update with importance weights
+        self.update(observation)
+
+        # Adjust weights for auxiliary sampling
+        self.weights = self.weights * selected_weights / (selected_aux_weights + 1e-10)
+        self.weights = self.weights / np.sum(self.weights)
+        self.log_weights = np.log(self.weights)
+
+        # ESS and resampling
+        ess = self.compute_ess()
+        if resample and ess < self.resample_threshold * self.n_particles:
+            self.resample()
+            ess = self.n_particles
+
+        state = ParticleState(
+            particles=self.particles.copy(),
+            weights=self.weights.copy(),
+            log_weights=self.log_weights.copy(),
+            ess=ess
+        )
+        self.history.append(state)
+
+        return state
+
+
+class RaoBlackwellizedParticleFilter:
+    """
+    Rao-Blackwellized Particle Filter (RBPF).
+
+    For models with linear-Gaussian substructure:
+    - Part of state updated with Kalman filter (exact)
+    - Remaining part updated with particle filter
+
+    Reduces variance by marginalizing out linear components.
+    """
+
+    def __init__(
+        self,
+        n_particles: int,
+        nonlinear_dim: int,
+        linear_dim: int,
+        nonlinear_dynamics_fn: Callable,
+        linear_dynamics_fn: Callable,
+        observation_fn: Callable,
+        F_linear: np.ndarray,
+        H_linear: np.ndarray,
+        Q_linear: np.ndarray,
+        R: np.ndarray
+    ):
+        """
+        Initialize Rao-Blackwellized particle filter.
+
+        Parameters
+        ----------
+        n_particles : int
+            Number of particles for nonlinear part
+        nonlinear_dim : int
+            Dimension of nonlinear state
+        linear_dim : int
+            Dimension of linear state
+        nonlinear_dynamics_fn : callable
+            Nonlinear state dynamics
+        linear_dynamics_fn : callable
+            Linear state dynamics (conditioned on nonlinear state)
+        observation_fn : callable
+            Observation likelihood
+        F_linear : np.ndarray
+            Linear dynamics matrix
+        H_linear : np.ndarray
+            Linear observation matrix
+        Q_linear : np.ndarray
+            Linear process noise covariance
+        R : np.ndarray
+            Observation noise covariance
+        """
+        self.n_particles = n_particles
+        self.nonlinear_dim = nonlinear_dim
+        self.linear_dim = linear_dim
+
+        self.nonlinear_dynamics_fn = nonlinear_dynamics_fn
+        self.linear_dynamics_fn = linear_dynamics_fn
+        self.observation_fn = observation_fn
+
+        # Linear substructure parameters (for Kalman filter)
+        self.F_linear = F_linear
+        self.H_linear = H_linear
+        self.Q_linear = Q_linear
+        self.R = R
+
+        # Initialize particles (nonlinear part)
+        self.nonlinear_particles = np.random.randn(n_particles, nonlinear_dim)
+        self.weights = np.ones(n_particles) / n_particles
+
+        # Initialize Kalman filters (one per particle)
+        self.linear_means = [np.zeros(linear_dim) for _ in range(n_particles)]
+        self.linear_covs = [np.eye(linear_dim) for _ in range(n_particles)]
+
+    def filter_step(self, observation: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        RBPF filtering step.
+
+        Parameters
+        ----------
+        observation : np.ndarray
+            Current observation
+
+        Returns
+        -------
+        tuple
+            (nonlinear_estimate, linear_estimate)
+        """
+        # Step 1: Propagate nonlinear particles
+        new_nonlinear_particles = np.zeros_like(self.nonlinear_particles)
+        for i in range(self.n_particles):
+            noise = np.random.randn(self.nonlinear_dim) * 0.1
+            new_nonlinear_particles[i] = self.nonlinear_dynamics_fn(
+                self.nonlinear_particles[i], noise
+            )
+
+        # Step 2: Update linear state with Kalman filter (per particle)
+        new_linear_means = []
+        new_linear_covs = []
+        log_likelihoods = np.zeros(self.n_particles)
+
+        for i in range(self.n_particles):
+            # Kalman prediction
+            m_pred = self.F_linear @ self.linear_means[i]
+            P_pred = self.F_linear @ self.linear_covs[i] @ self.F_linear.T + self.Q_linear
+
+            # Kalman update
+            innovation = observation - self.H_linear @ m_pred
+            S = self.H_linear @ P_pred @ self.H_linear.T + self.R
+            K = P_pred @ self.H_linear.T @ np.linalg.inv(S)
+
+            m_new = m_pred + K @ innovation
+            P_new = (np.eye(self.linear_dim) - K @ self.H_linear) @ P_pred
+
+            new_linear_means.append(m_new)
+            new_linear_covs.append(P_new)
+
+            # Log-likelihood
+            log_likelihoods[i] = multivariate_normal.logpdf(innovation, mean=np.zeros_like(innovation), cov=S)
+
+        # Step 3: Update weights
+        max_ll = np.max(log_likelihoods)
+        weights = np.exp(log_likelihoods - max_ll)
+        self.weights = self.weights * weights
+        self.weights = self.weights / np.sum(self.weights)
+
+        # Step 4: Resample if needed
+        ess = 1.0 / np.sum(self.weights ** 2)
+        if ess < 0.5 * self.n_particles:
+            indices = np.random.choice(self.n_particles, size=self.n_particles, p=self.weights)
+            new_nonlinear_particles = new_nonlinear_particles[indices]
+            new_linear_means = [new_linear_means[i] for i in indices]
+            new_linear_covs = [new_linear_covs[i] for i in indices]
+            self.weights = np.ones(self.n_particles) / self.n_particles
+
+        # Update state
+        self.nonlinear_particles = new_nonlinear_particles
+        self.linear_means = new_linear_means
+        self.linear_covs = new_linear_covs
+
+        # Estimates
+        nonlinear_estimate = np.average(self.nonlinear_particles, weights=self.weights, axis=0)
+        linear_estimate = np.average(new_linear_means, weights=self.weights, axis=0)
+
+        return nonlinear_estimate, linear_estimate

geobot/inference/variational_inference.py

@@ -0,0 +1,531 @@
+"""
+Variational Inference (VI) Engine
+
+Implements scalable approximate Bayesian inference via optimization:
+- Mean-field variational inference
+- Automatic Differentiation Variational Inference (ADVI)
+- Evidence Lower Bound (ELBO) optimization
+- Coordinate ascent variational inference (CAVI)
+
+Provides high-dimensional posterior approximation when MCMC is intractable.
+"""
+
+import numpy as np
+from typing import Callable, Dict, List, Optional, Tuple, Any
+from dataclasses import dataclass
+from scipy.stats import norm, multivariate_normal
+from scipy.optimize import minimize
+
+
+@dataclass
+class VariationalDistribution:
+    """
+    Parametric variational distribution q(z | λ).
+
+    Attributes
+    ----------
+    family : str
+        Distribution family ('normal', 'multivariate_normal')
+    parameters : dict
+        Distribution parameters
+    """
+    family: str
+    parameters: Dict[str, np.ndarray]
+
+    def sample(self, n_samples: int = 1) -> np.ndarray:
+        """Sample from variational distribution."""
+        if self.family == 'normal':
+            mu = self.parameters['mu']
+            sigma = self.parameters['sigma']
+            return np.random.normal(mu, sigma, size=(n_samples, len(mu)))
+        elif self.family == 'multivariate_normal':
+            mu = self.parameters['mu']
+            cov = self.parameters['cov']
+            return np.random.multivariate_normal(mu, cov, size=n_samples)
+        else:
+            raise ValueError(f"Unknown family: {self.family}")
+
+    def log_prob(self, z: np.ndarray) -> np.ndarray:
+        """Compute log probability."""
+        if self.family == 'normal':
+            mu = self.parameters['mu']
+            sigma = self.parameters['sigma']
+            return np.sum(norm.logpdf(z, loc=mu, scale=sigma), axis=-1)
+        elif self.family == 'multivariate_normal':
+            mu = self.parameters['mu']
+            cov = self.parameters['cov']
+            return multivariate_normal.logpdf(z, mean=mu, cov=cov)
+        else:
+            raise ValueError(f"Unknown family: {self.family}")
+
+    def entropy(self) -> float:
+        """Compute entropy H[q]."""
+        if self.family == 'normal':
+            sigma = self.parameters['sigma']
+            # H = 0.5 * log(2πeσ²)
+            return 0.5 * np.sum(np.log(2 * np.pi * np.e * sigma**2))
+        elif self.family == 'multivariate_normal':
+            cov = self.parameters['cov']
+            d = len(cov)
+            # H = 0.5 * log((2πe)^d |Σ|)
+            sign, logdet = np.linalg.slogdet(cov)
+            return 0.5 * (d * np.log(2 * np.pi * np.e) + logdet)
+        else:
+            raise ValueError(f"Unknown family: {self.family}")
+
+
+class VariationalInference:
+    """
+    Variational Inference engine.
+
+    Approximates posterior p(z|x) with variational distribution q(z|λ)
+    by maximizing Evidence Lower Bound (ELBO):
+
+    ELBO(λ) = E_q[log p(x,z)] - E_q[log q(z|λ)]
+            = E_q[log p(x|z)] + E_q[log p(z)] - E_q[log q(z|λ)]
+
+    Equivalently: minimize KL(q(z|λ) || p(z|x))
+    """
+
+    def __init__(
+        self,
+        log_joint: Callable,
+        variational_family: str = 'normal',
+        n_samples: int = 100
+    ):
+        """
+        Initialize variational inference.
+
+        Parameters
+        ----------
+        log_joint : callable
+            Log joint probability: log p(x, z)
+        variational_family : str
+            Variational family ('normal', 'multivariate_normal')
+        n_samples : int
+            Number of Monte Carlo samples for ELBO estimation
+        """
+        self.log_joint = log_joint
+        self.variational_family = variational_family
+        self.n_samples = n_samples
+        self.q = None
+
+    def elbo(
+        self,
+        variational_params: np.ndarray,
+        param_shapes: Dict[str, Tuple],
+        observed_data: Any
+    ) -> float:
+        """
+        Compute Evidence Lower Bound (ELBO).
+
+        ELBO = E_q[log p(x,z)] - E_q[log q(z)]
+
+        Parameters
+        ----------
+        variational_params : np.ndarray
+            Flattened variational parameters
+        param_shapes : dict
+            Shapes of each parameter
+        observed_data : any
+            Observed data x
+
+        Returns
+        -------
+        float
+            ELBO value
+        """
+        # Unpack parameters
+        params = self._unpack_params(variational_params, param_shapes)
+
+        # Create variational distribution
+        q = VariationalDistribution(self.variational_family, params)
+
+        # Sample from q
+        z_samples = q.sample(self.n_samples)
+
+        # Compute E_q[log p(x, z)]
+        log_joint_vals = np.array([self.log_joint(z, observed_data) for z in z_samples])
+        expected_log_joint = np.mean(log_joint_vals)
+
+        # Compute E_q[log q(z)]
+        log_q_vals = q.log_prob(z_samples)
+        expected_log_q = np.mean(log_q_vals)
+
+        # ELBO
+        elbo_val = expected_log_joint - expected_log_q
+
+        return elbo_val
+
+    def neg_elbo(self, variational_params: np.ndarray, param_shapes: Dict, observed_data: Any) -> float:
+        """Negative ELBO for minimization."""
+        return -self.elbo(variational_params, param_shapes, observed_data)
+
+    def fit(
+        self,
+        observed_data: Any,
+        init_params: Dict[str, np.ndarray],
+        max_iter: int = 1000,
+        method: str = 'L-BFGS-B'
+    ) -> VariationalDistribution:
+        """
+        Fit variational distribution via ELBO optimization.
+
+        Parameters
+        ----------
+        observed_data : any
+            Observed data
+        init_params : dict
+            Initial variational parameters
+        max_iter : int
+            Maximum optimization iterations
+        method : str
+            Optimization method
+
+        Returns
+        -------
+        VariationalDistribution
+            Optimized variational distribution
+        """
+        # Pack initial parameters
+        flat_params, param_shapes = self._pack_params(init_params)
+
+        # Optimize
+        result = minimize(
+            fun=self.neg_elbo,
+            x0=flat_params,
+            args=(param_shapes, observed_data),
+            method=method,
+            options={'maxiter': max_iter, 'disp': True}
+        )
+
+        # Unpack optimized parameters
+        opt_params = self._unpack_params(result.x, param_shapes)
+
+        # Create variational distribution
+        self.q = VariationalDistribution(self.variational_family, opt_params)
+
+        return self.q
+
+    def _pack_params(self, params: Dict[str, np.ndarray]) -> Tuple[np.ndarray, Dict]:
+        """Pack parameters into flat array."""
+        flat = []
+        shapes = {}
+        for key, val in params.items():
+            flat.append(val.flatten())
+            shapes[key] = val.shape
+        return np.concatenate(flat), shapes
+
+    def _unpack_params(self, flat: np.ndarray, shapes: Dict) -> Dict[str, np.ndarray]:
+        """Unpack flat array into parameters."""
+        params = {}
+        idx = 0
+        for key, shape in shapes.items():
+            size = np.prod(shape)
+            params[key] = flat[idx:idx+size].reshape(shape)
+            idx += size
+        return params
+
+
+class MeanFieldVI(VariationalInference):
+    """
+    Mean-Field Variational Inference.
+
+    Assumes variational distribution factorizes:
+    q(z | λ) = ∏_i q_i(z_i | λ_i)
+
+    Uses coordinate ascent variational inference (CAVI) to optimize
+    each factor in turn.
+    """
+
+    def __init__(
+        self,
+        log_joint: Callable,
+        factor_families: List[str],
+        n_samples: int = 100
+    ):
+        """
+        Initialize mean-field VI.
+
+        Parameters
+        ----------
+        log_joint : callable
+            Log joint probability
+        factor_families : list
+            Distribution family for each factor
+        n_samples : int
+            Number of samples for ELBO
+        """
+        super().__init__(log_joint, 'mean_field', n_samples)
+        self.factor_families = factor_families
+        self.n_factors = len(factor_families)
+
+    def fit_cavi(
+        self,
+        observed_data: Any,
+        init_params: List[Dict[str, np.ndarray]],
+        max_iter: int = 100,
+        tol: float = 1e-4
+    ) -> List[VariationalDistribution]:
+        """
+        Fit using Coordinate Ascent Variational Inference (CAVI).
+
+        Parameters
+        ----------
+        observed_data : any
+            Observed data
+        init_params : list
+            Initial parameters for each factor
+        max_iter : int
+            Maximum CAVI iterations
+        tol : float
+            Convergence tolerance
+
+        Returns
+        -------
+        list
+            List of optimized factor distributions
+        """
+        # Initialize factors
+        factors = [
+            VariationalDistribution(family, params)
+            for family, params in zip(self.factor_families, init_params)
+        ]
+
+        prev_elbo = -np.inf
+
+        for iteration in range(max_iter):
+            # Update each factor in turn
+            for i in range(self.n_factors):
+                # Update factor i holding others fixed
+                factors[i] = self._update_factor(i, factors, observed_data)
+
+            # Compute ELBO
+            current_elbo = self._compute_mean_field_elbo(factors, observed_data)
+
+            # Check convergence
+            if abs(current_elbo - prev_elbo) < tol:
+                print(f"CAVI converged at iteration {iteration}")
+                break
+
+            prev_elbo = current_elbo
+
+            if iteration % 10 == 0:
+                print(f"Iteration {iteration}, ELBO: {current_elbo:.4f}")
+
+        self.factors = factors
+        return factors
+
+    def _update_factor(
+        self,
+        factor_idx: int,
+        factors: List[VariationalDistribution],
+        observed_data: Any
+    ) -> VariationalDistribution:
+        """
+        Update a single factor via optimization.
+
+        Parameters
+        ----------
+        factor_idx : int
+            Index of factor to update
+        factors : list
+            Current factor distributions
+        observed_data : any
+            Observed data
+
+        Returns
+        -------
+        VariationalDistribution
+            Updated factor
+        """
+        # This is a simplified version - full implementation would compute
+        # conditional expectations analytically for conjugate models
+
+        # For now, use gradient-based optimization
+        current_params = factors[factor_idx].parameters
+
+        def factor_neg_elbo(params_flat):
+            # Unpack
+            if self.factor_families[factor_idx] == 'normal':
+                d = len(params_flat) // 2
+                mu = params_flat[:d]
+                log_sigma = params_flat[d:]
+                sigma = np.exp(log_sigma)
+                params = {'mu': mu, 'sigma': sigma}
+            else:
+                raise NotImplementedError
+
+            # Create trial factor
+            trial_factor = VariationalDistribution(self.factor_families[factor_idx], params)
+
+            # Replace in factors
+            trial_factors = factors.copy()
+            trial_factors[factor_idx] = trial_factor
+
+            # Compute ELBO
+            elbo = self._compute_mean_field_elbo(trial_factors, observed_data)
+            return -elbo
+
+        # Pack current params
+        if self.factor_families[factor_idx] == 'normal':
+            params_flat = np.concatenate([
+                current_params['mu'],
+                np.log(current_params['sigma'])
+            ])
+        else:
+            raise NotImplementedError
+
+        # Optimize
+        result = minimize(factor_neg_elbo, params_flat, method='L-BFGS-B')
+
+        # Unpack
+        if self.factor_families[factor_idx] == 'normal':
+            d = len(result.x) // 2
+            mu = result.x[:d]
+            sigma = np.exp(result.x[d:])
+            opt_params = {'mu': mu, 'sigma': sigma}
+        else:
+            raise NotImplementedError
+
+        return VariationalDistribution(self.factor_families[factor_idx], opt_params)
+
+    def _compute_mean_field_elbo(
+        self,
+        factors: List[VariationalDistribution],
+        observed_data: Any
+    ) -> float:
+        """
+        Compute ELBO for mean-field approximation.
+
+        Parameters
+        ----------
+        factors : list
+            Factor distributions
+        observed_data : any
+            Observed data
+
+        Returns
+        -------
+        float
+            ELBO
+        """
+        # Sample from each factor
+        samples = []
+        for factor in factors:
+            samples.append(factor.sample(self.n_samples))
+
+        # Combine samples
+        z_samples = np.column_stack(samples)
+
+        # Compute E_q[log p(x, z)]
+        log_joint_vals = np.array([self.log_joint(z, observed_data) for z in z_samples])
+        expected_log_joint = np.mean(log_joint_vals)
+
+        # Compute E_q[log q(z)] = sum_i E_q[log q_i(z_i)]
+        expected_log_q = 0.0
+        for i, factor in enumerate(factors):
+            log_q_vals = factor.log_prob(samples[i])
+            expected_log_q += np.mean(log_q_vals)
+
+        return expected_log_joint - expected_log_q
+
+
+class ADVI:
+    """
+    Automatic Differentiation Variational Inference (ADVI).
+
+    Transforms constrained latent variables to unconstrained space,
+    then performs VI with Gaussian variational family.
+
+    Uses reparameterization trick for low-variance gradient estimates.
+    """
+
+    def __init__(
+        self,
+        log_joint: Callable,
+        transform_fn: Optional[Callable] = None,
+        inverse_transform_fn: Optional[Callable] = None
+    ):
+        """
+        Initialize ADVI.
+
+        Parameters
+        ----------
+        log_joint : callable
+            Log joint in original (possibly constrained) space
+        transform_fn : callable, optional
+            Transform to unconstrained space
+        inverse_transform_fn : callable, optional
+            Inverse transform
+        """
+        self.log_joint = log_joint
+        self.transform_fn = transform_fn or (lambda x: x)
+        self.inverse_transform_fn = inverse_transform_fn or (lambda x: x)
+
+    def fit(
+        self,
+        observed_data: Any,
+        latent_dim: int,
+        n_samples: int = 10,
+        max_iter: int = 1000,
+        learning_rate: float = 0.01
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Fit ADVI using gradient ascent on ELBO.
+
+        Parameters
+        ----------
+        observed_data : any
+            Observed data
+        latent_dim : int
+            Dimension of latent variables
+        n_samples : int
+            Number of samples for ELBO gradient estimation
+        max_iter : int
+            Maximum iterations
+        learning_rate : float
+            Learning rate for gradient ascent
+
+        Returns
+        -------
+        tuple
+            (mean, log_std) of variational distribution
+        """
+        # Initialize variational parameters (Gaussian in unconstrained space)
+        mu = np.zeros(latent_dim)
+        log_sigma = np.zeros(latent_dim)
+
+        for iteration in range(max_iter):
+            # Sample from standard normal
+            epsilon = np.random.randn(n_samples, latent_dim)
+
+            # Reparameterization: z = μ + σ * ε
+            sigma = np.exp(log_sigma)
+            z_unconstrained = mu + sigma * epsilon
+
+            # Transform to constrained space
+            z_constrained = np.array([self.inverse_transform_fn(z) for z in z_unconstrained])
+
+            # Compute log joint
+            log_joints = np.array([self.log_joint(z, observed_data) for z in z_constrained])
+
+            # Compute ELBO (with entropy)
+            entropy = 0.5 * np.sum(np.log(2 * np.pi * np.e * sigma**2))
+            elbo = np.mean(log_joints) + entropy
+
+            # Gradient estimates (simplified - would use autograd in practice)
+            grad_mu = np.mean((log_joints[:, np.newaxis] - elbo) * (z_unconstrained - mu) / (sigma**2), axis=0)
+            grad_log_sigma = np.mean(
+                (log_joints[:, np.newaxis] - elbo) * ((z_unconstrained - mu)**2 / sigma**2 - 1),
+                axis=0
+            )
+
+            # Update parameters
+            mu = mu + learning_rate * grad_mu
+            log_sigma = log_sigma + learning_rate * grad_log_sigma
+
+            if iteration % 100 == 0:
+                print(f"Iteration {iteration}, ELBO: {elbo:.4f}")
+
+        return mu, log_sigma

geobot/ml/__init__.py

@@ -0,0 +1,39 @@
+"""
+Machine Learning enhancers for GeoBotv1
+
+Optional but powerful additions once the causal backbone is built.
+Critical principle: These help discover new relationships but must not replace causality.
+"""
+
+from .risk_scoring import RiskScorer
+from .feature_discovery import FeatureDiscovery
+from .embedding import GeopoliticalEmbedding
+# GNN imports are optional (require PyTorch)
+try:
+    from .graph_neural_networks import (
+        CausalGNN,
+        GeopoliticalNetworkGNN,
+        AttentionGNN,
+        MessagePassingCausalGNN,
+        GNNTrainer,
+        NetworkToGraph
+    )
+    _has_gnn = True
+except ImportError:
+    _has_gnn = False
+
+__all__ = [
+    "RiskScorer",
+    "FeatureDiscovery",
+    "GeopoliticalEmbedding",
+]
+
+if _has_gnn:
+    __all__.extend([
+        "CausalGNN",
+        "GeopoliticalNetworkGNN",
+        "AttentionGNN",
+        "MessagePassingCausalGNN",
+        "GNNTrainer",
+        "NetworkToGraph",
+    ])

geobot/ml/embedding.py

@@ -0,0 +1,76 @@
+"""
+Geopolitical embeddings for text and entities.
+"""
+
+import numpy as np
+from typing import List, Dict, Optional
+
+
+class GeopoliticalEmbedding:
+    """
+    Create embeddings for geopolitical entities and text.
+
+    Transforms text into risk vectors using NLP models.
+    """
+
+    def __init__(self, model_name: str = 'sentence-transformers/all-MiniLM-L6-v2'):
+        """
+        Initialize embedding model.
+
+        Parameters
+        ----------
+        model_name : str
+            Name of the embedding model
+        """
+        self.model_name = model_name
+        self.model = None
+        self._load_model()
+
+    def _load_model(self) -> None:
+        """Load embedding model."""
+        try:
+            from sentence_transformers import SentenceTransformer
+            self.model = SentenceTransformer(self.model_name)
+        except ImportError:
+            print("sentence-transformers not installed. Embeddings will not be available.")
+            self.model = None
+
+    def encode_text(self, texts: List[str]) -> np.ndarray:
+        """
+        Encode texts into vectors.
+
+        Parameters
+        ----------
+        texts : list
+            List of texts to encode
+
+        Returns
+        -------
+        np.ndarray
+            Embeddings
+        """
+        if self.model is None:
+            raise ValueError("Model not loaded")
+
+        return self.model.encode(texts)
+
+    def compute_similarity(self, text1: str, text2: str) -> float:
+        """
+        Compute similarity between two texts.
+
+        Parameters
+        ----------
+        text1 : str
+            First text
+        text2 : str
+            Second text
+
+        Returns
+        -------
+        float
+            Cosine similarity
+        """
+        embeddings = self.encode_text([text1, text2])
+        similarity = np.dot(embeddings[0], embeddings[1]) / \
+                    (np.linalg.norm(embeddings[0]) * np.linalg.norm(embeddings[1]))
+        return float(similarity)

geobot/ml/feature_discovery.py

@@ -0,0 +1,81 @@
+"""
+Feature discovery using Random Forests and other methods.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Tuple
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.decomposition import PCA
+
+
+class FeatureDiscovery:
+    """
+    Discover important features and relationships in geopolitical data.
+    """
+
+    def __init__(self):
+        """Initialize feature discovery."""
+        self.feature_scores = {}
+
+    def discover_important_features(
+        self,
+        X: pd.DataFrame,
+        y: np.ndarray,
+        n_top: int = 10
+    ) -> List[Tuple[str, float]]:
+        """
+        Discover most important features using Random Forest.
+
+        Parameters
+        ----------
+        X : pd.DataFrame
+            Feature matrix
+        y : np.ndarray
+            Target variable
+        n_top : int
+            Number of top features to return
+
+        Returns
+        -------
+        list
+            List of (feature_name, importance_score) tuples
+        """
+        model = RandomForestRegressor(n_estimators=100, random_state=42)
+        model.fit(X, y)
+
+        importance = model.feature_importances_
+        self.feature_scores = dict(zip(X.columns, importance))
+
+        sorted_features = sorted(
+            self.feature_scores.items(),
+            key=lambda x: x[1],
+            reverse=True
+        )
+
+        return sorted_features[:n_top]
+
+    def discover_latent_factors(
+        self,
+        X: pd.DataFrame,
+        n_components: int = 5
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Discover latent factors using PCA.
+
+        Parameters
+        ----------
+        X : pd.DataFrame
+            Feature matrix
+        n_components : int
+            Number of components
+
+        Returns
+        -------
+        tuple
+            (transformed_data, explained_variance)
+        """
+        pca = PCA(n_components=n_components)
+        transformed = pca.fit_transform(X)
+
+        return transformed, pca.explained_variance_ratio_

geobot/ml/graph_neural_networks.py

@@ -0,0 +1,628 @@
+"""
+Graph Neural Networks for Causal Graphs and Geopolitical Networks
+
+Implements GNNs for:
+- Alliance and trade network analysis
+- Causal graph representation learning
+- Message passing on DAGs
+- Attention mechanisms for influence propagation
+- Graph classification and regression
+
+Respects identifiability and invariance constraints from causal theory.
+"""
+
+import numpy as np
+from typing import List, Dict, Tuple, Optional, Callable
+import networkx as nx
+
+try:
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+    HAS_TORCH = True
+except ImportError:
+    HAS_TORCH = False
+    print("PyTorch not available. GNN functionality limited.")
+
+try:
+    import torch_geometric
+    from torch_geometric.nn import GCNConv, GATConv, MessagePassing
+    from torch_geometric.data import Data
+    HAS_TORCH_GEOMETRIC = True
+except ImportError:
+    HAS_TORCH_GEOMETRIC = False
+    print("torch_geometric not available. Install with: pip install torch-geometric")
+
+
+if HAS_TORCH:
+    class CausalGNN(nn.Module):
+        """
+        Graph Neural Network for causal graphs.
+
+        Respects causal ordering (topological) and propagates information
+        along causal edges.
+        """
+
+        def __init__(
+            self,
+            node_features: int,
+            hidden_dim: int,
+            output_dim: int,
+            num_layers: int = 2,
+            attention: bool = False
+        ):
+            """
+            Initialize Causal GNN.
+
+            Parameters
+            ----------
+            node_features : int
+                Dimension of input node features
+            hidden_dim : int
+                Hidden layer dimension
+            output_dim : int
+                Output dimension
+            num_layers : int
+                Number of GNN layers
+            attention : bool
+                Use attention mechanism (GAT)
+            """
+            super(CausalGNN, self).__init__()
+
+            self.num_layers = num_layers
+            self.attention = attention
+
+            # Input layer
+            if attention and HAS_TORCH_GEOMETRIC:
+                self.conv1 = GATConv(node_features, hidden_dim, heads=4, concat=True)
+                self.convs = nn.ModuleList([
+                    GATConv(hidden_dim * 4, hidden_dim, heads=4, concat=True)
+                    for _ in range(num_layers - 2)
+                ])
+                self.conv_final = GATConv(hidden_dim * 4, output_dim, heads=1, concat=False)
+            elif HAS_TORCH_GEOMETRIC:
+                self.conv1 = GCNConv(node_features, hidden_dim)
+                self.convs = nn.ModuleList([
+                    GCNConv(hidden_dim, hidden_dim)
+                    for _ in range(num_layers - 2)
+                ])
+                self.conv_final = GCNConv(hidden_dim, output_dim)
+            else:
+                # Fallback to simple linear layers
+                self.linear1 = nn.Linear(node_features, hidden_dim)
+                self.linears = nn.ModuleList([
+                    nn.Linear(hidden_dim, hidden_dim)
+                    for _ in range(num_layers - 2)
+                ])
+                self.linear_final = nn.Linear(hidden_dim, output_dim)
+
+        def forward(self, data):
+            """
+            Forward pass.
+
+            Parameters
+            ----------
+            data : torch_geometric.data.Data
+                Graph data with x (node features) and edge_index
+
+            Returns
+            -------
+            torch.Tensor
+                Node embeddings
+            """
+            if HAS_TORCH_GEOMETRIC:
+                x, edge_index = data.x, data.edge_index
+
+                # First layer
+                x = self.conv1(x, edge_index)
+                x = F.relu(x)
+                x = F.dropout(x, p=0.2, training=self.training)
+
+                # Hidden layers
+                for conv in self.convs:
+                    x = conv(x, edge_index)
+                    x = F.relu(x)
+                    x = F.dropout(x, p=0.2, training=self.training)
+
+                # Output layer
+                x = self.conv_final(x, edge_index)
+
+            else:
+                x = data.x
+
+                x = self.linear1(x)
+                x = F.relu(x)
+                x = F.dropout(x, p=0.2, training=self.training)
+
+                for linear in self.linears:
+                    x = linear(x)
+                    x = F.relu(x)
+                    x = F.dropout(x, p=0.2, training=self.training)
+
+                x = self.linear_final(x)
+
+            return x
+
+
+    class GeopoliticalNetworkGNN(nn.Module):
+        """
+        GNN for geopolitical networks (alliances, trade, etc.).
+
+        Models influence propagation and network effects.
+        """
+
+        def __init__(
+            self,
+            node_features: int,
+            edge_features: int,
+            hidden_dim: int,
+            output_dim: int
+        ):
+            """
+            Initialize geopolitical network GNN.
+
+            Parameters
+            ----------
+            node_features : int
+                Node feature dimension
+            edge_features : int
+                Edge feature dimension
+            hidden_dim : int
+                Hidden dimension
+            output_dim : int
+                Output dimension
+            """
+            super(GeopoliticalNetworkGNN, self).__init__()
+
+            if HAS_TORCH_GEOMETRIC:
+                self.conv1 = GCNConv(node_features, hidden_dim)
+                self.conv2 = GCNConv(hidden_dim, hidden_dim)
+                self.conv3 = GCNConv(hidden_dim, output_dim)
+            else:
+                self.linear1 = nn.Linear(node_features, hidden_dim)
+                self.linear2 = nn.Linear(hidden_dim, hidden_dim)
+                self.linear3 = nn.Linear(hidden_dim, output_dim)
+
+            # Edge feature processing
+            self.edge_mlp = nn.Sequential(
+                nn.Linear(edge_features, hidden_dim),
+                nn.ReLU(),
+                nn.Linear(hidden_dim, hidden_dim)
+            )
+
+        def forward(self, data):
+            """
+            Forward pass.
+
+            Parameters
+            ----------
+            data : Data
+                Graph data
+
+            Returns
+            -------
+            torch.Tensor
+                Node embeddings
+            """
+            if HAS_TORCH_GEOMETRIC:
+                x, edge_index = data.x, data.edge_index
+
+                x = self.conv1(x, edge_index)
+                x = F.relu(x)
+
+                x = self.conv2(x, edge_index)
+                x = F.relu(x)
+
+                x = self.conv3(x, edge_index)
+            else:
+                x = data.x
+
+                x = self.linear1(x)
+                x = F.relu(x)
+
+                x = self.linear2(x)
+                x = F.relu(x)
+
+                x = self.linear3(x)
+
+            return x
+
+
+    class MessagePassingCausalGNN(MessagePassing if HAS_TORCH_GEOMETRIC else nn.Module):
+        """
+        Custom message passing for causal graphs.
+
+        Implements directed message passing that respects causal structure:
+        - Messages flow only in direction of causal edges
+        - Aggregation respects causal mechanisms
+        """
+
+        def __init__(self, node_dim: int, edge_dim: int, hidden_dim: int):
+            """
+            Initialize message passing GNN.
+
+            Parameters
+            ----------
+            node_dim : int
+                Node feature dimension
+            edge_dim : int
+                Edge feature dimension
+            hidden_dim : int
+                Hidden dimension
+            """
+            if HAS_TORCH_GEOMETRIC:
+                super(MessagePassingCausalGNN, self).__init__(aggr='add')
+            else:
+                super(MessagePassingCausalGNN, self).__init__()
+
+            self.node_dim = node_dim
+            self.edge_dim = edge_dim
+            self.hidden_dim = hidden_dim
+
+            # Message function
+            self.message_mlp = nn.Sequential(
+                nn.Linear(node_dim + node_dim + edge_dim, hidden_dim),
+                nn.ReLU(),
+                nn.Linear(hidden_dim, hidden_dim)
+            )
+
+            # Update function
+            self.update_mlp = nn.Sequential(
+                nn.Linear(node_dim + hidden_dim, hidden_dim),
+                nn.ReLU(),
+                nn.Linear(hidden_dim, node_dim)
+            )
+
+        def forward(self, x, edge_index, edge_attr):
+            """
+            Forward pass.
+
+            Parameters
+            ----------
+            x : torch.Tensor
+                Node features
+            edge_index : torch.Tensor
+                Edge indices
+            edge_attr : torch.Tensor
+                Edge attributes
+
+            Returns
+            -------
+            torch.Tensor
+                Updated node features
+            """
+            if HAS_TORCH_GEOMETRIC:
+                return self.propagate(edge_index, x=x, edge_attr=edge_attr)
+            else:
+                # Fallback implementation
+                return x
+
+        def message(self, x_i, x_j, edge_attr):
+            """
+            Construct messages.
+
+            x_i: target node features
+            x_j: source node features
+            edge_attr: edge features
+
+            Returns
+            -------
+            torch.Tensor
+                Messages
+            """
+            # Concatenate source, target, and edge features
+            msg_input = torch.cat([x_i, x_j, edge_attr], dim=-1)
+            return self.message_mlp(msg_input)
+
+        def update(self, aggr_out, x):
+            """
+            Update node features.
+
+            Parameters
+            ----------
+            aggr_out : torch.Tensor
+                Aggregated messages
+            x : torch.Tensor
+                Current node features
+
+            Returns
+            -------
+            torch.Tensor
+                Updated node features
+            """
+            # Concatenate aggregated messages with current features
+            update_input = torch.cat([x, aggr_out], dim=-1)
+            return self.update_mlp(update_input)
+
+
+    class AttentionGNN(nn.Module):
+        """
+        Graph Attention Network for geopolitical influence.
+
+        Uses attention to weight importance of different neighbors/allies.
+        """
+
+        def __init__(
+            self,
+            node_features: int,
+            hidden_dim: int,
+            output_dim: int,
+            num_heads: int = 4
+        ):
+            """
+            Initialize attention GNN.
+
+            Parameters
+            ----------
+            node_features : int
+                Input node feature dimension
+            hidden_dim : int
+                Hidden dimension
+            output_dim : int
+                Output dimension
+            num_heads : int
+                Number of attention heads
+            """
+            super(AttentionGNN, self).__init__()
+
+            if HAS_TORCH_GEOMETRIC:
+                self.conv1 = GATConv(node_features, hidden_dim, heads=num_heads, concat=True)
+                self.conv2 = GATConv(hidden_dim * num_heads, output_dim, heads=1, concat=False)
+            else:
+                # Fallback
+                self.linear1 = nn.Linear(node_features, hidden_dim * num_heads)
+                self.linear2 = nn.Linear(hidden_dim * num_heads, output_dim)
+
+        def forward(self, data):
+            """
+            Forward pass with attention.
+
+            Parameters
+            ----------
+            data : Data
+                Graph data
+
+            Returns
+            -------
+            torch.Tensor
+                Node embeddings with attention weights
+            """
+            if HAS_TORCH_GEOMETRIC:
+                x, edge_index = data.x, data.edge_index
+
+                # First layer with multi-head attention
+                x, attention_weights1 = self.conv1(x, edge_index, return_attention_weights=True)
+                x = F.elu(x)
+                x = F.dropout(x, p=0.3, training=self.training)
+
+                # Second layer
+                x, attention_weights2 = self.conv2(x, edge_index, return_attention_weights=True)
+
+                return x, (attention_weights1, attention_weights2)
+            else:
+                x = data.x
+
+                x = self.linear1(x)
+                x = F.elu(x)
+                x = F.dropout(x, p=0.3, training=self.training)
+
+                x = self.linear2(x)
+
+                return x, None
+
+
+class GNNTrainer:
+    """
+    Trainer for GNN models.
+
+    Handles training, validation, and evaluation.
+    """
+
+    def __init__(
+        self,
+        model,
+        learning_rate: float = 0.01,
+        weight_decay: float = 5e-4
+    ):
+        """
+        Initialize GNN trainer.
+
+        Parameters
+        ----------
+        model : nn.Module
+            GNN model
+        learning_rate : float
+            Learning rate
+        weight_decay : float
+            Weight decay (L2 regularization)
+        """
+        if not HAS_TORCH:
+            raise ImportError("PyTorch required for GNN training")
+
+        self.model = model
+        self.optimizer = torch.optim.Adam(
+            model.parameters(),
+            lr=learning_rate,
+            weight_decay=weight_decay
+        )
+
+    def train_step(
+        self,
+        data,
+        labels,
+        loss_fn: Callable
+    ) -> float:
+        """
+        Single training step.
+
+        Parameters
+        ----------
+        data : Data
+            Graph data
+        labels : torch.Tensor
+            Labels
+        loss_fn : callable
+            Loss function
+
+        Returns
+        -------
+        float
+            Loss value
+        """
+        self.model.train()
+        self.optimizer.zero_grad()
+
+        # Forward pass
+        out = self.model(data)
+
+        # Compute loss
+        loss = loss_fn(out, labels)
+
+        # Backward pass
+        loss.backward()
+        self.optimizer.step()
+
+        return loss.item()
+
+    def evaluate(
+        self,
+        data,
+        labels,
+        metric_fn: Callable
+    ) -> float:
+        """
+        Evaluate model.
+
+        Parameters
+        ----------
+        data : Data
+            Graph data
+        labels : torch.Tensor
+            True labels
+        metric_fn : callable
+            Evaluation metric
+
+        Returns
+        -------
+        float
+            Metric value
+        """
+        self.model.eval()
+
+        with torch.no_grad():
+            out = self.model(data)
+            metric = metric_fn(out, labels)
+
+        return metric
+
+
+class NetworkToGraph:
+    """
+    Convert NetworkX graph to PyTorch Geometric format.
+    """
+
+    @staticmethod
+    def convert(
+        G: nx.Graph,
+        node_features: Optional[Dict] = None,
+        edge_features: Optional[Dict] = None
+    ):
+        """
+        Convert NetworkX graph to PyTorch Geometric Data.
+
+        Parameters
+        ----------
+        G : nx.Graph
+            NetworkX graph
+        node_features : dict, optional
+            Node feature dictionary
+        edge_features : dict, optional
+            Edge feature dictionary
+
+        Returns
+        -------
+        Data
+            PyTorch Geometric Data object
+        """
+        if not HAS_TORCH or not HAS_TORCH_GEOMETRIC:
+            raise ImportError("PyTorch and torch_geometric required")
+
+        # Node features
+        if node_features:
+            x = torch.tensor([
+                node_features[node]
+                for node in G.nodes()
+            ], dtype=torch.float)
+        else:
+            # Default: one-hot encoding
+            n_nodes = G.number_of_nodes()
+            x = torch.eye(n_nodes)
+
+        # Edge index
+        edge_index = torch.tensor(
+            list(G.edges()),
+            dtype=torch.long
+        ).t().contiguous()
+
+        # Edge features
+        if edge_features:
+            edge_attr = torch.tensor([
+                edge_features[(u, v)]
+                for u, v in G.edges()
+            ], dtype=torch.float)
+        else:
+            edge_attr = None
+
+        data = Data(x=x, edge_index=edge_index, edge_attr=edge_attr)
+
+        return data
+
+
+def example_geopolitical_gnn():
+    """
+    Example: GNN for geopolitical alliance network.
+    """
+    if not HAS_TORCH or not HAS_TORCH_GEOMETRIC:
+        print("PyTorch and torch_geometric required for GNN examples")
+        return
+
+    # Create example graph (alliance network)
+    G = nx.DiGraph()
+    countries = ['USA', 'China', 'Russia', 'EU', 'India']
+    G.add_nodes_from(countries)
+
+    # Add alliance edges
+    alliances = [
+        ('USA', 'EU'),
+        ('USA', 'India'),
+        ('China', 'Russia'),
+    ]
+    G.add_edges_from(alliances)
+
+    # Node features (e.g., GDP, military strength, etc.)
+    node_features = {
+        'USA': [1.0, 0.9, 0.8],
+        'China': [0.8, 0.7, 0.9],
+        'Russia': [0.5, 0.7, 0.6],
+        'EU': [0.9, 0.6, 0.7],
+        'India': [0.6, 0.6, 0.7]
+    }
+
+    # Convert to PyTorch Geometric format
+    data = NetworkToGraph.convert(G, node_features)
+
+    # Create model
+    model = CausalGNN(
+        node_features=3,
+        hidden_dim=16,
+        output_dim=8,
+        num_layers=2
+    )
+
+    # Forward pass
+    embeddings = model(data)
+
+    print("Node embeddings shape:", embeddings.shape)
+    print("Node embeddings:", embeddings)
+
+    return model, data, embeddings

geobot/ml/risk_scoring.py

@@ -0,0 +1,159 @@
+"""
+Risk scoring using gradient boosting and ensemble methods.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Optional, Any, Tuple
+from sklearn.ensemble import GradientBoostingClassifier, RandomForestClassifier
+from sklearn.model_selection import cross_val_score
+
+
+class RiskScorer:
+    """
+    Nonlinear risk scoring using ensemble methods.
+
+    Uses Gradient Boosting and Random Forests to discover nonlinear
+    patterns in geopolitical risk factors.
+    """
+
+    def __init__(self, method: str = 'gradient_boosting'):
+        """
+        Initialize risk scorer.
+
+        Parameters
+        ----------
+        method : str
+            Method to use ('gradient_boosting', 'random_forest', 'ensemble')
+        """
+        self.method = method
+        self.model = None
+        self.feature_names = None
+        self.is_trained = False
+
+    def train(
+        self,
+        X: pd.DataFrame,
+        y: np.ndarray,
+        n_estimators: int = 100,
+        max_depth: int = 5
+    ) -> Dict[str, Any]:
+        """
+        Train risk scoring model.
+
+        Parameters
+        ----------
+        X : pd.DataFrame
+            Feature matrix
+        y : np.ndarray
+            Risk labels (0 = low risk, 1 = high risk)
+        n_estimators : int
+            Number of estimators
+        max_depth : int
+            Maximum tree depth
+
+        Returns
+        -------
+        dict
+            Training results
+        """
+        self.feature_names = X.columns.tolist()
+
+        if self.method == 'gradient_boosting':
+            self.model = GradientBoostingClassifier(
+                n_estimators=n_estimators,
+                max_depth=max_depth,
+                random_state=42
+            )
+        elif self.method == 'random_forest':
+            self.model = RandomForestClassifier(
+                n_estimators=n_estimators,
+                max_depth=max_depth,
+                random_state=42
+            )
+        else:
+            raise ValueError(f"Unknown method: {self.method}")
+
+        # Train
+        self.model.fit(X, y)
+        self.is_trained = True
+
+        # Cross-validation score
+        cv_scores = cross_val_score(self.model, X, y, cv=5)
+
+        return {
+            'cv_mean': cv_scores.mean(),
+            'cv_std': cv_scores.std(),
+            'feature_importance': self.get_feature_importance()
+        }
+
+    def predict_risk(self, X: pd.DataFrame) -> np.ndarray:
+        """
+        Predict risk scores.
+
+        Parameters
+        ----------
+        X : pd.DataFrame
+            Features
+
+        Returns
+        -------
+        np.ndarray
+            Risk probabilities
+        """
+        if not self.is_trained:
+            raise ValueError("Model not trained yet")
+
+        return self.model.predict_proba(X)[:, 1]
+
+    def get_feature_importance(self) -> Dict[str, float]:
+        """
+        Get feature importance scores.
+
+        Returns
+        -------
+        dict
+            Feature importance
+        """
+        if not self.is_trained:
+            raise ValueError("Model not trained yet")
+
+        importance = self.model.feature_importances_
+        return dict(zip(self.feature_names, importance))
+
+    def explain_prediction(self, X: pd.DataFrame, index: int) -> Dict[str, Any]:
+        """
+        Explain a specific prediction.
+
+        Parameters
+        ----------
+        X : pd.DataFrame
+            Features
+        index : int
+            Index of sample to explain
+
+        Returns
+        -------
+        dict
+            Explanation
+        """
+        if not self.is_trained:
+            raise ValueError("Model not trained yet")
+
+        sample = X.iloc[index:index+1]
+        risk_score = self.predict_risk(sample)[0]
+
+        # Feature contributions (simplified)
+        feature_values = sample.iloc[0].to_dict()
+        feature_importance = self.get_feature_importance()
+
+        contributions = {
+            feat: feature_values[feat] * feature_importance[feat]
+            for feat in feature_values.keys()
+        }
+
+        return {
+            'risk_score': risk_score,
+            'top_risk_factors': sorted(contributions.items(), key=lambda x: x[1], reverse=True)[:5],
+            'feature_values': feature_values
+        }

geobot/models/__init__.py

@@ -0,0 +1,32 @@
+"""
+Causal models and structural frameworks for GeoBotv1
+"""
+
+from .causal_graph import CausalGraph, StructuralCausalModel
+from .causal_discovery import CausalDiscovery
+from .quasi_experimental import (
+    SyntheticControlMethod,
+    DifferenceinDifferences,
+    RegressionDiscontinuity,
+    InstrumentalVariables,
+    SyntheticControlResult,
+    DIDResult,
+    RDDResult,
+    IVResult,
+    estimate_treatment_effect_bounds
+)
+
+__all__ = [
+    "CausalGraph",
+    "StructuralCausalModel",
+    "CausalDiscovery",
+    "SyntheticControlMethod",
+    "DifferenceinDifferences",
+    "RegressionDiscontinuity",
+    "InstrumentalVariables",
+    "SyntheticControlResult",
+    "DIDResult",
+    "RDDResult",
+    "IVResult",
+    "estimate_treatment_effect_bounds",
+]

geobot/models/causal_discovery.py

@@ -0,0 +1,363 @@
+"""
+Causal Discovery Module
+
+Discover causal relationships from observational data using various algorithms.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Optional, Dict, List, Tuple
+from .causal_graph import CausalGraph
+
+
+class CausalDiscovery:
+    """
+    Discover causal structures from data.
+
+    Implements various causal discovery algorithms to learn
+    causal graphs from observational data.
+    """
+
+    def __init__(self, method: str = 'pc'):
+        """
+        Initialize causal discovery.
+
+        Parameters
+        ----------
+        method : str
+            Discovery method ('pc', 'ges', 'lingam')
+        """
+        self.method = method
+
+    def discover_from_data(
+        self,
+        data: pd.DataFrame,
+        alpha: float = 0.05,
+        max_cond_vars: int = 3
+    ) -> CausalGraph:
+        """
+        Discover causal graph from data.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Observational data
+        alpha : float
+            Significance level for independence tests
+        max_cond_vars : int
+            Maximum number of conditioning variables
+
+        Returns
+        -------
+        CausalGraph
+            Discovered causal graph
+        """
+        if self.method == 'pc':
+            return self._pc_algorithm(data, alpha, max_cond_vars)
+        elif self.method == 'ges':
+            return self._ges_algorithm(data)
+        elif self.method == 'lingam':
+            return self._lingam_algorithm(data)
+        else:
+            raise ValueError(f"Unknown method: {self.method}")
+
+    def _pc_algorithm(
+        self,
+        data: pd.DataFrame,
+        alpha: float,
+        max_cond_vars: int
+    ) -> CausalGraph:
+        """
+        PC (Peter-Clark) algorithm for causal discovery.
+
+        This is a constraint-based algorithm that uses conditional
+        independence tests to discover causal structure.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Observational data
+        alpha : float
+            Significance level
+        max_cond_vars : int
+            Maximum conditioning set size
+
+        Returns
+        -------
+        CausalGraph
+            Discovered graph
+        """
+        try:
+            from pgmpy.estimators import PC
+            from pgmpy.independence_tests import ChiSquareTest
+
+            # PC algorithm
+            pc = PC(data=data)
+            model = pc.estimate(
+                significance_level=alpha,
+                max_cond_vars=max_cond_vars
+            )
+
+            # Convert to CausalGraph
+            graph = CausalGraph(name="pc_discovered")
+
+            # Add nodes
+            for node in model.nodes():
+                graph.add_node(node)
+
+            # Add edges
+            for edge in model.edges():
+                graph.add_edge(edge[0], edge[1])
+
+            return graph
+
+        except ImportError:
+            print("pgmpy required for PC algorithm")
+            return self._simple_correlation_graph(data)
+
+    def _ges_algorithm(self, data: pd.DataFrame) -> CausalGraph:
+        """
+        GES (Greedy Equivalence Search) algorithm.
+
+        Score-based causal discovery algorithm.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Observational data
+
+        Returns
+        -------
+        CausalGraph
+            Discovered graph
+        """
+        # Placeholder - requires causal-learn or similar
+        print("GES algorithm not fully implemented yet")
+        return self._simple_correlation_graph(data)
+
+    def _lingam_algorithm(self, data: pd.DataFrame) -> CausalGraph:
+        """
+        LiNGAM (Linear Non-Gaussian Acyclic Model) algorithm.
+
+        Assumes linear relationships and non-Gaussian noise.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Observational data
+
+        Returns
+        -------
+        CausalGraph
+            Discovered graph
+        """
+        # Placeholder - requires lingam package
+        print("LiNGAM algorithm not fully implemented yet")
+        return self._simple_correlation_graph(data)
+
+    def _simple_correlation_graph(
+        self,
+        data: pd.DataFrame,
+        threshold: float = 0.3
+    ) -> CausalGraph:
+        """
+        Create a simple graph based on correlations.
+
+        This is a fallback method and does NOT imply causation.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Data
+        threshold : float
+            Correlation threshold
+
+        Returns
+        -------
+        CausalGraph
+            Correlation-based graph
+        """
+        graph = CausalGraph(name="correlation_based")
+
+        # Add nodes
+        for col in data.columns:
+            graph.add_node(col)
+
+        # Add edges based on correlation
+        corr_matrix = data.corr()
+
+        for i, col1 in enumerate(data.columns):
+            for j, col2 in enumerate(data.columns):
+                if i < j:  # Avoid duplicates
+                    corr = abs(corr_matrix.loc[col1, col2])
+                    if corr > threshold:
+                        # Arbitrary direction - this is NOT causal
+                        try:
+                            graph.add_edge(
+                                col1, col2,
+                                strength=corr,
+                                confidence=0.5,
+                                mechanism="correlation (not causal)"
+                            )
+                        except ValueError:
+                            # Would create cycle, try other direction
+                            try:
+                                graph.add_edge(
+                                    col2, col1,
+                                    strength=corr,
+                                    confidence=0.5,
+                                    mechanism="correlation (not causal)"
+                                )
+                            except ValueError:
+                                # Both directions create cycles, skip
+                                pass
+
+        return graph
+
+    def test_conditional_independence(
+        self,
+        data: pd.DataFrame,
+        X: str,
+        Y: str,
+        Z: Optional[List[str]] = None,
+        method: str = 'fisherz'
+    ) -> Tuple[float, float]:
+        """
+        Test conditional independence X ⊥ Y | Z.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Data
+        X : str
+            First variable
+        Y : str
+            Second variable
+        Z : List[str], optional
+            Conditioning variables
+        method : str
+            Test method ('fisherz', 'chi_square')
+
+        Returns
+        -------
+        tuple
+            (test_statistic, p_value)
+        """
+        if Z is None:
+            Z = []
+
+        if method == 'fisherz':
+            return self._fisherz_test(data, X, Y, Z)
+        elif method == 'chi_square':
+            return self._chi_square_test(data, X, Y, Z)
+        else:
+            raise ValueError(f"Unknown test method: {method}")
+
+    def _fisherz_test(
+        self,
+        data: pd.DataFrame,
+        X: str,
+        Y: str,
+        Z: List[str]
+    ) -> Tuple[float, float]:
+        """
+        Fisher's Z test for conditional independence.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Data
+        X : str
+            First variable
+        Y : str
+            Second variable
+        Z : List[str]
+            Conditioning variables
+
+        Returns
+        -------
+        tuple
+            (test_statistic, p_value)
+        """
+        from scipy.stats import norm
+
+        n = len(data)
+
+        if len(Z) == 0:
+            # Unconditional correlation
+            corr = data[[X, Y]].corr().loc[X, Y]
+        else:
+            # Partial correlation
+            all_vars = [X, Y] + Z
+            corr_matrix = data[all_vars].corr()
+
+            # Compute partial correlation
+            # This is a simplified version
+            corr_XY = corr_matrix.loc[X, Y]
+            corr = corr_XY  # Placeholder
+
+        # Fisher's Z transformation
+        if abs(corr) >= 0.9999:
+            corr = 0.9999 * np.sign(corr)
+
+        z = 0.5 * np.log((1 + corr) / (1 - corr))
+        test_stat = np.sqrt(n - len(Z) - 3) * z
+
+        # Two-tailed p-value
+        p_value = 2 * (1 - norm.cdf(abs(test_stat)))
+
+        return test_stat, p_value
+
+    def _chi_square_test(
+        self,
+        data: pd.DataFrame,
+        X: str,
+        Y: str,
+        Z: List[str]
+    ) -> Tuple[float, float]:
+        """
+        Chi-square test for conditional independence.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Data
+        X : str
+            First variable
+        Y : str
+            Second variable
+        Z : List[str]
+            Conditioning variables
+
+        Returns
+        -------
+        tuple
+            (test_statistic, p_value)
+        """
+        from scipy.stats import chi2_contingency
+
+        if len(Z) == 0:
+            # Unconditional test
+            contingency_table = pd.crosstab(data[X], data[Y])
+            chi2, p_value, dof, expected = chi2_contingency(contingency_table)
+            return chi2, p_value
+        else:
+            # Conditional test - stratify by Z
+            # This is simplified
+            chi2_sum = 0
+            dof_sum = 0
+
+            for z_value in data[Z[0]].unique():
+                subset = data[data[Z[0]] == z_value]
+                if len(subset) > 1:
+                    contingency_table = pd.crosstab(subset[X], subset[Y])
+                    if contingency_table.shape[0] > 1 and contingency_table.shape[1] > 1:
+                        chi2, _, dof, _ = chi2_contingency(contingency_table)
+                        chi2_sum += chi2
+                        dof_sum += dof
+
+            # Approximate p-value
+            from scipy.stats import chi2
+            p_value = 1 - chi2.cdf(chi2_sum, dof_sum) if dof_sum > 0 else 1.0
+
+            return chi2_sum, p_value

geobot/models/causal_graph.py

@@ -0,0 +1,588 @@
+"""
+Causal Graph Module - DAG Representation
+
+Provides infrastructure for representing and analyzing causal relationships
+in geopolitical systems using Directed Acyclic Graphs (DAGs).
+
+This module answers:
+- What causes conflict?
+- What causes collapse?
+- What causes escalation?
+- What causes mobilization?
+- What causes instability?
+
+Critical for: Real forecasting of interventions, not just correlation-based guessing.
+"""
+
+import numpy as np
+import networkx as nx
+from typing import Dict, List, Set, Optional, Tuple, Any, Callable
+from dataclasses import dataclass, field
+import json
+
+
+@dataclass
+class CausalEdge:
+    """
+    Represents a causal edge in the graph.
+
+    Attributes
+    ----------
+    source : str
+        Source node (cause)
+    target : str
+        Target node (effect)
+    strength : float
+        Strength of causal relationship (-1 to 1)
+    confidence : float
+        Confidence in this relationship (0 to 1)
+    mechanism : str
+        Description of causal mechanism
+    """
+    source: str
+    target: str
+    strength: float = 1.0
+    confidence: float = 1.0
+    mechanism: str = ""
+
+
+class CausalGraph:
+    """
+    Directed Acyclic Graph (DAG) for causal relationships.
+
+    This class provides the foundation for causal inference in geopolitical
+    forecasting, ensuring that we understand what actually causes events
+    rather than just observing correlations.
+    """
+
+    def __init__(self, name: str = "geopolitical_dag"):
+        """
+        Initialize causal graph.
+
+        Parameters
+        ----------
+        name : str
+            Name of the causal graph
+        """
+        self.name = name
+        self.graph = nx.DiGraph()
+        self.edges: List[CausalEdge] = []
+        self.node_metadata: Dict[str, Dict[str, Any]] = {}
+
+    def add_node(
+        self,
+        node: str,
+        node_type: str = "variable",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """
+        Add a node to the causal graph.
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+        node_type : str
+            Type of node ('variable', 'event', 'policy', 'state')
+        metadata : dict, optional
+            Additional metadata for the node
+        """
+        self.graph.add_node(node)
+        self.node_metadata[node] = {
+            'type': node_type,
+            'metadata': metadata or {}
+        }
+
+    def add_edge(
+        self,
+        source: str,
+        target: str,
+        strength: float = 1.0,
+        confidence: float = 1.0,
+        mechanism: str = ""
+    ) -> None:
+        """
+        Add a causal edge to the graph.
+
+        Parameters
+        ----------
+        source : str
+            Source node (cause)
+        target : str
+            Target node (effect)
+        strength : float
+            Strength of causal relationship
+        confidence : float
+            Confidence in this relationship
+        mechanism : str
+            Description of causal mechanism
+        """
+        # Check for cycles
+        if not self._would_create_cycle(source, target):
+            self.graph.add_edge(source, target)
+            edge = CausalEdge(source, target, strength, confidence, mechanism)
+            self.edges.append(edge)
+        else:
+            raise ValueError(f"Adding edge {source} -> {target} would create a cycle")
+
+    def remove_edge(self, source: str, target: str) -> None:
+        """
+        Remove a causal edge.
+
+        Parameters
+        ----------
+        source : str
+            Source node
+        target : str
+            Target node
+        """
+        if self.graph.has_edge(source, target):
+            self.graph.remove_edge(source, target)
+            self.edges = [e for e in self.edges if not (e.source == source and e.target == target)]
+
+    def _would_create_cycle(self, source: str, target: str) -> bool:
+        """
+        Check if adding an edge would create a cycle.
+
+        Parameters
+        ----------
+        source : str
+            Source node
+        target : str
+            Target node
+
+        Returns
+        -------
+        bool
+            True if edge would create cycle
+        """
+        # Add nodes if they don't exist
+        if source not in self.graph:
+            self.graph.add_node(source)
+        if target not in self.graph:
+            self.graph.add_node(target)
+
+        # Temporarily add edge and check for cycles
+        self.graph.add_edge(source, target)
+        has_cycle = not nx.is_directed_acyclic_graph(self.graph)
+        self.graph.remove_edge(source, target)
+
+        return has_cycle
+
+    def get_parents(self, node: str) -> List[str]:
+        """
+        Get direct parents (causes) of a node.
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+
+        Returns
+        -------
+        List[str]
+            List of parent nodes
+        """
+        return list(self.graph.predecessors(node))
+
+    def get_children(self, node: str) -> List[str]:
+        """
+        Get direct children (effects) of a node.
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+
+        Returns
+        -------
+        List[str]
+            List of child nodes
+        """
+        return list(self.graph.successors(node))
+
+    def get_ancestors(self, node: str) -> Set[str]:
+        """
+        Get all ancestors (causes) of a node.
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+
+        Returns
+        -------
+        Set[str]
+            Set of ancestor nodes
+        """
+        return nx.ancestors(self.graph, node)
+
+    def get_descendants(self, node: str) -> Set[str]:
+        """
+        Get all descendants (effects) of a node.
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+
+        Returns
+        -------
+        Set[str]
+            Set of descendant nodes
+        """
+        return nx.descendants(self.graph, node)
+
+    def get_topological_order(self) -> List[str]:
+        """
+        Get topological ordering of nodes.
+
+        This is useful for computing values in causal order.
+
+        Returns
+        -------
+        List[str]
+            Nodes in topological order
+        """
+        return list(nx.topological_sort(self.graph))
+
+    def is_ancestor(self, node1: str, node2: str) -> bool:
+        """
+        Check if node1 is an ancestor of node2.
+
+        Parameters
+        ----------
+        node1 : str
+            Potential ancestor
+        node2 : str
+            Potential descendant
+
+        Returns
+        -------
+        bool
+            True if node1 is ancestor of node2
+        """
+        return node1 in self.get_ancestors(node2)
+
+    def is_descendant(self, node1: str, node2: str) -> bool:
+        """
+        Check if node1 is a descendant of node2.
+
+        Parameters
+        ----------
+        node1 : str
+            Potential descendant
+        node2 : str
+            Potential ancestor
+
+        Returns
+        -------
+        bool
+            True if node1 is descendant of node2
+        """
+        return node1 in self.get_descendants(node2)
+
+    def get_markov_blanket(self, node: str) -> Set[str]:
+        """
+        Get Markov blanket of a node.
+
+        The Markov blanket includes: parents, children, and co-parents
+        (other parents of children).
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+
+        Returns
+        -------
+        Set[str]
+            Markov blanket nodes
+        """
+        parents = set(self.get_parents(node))
+        children = set(self.get_children(node))
+
+        # Get co-parents (parents of children)
+        co_parents = set()
+        for child in children:
+            co_parents.update(self.get_parents(child))
+
+        co_parents.discard(node)
+
+        return parents | children | co_parents
+
+    def d_separated(self, X: Set[str], Y: Set[str], Z: Set[str]) -> bool:
+        """
+        Test if X and Y are d-separated given Z.
+
+        This is fundamental for determining conditional independence.
+
+        Parameters
+        ----------
+        X : Set[str]
+            First set of nodes
+        Y : Set[str]
+            Second set of nodes
+        Z : Set[str]
+            Conditioning set
+
+        Returns
+        -------
+        bool
+            True if X and Y are d-separated given Z
+        """
+        return nx.d_separated(self.graph, X, Y, Z)
+
+    def visualize(self, output_path: Optional[str] = None) -> None:
+        """
+        Visualize the causal graph.
+
+        Parameters
+        ----------
+        output_path : str, optional
+            Path to save visualization
+        """
+        try:
+            import matplotlib.pyplot as plt
+
+            pos = nx.spring_layout(self.graph)
+            plt.figure(figsize=(12, 8))
+
+            nx.draw(
+                self.graph,
+                pos,
+                with_labels=True,
+                node_color='lightblue',
+                node_size=3000,
+                font_size=10,
+                font_weight='bold',
+                arrows=True,
+                arrowsize=20,
+                edge_color='gray'
+            )
+
+            plt.title(f"Causal Graph: {self.name}")
+
+            if output_path:
+                plt.savefig(output_path)
+            else:
+                plt.show()
+
+        except ImportError:
+            print("Matplotlib required for visualization")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert graph to dictionary representation.
+
+        Returns
+        -------
+        dict
+            Dictionary representation
+        """
+        return {
+            'name': self.name,
+            'nodes': [
+                {'id': node, **self.node_metadata.get(node, {})}
+                for node in self.graph.nodes()
+            ],
+            'edges': [
+                {
+                    'source': edge.source,
+                    'target': edge.target,
+                    'strength': edge.strength,
+                    'confidence': edge.confidence,
+                    'mechanism': edge.mechanism
+                }
+                for edge in self.edges
+            ]
+        }
+
+    def to_json(self, path: str) -> None:
+        """
+        Save graph to JSON file.
+
+        Parameters
+        ----------
+        path : str
+            Output file path
+        """
+        with open(path, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'CausalGraph':
+        """
+        Load graph from dictionary.
+
+        Parameters
+        ----------
+        data : dict
+            Dictionary representation
+
+        Returns
+        -------
+        CausalGraph
+            Loaded graph
+        """
+        graph = cls(name=data['name'])
+
+        # Add nodes
+        for node_data in data['nodes']:
+            graph.add_node(
+                node_data['id'],
+                node_type=node_data.get('type', 'variable'),
+                metadata=node_data.get('metadata', {})
+            )
+
+        # Add edges
+        for edge_data in data['edges']:
+            graph.add_edge(
+                edge_data['source'],
+                edge_data['target'],
+                strength=edge_data.get('strength', 1.0),
+                confidence=edge_data.get('confidence', 1.0),
+                mechanism=edge_data.get('mechanism', '')
+            )
+
+        return graph
+
+    @classmethod
+    def from_json(cls, path: str) -> 'CausalGraph':
+        """
+        Load graph from JSON file.
+
+        Parameters
+        ----------
+        path : str
+            Input file path
+
+        Returns
+        -------
+        CausalGraph
+            Loaded graph
+        """
+        with open(path, 'r') as f:
+            data = json.load(f)
+        return cls.from_dict(data)
+
+
+class StructuralCausalModel:
+    """
+    Structural Causal Model (SCM) with functional equations.
+
+    An SCM defines how each variable is generated from its parents
+    and exogenous noise.
+    """
+
+    def __init__(self, causal_graph: CausalGraph):
+        """
+        Initialize structural causal model.
+
+        Parameters
+        ----------
+        causal_graph : CausalGraph
+            Underlying causal graph
+        """
+        self.graph = causal_graph
+        self.functions: Dict[str, Callable] = {}
+        self.noise_distributions: Dict[str, Any] = {}
+
+    def set_function(
+        self,
+        node: str,
+        function: Callable,
+        noise_dist: Optional[Any] = None
+    ) -> None:
+        """
+        Set structural equation for a node.
+
+        Parameters
+        ----------
+        node : str
+            Node identifier
+        function : callable
+            Function that computes node value from parents
+            Signature: f(parent_values, noise) -> value
+        noise_dist : optional
+            Noise distribution for this variable
+        """
+        self.functions[node] = function
+        if noise_dist is not None:
+            self.noise_distributions[node] = noise_dist
+
+    def sample(
+        self,
+        n_samples: int = 1,
+        interventions: Optional[Dict[str, float]] = None
+    ) -> Dict[str, np.ndarray]:
+        """
+        Sample from the structural causal model.
+
+        Parameters
+        ----------
+        n_samples : int
+            Number of samples to generate
+        interventions : dict, optional
+            Dictionary of interventions {node: value}
+
+        Returns
+        -------
+        dict
+            Dictionary of samples for each variable
+        """
+        samples = {node: np.zeros(n_samples) for node in self.graph.graph.nodes()}
+
+        # Sample in topological order
+        for node in self.graph.get_topological_order():
+            # Check if this node is intervened upon
+            if interventions and node in interventions:
+                samples[node] = np.full(n_samples, interventions[node])
+            else:
+                # Get parent values
+                parents = self.graph.get_parents(node)
+                parent_values = {p: samples[p] for p in parents}
+
+                # Sample noise
+                if node in self.noise_distributions:
+                    noise = self.noise_distributions[node].rvs(n_samples)
+                else:
+                    noise = np.zeros(n_samples)
+
+                # Compute value using structural equation
+                if node in self.functions:
+                    samples[node] = self.functions[node](parent_values, noise)
+                else:
+                    # Default: just use noise
+                    samples[node] = noise
+
+        return samples
+
+    def compute_counterfactual(
+        self,
+        observed: Dict[str, float],
+        interventions: Dict[str, float]
+    ) -> Dict[str, float]:
+        """
+        Compute counterfactual: What would happen if we intervened?
+
+        Parameters
+        ----------
+        observed : dict
+            Observed values
+        interventions : dict
+            Interventions to apply
+
+        Returns
+        -------
+        dict
+            Counterfactual values
+        """
+        # This is a simplified version
+        # Full counterfactual computation requires abduction-action-prediction
+
+        # For now, we sample with interventions
+        samples = self.sample(n_samples=1000, interventions=interventions)
+
+        # Return means
+        return {node: np.mean(values) for node, values in samples.items()}

geobot/models/quasi_experimental.py

@@ -0,0 +1,715 @@
+"""
+Quasi-Experimental Causal Inference Methods
+
+When randomized experiments are impossible, quasi-experimental designs
+provide credible causal identification under weaker assumptions.
+
+Core methods:
+1. Synthetic Control Method (SCM): Construct counterfactual from weighted controls
+2. Difference-in-Differences (DiD): Compare treatment vs control before/after
+3. Regression Discontinuity Design (RDD): Exploit threshold-based treatment assignment
+4. Instrumental Variables (IV): Use exogenous variation to identify causal effects
+5. Causal Forests: Machine learning for heterogeneous treatment effects
+
+Applications in geopolitics:
+- SCM: Effect of sanctions on target country (compare to synthetic control)
+- DiD: Impact of regime change (compare neighboring countries before/after)
+- RDD: Effect of election outcomes (winners vs losers near threshold)
+- IV: Effect of trade on conflict (use geographic instruments)
+"""
+
+import numpy as np
+from scipy import optimize, stats
+from typing import Dict, List, Tuple, Optional, Union
+from dataclasses import dataclass
+import warnings
+
+
+@dataclass
+class SyntheticControlResult:
+    """Results from Synthetic Control Method."""
+    weights: np.ndarray  # Weights on control units
+    treated_outcome: np.ndarray  # Actual treated unit outcomes
+    synthetic_outcome: np.ndarray  # Synthetic control outcomes
+    treatment_effect: np.ndarray  # Difference (post-treatment)
+    pre_treatment_fit: float  # RMSPE in pre-treatment period
+    control_units: List[str]  # Names of control units
+    treatment_time: int  # Index where treatment starts
+    p_value: Optional[float] = None  # From permutation test
+
+
+@dataclass
+class DIDResult:
+    """Results from Difference-in-Differences."""
+    att: float  # Average Treatment effect on Treated
+    se: float  # Standard error
+    t_stat: float
+    p_value: float
+    pre_treatment_diff: float  # Check parallel trends
+    post_treatment_diff: float
+    n_treated: int
+    n_control: int
+
+
+@dataclass
+class RDDResult:
+    """Results from Regression Discontinuity Design."""
+    treatment_effect: float  # Local Average Treatment Effect (LATE)
+    se: float
+    t_stat: float
+    p_value: float
+    bandwidth: float
+    n_left: int  # Observations below cutoff
+    n_right: int  # Observations above cutoff
+
+
+@dataclass
+class IVResult:
+    """Results from Instrumental Variables estimation."""
+    beta_iv: np.ndarray  # IV estimates
+    beta_ols: np.ndarray  # OLS estimates (for comparison)
+    se_iv: np.ndarray  # Standard errors
+    first_stage_f: float  # First stage F-statistic
+    weak_instrument: bool  # True if F < 10
+
+
+class SyntheticControlMethod:
+    """
+    Synthetic Control Method (Abadie, Diamond, Hainmueller 2010, 2015)
+
+    Creates a synthetic version of the treated unit as a weighted average
+    of control units to estimate counterfactual outcomes.
+
+    Key idea: If we can match pre-treatment outcomes and covariates perfectly,
+    the synthetic control provides a valid counterfactual.
+
+    Example:
+        >>> # Effect of sanctions on Iran's GDP
+        >>> scm = SyntheticControlMethod()
+        >>> result = scm.fit(
+        ...     treated_outcome=iran_gdp,  # (T,)
+        ...     control_outcomes=other_countries_gdp,  # (T, J)
+        ...     treatment_time=20,  # Sanctions imposed at t=20
+        ...     treated_covariates=iran_covariates,  # (K,)
+        ...     control_covariates=other_covariates  # (J, K)
+        ... )
+        >>> print(f"Average treatment effect: {np.mean(result.treatment_effect):.2f}")
+    """
+
+    def __init__(self, loss: str = 'l2'):
+        """
+        Initialize SCM.
+
+        Args:
+            loss: Loss function for matching ('l2' or 'l1')
+        """
+        self.loss = loss
+
+    def fit(self, treated_outcome: np.ndarray, control_outcomes: np.ndarray,
+            treatment_time: int,
+            treated_covariates: Optional[np.ndarray] = None,
+            control_covariates: Optional[np.ndarray] = None,
+            control_names: Optional[List[str]] = None,
+            custom_weights: Optional[np.ndarray] = None) -> SyntheticControlResult:
+        """
+        Fit synthetic control model.
+
+        Args:
+            treated_outcome: Outcome for treated unit, shape (T,)
+            control_outcomes: Outcomes for control units, shape (T, J)
+            treatment_time: Time index when treatment begins
+            treated_covariates: Covariates for treated unit, shape (K,)
+            control_covariates: Covariates for controls, shape (J, K)
+            control_names: Names of control units
+            custom_weights: Optional custom weights for different predictors
+
+        Returns:
+            SyntheticControlResult with estimated effects
+        """
+        T, J = control_outcomes.shape
+
+        if control_names is None:
+            control_names = [f"control_{j}" for j in range(J)]
+
+        # Pre-treatment period
+        Y1_pre = treated_outcome[:treatment_time]
+        Y0_pre = control_outcomes[:treatment_time, :]
+
+        # Construct predictors matrix
+        if treated_covariates is not None and control_covariates is not None:
+            # Include both outcomes and covariates
+            X1 = np.concatenate([Y1_pre, treated_covariates])
+            X0 = np.vstack([Y0_pre.T, control_covariates.T])  # Shape: (J, T_pre + K)
+        else:
+            # Use only pre-treatment outcomes
+            X1 = Y1_pre
+            X0 = Y0_pre.T  # Shape: (J, T_pre)
+
+        # Find weights that minimize ||X1 - X0 w||
+        weights = self._optimize_weights(X1, X0, custom_weights)
+
+        # Construct synthetic control
+        synthetic_outcome = control_outcomes @ weights
+
+        # Compute treatment effects (post-treatment)
+        treatment_effect = np.zeros(T)
+        treatment_effect[treatment_time:] = (
+            treated_outcome[treatment_time:] - synthetic_outcome[treatment_time:]
+        )
+
+        # Pre-treatment fit quality
+        pre_treatment_fit = np.sqrt(np.mean((Y1_pre - synthetic_outcome[:treatment_time]) ** 2))
+
+        return SyntheticControlResult(
+            weights=weights,
+            treated_outcome=treated_outcome,
+            synthetic_outcome=synthetic_outcome,
+            treatment_effect=treatment_effect,
+            pre_treatment_fit=pre_treatment_fit,
+            control_units=control_names,
+            treatment_time=treatment_time
+        )
+
+    def _optimize_weights(self, X1: np.ndarray, X0: np.ndarray,
+                         V: Optional[np.ndarray] = None) -> np.ndarray:
+        """
+        Optimize weights to minimize prediction error.
+
+        min_w ||X1 - X0 w||_V^2
+        s.t. w >= 0, sum(w) = 1
+
+        Args:
+            X1: Target predictors, shape (K,)
+            X0: Control predictors, shape (J, K)
+            V: Optional weighting matrix
+
+        Returns:
+            Optimal weights, shape (J,)
+        """
+        J = X0.shape[0]
+
+        if V is None:
+            V = np.eye(len(X1))
+
+        # Objective function
+        def objective(w):
+            diff = X1 - X0.T @ w
+            return diff.T @ V @ diff
+
+        # Constraints: w >= 0, sum(w) = 1
+        constraints = {'type': 'eq', 'fun': lambda w: np.sum(w) - 1}
+        bounds = [(0, 1) for _ in range(J)]
+
+        # Initial guess: equal weights
+        w0 = np.ones(J) / J
+
+        # Optimize
+        result = optimize.minimize(
+            objective,
+            x0=w0,
+            method='SLSQP',
+            bounds=bounds,
+            constraints=constraints
+        )
+
+        if not result.success:
+            warnings.warn("Optimization did not fully converge")
+
+        return result.x
+
+    def placebo_test(self, treated_outcome: np.ndarray, control_outcomes: np.ndarray,
+                    treatment_time: int, n_permutations: int = 100) -> float:
+        """
+        Conduct placebo test by applying SCM to control units.
+
+        Tests whether the observed treatment effect is unusually large
+        compared to effects from placebo treatments on controls.
+
+        Args:
+            treated_outcome: Treated unit outcome
+            control_outcomes: Control units outcomes
+            treatment_time: Treatment time
+            n_permutations: Number of placebo tests
+
+        Returns:
+            p-value: Proportion of placebos with larger effect
+        """
+        # Fit actual SCM
+        actual_result = self.fit(treated_outcome, control_outcomes, treatment_time)
+        actual_effect = np.abs(np.mean(actual_result.treatment_effect[treatment_time:]))
+
+        # Run placebo tests
+        placebo_effects = []
+        J = control_outcomes.shape[1]
+
+        for j in range(min(J, n_permutations)):
+            # Treat control j as if it were treated
+            placebo_treated = control_outcomes[:, j]
+            placebo_controls = np.delete(control_outcomes, j, axis=1)
+
+            try:
+                placebo_result = self.fit(placebo_treated, placebo_controls, treatment_time)
+                placebo_effect = np.abs(np.mean(placebo_result.treatment_effect[treatment_time:]))
+                placebo_effects.append(placebo_effect)
+            except:
+                continue
+
+        # p-value: proportion of placebos with larger effect
+        placebo_effects = np.array(placebo_effects)
+        p_value = np.mean(placebo_effects >= actual_effect)
+
+        return p_value
+
+
+class DifferenceinDifferences:
+    """
+    Difference-in-Differences (DiD) Estimation
+
+    Compares changes over time between treatment and control groups.
+
+    Model:
+    Y_it = β_0 + β_1 * Treated_i + β_2 * Post_t + β_3 * (Treated_i × Post_t) + ε_it
+
+    where β_3 is the DiD estimate (Average Treatment effect on Treated).
+
+    Key assumption: Parallel trends (treatment and control would have
+    followed same trend absent treatment).
+
+    Example:
+        >>> # Effect of regime change in country A
+        >>> did = DifferenceinDifferences()
+        >>> result = did.estimate(
+        ...     treated_pre=country_a_gdp_before,
+        ...     treated_post=country_a_gdp_after,
+        ...     control_pre=neighbors_gdp_before,
+        ...     control_post=neighbors_gdp_after
+        ... )
+        >>> print(f"ATT: {result.att:.3f} (p={result.p_value:.3f})")
+    """
+
+    def estimate(self, treated_pre: np.ndarray, treated_post: np.ndarray,
+                control_pre: np.ndarray, control_post: np.ndarray,
+                cluster_robust: bool = False) -> DIDResult:
+        """
+        Estimate DiD effect.
+
+        Args:
+            treated_pre: Treated group pre-treatment, shape (n_treated,)
+            treated_post: Treated group post-treatment, shape (n_treated,)
+            control_pre: Control group pre-treatment, shape (n_control,)
+            control_post: Control group post-treatment, shape (n_control,)
+            cluster_robust: Use cluster-robust standard errors
+
+        Returns:
+            DIDResult with ATT estimate
+        """
+        # Convert to arrays
+        treated_pre = np.asarray(treated_pre)
+        treated_post = np.asarray(treated_post)
+        control_pre = np.asarray(control_pre)
+        control_post = np.asarray(control_post)
+
+        # Sample sizes
+        n_treated = len(treated_pre)
+        n_control = len(control_pre)
+
+        # Mean outcomes
+        y_treated_pre = np.mean(treated_pre)
+        y_treated_post = np.mean(treated_post)
+        y_control_pre = np.mean(control_pre)
+        y_control_post = np.mean(control_post)
+
+        # DiD estimate
+        diff_treated = y_treated_post - y_treated_pre
+        diff_control = y_control_post - y_control_pre
+        att = diff_treated - diff_control
+
+        # Standard error (assuming homoskedasticity)
+        var_treated_pre = np.var(treated_pre, ddof=1)
+        var_treated_post = np.var(treated_post, ddof=1)
+        var_control_pre = np.var(control_pre, ddof=1)
+        var_control_post = np.var(control_post, ddof=1)
+
+        se = np.sqrt(
+            var_treated_post / n_treated +
+            var_treated_pre / n_treated +
+            var_control_post / n_control +
+            var_control_pre / n_control
+        )
+
+        # Test statistic
+        t_stat = att / se
+        p_value = 2 * (1 - stats.t.cdf(np.abs(t_stat), df=n_treated + n_control - 2))
+
+        return DIDResult(
+            att=att,
+            se=se,
+            t_stat=t_stat,
+            p_value=p_value,
+            pre_treatment_diff=y_treated_pre - y_control_pre,
+            post_treatment_diff=y_treated_post - y_control_post,
+            n_treated=n_treated,
+            n_control=n_control
+        )
+
+    def panel_did(self, panel_data: np.ndarray, treatment_indicator: np.ndarray,
+                 time_indicator: np.ndarray, unit_ids: np.ndarray) -> DIDResult:
+        """
+        Estimate DiD with panel data and fixed effects.
+
+        Model:
+        Y_it = α_i + γ_t + δ * (Treatment_i × Post_t) + ε_it
+
+        Args:
+            panel_data: Outcome variable, shape (N*T,)
+            treatment_indicator: 1 if unit is treated, 0 otherwise, shape (N*T,)
+            time_indicator: 1 if post-treatment, 0 if pre, shape (N*T,)
+            unit_ids: Unit identifiers, shape (N*T,)
+
+        Returns:
+            DIDResult
+        """
+        # Create interaction term
+        did_term = treatment_indicator * time_indicator
+
+        # Demean for fixed effects (within transformation)
+        n_obs = len(panel_data)
+        unique_units = np.unique(unit_ids)
+        unique_times = np.unique(time_indicator)
+
+        # Demean by unit (removes α_i)
+        y_demeaned = np.zeros(n_obs)
+        did_demeaned = np.zeros(n_obs)
+
+        for unit in unique_units:
+            mask = unit_ids == unit
+            y_demeaned[mask] = panel_data[mask] - np.mean(panel_data[mask])
+            did_demeaned[mask] = did_term[mask] - np.mean(did_term[mask])
+
+        # Regression: y_demeaned ~ did_demeaned (absorbs time FE implicitly)
+        # Simple OLS
+        att = np.sum(did_demeaned * y_demeaned) / np.sum(did_demeaned ** 2)
+
+        # Standard error
+        residuals = y_demeaned - att * did_demeaned
+        rss = np.sum(residuals ** 2)
+        se = np.sqrt(rss / (n_obs - 2) / np.sum(did_demeaned ** 2))
+
+        t_stat = att / se
+        p_value = 2 * (1 - stats.t.cdf(np.abs(t_stat), df=n_obs - 2))
+
+        n_treated = np.sum(treatment_indicator > 0)
+        n_control = n_obs - n_treated
+
+        return DIDResult(
+            att=att,
+            se=se,
+            t_stat=t_stat,
+            p_value=p_value,
+            pre_treatment_diff=0.0,  # Not directly computed
+            post_treatment_diff=0.0,
+            n_treated=n_treated,
+            n_control=n_control
+        )
+
+
+class RegressionDiscontinuity:
+    """
+    Regression Discontinuity Design (RDD)
+
+    Estimates treatment effects when treatment assignment is determined
+    by whether a running variable crosses a threshold.
+
+    Sharp RDD: Treatment deterministically assigned at cutoff
+    Fuzzy RDD: Probability of treatment jumps at cutoff
+
+    Example: Effect of election victory on policy outcomes
+    - Running variable: Vote margin
+    - Cutoff: 50%
+    - Treatment: Winning election
+
+    Example:
+        >>> # Effect of election victory on military spending
+        >>> rdd = RegressionDiscontinuity(cutoff=0.5)  # 50% vote share
+        >>> result = rdd.estimate_sharp(
+        ...     running_var=vote_share,  # Vote percentage
+        ...     outcome=military_spending,
+        ...     bandwidth=0.1  # 10% bandwidth
+        ... )
+    """
+
+    def __init__(self, cutoff: float = 0.0):
+        """
+        Initialize RDD.
+
+        Args:
+            cutoff: Threshold value for treatment assignment
+        """
+        self.cutoff = cutoff
+
+    def estimate_sharp(self, running_var: np.ndarray, outcome: np.ndarray,
+                      bandwidth: Optional[float] = None,
+                      kernel: str = 'triangular',
+                      polynomial_order: int = 1) -> RDDResult:
+        """
+        Estimate sharp RDD effect.
+
+        Args:
+            running_var: Running variable (e.g., vote share)
+            outcome: Outcome variable
+            bandwidth: Bandwidth around cutoff (if None, use data-driven selection)
+            kernel: Weighting kernel ('triangular', 'uniform', 'epanechnikov')
+            polynomial_order: Order of local polynomial
+
+        Returns:
+            RDDResult with treatment effect estimate
+        """
+        running_var = np.asarray(running_var)
+        outcome = np.asarray(outcome)
+
+        # Center running variable at cutoff
+        X = running_var - self.cutoff
+
+        # Select bandwidth if not provided
+        if bandwidth is None:
+            bandwidth = self._select_bandwidth(X, outcome)
+
+        # Restrict to bandwidth
+        in_bandwidth = np.abs(X) <= bandwidth
+        X_bw = X[in_bandwidth]
+        Y_bw = outcome[in_bandwidth]
+
+        # Treatment indicator (above cutoff)
+        D = (X_bw >= 0).astype(float)
+
+        # Create weights
+        weights = self._kernel_weights(X_bw, bandwidth, kernel)
+
+        # Fit local polynomial separately on each side
+        # Model: Y = α + β*D + γ*X + δ*(D*X) + higher order terms
+
+        # Design matrix
+        Z = np.column_stack([
+            np.ones(len(X_bw)),  # Intercept
+            D,  # Treatment
+            X_bw,  # Running variable
+            D * X_bw  # Interaction
+        ])
+
+        # Weighted least squares
+        W = np.diag(weights)
+        try:
+            beta = np.linalg.solve(Z.T @ W @ Z, Z.T @ W @ Y_bw)
+        except np.linalg.LinAlgError:
+            beta = np.linalg.lstsq(Z.T @ W @ Z, Z.T @ W @ Y_bw, rcond=None)[0]
+
+        # Treatment effect is coefficient on D
+        treatment_effect = beta[1]
+
+        # Standard error (heteroskedasticity-robust)
+        residuals = Y_bw - Z @ beta
+        meat = Z.T @ W @ np.diag(residuals ** 2) @ W @ Z
+        bread_inv = np.linalg.inv(Z.T @ W @ Z)
+        vcov = bread_inv @ meat @ bread_inv
+        se = np.sqrt(vcov[1, 1])
+
+        # Test statistic
+        t_stat = treatment_effect / se
+        n_left = np.sum(X_bw < 0)
+        n_right = np.sum(X_bw >= 0)
+        df = len(X_bw) - Z.shape[1]
+        p_value = 2 * (1 - stats.t.cdf(np.abs(t_stat), df=df))
+
+        return RDDResult(
+            treatment_effect=treatment_effect,
+            se=se,
+            t_stat=t_stat,
+            p_value=p_value,
+            bandwidth=bandwidth,
+            n_left=n_left,
+            n_right=n_right
+        )
+
+    def _select_bandwidth(self, X: np.ndarray, Y: np.ndarray) -> float:
+        """
+        Select bandwidth using Imbens-Kalyanaraman method (simplified).
+
+        Args:
+            X: Centered running variable
+            Y: Outcome
+
+        Returns:
+            Optimal bandwidth
+        """
+        # Simplified: use rule of thumb
+        # h = C * σ * n^{-1/5}
+        sigma = np.std(Y)
+        n = len(Y)
+        bandwidth = 1.06 * sigma * (n ** (-1 / 5))
+
+        # Ensure reasonable range
+        bandwidth = np.clip(bandwidth, 0.1 * np.std(X), 2.0 * np.std(X))
+
+        return bandwidth
+
+    def _kernel_weights(self, X: np.ndarray, bandwidth: float, kernel: str) -> np.ndarray:
+        """Compute kernel weights."""
+        u = X / bandwidth
+
+        if kernel == 'triangular':
+            weights = np.maximum(1 - np.abs(u), 0)
+        elif kernel == 'uniform':
+            weights = (np.abs(u) <= 1).astype(float)
+        elif kernel == 'epanechnikov':
+            weights = np.maximum(0.75 * (1 - u ** 2), 0)
+        else:
+            weights = np.ones(len(X))
+
+        return weights
+
+
+class InstrumentalVariables:
+    """
+    Instrumental Variables (IV) Estimation
+
+    Addresses endogeneity (omitted variable bias, reverse causality)
+    using exogenous variation from an instrument.
+
+    Model:
+    Y = β_0 + β_1 * X + ε  (Structural equation)
+    X = γ_0 + γ_1 * Z + η  (First stage)
+
+    where:
+    - X: Endogenous variable
+    - Z: Instrument (exogenous, correlated with X, affects Y only through X)
+    - β_1: Causal effect of X on Y
+
+    Estimation: Two-Stage Least Squares (2SLS)
+
+    Example:
+        >>> # Effect of trade on conflict (trade is endogenous)
+        >>> # Instrument: Geographic distance to major ports
+        >>> iv = InstrumentalVariables()
+        >>> result = iv.estimate_2sls(
+        ...     outcome=conflict_intensity,
+        ...     endogenous=trade_volume,
+        ...     instrument=distance_to_port,
+        ...     exogenous_controls=other_covariates
+        ... )
+        >>> print(f"IV estimate: {result.beta_iv[0]:.3f}")
+        >>> print(f"First stage F: {result.first_stage_f:.1f}")
+    """
+
+    def estimate_2sls(self, outcome: np.ndarray, endogenous: np.ndarray,
+                     instrument: np.ndarray,
+                     exogenous_controls: Optional[np.ndarray] = None) -> IVResult:
+        """
+        Two-Stage Least Squares estimation.
+
+        Args:
+            outcome: Dependent variable Y, shape (n,)
+            endogenous: Endogenous variable X, shape (n,) or (n, k)
+            instrument: Instrument Z, shape (n,) or (n, m)
+            exogenous_controls: Additional exogenous controls, shape (n, p)
+
+        Returns:
+            IVResult with IV estimates
+        """
+        outcome = np.asarray(outcome).reshape(-1, 1)
+        endogenous = np.atleast_2d(endogenous)
+        if endogenous.ndim == 1:
+            endogenous = endogenous.reshape(-1, 1)
+        instrument = np.atleast_2d(instrument)
+        if instrument.ndim == 1:
+            instrument = instrument.reshape(-1, 1)
+
+        n = len(outcome)
+
+        # Construct design matrices
+        if exogenous_controls is not None:
+            exogenous_controls = np.atleast_2d(exogenous_controls)
+            W = np.column_stack([np.ones((n, 1)), exogenous_controls])
+        else:
+            W = np.ones((n, 1))
+
+        # Full instrument matrix: [W, Z]
+        Z_full = np.column_stack([W, instrument])
+
+        # STAGE 1: Regress endogenous on instruments
+        # X = Z_full @ γ + residuals
+        first_stage_coef = np.linalg.lstsq(Z_full, endogenous, rcond=None)[0]
+        X_hat = Z_full @ first_stage_coef  # Fitted values
+
+        # First stage F-statistic
+        residuals_first = endogenous - X_hat
+        rss_first = np.sum(residuals_first ** 2, axis=0)
+        tss_first = np.sum((endogenous - np.mean(endogenous, axis=0)) ** 2, axis=0)
+        r_squared_first = 1 - rss_first / tss_first
+
+        k_instruments = instrument.shape[1]
+        k_exogenous = W.shape[1]
+        first_stage_f = (r_squared_first / k_instruments) / ((1 - r_squared_first) / (n - k_exogenous - k_instruments))
+        first_stage_f = float(np.mean(first_stage_f))  # Average if multiple endogenous
+
+        # STAGE 2: Regress Y on X_hat and W
+        X_full = np.column_stack([W, X_hat])
+        beta_iv = np.linalg.lstsq(X_full, outcome, rcond=None)[0]
+
+        # Standard errors (2SLS requires special formula)
+        Y_hat = X_full @ beta_iv
+        residuals_second = outcome - Y_hat
+        sigma_sq = np.sum(residuals_second ** 2) / (n - X_full.shape[1])
+
+        # Variance: σ^2 (X_hat' X_hat)^{-1}
+        vcov = sigma_sq * np.linalg.inv(X_full.T @ X_full)
+        se_iv = np.sqrt(np.diag(vcov)).reshape(-1, 1)
+
+        # OLS for comparison (biased but often smaller SE)
+        X_full_ols = np.column_stack([W, endogenous])
+        beta_ols = np.linalg.lstsq(X_full_ols, outcome, rcond=None)[0]
+
+        # Weak instrument warning
+        weak_instrument = first_stage_f < 10
+
+        return IVResult(
+            beta_iv=beta_iv[k_exogenous:, 0],  # Exclude intercept/controls
+            beta_ols=beta_ols[k_exogenous:, 0],
+            se_iv=se_iv[k_exogenous:, 0],
+            first_stage_f=first_stage_f,
+            weak_instrument=weak_instrument
+        )
+
+
+def estimate_treatment_effect_bounds(outcome_treated: np.ndarray,
+                                    outcome_control: np.ndarray,
+                                    selection_probability: float = 0.5) -> Tuple[float, float]:
+    """
+    Estimate bounds on treatment effect under selection on unobservables.
+
+    When treatment assignment is not random, the true effect lies within bounds.
+    This implements Manski bounds (worst-case bounds).
+
+    Args:
+        outcome_treated: Outcomes for treated group
+        outcome_control: Outcomes for control group
+        selection_probability: P(Treatment | unobservables)
+
+    Returns:
+        (lower_bound, upper_bound) on average treatment effect
+    """
+    # Observed means
+    y_treated = np.mean(outcome_treated)
+    y_control = np.mean(outcome_control)
+
+    # Range of outcomes
+    y_min = min(np.min(outcome_treated), np.min(outcome_control))
+    y_max = max(np.max(outcome_treated), np.max(outcome_control))
+
+    # Worst-case bounds
+    # Lower bound: assume best outcomes for control in unobserved potential outcomes
+    lower_bound = y_treated - y_max
+
+    # Upper bound: assume worst outcomes for control in unobserved potential outcomes
+    upper_bound = y_treated - y_min
+
+    return (lower_bound, upper_bound)

geobot/simulation/__init__.py

@@ -0,0 +1,31 @@
+"""
+Simulation engines for GeoBotv1
+"""
+
+from .monte_carlo import MonteCarloEngine, ShockSimulator
+from .agent_based import AgentBasedModel, GeopoliticalAgent
+from .sde_solver import (
+    EulerMaruyama,
+    Milstein,
+    StochasticRungeKutta,
+    JumpDiffusionProcess,
+    GeopoliticalSDE,
+    ornstein_uhlenbeck_process
+)
+
+# Hawkes processes (wrapper for timeseries.point_processes)
+from . import hawkes
+
+__all__ = [
+    "MonteCarloEngine",
+    "ShockSimulator",
+    "AgentBasedModel",
+    "GeopoliticalAgent",
+    "EulerMaruyama",
+    "Milstein",
+    "StochasticRungeKutta",
+    "JumpDiffusionProcess",
+    "GeopoliticalSDE",
+    "ornstein_uhlenbeck_process",
+    "hawkes",
+]

geobot/simulation/agent_based.py

@@ -0,0 +1,349 @@
+"""
+Agent-Based Modeling for Geopolitical Simulation
+
+Models individual actors (states, organizations, leaders) and their interactions.
+"""
+
+import numpy as np
+from typing import Dict, List, Optional, Any, Tuple
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class AgentType(Enum):
+    """Types of geopolitical agents."""
+    STATE = "state"
+    ORGANIZATION = "organization"
+    LEADER = "leader"
+    ALLIANCE = "alliance"
+
+
+@dataclass
+class AgentState:
+    """State variables for an agent."""
+    position: np.ndarray  # Position in feature space
+    resources: float = 1.0
+    power: float = 1.0
+    hostility: float = 0.0
+    cooperation: float = 0.5
+    stability: float = 1.0
+    custom: Dict[str, float] = field(default_factory=dict)
+
+
+class GeopoliticalAgent:
+    """
+    Represents a geopolitical actor.
+
+    Agents have internal state, decision-making logic, and
+    interact with other agents and the environment.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        agent_type: AgentType,
+        initial_state: AgentState
+    ):
+        """
+        Initialize agent.
+
+        Parameters
+        ----------
+        agent_id : str
+            Unique agent identifier
+        agent_type : AgentType
+            Type of agent
+        initial_state : AgentState
+            Initial state
+        """
+        self.agent_id = agent_id
+        self.agent_type = agent_type
+        self.state = initial_state
+        self.history: List[AgentState] = [initial_state]
+        self.relationships: Dict[str, float] = {}  # {agent_id: relationship_strength}
+
+    def update_state(self, **kwargs) -> None:
+        """Update agent state variables."""
+        for key, value in kwargs.items():
+            if hasattr(self.state, key):
+                setattr(self.state, key, value)
+            else:
+                self.state.custom[key] = value
+
+    def decide_action(
+        self,
+        environment: Dict[str, Any],
+        other_agents: List['GeopoliticalAgent']
+    ) -> Dict[str, Any]:
+        """
+        Decide on action based on current state and environment.
+
+        Parameters
+        ----------
+        environment : dict
+            Environmental factors
+        other_agents : list
+            Other agents in the system
+
+        Returns
+        -------
+        dict
+            Chosen action
+        """
+        # Simple decision logic (can be made more sophisticated)
+        action = {
+            'type': 'none',
+            'target': None,
+            'intensity': 0.0
+        }
+
+        # Check for threats
+        threats = [
+            agent for agent in other_agents
+            if self.relationships.get(agent.agent_id, 0) < -0.5
+            and agent.state.power > self.state.power * 0.8
+        ]
+
+        if threats and self.state.hostility > 0.5:
+            # Consider conflict
+            action = {
+                'type': 'escalate',
+                'target': threats[0].agent_id,
+                'intensity': self.state.hostility
+            }
+        elif self.state.cooperation > 0.7:
+            # Seek cooperation
+            potential_partners = [
+                agent for agent in other_agents
+                if self.relationships.get(agent.agent_id, 0) > 0.3
+            ]
+            if potential_partners:
+                action = {
+                    'type': 'cooperate',
+                    'target': potential_partners[0].agent_id,
+                    'intensity': self.state.cooperation
+                }
+
+        return action
+
+    def interact(self, other_agent: 'GeopoliticalAgent', action: Dict[str, Any]) -> None:
+        """
+        Interact with another agent.
+
+        Parameters
+        ----------
+        other_agent : GeopoliticalAgent
+            Other agent
+        action : dict
+            Action to perform
+        """
+        action_type = action['type']
+        intensity = action['intensity']
+
+        if action_type == 'cooperate':
+            # Strengthen relationship
+            current_rel = self.relationships.get(other_agent.agent_id, 0)
+            self.relationships[other_agent.agent_id] = min(1.0, current_rel + 0.1 * intensity)
+
+            # Mutual benefit
+            self.state.resources += 0.05 * intensity
+            other_agent.state.resources += 0.05 * intensity
+
+        elif action_type == 'escalate':
+            # Weaken relationship
+            current_rel = self.relationships.get(other_agent.agent_id, 0)
+            self.relationships[other_agent.agent_id] = max(-1.0, current_rel - 0.2 * intensity)
+
+            # Conflict effects
+            power_ratio = self.state.power / (other_agent.state.power + 1e-6)
+            if power_ratio > 1:
+                self.state.resources += 0.1 * intensity
+                other_agent.state.resources -= 0.15 * intensity
+                other_agent.state.stability -= 0.1 * intensity
+            else:
+                self.state.resources -= 0.1 * intensity
+                self.state.stability -= 0.05 * intensity
+
+    def save_state(self) -> None:
+        """Save current state to history."""
+        self.history.append(AgentState(
+            position=self.state.position.copy(),
+            resources=self.state.resources,
+            power=self.state.power,
+            hostility=self.state.hostility,
+            cooperation=self.state.cooperation,
+            stability=self.state.stability,
+            custom=self.state.custom.copy()
+        ))
+
+
+class AgentBasedModel:
+    """
+    Agent-based model for geopolitical simulation.
+
+    Manages multiple agents and their interactions over time.
+    """
+
+    def __init__(self):
+        """Initialize agent-based model."""
+        self.agents: Dict[str, GeopoliticalAgent] = {}
+        self.environment: Dict[str, Any] = {}
+        self.time: int = 0
+
+    def add_agent(self, agent: GeopoliticalAgent) -> None:
+        """
+        Add agent to model.
+
+        Parameters
+        ----------
+        agent : GeopoliticalAgent
+            Agent to add
+        """
+        self.agents[agent.agent_id] = agent
+
+    def remove_agent(self, agent_id: str) -> None:
+        """
+        Remove agent from model.
+
+        Parameters
+        ----------
+        agent_id : str
+            Agent ID to remove
+        """
+        if agent_id in self.agents:
+            del self.agents[agent_id]
+
+    def set_environment(self, **kwargs) -> None:
+        """Set environmental variables."""
+        self.environment.update(kwargs)
+
+    def step(self) -> None:
+        """
+        Execute one time step of simulation.
+
+        All agents make decisions and interact.
+        """
+        self.time += 1
+
+        # Phase 1: All agents decide actions
+        actions = {}
+        other_agents_list = list(self.agents.values())
+
+        for agent in self.agents.values():
+            action = agent.decide_action(self.environment, other_agents_list)
+            actions[agent.agent_id] = action
+
+        # Phase 2: Execute actions
+        for agent_id, action in actions.items():
+            agent = self.agents[agent_id]
+
+            if action['type'] != 'none' and action['target'] is not None:
+                if action['target'] in self.agents:
+                    target = self.agents[action['target']]
+                    agent.interact(target, action)
+
+        # Phase 3: Environmental updates
+        for agent in self.agents.values():
+            # Resource growth
+            agent.state.resources *= (1 + 0.01 * agent.state.stability)
+
+            # Power calculation
+            agent.state.power = agent.state.resources * agent.state.stability
+
+            # Add noise
+            agent.state.hostility += np.random.normal(0, 0.05)
+            agent.state.hostility = np.clip(agent.state.hostility, 0, 1)
+
+            agent.state.cooperation += np.random.normal(0, 0.05)
+            agent.state.cooperation = np.clip(agent.state.cooperation, 0, 1)
+
+            # Save state
+            agent.save_state()
+
+    def run(self, n_steps: int) -> None:
+        """
+        Run simulation for multiple steps.
+
+        Parameters
+        ----------
+        n_steps : int
+            Number of time steps
+        """
+        for _ in range(n_steps):
+            self.step()
+
+    def get_agent_trajectories(self, agent_id: str) -> Dict[str, List[float]]:
+        """
+        Get historical trajectories for an agent.
+
+        Parameters
+        ----------
+        agent_id : str
+            Agent ID
+
+        Returns
+        -------
+        dict
+            Trajectories of state variables
+        """
+        if agent_id not in self.agents:
+            return {}
+
+        agent = self.agents[agent_id]
+        history = agent.history
+
+        return {
+            'resources': [s.resources for s in history],
+            'power': [s.power for s in history],
+            'hostility': [s.hostility for s in history],
+            'cooperation': [s.cooperation for s in history],
+            'stability': [s.stability for s in history]
+        }
+
+    def get_system_state(self) -> Dict[str, Any]:
+        """
+        Get current state of entire system.
+
+        Returns
+        -------
+        dict
+            System state
+        """
+        return {
+            'time': self.time,
+            'n_agents': len(self.agents),
+            'total_resources': sum(a.state.resources for a in self.agents.values()),
+            'mean_hostility': np.mean([a.state.hostility for a in self.agents.values()]),
+            'mean_cooperation': np.mean([a.state.cooperation for a in self.agents.values()]),
+            'mean_stability': np.mean([a.state.stability for a in self.agents.values()])
+        }
+
+    def analyze_network(self) -> Dict[str, Any]:
+        """
+        Analyze the network of relationships.
+
+        Returns
+        -------
+        dict
+            Network metrics
+        """
+        import networkx as nx
+
+        # Build network
+        G = nx.Graph()
+        for agent in self.agents.values():
+            G.add_node(agent.agent_id)
+
+        for agent in self.agents.values():
+            for other_id, strength in agent.relationships.items():
+                if strength > 0.1:  # Only positive relationships
+                    G.add_edge(agent.agent_id, other_id, weight=strength)
+
+        # Compute metrics
+        return {
+            'n_nodes': G.number_of_nodes(),
+            'n_edges': G.number_of_edges(),
+            'density': nx.density(G),
+            'average_clustering': nx.average_clustering(G) if G.number_of_edges() > 0 else 0,
+            'connected_components': nx.number_connected_components(G)
+        }