Prompt Module

Prompt management utilities for LLM applications.

This module provides comprehensive prompt engineering tools: - Template engine with variable substitution - Prompt versioning and A/B testing - Few-shot example management - Prompt compression and optimization

kerb.prompt.render_template(template, variables, delimiters=('{{', '}}'), allow_missing=False)[source]

Render a template with variable substitution.

Supports nested variables, conditionals, and loops with simple syntax.

Parameters:

template (str) – Template string with variable placeholders
variables (Dict[str, Any]) – Dictionary of variables to substitute
delimiters (Tuple[str, str]) – Opening and closing delimiters. Defaults to (“{{”, “}}”).
allow_missing (bool) – If True, missing variables are left as-is. If False, raises KeyError. Defaults to False.

Returns:

Rendered template with variables substituted

Return type:

str

Examples

>>> render_template("Hello {{name}}!", {"name": "Alice"})
'Hello Alice!'

>>> render_template("{{greeting}} {{name}}!", {"greeting": "Hi", "name": "Bob"})
'Hi Bob!'

>>> render_template("Value: {value}", {"value": 42}, delimiters=("{", "}"))
'Value: 42'

kerb.prompt.render_template_safe(template, variables, delimiters=('{{', '}}'), default='')[source]

Render a template with safe handling of missing variables.

Missing variables are replaced with the default value instead of raising errors.

Parameters:

template (str) – Template string with variable placeholders
variables (Dict[str, Any]) – Dictionary of variables to substitute
delimiters (Tuple[str, str]) – Opening and closing delimiters. Defaults to (“{{”, “}}”).
default (str) – Default value for missing variables. Defaults to “”.

Returns:

Rendered template with variables substituted

Return type:

str

Examples

>>> render_template_safe("Hello {{name}}!", {})
'Hello !'

>>> render_template_safe("Hello {{name}}!", {}, default="[unknown]")
'Hello [unknown]!'

kerb.prompt.validate_template(template, variables, delimiters=('{{', '}}'))[source]

Validate that all template variables are available.

Parameters:

template (str) – Template string to validate
variables (Dict[str, Any]) – Available variables
delimiters (Tuple[str, str]) – Opening and closing delimiters. Defaults to (“{{”, “}}”).

Returns:

(is_valid, missing_variables)

Return type:

Tuple[bool, List[str]]

Examples

>>> validate_template("Hello {{name}}!", {"name": "Alice"})
(True, [])

>>> validate_template("Hello {{name}}!", {})
(False, ['name'])

kerb.prompt.extract_template_variables(template, delimiters=('{{', '}}'))[source]

Extract all variable names from a template.

Parameters:

template (str) – Template string to analyze
delimiters (Tuple[str, str]) – Opening and closing delimiters. Defaults to (“{{”, “}}”).

Returns:

List of unique variable names found in template

Return type:

List[str]

Examples

>>> extract_template_variables("Hello {{name}}!")
['name']

>>> extract_template_variables("{{greeting}} {{name}}, you are {{age}} years old!")
['greeting', 'name', 'age']

class kerb.prompt.PromptVersion(name, version, template, description='', created_at=<factory>, metadata=<factory>, variables=<factory>)[source]

Bases: object

A versioned prompt with metadata for tracking and comparison.

name

Unique name for this prompt

Type:: str

version

Version identifier (e.g., “1.0”, “v2”, “experimental”)

Type:: str

template

The prompt template

Type:: str

description

Description of this version

Type:: str

created_at

Timestamp of creation

Type:: str

metadata

Additional metadata (performance metrics, etc.)

Type:: Dict[str, Any]

variables

Default variable values

Type:: Dict[str, Any]

name: str

version: str

template: str

description: str = ''

created_at: str

metadata: Dict[str, Any]

variables: Dict[str, Any]

render(variables=None, **kwargs)[source]

Render this prompt version with variables.

Parameters:

variables (Optional[Dict[str, Any]]) – Variables to use for rendering. Will be merged with default variables.
**kwargs – Additional variables as keyword arguments

Returns:

Rendered prompt

Return type:

str

to_dict()[source]

Convert to dictionary representation.

Return type:: Dict[str, Any]

__init__(name, version, template, description='', created_at=<factory>, metadata=<factory>, variables=<factory>)

class kerb.prompt.PromptRegistry[source]

Bases: object

Registry for managing multiple prompt versions and A/B testing.

Enables version tracking, comparison, and selection for prompt experimentation.

__init__()[source]: Initialize an empty prompt registry.

register(prompt)[source]

Register a prompt version.

Parameters:: prompt (PromptVersion) – Prompt version to register
Return type:: None

get(name, version=None)[source]

Retrieve a prompt version.

Parameters:

name (str) – Prompt name
version (Optional[str]) – Version to retrieve. If None, returns latest. Defaults to None.

Returns:

Prompt version if found, None otherwise

Return type:

Optional[PromptVersion]

list_versions(name)[source]

List all versions for a prompt.

Parameters:: name (str) – Prompt name
Returns:: List of version identifiers
Return type:: List[str]

list_prompts()[source]

List all registered prompt names.

Returns:: List of prompt names
Return type:: List[str]

compare(name, versions=None)[source]

Compare versions of a prompt.

Parameters:

name (str) – Prompt name
versions (Optional[List[str]]) – Versions to compare. If None, compares all. Defaults to None.

Returns:

Comparison data including templates, metadata, and differences

Return type:

Dict[str, Any]

select_ab_version(name, strategy='random')[source]

Select a version for A/B testing.

Parameters:

name (str) – Prompt name
strategy (str) – Selection strategy (“random”, “weighted”, “newest”, “oldest”). Defaults to “random”.

Returns:

Selected prompt version

Return type:

Optional[PromptVersion]

kerb.prompt.create_version(name, version, template, description='', metadata=None, variables=None)[source]

Create a new prompt version.

Parameters:

name (str) – Unique name for this prompt
version (str) – Version identifier
template (str) – The prompt template
description (str) – Description of this version. Defaults to “”.
metadata (Optional[Dict[str, Any]]) – Additional metadata. Defaults to None.
variables (Optional[Dict[str, Any]]) – Default variable values. Defaults to None.

Returns:

The created prompt version

Return type:

PromptVersion

Examples

>>> v1 = create_version(
...     name="greeting",
...     version="1.0",
...     template="Hello {{name}}!",
...     description="Simple greeting"
... )

kerb.prompt.register_prompt(prompt)[source]

Register a prompt version in the global registry.

Parameters:: prompt (PromptVersion) – Prompt version to register
Return type:: None

kerb.prompt.get_prompt(name, version=None)[source]

Retrieve a prompt from the global registry.

Parameters:

name (str) – Prompt name
version (Optional[str]) – Version to retrieve. If None, returns latest. Defaults to None.

Returns:

Prompt version if found, None otherwise

Return type:

Optional[PromptVersion]

kerb.prompt.list_versions(name)[source]

List all versions for a prompt in the global registry.

Parameters:: name (str) – Prompt name
Returns:: List of version identifiers
Return type:: List[str]

kerb.prompt.compare_versions(name, versions=None)[source]

Compare versions of a prompt in the global registry.

Parameters:

name (str) – Prompt name
versions (Optional[List[str]]) – Versions to compare. If None, compares all. Defaults to None.

Returns:

Comparison data

Return type:

Dict[str, Any]

kerb.prompt.select_version(name, strategy='random')[source]

Select a version for A/B testing from the global registry.

Parameters:

name (str) – Prompt name
strategy (Union[VersionSelectionStrategy, str]) – Selection strategy (VersionSelectionStrategy enum or string: “random”, “latest”, “best_performing”, “a_b_test”)

Returns:

Selected prompt version

Return type:

Optional[PromptVersion]

Examples

>>> from kerb.core.enums import VersionSelectionStrategy
>>> version = select_version("greeting", strategy=VersionSelectionStrategy.BEST_PERFORMING)

class kerb.prompt.FewShotExample(input, output, metadata=<factory>)[source]

Bases: object

A few-shot example with input and output.

input

Example input

Type:: str

output

Example output

Type:: str

metadata

Additional metadata (category, difficulty, etc.)

Type:: Dict[str, Any]

input: str

output: str

metadata: Dict[str, Any]

to_dict()[source]

Convert to dictionary representation.

Return type:: Dict[str, Any]

format(template='Input: {input}\\nOutput: {output}')[source]

Format the example using a template.

Parameters:: template (str) – Format template. Defaults to “Input: {input}nOutput: {output}”.
Returns:: Formatted example
Return type:: str

__init__(input, output, metadata=<factory>)

class kerb.prompt.ExampleSelector(examples=None)[source]

Bases: object

Manages and selects few-shot examples for prompts.

Supports multiple selection strategies including random, semantic similarity, and diversity-based selection.

__init__(examples=None)[source]

Initialize the example selector.

Parameters:: examples (Optional[List[FewShotExample]]) – Initial examples. Defaults to None.

add(example)[source]

Add an example to the selector.

Parameters:: example (FewShotExample) – Example to add
Return type:: None

select(k=3, strategy=SelectionStrategy.RANDOM, query=None, filter_fn=None)[source]

Select k examples using the specified strategy.

Parameters:

k (int) – Number of examples to select. Defaults to 3.
strategy (Union[str, SelectionStrategy]) – Selection strategy. Defaults to RANDOM.
query (Optional[str]) – Query text for semantic selection. Defaults to None.
filter_fn (Optional[Callable[[FewShotExample], bool]]) – Filter function to apply before selection. Defaults to None.

Returns:

Selected examples

Return type:

List[FewShotExample]

format_examples(examples, template='Input: {input}\\nOutput: {output}', separator='\\n\\n')[source]

Format multiple examples into a single string.

Parameters:

examples (List[FewShotExample]) – Examples to format
template (str) – Format template for each example. Defaults to “Input: {input}nOutput: {output}”.
separator (str) – Separator between examples. Defaults to “nn”.

Returns:

Formatted examples string

Return type:

str

kerb.prompt.create_example(input_text, output_text, metadata=None)[source]

Create a few-shot example.

Parameters:

input_text (str) – Example input
output_text (str) – Example output
metadata (Optional[Dict[str, Any]]) – Additional metadata. Defaults to None.

Returns:

The created example

Return type:

FewShotExample

Examples

>>> ex = create_example(
...     input_text="What is 2+2?",
...     output_text="4",
...     metadata={"difficulty": "easy"}
... )

kerb.prompt.select_examples(examples, k=3, strategy='random', query=None, filter_fn=None)[source]

Select k examples from a list using the specified strategy.

Parameters:

examples (List[FewShotExample]) – Available examples
k (int) – Number of examples to select
strategy (Union[SelectionStrategy, str]) – Selection strategy (SelectionStrategy enum or string: “random”, “similarity”, “diverse”, “recent”, “fixed”)
query (Optional[str]) – Query text for semantic selection
filter_fn (Optional[Callable[[FewShotExample], bool]]) – Filter function

Returns:

Selected examples

Return type:

List[FewShotExample]

Examples

>>> from kerb.core.enums import SelectionStrategy
>>> selected = select_examples(examples, k=3, strategy=SelectionStrategy.SIMILARITY, query="example query")

kerb.prompt.format_examples(examples, template='Input: {input}\\nOutput: {output}', separator='\\n\\n')[source]

Format multiple examples into a single string.

Parameters:

examples (List[FewShotExample]) – Examples to format
template (str) – Format template for each example. Defaults to “Input: {input}nOutput: {output}”.
separator (str) – Separator between examples. Defaults to “nn”.

Returns:

Formatted examples string

Return type:

str

Examples

>>> ex1 = create_example("What is 2+2?", "4")
>>> ex2 = create_example("What is 3+3?", "6")
>>> format_examples([ex1, ex2])
'Input: What is 2+2?\nOutput: 4\n\nInput: What is 3+3?\nOutput: 6'

kerb.prompt.compress_prompt(prompt, max_length=None, strategies=None)[source]

Compress a prompt using multiple optimization strategies.

Parameters:

prompt (str) – Prompt to compress
max_length (Optional[int]) – Target maximum length. If None, applies all strategies without length constraint. Defaults to None.
strategies (Optional[List[str]]) – List of strategies to apply. Options: [“whitespace”, “abbreviations”]. If None, applies all strategies. Defaults to None.

Returns:

Compressed prompt

Return type:

str

Examples

>>> compress_prompt("Hello    world!  This   is   a    test.")
'Hello world! This is a test.'

kerb.prompt.optimize_whitespace(prompt)[source]

Optimize whitespace in a prompt.

Removes excessive spaces, trailing whitespace, and normalizes line breaks.

Parameters:: prompt (str) – Prompt to optimize
Returns:: Prompt with optimized whitespace
Return type:: str

Examples

>>> optimize_whitespace("Hello    world!  \n\n\n  Test")
'Hello world!\n\nTest'

kerb.prompt.analyze_prompt(prompt, tokenizer=None)[source]

Analyze a prompt and return statistics.

Parameters:

prompt (str) – Prompt to analyze
tokenizer (Optional[Any]) – Tokenizer to use for token counting. If None, uses character approximation. Defaults to None.

Returns:

Analysis results including length, word count, line count, etc.

Return type:

Dict[str, Any]

Examples

>>> analyze_prompt("Hello world! This is a test.")
{
    'length': 28,
    'words': 6,
    'lines': 1,
    'sentences': 2,
    'tokens_approx': 7,
    'variables': []
}

Prompt engineering utilities, templates, and chain-of-thought patterns.