🤖 Deterministic Agent Supervisor (DAS)

State-Machine-Constrained Multi-Agent Engine with Structured Anthropic Outputs. Because one hallucinated flag or out-of-order execution should not take down an entire cloud region.

---

🌌 The Manifesto: Why This Exists

Non-determinism is the absolute bane of automated infrastructure management.

When you trust a traditional autonomous LLM agent with a production environment, you are playing Russian roulette. A single minor execution drift, a hallucinated CLI flag, or an out-of-order terraform apply can drop database clusters, isolate networks, or trigger catastrophic cascade failures.

Deterministic Agent Supervisor (DAS) solves this by decoupling reasoning from state transition validation:

1. The Brain (Python + Anthropic Claude 3.5 Sonnet): Proposes actions and drafts configuration variations using strict JSON Schema Tool parameters.
2. The Guardrail (Native Compiled Rust): Implements a strictly immutable, compile-time hardcoded state machine. If the agent attempts a forbidden transition (e.g., trying to jump from Planning directly to Executing without an explicit Approved block), Rust violently rejects the transition memory space before a single byte touches your cloud provider.

---

🏗️ Architecture & Mechanics

[ Cloud / Infrastructure Objective ]
│
▼
┌──────────────────────────────────────────┐
│        Python Orchestration Layer        │
└──────────────────┬───────────────────────┘
│
▼ (1. Context + State Prompt)
┌──────────────────────────────────────────┐
│      Anthropic Claude 3.5 Sonnet         │
│   (Forced to yield Structured JSON)     │
└──────────────────┬───────────────────────┘
│
▼ (2. Proposed Action Payload)
┌──────────────────────────────────────────┐     🚫 [ILLEGAL DRIFT]
│       Rust Immutable State Machine       │ ──► (Panic / Memory Boundary Isolation)
│  (Validates transitions out of reach)   │
└──────────────────┬───────────────────────┘
│
▼ (3. Verified Transitions Only)
[ Safe Deterministic Infrastructure Update ]

---

🛠️ Features & Safety Guarantees

• Zero-Drift Execution: No matter what the LLM hallucinates, it cannot transition into an unapproved state.
• Type-Safe Python bindings via PyO3: The state machine is built natively in Rust and compiled down to a high-performance Python extension module (supervisor_core).
• Structured Tool Enforcement: Uses Anthropic's native tool_choice mode to force Claude to respond exclusively in raw, structured JSON matching our Pydantic model state targets.

---

📦 Repository Structure

deterministic-agent-supervisor/
├── .gitignore
├── Cargo.toml                  # Rust compilation definitions & PyO3 settings
├── README.md                   # This master documentation
├── requirements.txt            # Python ecosystem dependencies
├── src/
│   ├── lib.rs                  # Core Immutable State Machine (Rust Engine)
│   └── main.rs                 # Native Rust playground/CLI binary
└── supervisor/
    ├── __init__.py
    ├── agent.py                # Anthropic API layer & JSON Schema mappings
    ├── engine.py               # FFI Engine link abstraction
    └── main.py                 # Core supervisor workflow loop

---

🚀 Onboarding & Quickstart

Get your deterministic multi-agent supervisor up and running in less than 3 minutes.

Prerequisites

• Rust Toolchain: cargo, rustc (Edition 2021)
• Python: Version 3.10 or higher
• An Anthropic API Key with access to Claude 3.5 Sonnet

1. Clone & Environment Setup

# Clone the repository
git clone [https://github.com/yourusername/deterministic-agent-supervisor.git](https://github.com/yourusername/deterministic-agent-supervisor.git)
cd deterministic-agent-supervisor

# Set up a clean Python virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# Install essential Python packages
pip install -r requirements.txt

2. Compile the Rust Guardrail Engine

We use maturin to natively compile our Rust core validation logic directly into the local Python environment.

# Install maturin for compilation
pip install maturin

# Compile and bind the Rust module in release mode
maturin develop --release

3. Configure Credentials & Launch

Set your Anthropic token and execute the orchestration supervisor script:

export ANTHROPIC_API_KEY="your_actual_anthropic_api_key_here"

# Execute the supervisor engine
python supervisor/main.py

---

🔍 Code Walkthrough

The Immutable Guardrail (src/lib.rs)

Our state machine logic is isolated inside native compiled code. Changes to the permitted pathways cannot be manipulated or side-stepped by prompt injections or model degradation.

// Only strict linear or explicit fail paths are mapped
transitions.insert("Idle".to_string(), vec!["Planning".to_string()]);
transitions.insert("Planning".to_string(), vec!["Approved".to_string(), "Failed".to_string()]);
transitions.insert("Approved".to_string(), vec!["Executing".to_string(), "Failed".to_string()]);

The Structured Engine Response (supervisor/agent.py)

We wrap Anthropic calls using Pydantic parameters, mapping the target state string natively into Claude's attention space.

class AgentAction(BaseModel):
    next_state: str = Field(description="Must be Planning, Approved, Executing, Success, or Failed.")
    command: str = Field(description="The exact infrastructure command to execute.")
    rationale: str = Field(description="Human-readable context justification.")

---

🤝 Contributing & Community

We are building the future of dependable, bulletproof AI automation. If you find a structural edge-case, open a Pull Request!

1. Fork the repo.
2. Create your feature branch (git checkout -b feature/safer-transitions).
3. Make sure your Rust code passes tests (cargo test) and Python linting rules conform.
4. Open a PR to main.

---

📄 License

Distributed under the MIT License.