ltpmcp

📐 ltpmcp — Compile goals into deterministic, verifiable plans

Part of the MCP AI Suite.

 ⭐ Star on GitHub · 📚 Docs

ltpmcp compiles a natural-language goal into a deterministic, verifiable execution plan in a single LLM call — then runs it step by step with parallel branches, conditionals, loops, and retries. Compile once, run predictably and token-cheap. Python library · CLI · MCP server · REST API.

pip install mcpaisuite-ltpmcp

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• API Reference
• Architecture
• Testing
• License

Features

• Single-call compilation -- converts a natural-language goal into a structured execution plan with one LLM call
• Micro-CLI syntax -- compact ~20 tokens/step format (search, fetch, exec, respond) for token efficiency
• Deterministic runtime -- executes plans step-by-step with variable passing, conditionals, and loops
• Conditional branching -- ?IF ($var == "value") THEN ... with numeric, string, and contains operators
• FOREACH iteration -- iterate over list variables with per-item processing
• ON_FAIL error handling -- retry N times, GOTO fallback step, or terminate with message
• RE-PLAN -- dynamically recompile the plan mid-execution when results invalidate the approach
• Parallel execution groups -- concurrent step execution within the same group
• Type casting -- output variables cast to int, float, list, bool, or json
• Mermaid visualization -- export plans as Mermaid flowcharts
• Plan diff -- diff_plans(a, b) structural diff of two plans (added/removed/changed/reordered steps)
• Library, CLI, MCP & API -- import it, or use the ltpmcp CLI (parse/validate/visualize/diff), the ltpmcp-server MCP server (4 tools: parse_plan, validate_plan, visualize_plan, diff_plans), or the optional ltpmcp-api FastAPI app (/parse, /validate, /visualize, /diff, /compile)

Installation

pip install mcpaisuite-ltpmcp
# Optional extras:
pip install mcpaisuite-ltpmcp[dev]    # Development tools
pip install "mcpaisuite-ltpmcp[api]"  # FastAPI server (ltpmcp-api)

Console scripts: ltpmcp (CLI), ltpmcp-server (MCP, stdio), ltpmcp-api (FastAPI). Runtime deps: pydantic, structlog, click, mcp.

Quick Start

from ltpmcp import LTPCompiler, LTPRuntime

async def my_llm(messages):
    # Your LLM completion function
    return await call_llm(messages)

compiler = LTPCompiler(llm_fn=my_llm)
plan = await compiler.compile("What is the weather in Ibiza?")

runtime = LTPRuntime()
result = await runtime.execute(plan, tool_executor=my_tool_fn, llm_fn=my_llm)
print(result["response"])

Configuration

LTP is configured programmatically via the compiler and runtime constructors. No environment variables are required.

Parameter	Description
llm_fn	Async callable (messages) -> str for plan compilation and LLM ops
tool_executor	Async callable (tool_name, args, namespace) -> dict for tool execution
max_replans	Maximum RE-PLAN recompilations allowed (default: 3)

API Reference

LTPCompiler

Compiles a user goal into an LTP plan using one LLM call with Micro-CLI syntax.

compiler = LTPCompiler(llm_fn=my_llm)
plan = await compiler.compile(goal, context="") -> LTPPlan | None  # None on compile failure

LTPRuntime

Deterministic execution engine for LTP plans.

runtime = LTPRuntime(audit_fn=None)
result = await runtime.execute(plan, tool_executor, llm_fn,
                               agent_fn=None, namespace="default",
                               max_replans=3, progress_callback=None) -> dict

LTPPlan / LTPStep

plan.steps         # list[LTPStep]
plan.step_count    # int
plan.variables     # dict[str, Any]
plan.raw           # str -- original Micro-CLI text

Utility Functions

from ltpmcp import validate_plan, plan_to_mermaid, diff_plans

errors = validate_plan(plan)       # list[str] -- validation errors
mermaid = plan_to_mermaid(plan)    # str -- Mermaid diagram
changes = diff_plans(plan_a, plan_b)  # dict -- added/removed/changed/reordered + winner-free summary

Architecture

LTPCompiler sends a single prompt with Micro-CLI syntax examples to the LLM, which returns a compact step-by-step plan. The compiler converts Micro-CLI commands to standard LTP format (with @TOOL references), which is parsed by LTPParser into an LTPPlan AST. LTPRuntime then executes each step sequentially, resolving $variable references with dot-notation support, evaluating conditions, handling FOREACH loops, and routing tool calls through the provided executor.

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

Apache-2.0 — see LICENSE.

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact contact@mcpaisuite.com.