Metadata-Version: 2.4
Name: symforge
Version: 0.5.0
Summary: SymForge — Agent Plan Verification Layer. A neuro-symbolic planner that produces mathematically verifiable Plan DAGs for LLM agents.
License: MIT License
         
         Copyright (c) 2026 SymForge
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
License-File: LICENSE
Keywords: mcp,planning,llm-agent,dag,htn,symbolic-ai,neuro-symbolic,task-planning,ai-agent
Author: SymForge Team
Requires-Python: >=3.10
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Provides-Extra: dev
Provides-Extra: yaml
Requires-Dist: mcp (>=1.0)
Requires-Dist: networkx (>=3.0)
Requires-Dist: pydantic (>=2.0)
Requires-Dist: pytest (>=7.4) ; extra == "dev"
Requires-Dist: pytest-cov (>=4.1) ; extra == "dev"
Requires-Dist: pyyaml (>=6.0) ; extra == "yaml"
Project-URL: Documentation, https://gitcode.com/wsm1998/SymForge#readme
Project-URL: Homepage, https://gitcode.com/wsm1998/SymForge
Project-URL: Issues, https://gitcode.com/wsm1998/SymForge/issues
Project-URL: Repository, https://gitcode.com/wsm1998/SymForge.git
Description-Content-Type: text/markdown

# SymForge — Neuro-Symbolic Planner for LLM Agent Tool Orchestration

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

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![Tests](https://img.shields.io/badge/tests-162%20passed-brightgreen)]()
[![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)]()
[![Version](https://img.shields.io/badge/version-0.5.0-yellow)]()

---

## 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

```bash
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`):

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

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

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

**Claude Code** (`.claude/mcp.json`):

```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:

```bash
# 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

```bash
# 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](./LICENSE).

