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_checkedorunverified.
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.
| Host | Sandbox | Setup guide |
|---|---|---|
| Windows 10 or 11 | AppContainer | docs/hosts/windows.md |
| Linux, kernel 5.13 or later | Landlock | docs/hosts/linux.md |
| macOS | Seatbelt | docs/hosts/macos.md |
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.
- Maintainers: releasing to PyPI.
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
Metadata
Release files for pdl-taskmaster 2.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pdl_taskmaster-2.6.0.tar.gz | 1.4 MB | With provenance | Details for pdl_taskmaster-2.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pdl_taskmaster-2.6.0-py3-none-any.whl | Python 3 | none | any | Details for pdl_taskmaster-2.6.0-py3-none-any.whl |
Total release size: 1.7 MB
Release files / pdl_taskmaster-2.6.0.tar.gz
| Download URL | pdl_taskmaster-2.6.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6bbc8ec0b8b08b3578e21403ba1485b33eadbb1689b481fee0aed1d0d64ba7a4
|
|
BLAKE2b-256 checksum How to use checksums |
5083feffed835a9f6a627ea4cb795e699ed0035ff2004f0ba5cc2e34a7de0e07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / pdl_taskmaster-2.6.0-py3-none-any.whl
| Download URL | pdl_taskmaster-2.6.0-py3-none-any.whl |
|---|---|
| Size | 341.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
681e7bc4661c52cf73559d9b5d1816426a00fd7701220b93e3827bf18e6b25b7
|
|
BLAKE2b-256 checksum How to use checksums |
3d52f0957b2d198e7a30827773116e59156f04f9f84882bea45648028f9da9c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logSecurity for pdl-taskmaster 2.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pdl_taskmaster-2.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.