pbt — prompt-build-tool
A data-engineering-inspired prompt orchestration tool for LLMs (think dbt for prompts).
Write modular prompts in Jinja2, chain them into a DAG with ref(), and validate outputs against reality with pbt test—so you can iterate on complex LLM workflows without losing context or rewriting from scratch. (Read more on the philosophy in motivation.md).
Quick start
Install with uv (or pip install prompt-build-tool anthropic):
uv tool install prompt-build-tool --with anthropic
pbt init --provider anthropic # or: openai | gemini
export ANTHROPIC_API_KEY=your_key_here
Edit your .prompt files in models/, then run the pipeline, test expectations, and inspect the run:
pbt run # Execute the prompt DAG
pbt test # Validate outputs against tests/
pbt docs # Generate & open an HTML report of the run
pbt serve # Launch the interactive local UI / HTTP server
Core concepts
1. Models (models/*.prompt)
Each .prompt file is a node in your DAG. Use ref('model_name') to inject the output of an upstream model:
{# models/outline.prompt #}
Based on this topic, create a detailed outline:
{{ ref('topic') }}
2. Model types (config(model_type=...))
Not every node in your pipeline needs to be a standard LLM call. Override model_type at the top of a .prompt file for deterministic steps, formatting, or coding agents:
| Model Type | What it does | Declaration |
|---|---|---|
| LLM (default) | Sends the rendered Jinja prompt to your configured LLM. | Standard .prompt file |
template |
Renders Jinja directly with no LLM call (for reshaping upstream outputs). | {{ config(model_type="template") }} |
execute_python |
Runs rendered template as Python; captures stdout or output variable. |
{{ config(model_type="execute_python") }} |
agent |
Hands the rendered prompt as a task to a coding agent (mini-swe-agent). |
{{ config(model_type="agent", agent_dir="./repo") }} |
(Optional extra model kinds like python_modal, agent_modal, and agent37 are available via pip install "prompt-build-tool[extras]").
3. Tests (tests/*.prompt)
Run pbt test to validate the latest run's outputs against your expectations:
- LLM-as-a-judge: Prompt tests in
tests/*.promptpass when the LLM returns{"results": "pass"}. - Deterministic checks: Compare output fields directly in YAML using
expect(no LLM judge needed).
4. Visualizing & serving (pbt docs & pbt serve)
Instead of digging through terminal logs, inspect and interact with your prompt graph visually:
pbt docsgenerates a self-contained HTML report of every run—showing rendered prompts, model outputs, token usage, and test results across the DAG.pbt servestarts a local server to interactively explore the DAG, edit nodes, and trigger runs via HTTP or the visual UI.
Documentation
| Category | Guides |
|---|---|
| Inputs & Data | Passing variables (promptdata) · Passing files (promptfiles) · RAG inside prompts · Global instructions |
| Workflow & DAG | Grouping models in folders · Map & reduce (each=) · Dynamically skipping models · Models that produce files |
| Testing & Eval | Writing tests · Validation · [Bulk YAML testing & expect](https://www.google.com/search?q=docs/ADVANCED_USAGE.md%23bulk-testing-with-yaml-cases-pbt-test) |
| CLI, UI & API | pbt docs (HTML report) · pbt serve & HTTP server · pbt ls · Python API & callbacks · Token usage |
| Customization | Custom LLM backend (client.py) · [Output format & config()](https://www.google.com/search?q=docs/ADVANCED_USAGE.md%23output-format-config-config) · Agent models · Custom model kinds · Architecture |
1 maintainer
Metadata
1 maintainer
Release files for prompt-build-tool 0.5.11
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 | |
|---|---|---|---|---|
| prompt_build_tool-0.5.11.tar.gz | 185.9 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| prompt_build_tool-0.5.11-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 355.6 kB
Release files / prompt_build_tool-0.5.11.tar.gz
| Download URL | prompt_build_tool-0.5.11.tar.gz |
|---|---|
| Size | 185.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a0317b623dd8564013ce14e7bcb480e69e0ba4c5623332281bcfee19111789f
|
|
BLAKE2b-256 checksum How to use checksums |
23c1b271ba020004d38251f6f9b3c3a7008fda40d1de537c8561642b48bdff18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.0
|
Release files / prompt_build_tool-0.5.11-py3-none-any.whl
| Download URL | prompt_build_tool-0.5.11-py3-none-any.whl |
|---|---|
| Size | 169.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9c61f0c86b6a9a599134ea3948a681cf7af522b49ff7fdc1b07337e534abddd9
|
|
BLAKE2b-256 checksum How to use checksums |
cdab4d57fcaa50c97b21bf48449d30f4233f6b5ad1d59f6cf6197c5f4af440e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.0
|
Security for prompt-build-tool 0.5.11
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.
