Prompt packs¶
A pack is a directory under a root: pack.yaml plus jinja templates. Loading validates the manifest and names the text by its sha, so the stamp beside an output row says exactly which prompt produced it. The packs this example loads live in examples/prompt_pack/packs/.
"""Prompt packs: prompts as versioned files, named by the sha of their text.
A pack is a directory, `<root>/<feature.action>/`, holding `pack.yaml` and its jinja templates.
`prompts.load` validates the manifest and fingerprints the sources; the stamp stored beside each
output row (`{pack, version, sha}`) says which text produced it, so an edited prompt is never
mistaken for the one that was evaluated.
"""
from pathlib import Path
from llm_ports import prompts
ROOT = Path(__file__).with_name("packs")
pack = prompts.load("orders.summarize", ROOT)
print(pack.stamp_str()) # orders.summarize@1.0.0+<sha of the template>
print(pack.render(slots={"count": "how many items", "total": "the order total"}))
# The registry loads every pack strictly; `unevaluated` names the packs whose served text has no
# grade yet. Here nothing was graded, so every pack is due.
served = prompts.served_shas(ROOT)
print(sorted(served))
print(prompts.unevaluated(served, evaluated={}))
# The stamp follows the text, not the version field: an edited template is a new sha.
candidate = pack.source.replace("one sentence", "two sentences")
assert prompts.content_sha([candidate]) != pack.content_sha
A pack has two names. content_sha covers the template text and never changes algorithm; identity covers the manifest bytes and every file the templates can render (templates plus includes), so a version bump, a re-pointed grader or an edited partial moves it (ADR-0026). A template that includes a file the manifest does not list fails at load (list partials in includes as relative paths, e.g. partials/h.j2), and so does a pack file with a carriage return: keep packs LF with * text=auto eol=lf in .gitattributes.
Source: examples/prompt_pack/main.py