🔥 Neurosymbolic Forge (NSForge)

Turn concepts into verifiable, traceable formulas. NSForge is an MCP server that forges new formulas through deterministic, provenance-tracked derivation — the AI orchestrates, tools reify.

License Python MCP Tools Harness

🌐 English | 繁體中文

💡 Why NSForge?

LLMs are great at understanding and planning, but doing symbolic math by hand makes them hallucinate, contradict themselves, and produce unverifiable results. NSForge draws a clean line:

North star: every symbol, equation, value, and line of code in a result has a tool call as its birth certificate. The amount the AI computes by hand approaches zero.

NSForge is NOT a formula database — it's a derivation factory. Formulas are inputs (from SymPy‑MCP, Wikidata, BioModels, you); the operators (compose · substitute · solve · verify · prove) are the product.

🪜 The Reification Ladder

The core idea: climb from a fuzzy concept to executable, provenance-bound code, one deterministic rung at a time.

flowchart LR
    C["💭 CONCEPT<br/>a goal"] --> S["🔤 SYMBOL<br/>typed + units"]
    S --> D["🧩 DERIVATION<br/>composed"]
    D --> V{"✅ verify"}
    V -->|"fails"| D
    V -->|"passes"| A["⚙️ ALGORITHM<br/>code"]
    A -. "emitted only if ledger complete" .-> L[["📒 provenance ledger"]]
    C -.-> L
    S -.-> L
    D -.-> L

📖 Deep dive: Reification-ladder direction · General-formula-exploration roadmap

🌍 Ecosystem: don't reinvent the wheel

NSForge works with other MCP servers, not against them.

flowchart TB
    subgraph SY["🔢 sympy-mcp · 32 tools"]
        direction LR
        SY1["Base formulas: F=ma, PV=nRT, Arrhenius"]
        SY2["Constants · ODE / PDE / matrices"]
    end
    subgraph NS["🔨 nsforge-mcp · 91 tools — YOU ARE HERE"]
        direction LR
        NS1["Derivation framework<br/>compose · verify · code"]
        NS2["Provenance repository"]
        NS3["Formula search<br/>Wikidata · BioModels · SciPy"]
    end
    subgraph US["🎯 usolver-mcp · optional"]
        US1["Z3 · OR-Tools · CVXPY · HiGHS"]
    end
    SY -->|"base formulas"| NS
    NS -->|"prepared model"| US
    NS -->|"stores CREATED formulas"| REPO[("formulas/derivations")]

📦 Installation

Requirements: Python 3.12+ and uv (recommended).

uv add nsforge-mcp          # or: pip install nsforge-mcp

git clone https://github.com/u9401066/nsforge-mcp.git
cd nsforge-mcp
uv sync --all-extras
uv run python -c "import nsforge; print(nsforge.__version__)"

Configure as an MCP server

{
  "mcpServers": {
    "nsforge": { "command": "uvx", "args": ["nsforge-mcp"] }
  }
}

🎬 How it works — SymPy-MCP first

The golden rule: compute & verify with SymPy-MCP, then record with NSForge (provenance + human insight at every step).

flowchart LR
    A["🤖 LLM<br/>understand + plan"] --> B["🔢 SymPy-MCP<br/>compute + verify"]
    B --> C["🔨 NSForge<br/>record step + provenance"]
    C --> D{"more<br/>steps?"}
    D -->|"yes"| B
    D -->|"no"| E["✅ complete<br/>stored formula + code"]

🧭 Autonomous task orchestration (L2 / L3)

Hand NSForge a declarative Derivation Task Spec (DTS) and it runs the whole ladder for you. task_explore turns a single answer into a space of verified answers: it runs the base derivation plus every alternative, then ranks the survivors.

flowchart TD
    DTS["📋 Derivation Task Spec"] --> BASE["base derivation"]
    DTS --> ALT1["alternative 1"]
    DTS --> ALT2["alternative 2"]
    BASE --> V["verify · acceptance oracles · provenance"]
    ALT1 --> V
    ALT2 --> V
    V --> RANK["🏆 ranked candidates<br/>verified · oracles passed · simpler"]

• task_plan — reify a DTS into an ordered, provenance-tagged plan
• task_run — run the ladder end-to-end (optional hard timeout_s)
• task_explore — branching search returning all verified candidates

📖 General-formula-exploration roadmap

🎛️ Step-by-step control

Navigate and edit a derivation like a version-controlled document. Expressions are immutable (that keeps verification honest) — to change a result, rollback to a valid state and re-derive.

stateDiagram-v2
    direction LR
    [*] --> deriving
    deriving --> deriving: get_step / update_step / insert_note
    deriving --> earlier: rollback
    earlier --> deriving: re-derive a new path
    deriving --> [*]: complete + save

derivation_get_step · derivation_update_step · derivation_rollback · derivation_insert_note · derivation_delete_step — see the tool reference.

🛠️ Tools at a glance — 91 tools · 82 loaded by default

📖 Full list with every tool: Tool Reference · machine-readable capabilities.json

✅ Verification harness

One command is the ground truth. python scripts/check.py runs 10 gates — a green run is the definition of "done".

lint · format · type · import · manifest · test · bench · generic · provenance · diff

• bench — known derivations reproduce correctly
• generic — unseen, randomly-composed formulas derive correctly (proves NSForge is a derivation calculus, not a hand-built library)
• provenance — every benchmark derivation carries a complete tool-provenance ledger (no hand-derived leaks)

python scripts/check.py            # all gates
python scripts/check.py --json     # machine-readable (for agents)

📚 Derivation repository

Derived formulas are stored with full provenance — LaTeX, SymPy form, the base formulas combined, the steps taken, verification status, and clinical/physical context.

🐍 Worked example: examples/npo_antibiotic_analysis.py

🧠 Agent skills

NSForge ships 19 pre-built skills that teach agents how to use the tools — 6 NSForge workflows (nsforge-derivation-workflow, nsforge-formula-search, nsforge-verification-suite, …) plus 13 general development skills.

📖 NSForge Skills Guide

🔗 Optional: NSForge → USolver

NSForge derives the domain-smart formula; USolver finds the math-optimal values.

flowchart LR
    N["🔨 NSForge<br/>derive modified formula"] --> P["derivation_prepare_for_optimization"]
    P --> U["🎯 USolver<br/>Z3 · OR-Tools · CVXPY"]
    U --> R["optimal parameters"]

📖 Skill: nsforge-usolver-collab

🏗️ Architecture & development

DDD with a pure domain core and a replaceable MCP layer (nsforge core has no MCP dependency).

uv sync --all-extras     # set up
uv run pytest            # tests
python scripts/check.py  # full harness (10 gates)
uv run nsforge-mcp       # start the server

📖 Architecture · Contributing · NSForge vs SymPy-MCP

🗺️ Roadmap

Reification-ladder phases 1–6 are live (engine → benchmarks → suggester → self-correction → provenance → explore mode). Remaining: Lean4 formal verification (optional) and multi-agent infrastructure.

📖 ROADMAP.md · General-formula-exploration roadmap

📄 License

Apache License 2.0