Skip to main content

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.

License: MIT Docs Python

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.

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/:

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)

Source distribution for pdl-taskmaster 2.6.0
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)

Table of built distributions (wheels) for pdl-taskmaster 2.6.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page