symforge 0.5.0

SymForge — Agent Plan Verification Layer. A neuro-symbolic planner that produces mathematically verifiable Plan DAGs for LLM agents.

SymForge — Neuro-Symbolic Planner for LLM Agent Tool Orchestration

Give your LLM Agent mathematically verifiable plans — not probabilistic guesses.

---

What is SymForge?

SymForge is an MCP Server that provides LLM agents with symbolic planning capabilities. Instead of letting the LLM hallucinate tool-call sequences, SymForge uses classical AI planning (HTN + backward chaining) to produce a mathematically verifiable Plan DAG.

User: "Add JWT refresh token support"
  → LLM Agent calls SymForge MCP tool: plan(goal="JWT refresh")
  → SymForge returns a Plan DAG (JSON) with validated dependencies
  → LLM Agent reads the DAG and generates actual code

Why not just let the LLM figure it out?

Problem	Pure LLM	SymForge
Non-deterministic output	Same prompt → different plan	Same input → same output
Dependency validation	"Feels right"	Mathematically verified (NetworkX DAG)
Rollback on failure	Manual cleanup	Built-in compensation actions
Complex task decomposition	Flat list of steps	HTN three-level hierarchy
Context awareness	Prompt-dependent	Auto-skips already-completed steps

---

Quick Start

1. Install

pip install symforge
# or from source:
git clone https://gitcode.com/wsm1998/SymForge.git && cd SymForge && pip install .

2. Configure your MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "symforge": {
      "command": "symforge-mcp"
    }
  }
}

Cursor / Cline (.cursor/mcp.json or Cline MCP settings):

{
  "mcpServers": {
    "symforge": {
      "command": "python",
      "args": ["-m", "symforge.adapters.mcp_server"]
    }
  }
}

Claude Code (.claude/mcp.json):

{
  "mcpServers": {
    "symforge": {
      "command": "symforge-mcp"
    }
  }
}

3. Use it

In Claude Desktop (or any MCP-compatible client), the agent can now call:

• plan(goal, context?, initial_state?) — Generate a Plan DAG
• validate(plan_json) — Validate an existing plan

Example conversation:

User: Add user registration to my app

Claude: (calls plan("Enable_user_registration")) → Gets back a 3-node DAG: create_user_repo → create_user_service → compose_registration → Generates the actual code for each step in order

---

CLI Usage

SymForge also ships with a CLI for testing and debugging:

# Method decomposition (built-in goal)
symforge plan "Enable_user_registration"

# Backward chaining (entity:state format)
symforge plan "user_module:unit_implemented"

# With context
symforge plan "Implement_unit" -c '{"entity_id": "auth_service"}'

# YAML output
symforge plan "Enable_user_registration" --format yaml

# With initial state (skip already-satisfied steps)
symforge plan "Enable_user_registration" -s state.json

# Validate a plan file
symforge validate plan_output.json

---

MCP Tools Reference

plan

Parameter	Type	Required	Description
goal	string	✅	Planning goal — known method name (e.g. "Enable_user_registration") or "entity:state" format (e.g. "auth_service:unit_implemented")
context	object		Extra context like {"entity_id": "payment_module"}
initial_state	object		Pre-existing entity states, e.g. {"user_repo": "unit_exists"}

Returns: A Plan DAG JSON with plan_id, goal, nodes (topologically sorted actions), and edges (dependency pairs).

validate

Parameter	Type	Required	Description
plan_json	string	✅	Plan DAG JSON string to validate

Returns: {"valid": true/false, "errors?": [...], "plan_id?": "...", "node_count?": N}

Resource: symforge://state/current

Returns the current entity → state mapping (JSON).

---

Architecture

                         ┌──────────────────┐
                         │    LLM Agent      │
                         │  (Claude/Cursor)  │
                         └────────┬─────────┘
                                  │ MCP protocol (stdio)
                                  ▼
                         ┌──────────────────┐
                         │ SymForge MCP     │
                         │  Server           │
                         │                   │
                         │  Tools:           │
                         │  · plan           │
                         │  · validate       │
                         └────────┬─────────┘
                                  │
                         ┌────────▼─────────┐
                         │  SymForgeEngine   │
                         │  (Public API)     │
                         ├──────────────────┤
                         │  HTN Planner      │
                         │  ├─ Method decomp │
                         │  └─ Backward chain│
                         ├──────────────────┤
                         │  Graph Planner    │
                         │  └─ DAG validation│
                         ├──────────────────┤
                         │  State Manager    │
                         │  └─ Symbol table  │
                         └────────┬─────────┘
                                  │
                         ┌────────▼─────────┐
                         │   Action Library  │
                         │  L1: Atomic ops   │
                         │  L2: Composite    │
                         │  L3: System       │
                         └──────────────────┘

Planning strategies

Strategy	Trigger	How it works
Method decomposition	Goal matches a registered method name	Pre-defined decomposition function expands into action sequence
Backward chaining	Goal uses entity:state format	Starts from target state, finds actions that produce it, recursively resolves preconditions

State transition system

NONE → UNIT_EXISTS → UNIT_IMPLEMENTED → TEST_PASSED → COMPOSITE_READY → INTEGRATION_READY
       CREATE_UNIT    IMPLEMENT_UNIT     EXECUTE_TESTS  COMPOSE_MODULES   INTEGRATE_SERVICES

Action hierarchy

Level	Type	Example	Description
L1	CREATE_UNIT	Create file/module	Atomic, indivisible
L1	IMPLEMENT_UNIT	Implement business logic	Depends on UNIT_EXISTS
L1	EXECUTE_TESTS	Run tests	Depends on UNIT_IMPLEMENTED
L1	VERIFY	Final verification	Depends on TEST_PASSED
L2	COMPOSE_MODULES	Combine multiple modules	Depends on all child UNIT_EXISTS
L3	INTEGRATE_SERVICES	System-level integration	Depends on all modules COMPOSITE_READY

---

Design Principles

• SymForge plans, the LLM codes. SymForge stops at the Plan DAG — actual code generation is the agent's job.
• Deterministic. Same input always produces the same plan. Debuggable, reproducible.
• MCP-first. The MCP server is the primary interface; CLI is secondary.
• No code generation. The generators/ directory was intentionally removed — this is a design decision, not a gap.

---

Roadmap

Phase	Goal	Status
v0.1	Core reasoning engine	✅ Complete
v0.5	MCP Server + OpenAI FC adapter	✅ Complete
v1.0	Dynamic codebase awareness (Tree-sitter), execution engine, DAG visualization	⬜ Planned

---

Development

# Install dev dependencies
pip install -e ".[dev]"
# or with Poetry:
poetry install

# Run tests (162 tests)
pytest

# Run a specific test
pytest tests/test_planner.py::TestHTNPlannerBackwardChaining -v

# Run the MCP server locally for debugging
python -m symforge.adapters.mcp_server

License

MIT — see LICENSE.