Skip to main content

prompiler

Spec-to-artefact prompt compiler with multi-vendor adapters and MCP server.

prompiler compiles a declarative specification into deterministic prompt artefacts for Anthropic, OpenAI, Gemini, and Ollama backends, and exposes the compiler over a Model Context Protocol (MCP) server.

Features

  • Declarative specs with composition. Author extraction specs in YAML (spec_version: 2) and share common fields across specs with extends.
  • Deterministic codegen. Compile a spec into a byte-stable prompt, a Pydantic v2 model, and per-backend tool schemas.
  • Multi-vendor adapters. Anthropic, OpenAI, Gemini, and Ollama behind one BackendAdapter contract.
  • Multimodal input. Attach images and other modal parts (ModalContent / modal_parts) alongside the document text.
  • Streaming. Consume incremental results via run_stream (StreamEvent) from backends that support it.
  • Caching. A spec→artefact compile cache and a call→result cache, both on by default; opt out with PROMPILER_DISABLE_CACHE or disable_cache=True.
  • Self-correcting extraction. run / run_sync validate the response against the model and perform one corrective retry on failure.
  • Iterative refinement. prompiler refine --auto-apply runs a bounded propose→apply→evaluate loop against fixtures.
  • Credential management. prompiler login stores OAuth tokens; keychain and OAuth providers resolve vendor credentials.
  • Spec migration. prompiler migrate-spec rewrites a v1 spec to v2 in place (idempotent).
  • MCP server. Expose the compiler over the Model Context Protocol for agent tooling.

Status

The v2 feature set is complete; the project is in its final hardening, docs, and release phase. See docs/PLAN.md for the roadmap and docs/PRD.md for the product spec.

New here? Start with the Tutorial for a cold-install-to-extraction walkthrough, then the Python API reference.

Requirements

  • Python >=3.11,<3.12
  • uv for environment and dependency management

Quickstart

uv sync
uv run prompiler --help

Pre-commit hook (downstream projects)

If your project keeps prompt specs under version control, validate them on every commit with pre-commit. prompiler validate loads and lints each spec, exiting 0 when all specs are valid, 1 on a lint error, and 2 when the path does not exist.

Add a local hook to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: prompiler-validate
        name: validate prompt specs
        entry: prompiler validate
        language: system
        files: ^specs/.*\.ya?ml$
        pass_filenames: false
        args: ["specs/"]

prompiler must be importable in the hook environment — either install it into the same virtualenv pre-commit runs in, or pin it via a managed environment (language: python with additional_dependencies: ["prompiler"]).

Development

Project rules live in docs/RULES.md. The pre-commit gate (ruff, mypy, pytest -m unit with coverage) runs on git commit. See docs/MANUAL_TESTING.md for the test tiers and CLAUDE.md for the agent-facing entry point.

The CLI reference at docs/CLI.md is generated from the Typer app — do not edit it by hand. Regenerate it after changing any command surface:

uv run typer src/prompiler/cli.py utils docs --name prompiler --output docs/CLI.md

License

Apache-2.0. See LICENSE.

Metadata

Release files for prompiler 0.2.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 prompiler 0.2.0
File Size Uploaded Provenance Actions
prompiler-0.2.0.tar.gz 85.8 kB With provenance Details for prompiler-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for prompiler 0.2.0
File Interpreter ABI Platform Actions
prompiler-0.2.0-py3-none-any.whl Python 3 none any Details for prompiler-0.2.0-py3-none-any.whl

Total release size: 206.4 kB

Release files / prompiler-0.2.0.tar.gz

Download URL prompiler-0.2.0.tar.gz
Size 85.8 kB
Tags Source
SHA-256 checksum
How to use checksums
9031c4de7b2727eb96352106256f8cf564e60689482caa5fad7a55b13933dcab
BLAKE2b-256 checksum
How to use checksums
7589e40b7ca7ee932ba4608c426b86f5886ddf8b97cb0014a73b3429e9abdb37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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 Jun 14, 2026.

Transparency log

Release files / prompiler-0.2.0-py3-none-any.whl

Download URL prompiler-0.2.0-py3-none-any.whl
Size 120.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23764f34e43cbf4ac003a21e90abdc577d945520da1434dec79ceb623d31e9a8
BLAKE2b-256 checksum
How to use checksums
82d5527d251cf9d6d884dd9c146bf9e7bc7c2ba6f64f43a50b98248e424e1ad5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

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 Jun 14, 2026.

Transparency log

Security for prompiler 0.2.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 prompiler-0.2.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 Jun 14, 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