⚡ StateCraft: Production-Grade Stateful Agentic Workflows with LangGraph

StateCraft is an enterprise-grade learning and portfolio project demonstrating stateful, resilient, self-healing agentic workflows using LangGraph and LangChain.

It bridges the gap between toy linear chains and production autonomous systems by implementing:

• 🔀 Dynamic Branching & Conditional Routing (Intent and risk-based graph traversal)
• 🔄 Self-Correction & Evaluator-Optimizer Loop (AST static validation + sandboxed unit test reflection)
• 🛡️ Resilience, Retries & Fallback Circuit (Transient 429/503 fault tolerance with backoff & L2 cache)
• 👤 Human-in-the-Loop (HITL) Checkpoints (LangGraph native interrupt() and Command(resume=...) with time-travel)
• 👑 Hierarchical Supervisor Multi-Agent Subgraphs (Specialized Researcher, Engineer, and Auditor delegation)
• 🚀 Flagship Enterprise Orchestrator Engine (Autonomous software feature & security release gate)

---

🏗️ System Architecture

                       ┌────────────────────────────┐
                       │     User Ticket Ingest     │
                       └─────────────┬──────────────┘
                                     ▼
                       ┌────────────────────────────┐
                       │ 1. Triage & Risk Branching │
                       └─────────────┬──────────────┘
                                     │ Risk Assessment
                                     ▼
                             ◆───────────────◆
                            ╱    Risk Tier    ╲
                           ◆─────────┬─────────◆
                 TIER_1: Standard    │    TIER_2/3: High Risk
                   ┌─────────────────┴─────────────────┐
                   ▼                                   ▼
     ┌───────────────────────────┐       ┌───────────────────────────┐
     │       Standard Prep       │       │ 2. Resilient SecOps Fetch │
     └─────────────┬─────────────┘       │   (Exponential Retries)   │
                   │                     └─────────────┬─────────────┘
                   └─────────────────┬─────────────────┘
                                     ▼
  ┌───────────────►    ┌────────────────────────────┐
  │                    │ 3. Spec & Code Synthesis   │
  │                    └─────────────┬──────────────┘
  │                                  ▼
  │ Fails              ┌────────────────────────────┐
  │ (iter < max)       │   4. Evaluator-Optimizer   │
  └────────────────────┤ (AST & Unit Test Sandbox)  │
                       └─────────────┬──────────────┘
                                     │ Passes
                                     ▼
                          ◆─────────────────────◆
                         ╱ Human Signoff Needed? ╲
                        ◆────────────┬────────────◆
              TIER_1 Standard        │        TIER_2/3 Elevated
                   ┌─────────────────┴─────────────────┐
                   │                                   ▼
                   │                     ┌───────────────────────────┐
                   │                     │    5. HITL Checkpoint     │
                   │                     │        interrupt()        │
                   │                     └─────────────┬─────────────┘
                   │                                   │ Human Review
                   │                                   ▼
                   │                            ◆─────────────◆
                   │      Approve / Edit       ╱   Approved?   ╲
                   ├──────────────────────────◆────────┬────────◆
                   ▼                                   │ Reject
     ┌───────────────────────────┐                     ▼
     │ 6. Production Deployment  │       ┌───────────────────────────┐
     └─────────────┬─────────────┘       │ Incident Aborted & Logged │
                   │                     └─────────────┬─────────────┘
                   └─────────────────┬─────────────────┘
                                     ▼
                       ┌────────────────────────────┐
                       │ Release Live in Production │
                       └────────────────────────────┘

---

⚡ Quickstart

1. Zero-Cost Offline Mode (Default)

StateCraft includes a built-in Deterministic Mock LLM Engine. You can run the entire test suite, CLI, Streamlit studio, and API 100% locally with ZERO API keys or cloud costs!

# Clone and enter repository
git clone https://github.com/subasah/statecraft-langgraph.git
cd statecraft-langgraph

# Create and activate virtual environment (using uv or standard python)
uv venv .venv
source .venv/bin/activate

# Install dependencies and statecraft package in editable mode
uv pip install -e .

2. Optional: Connect Real LLMs (OpenAI / Google Gemini)

Copy .env.example to .env and set your preferred provider:

cp .env.example .env
# Set LLM_PROVIDER=openai or LLM_PROVIDER=google

---

🛠️ The 3 Ways to Run & Showcase

1. Interactive Streamlit Visual Studio

Launch the browser UI to visually step through graphs, trigger human interrupts, and view live state transitions:

streamlit run streamlit_app.py

Access in browser at http://localhost:8501

2. Rich Terminal CLI

Interactive terminal with colored banners, ASCII tables, and prompt runners:

python -m statecraft.cli
# Or using the installed entry point:
statecraft

3. FastAPI REST Server

Start the production headless orchestration API:

uvicorn statecraft.api:app --reload --port 8000

Interactive Swagger docs available at http://localhost:8000/docs

---

🧪 Automated Test Suite

Run all 14 unit and integration tests verifying every pattern:

pytest tests/ -v

Output:

tests/test_branching.py::test_branching_security PASSED                  [  7%]
tests/test_branching.py::test_branching_technical PASSED                 [ 14%]
tests/test_branching.py::test_branching_billing PASSED                   [ 21%]
tests/test_branching.py::test_branching_general_fast_path PASSED         [ 28%]
tests/test_enterprise_pipeline.py::test_enterprise_pipeline_standard_track PASSED [ 35%]
tests/test_enterprise_pipeline.py::test_enterprise_pipeline_critical_track_with_hitl_signoff PASSED [ 42%]
tests/test_human_in_the_loop.py::test_hitl_low_risk_auto_approves PASSED [ 50%]
tests/test_human_in_the_loop.py::test_hitl_high_risk_pauses_and_resumes_with_approval PASSED [ 57%]
tests/test_human_in_the_loop.py::test_hitl_resumes_with_human_edits_mutating_state PASSED [ 64%]
tests/test_resilience.py::test_resilience_flaky_service_recovers PASSED  [ 71%]
tests/test_resilience.py::test_resilience_down_service_trips_circuit_breaker PASSED [ 78%]
tests/test_self_correction.py::test_self_correction_recovers_and_passes PASSED [ 85%]
tests/test_self_correction.py::test_self_correction_bounds_iteration_limit PASSED [ 92%]
tests/test_supervisor.py::test_supervisor_orchestrates_all_specialists PASSED [100%]
============================== 14 passed in 1.19s ==============================

---

📚 Complete Documentation Catalog

• 📄 Interactive Web Documentation Portal: Browser-based portal with rendered Mermaid diagrams, code walkthroughs, and an interactive state simulator.
• 📐 01. High-Level Architecture Guide: Core theory, why stateful graphs beat linear DAGs, and system trade-offs.
• 🔬 02. Low-Level Engineering Guide: State schemas, channel reducers (Annotated[list, append_list]), checkpointer internals, and modern interrupt() mechanics.
• 📦 03. Reusable Patterns Catalog: Deep dive into all 5 orchestration patterns, failure modes, and best practices.
• 💼 04. Recruiter & Interview Cheat Sheet: 60-second elevator pitch, STAR method interview questions, and system design answers.

---

📁 Repository Structure

├── docs/
│   ├── index.html                 # Interactive Web Documentation Portal
│   ├── 01_HIGH_LEVEL_ARCHITECTURE.md
│   ├── 02_LOW_LEVEL_ENGINEERING.md
│   ├── 03_REUSABLE_PATTERNS.md
│   └── 04_RECRUITER_INTERVIEW_CHEATSHEET.md
├── src/
│   └── statecraft/
│       ├── __init__.py
│       ├── state.py               # TypedDict schemas and append reducers
│       ├── llm.py                 # Multi-provider LLM adapter (Mock, OpenAI, Google)
│       ├── patterns/
│       │   ├── dynamic_branching.py       # Pattern 1
│       │   ├── self_correction.py         # Pattern 2
│       │   ├── resilience_retries.py      # Pattern 3
│       │   ├── human_in_the_loop.py       # Pattern 4
│       │   └── hierarchical_supervisor.py # Pattern 5
│       ├── orchestrator/
│       │   └── enterprise_pipeline.py     # Flagship Unified Engine
│       ├── cli.py                 # Rich Terminal CLI
│       └── api.py                 # FastAPI REST Endpoints
├── tests/                         # Pytest test suite (14 passing tests)
├── streamlit_app.py               # Interactive Streamlit Visual Playground
├── pyproject.toml                 # Package configuration
├── requirements.txt               # Pinned dependencies
├── Makefile                       # One-command CLI targets
└── README.md

---

💼 Recruiter Talking Points (Quick Summary)

• Why LangGraph over standard chains? Real reasoning is non-linear and requires cycles (Evaluator-Optimizer). LangGraph is a state machine that natively supports cyclic graphs, persistent checkpoints, and time travel.
• How does Human-in-the-Loop work without blocking threads? Using LangGraph 1.2+'s interrupt(), the graph serializes state to storage (Postgres/Redis/Memory) and yields execution immediately. When a reviewer submits a verdict via Web UI or API, Command(resume=decision) awakens the thread at the exact checkpoint.
• How do you avoid infinite loops in self-correction? State tracks both error critiques and an iteration counter. Conditional edges enforce iterations < max_iterations, safely diverting to human escalation if the budget is exhausted.