Enterprise-Grade Strategic Simulation Architecture

Designed for Adaptive Fault Tolerance & Epistemic Resilience

An advanced multi-agent system designed to model, analyze, and simulate complex geopolitical scenarios. This repository implements a Decision-Centric architecture where agents communicate via strictly typed Pydantic objects (Decision, Signal), ensuring deterministic control flow and rigorous safety.

This system implements a tiered model strategy to balance cost, speed, and reasoning depth.

Note: The repository is currently configured for Groq (Testing Mode) by default to ensure accessible development.

We enforce a Semantic Firewall between System Faults and Strategic Risks.

• Strict Separation: API timeouts or Schema errors are never conflated with "High Risk".
• Degraded Mode: If the system loses contact with specialist agents (Zero Decisions), it automatically fails over to a neutral risk stance (Risk 0) rather than crashing or hallucinating a crisis.
• Consensus Abort: A single agent cannot trigger a mission abort. A quorum of ≥2 high-confidence, high-risk signals is required.

The system possesses "Cognitive Recovery" capabilities.

• The Problem: High-speed LLMs sometimes fail strict JSON schemas.
• The Solution: Instead of discarding malformed output, the Orchestrator intercepts the proper raw text, uses a fast recovery model to salvage semantic signals (e.g., "Risk Increasing"), and feeds this "Soft Intelligence" into the decision engine.
• Result: The system "thinks" even when it stutters.

Every agent's cognitive process is transparent. The Thought Stream UI displays the instantaneous "Inner Monologue" of security, economic, and technology specialists before they commit to a formal decision.

The architecture is orchestrated via a directed cyclic graph (LangGraph).

graph TD
    User(User Global Intelligence) --> Planner[Planner Agent]
    Planner -->|ExecutionPlan| Specialists
    
    subgraph "Parallel Intelligence Layer"
        Specialists --> Sec[Security Agent]
        Specialists --> Tech[Technology Agent]
        Specialists --> Econ[Economics Agent]
    end
    
    Sec -->|Decision / Signal| Aggregator
    Tech -->|Decision / Signal| Aggregator
    Econ -->|Decision / Signal| Aggregator
    
    Aggregator -->|CompositeDecision| Constraint[Constraint Gate]
    
    Constraint -->|Unsafe| Aggregator
    Constraint -->|Valid| Judgment[Judgment Agent]
    
    Judgment -->|Approve| Sim[Simulation Engine]
    Judgment -->|Reject| Constraint
    
    Sim -->|State Update| Report[Final Report]

• Python 3.12+
• Groq API Key (for Development/Testing)

1. Clone & Setup

   git clone https://github.com/your-org/simulation-agent.git
   cd simulation-agent
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

2. Environment Create a .env file:

   GROQ_API_KEY=gsk_...

3. Run the Dashboard

   streamlit run ui/app.py

The system includes a production-hardened test suite.

# Run all tests
pytest tests/

# Test LLM Client Resilience (Retries, JSON Stripping)
pytest tests/test_llm_client.py

MIT License.