Building a Reusable Python Prompt Library

Each earlier lesson in this unit introduced one piece of infrastructure in isolation: separating instructions from data (Lesson 1), centralizing reusable instructions (Lesson 2), templating (Lesson 3), an example library (Lesson 4), task-specific patterns (Lessons 5-6), explicit output requirements (Lesson 7), versioning (Lesson 8), and dataset-based testing (Lesson 9). This lesson assembles those pieces into a single, coherent Python package structure — the kind of internal library a real application accumulates once it has more than a couple of prompts to manage, and the natural end point of treating prompts as software artifacts rather than one-off strings.

Why a Dedicated Package, Not Scattered Files

Once an application has more than a handful of prompts, each with its own instructions, templates, examples, and versions, the individual pieces from earlier lessons need a consistent home and a consistent way of being composed. Scattering PromptTemplate instances, ExampleLibrary registrations, and PromptVersion objects across whichever module happens to need them first reproduces the exact duplication and drift problem that motivated centralizing instructions back in Lesson 2 — just at a larger scale. A dedicated package gives every part of the application one place to find, register, and reuse prompt infrastructure.

Suggested Package Layout

app/
  prompts/
    __init__.py
    core.py          # PromptTemplate, PromptVersion, PromptResult
    registry.py       # PromptRegistry
    examples.py       # ExampleLibrary and registered example sets
    tasks/
      __init__.py
      classification.py
      extraction.py
      summarization.py
    tests/
      test_core.py
      test_registry.py
      test_classification.py

This layout keeps the general-purpose building blocks (core.py, registry.py, examples.py) separate from task-specific prompt definitions (tasks/), which mirrors the structure of this unit itself: reusable infrastructure first, task patterns built on top of it second. New prompts for a new task get a new module under tasks/, importing whatever shared infrastructure they need, rather than reinventing template or versioning logic locally.

Assembling the Core Module

core.py holds the foundational data structures introduced across this unit, brought together in one place:

# app/prompts/core.py
from dataclasses import dataclass
from datetime import datetime, timezone
from string import Template

@dataclass(frozen=True)
class PromptTemplate:
    name: str
    template: Template
    required_vars: frozenset[str]

    @classmethod
    def from_string(cls, name: str, text: str, required_vars: set[str]) -> "PromptTemplate":
        return cls(name=name, template=Template(text), required_vars=frozenset(required_vars))

    def render(self, **kwargs) -> str:
        missing = self.required_vars - kwargs.keys()
        if missing:
            raise ValueError(f"Template '{self.name}' missing variables: {sorted(missing)}")
        return self.template.substitute(**kwargs)

@dataclass(frozen=True)
class PromptVersion:
    name: str
    version: str
    instructions: str

@dataclass(frozen=True)
class PromptResult:
    output_text: str
    prompt_name: str
    prompt_version: str
    model: str
    created_at: str

Each class here is exactly what earlier lessons developed independently — PromptTemplate from Lesson 3, PromptVersion and PromptResult from Lesson 8 — now living together as the shared vocabulary the rest of the package builds on. Any task module that needs a versioned prompt or a rendered template imports from here, rather than redefining similar classes locally.

Assembling the Registry Module

# app/prompts/registry.py
from app.prompts.core import PromptVersion

class PromptRegistry:
    def __init__(self):
        self._versions: dict[str, dict[str, PromptVersion]] = {}
        self._current: dict[str, str] = {}

    def register(self, prompt: PromptVersion, make_current: bool = False) -> None:
        self._versions.setdefault(prompt.name, {})[prompt.version] = prompt
        if make_current or prompt.name not in self._current:
            self._current[prompt.name] = prompt.version

    def get(self, name: str, version: str | None = None) -> PromptVersion:
        version = version or self._current[name]
        return self._versions[name][version]

    def set_current(self, name: str, version: str) -> None:
        if version not in self._versions.get(name, {}):
            raise ValueError(f"Unknown version '{version}' for prompt '{name}'")
        self._current[name] = version

# One shared registry instance for the whole application.
registry = PromptRegistry()

Exposing a single registry instance at module scope is a deliberate design choice: it makes the registry a straightforward application-wide singleton, importable from anywhere (from app.prompts.registry import registry), rather than something each caller has to construct and thread through function arguments. For an application large enough to need multiple independent registries (for example, strict test isolation), this can be swapped for explicit dependency injection instead, but a single shared registry is the simpler and usually sufficient default.

A Task Module Built on the Shared Infrastructure

With the core and registry in place, a task-specific module composes them without redefining anything:

# app/prompts/tasks/classification.py
from openai import OpenAI
from app.prompts.core import PromptVersion, PromptResult
from app.prompts.registry import registry
from datetime import datetime, timezone

client = OpenAI()

TICKET_CLASSIFIER_V1 = PromptVersion(
    name="ticket_classifier",
    version="v1",
    instructions=(
        "Classify the support ticket into exactly one of: billing, technical, "
        "account, other. Respond with only the category name, lowercase, "
        "no punctuation."
    ),
)

registry.register(TICKET_CLASSIFIER_V1, make_current=True)

def classify_ticket(ticket_text: str, model: str = "gpt-5.6-terra") -> PromptResult:
    prompt = registry.get("ticket_classifier")
    response = client.responses.create(
        model=model,
        instructions=prompt.instructions,
        input=ticket_text,
    )
    return PromptResult(
        output_text=response.output_text.strip().lower(),
        prompt_name=prompt.name,
        prompt_version=prompt.version,
        model=model,
        created_at=datetime.now(timezone.utc).isoformat(),
    )

Notice what this module does not contain: no redefinition of PromptVersion, no separate versioning logic, no separate result-tracking structure. It registers its own prompt version with the shared registry at import time and calls registry.get to fetch whichever version is currently active, exactly the pattern from Lesson 8. Adding a v2 and rolling it out later means adding a new PromptVersion constant and calling registry.set_current("ticket_classifier", "v2") — no changes to classify_ticket itself are needed, because it already asks the registry for the current version rather than referencing a specific one directly.

Wiring in the Example Library

A task that benefits from few-shot examples (Lesson 4) pulls from the shared ExampleLibrary the same way it pulls from the shared registry:

# app/prompts/examples.py
from dataclasses import dataclass, field

@dataclass(frozen=True)
class Example:
    input_text: str
    output_text: str

@dataclass
class ExampleLibrary:
    _sets: dict[str, list[Example]] = field(default_factory=dict)

    def register(self, task_name: str, examples: list[Example]) -> None:
        self._sets[task_name] = examples

    def format_for_prompt(self, task_name: str, limit: int | None = None) -> str:
        examples = self._sets.get(task_name, [])
        if limit is not None:
            examples = examples[:limit]
        blocks = [f"Input: {ex.input_text}\nOutput: {ex.output_text}" for ex in examples]
        return "\n\n".join(blocks)

example_library = ExampleLibrary()
example_library.register("ticket_classifier", [
    Example("I was charged twice this month.", "billing"),
    Example("The app crashes on upload.", "technical"),
])

# app/prompts/tasks/classification.py (extended)
from app.prompts.examples import example_library
from app.prompts.core import PromptTemplate

TICKET_CLASSIFIER_TEMPLATE = PromptTemplate.from_string(
    name="ticket_classifier_prompt",
    text="Classify the ticket below.\n\nExamples:\n$examples\n\nTicket: $ticket",
    required_vars={"examples", "ticket"},
)

def build_classification_prompt(ticket_text: str) -> str:
    examples_block = example_library.format_for_prompt("ticket_classifier")
    return TICKET_CLASSIFIER_TEMPLATE.render(examples=examples_block, ticket=ticket_text)

Every earlier lesson's contribution is now visible in a single, small module: PromptVersion for versioning, PromptTemplate for combining examples with task input, ExampleLibrary for the example set itself, and PromptRegistry for tracking which version is currently active. None of this logic was reinvented for this specific task — it was assembled from the shared package.

Testing the Assembled Library

The dependency-injection testing pattern used throughout this unit applies at the package level too — test each piece in isolation with fake data, and reserve a small number of true end-to-end calls (using the real API, run manually or in a separate integration suite, not in the regular automated test run) for confirming the pieces genuinely work together:

# app/prompts/tests/test_classification.py
from app.prompts.tasks.classification import build_classification_prompt

def test_build_classification_prompt_includes_examples_and_ticket():
    prompt = build_classification_prompt("My payment failed.")
    assert "My payment failed." in prompt
    assert "charged twice" in prompt  # from the registered example set
    print("PASS: classification prompt includes both examples and the input ticket")

def test_build_classification_prompt_handles_empty_examples():
    from app.prompts.examples import ExampleLibrary
    empty_library = ExampleLibrary()
    from app.prompts.core import PromptTemplate
    template = PromptTemplate.from_string(
        name="t", text="Examples:\n$examples\n\nTicket: $ticket", required_vars={"examples", "ticket"},
    )
    rendered = template.render(examples=empty_library.format_for_prompt("missing_task"), ticket="test")
    assert "Ticket: test" in rendered
    print("PASS: template renders correctly even with an empty example set")

test_build_classification_prompt_includes_examples_and_ticket()
test_build_classification_prompt_handles_empty_examples()

These tests run in milliseconds and require no network access, which means they can run on every commit as part of ordinary continuous integration — the same expectation applied to any other part of an application's test suite. The systematic dataset-based evaluation from Lesson 9, by contrast, does call the real API and is typically run less frequently (before a version rollout, on a schedule, or on demand) precisely because it is slower and consumes API quota; keeping the two kinds of testing separate, at different layers of the package, keeps the fast unit tests fast.

How the Pieces Relate

This table is the shape of the finished library: a small number of general-purpose classes, reused by every task module, each task module adding only what is genuinely task-specific — its instructions text, its examples, and its template. Extending the library to a new task means writing a new file under tasks/, not extending or modifying the shared infrastructure.

Common Mistakes

Redefining versioning, templating, or example-storage logic inside individual task modules. This is the same duplication risk raised throughout this unit, now at the level of infrastructure rather than instruction text — a second PromptVersion-like class defined locally in one task module inevitably drifts from the shared one.

Skipping fast unit tests in favor of only running the slower, API-calling evaluation suite. Structural bugs in template rendering or registry logic are cheaper and faster to catch with dependency-injected unit tests; reserve real API calls for the evaluation layer that actually needs to judge model behavior.

Letting the shared registry become a dumping ground without per-task ownership. As the number of registered prompts grows, task modules should remain responsible for registering and versioning their own prompts at import time, rather than a central file accumulating every prompt definition for every task.

Best Practices

Separate general-purpose prompt infrastructure from task-specific prompt definitions in the package structure. Shared classes belong in a small number of core modules; task modules should only add instructions, templates, and examples specific to their own task.

Expose a single shared registry instance for the application, and have task modules register their own prompt versions at import time. This keeps ownership local to each task while keeping lookup and rollout centralized.