Prompt Engineering & Templates
Relevant source files
The following files were used as context for generating this wiki page:
The Prompt Engineering & Templates module manages the creation, storage, and rendering of structured instructions sent to Large Language Models (LLMs). It provides a standardized framework for decoupling prompt logic from application code, enabling version control and dynamic variable injection for evaluation tasks.
This system ensures that evaluation workflows remain consistent by enforcing schema validation on templates and providing a centralized repository for prompt assets. Developers use this module to iterate on prompt designs without modifying the underlying evaluation engine.
Core Architecture and Logic
The architecture centers on the PromptEngine, which acts as the primary interface for resolving templates. It fetches raw template strings from the database, parses them for placeholders, and injects runtime data to produce the final string sent to the model.
The diagram shows the flow from a request to a rendered prompt string.
Sources: src/core/prompt_engine.py, src/services/template_service.py
Template Structures
Templates are defined using the PromptTemplate data model. This model includes fields for the raw content, versioning, and metadata required for categorization.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the template version. |
name | String | Human-readable name for the prompt. |
content | Text | The raw string containing Jinja2-style placeholders. |
version | Integer | Incremental version number for tracking changes. |
input_variables | List[String] | List of expected variable names for validation. |
Sources: src/db/models/prompt.py:10-45, src/api/schemas/templates.py:5-20
Implementation Details
Variable Injection and Rendering
The PromptEngine uses a renderer to swap placeholders within a template with actual evaluation data. If a required variable is missing from the input dictionary, the engine raises a MissingVariableError.
# src/core/prompt_engine.py:25-35
def render(self, template_id: str, variables: dict) -> str:
template = self.repository.get_by_id(template_id)
self.validate_variables(template.input_variables, variables)
return template.content.format(**variables)
Sources: src/core/prompt_engine.py:25-35
Versioning Workflow
When a user updates a template, the TemplateService creates a new record in the database rather than overwriting the existing one. This allows evaluation runs to be linked to specific immutable prompt versions.
The sequence diagram illustrates the immutable versioning logic.
Sources: src/services/template_service.py:50-75
API Interfaces
The platform exposes endpoints to manage the lifecycle of prompts. These endpoints allow for CRUD operations and testing of prompt rendering.
POST /v1/templates: Creates a new prompt template.GET /v1/templates/{id}: Retrieves a specific version of a template.POST /v1/templates/render: Previews a rendered prompt without saving it to the database.
Sources: src/api/schemas/templates.py, README.md
Summary
The Prompt Engineering & Templates module provides a robust foundation for managing LLM instructions. By centralizing prompt logic, providing strict versioning, and automating variable injection, the system ensures that evaluation results are reproducible and that prompts can be managed as code assets.