PDLt
A protocol harness for verified, auditable model execution: a Python library first, with an extensions SDK, an interactive REPL, a headless CLI and an MCP server on top.
PDLt sits between a request and a model.
- Interpretation: the model restates the request as short pseudocode. In review mode, the run stops for your confirmation before anything executes.
- Sandboxing: programs the model writes run under the operating system's own confinement (AppContainer on Windows, Landlock on Linux, Seatbelt on macOS). Without it, no program runs.
- Checking: the host checks every reply against its contract and runs the programs itself.
- Provenance: every published result says what it rests on:
host_verified, contract_checked or unverified.
The harness is a referee, never a solver: it adds no hints, keyword gates or fabricated witnesses (guardrails).
Entry points
| Use | Entry point | Read |
|---|
| Run tasks from Python (primary) | pdl_taskmaster.api: Session, TurnResult, create_worker, RunSettings | Python API |
| Add task types, verifiers or model providers | Extensions SDK: register_task_type, register_verifier, register_provider, and a conformance kit | Extensions SDK |
| Work interactively | REPL: pdlt | REPL quickstart |
| Automate (CI, scripts) | Headless: pdlt --non-interactive, with exit codes | Headless runs |
| Use PDLt from another agent | MCP server: python -m pdl_taskmaster.host.mcp_server | MCP server |
All of them go through the same library layer, and one conformance suite (tests/test_interface_conformance.py) checks that they agree on sessions, reviews, exit codes and provenance.
Install
PDLt needs Python 3.10 to 3.14 and an OS-native sandbox, so setup differs by host. Follow the page for your machine: it gives every command, a check after each step, and troubleshooting. Agents doing the setup should follow it step by step.
In short, in a virtual environment:
python -m pip install "pdl-taskmaster>=2.6.0" # from PyPI
python -m pip install -e ".[test]" # or, from a clone of this repository
Live runs need an OpenRouter key in OPENROUTER_API_KEY; the offline test suite and the sandbox check need none.
Python API
from pdl_taskmaster.api import Session, create_worker
worker = create_worker("api", model="nvidia/nemotron-3-super-120b-a12b:free")
with Session.open(worker, "pdlt-sessions/demo", no_review=True) as session:
result = session.send("Count the primes below 1000 and print the count.")
print(result.text)
print(result.stage, result.exit_status) # e.g. CLOSED_SUCCESS 0
if result.provenance: # present when a result was published
print(result.provenance["verification"]["level"])
Session.open defaults to the review route (no_review=False): send then stops at the prompt review, and confirm() moves on, or run(message, confirm=True) accepts each review for you. docs/api.md covers results, exit codes, providers, run settings, closed sessions and the sandbox.
Extensions SDK
Task types, verifiers and model providers are registered through versioned profiles (pdlt.task-type/1, pdlt.verifier/1, pdlt.provider/1). Registration validates a declaration and refuses it with every problem named; PDLt's own built-ins register the same way. check_task_type runs a declaration through real sessions offline before you rely on it. See docs/extensions.md.
REPL quickstart
bash (Linux, macOS):
export OPENROUTER_API_KEY="sk-or-v1-your-key"
pdlt --new-session # no review gates (the default)
pdlt --new-session --review # stop at the prompt and the plan for review
PowerShell (Windows):
$env:OPENROUTER_API_KEY = "sk-or-v1-your-key"
pdlt --new-session
Type a task at the > prompt, for example Count the primes below 1000 and print the count.
Command at the > prompt | Effect |
|---|
/confirm | Accept the prompt or plan under review |
/revise <feedback> | Ask for a revised prompt or plan |
/stop, /cancel | Cancel the task |
/no-review on|off, /fast on|off | Switch review mode |
/help, /quit | Every command; leave |
Every command, flag and mode: docs/repl.md.
Headless runs and the MCP server
Headless runs read tasks from a pipe or a file and exit with a code a script can test:
printf '%s\n' "Count the primes below 1000 and print the count." | pdlt --non-interactive --new-session
echo $?
| Exit | Meaning |
|---|
| 0 | Closed with a result the host established or contract-checked; a direct reply; a published boundary refusal |
| 1 | Cancelled, or failed closed |
| 2 | Stopped at a review gate |
| 3 | Waiting for input the task needs |
| 4 | Harness or provider error (never a task result) |
| 5 | Published, but not established by the host (CLOSED_UNVERIFIED) |
| 130 | Interrupted |
The PowerShell form and file input are in docs/repl.md.
The MCP server (python -m pdl_taskmaster.host.mcp_server, stdio) lets another agent run programs in PDLt's sandbox, have a deliverable checked, and read closed sessions' results with their provenance. Client configuration for each host is on the host pages; tools and resources are in docs/mcp/EXTERNAL_TOOLS.md.
Repository map
| Path | What it is |
|---|
src/pdl_taskmaster/api/ | The library layer every interface uses |
src/pdl_taskmaster/extensions/ | Versioned extension profiles, registries and the conformance kit |
src/pdl_taskmaster/runtime/ | Session engine, workspace, provenance, run settings |
src/pdl_taskmaster/providers/ | Model workers (api_worker.py) and System 1 (sys1/) |
src/pdl_taskmaster/verification/ | Sandbox, confinement backends, output verifier |
src/pdl_taskmaster/host/ | REPL, headless CLI, MCP server |
contracts/ | Hash-pinned operation contracts and the PDL Standard (contracts/standards/) |
tests/ | The offline suite |
run_catalogue.py, graders.py, prompts/ | The evaluation plane: the 112-prompt catalogue and its graders |
docs/ | Documentation; docs/plans/LEDGER.md records every decision |
Reviewers: start with REVIEWER.md. Agents working on the code: AGENTS.md.
Evaluation catalogue
python run_catalogue.py --dry-run lists the 112 prompts (source checkout only). Runs are written outside the repository, to PDLt-Catalogue-Archive beside the checkout, or to $PDLT_CATALOGUE_RUNS if set (catalogue_runs.py). See docs/evaluation.md and docs/benchmarks.md.
License
MIT. See LICENSE and NOTICE.md.
Documentation site
The full documentation is published at paragon-ux.github.io/PDLt-Test, built with Zensical from docs/:
- Overview: what PDLt is, its entry points and its two planes.
- Get started: choosing a host, then Windows, Linux or macOS.
- Use PDLt: Python API, Extensions SDK, REPL and headless runs, MCP server.
- Reference: environment variables, files and failures, providers and models, the OS sandbox.
- Design and evaluation: architecture and routing, the catalogue, benchmarks.
To build or preview it locally from a source checkout:
python -m pip install zensical==0.0.68
zensical build # writes site/
zensical serve # preview at http://localhost:8000
