Metadata-Version: 2.4
Name: mcpaisuite-ltpmcp
Version: 1.0.3
Summary: LTP (Lean Task Protocol) — compile LLM goals into deterministic execution plans
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/gashel01/ltpmcp
Project-URL: Repository, https://github.com/gashel01/ltpmcp
Project-URL: Issues, https://github.com/gashel01/ltpmcp/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: structlog>=24.0
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.0
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == "api"
Requires-Dist: uvicorn>=0.23; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# ltpmcp

> LTP (Lean Task Protocol) -- compile LLM goals into deterministic execution plans

Part of the [MCP AI Suite](https://mcpaisuite.dev).

## 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
- **Library, CLI & MCP server** -- import it, or use the `ltpmcp` CLI (`parse`/`validate`/`visualize`), the `ltpmcp-server` MCP server (3 tools: `parse_plan`, `validate_plan`, `visualize_plan`), or the optional `ltpmcp-api` FastAPI app

## Installation

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

```python
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.

```python
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.

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

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

### Utility Functions

```python
from ltpmcp import validate_plan, plan_to_mermaid

errors = validate_plan(plan)       # list[str] -- validation errors
mermaid = plan_to_mermaid(plan)    # str -- Mermaid diagram
```

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

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

## License

AGPL-3.0 — see [LICENSE](LICENSE).

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [gaeldev@gmail.com](mailto:gaeldev@gmail.com).
