Prompt Registry¶

brain.patterns.prompts ships a versioned, centralized registry of all pattern prompts. Override any system prompt without touching pattern source code, A/B test prompt versions, and diff changes with a unified view.

Why a prompt registry?¶

Without registry	With registry
Prompts hardcoded in pattern files	Prompts in a single queryable registry
Override requires forking	Override in one line: `registry.override(...)`
No version history	Full version history with diff support
No A/B testing path	Activate any registered version on demand
Prompts not inspectable at runtime	`registry.list()`, `registry.render()`

Quick start¶

from brain.patterns import registry, render

# See all registered prompts
for entry in registry.list():
    print(f"{entry.name:30} v{entry.active_version}")

# Render the active ReAct system prompt
text = render("react.system", tool_names="search, fetch_page")
print(text)

# Override for your use case
registry.override("react.system", "security-v1", """
You are a ReAct security research agent.
Available tools: {tool_names}
Always check for CVEs and cite NIST references when available.
""")

# Diff what changed
print(registry.diff("react.system", "1.0", "security-v1"))

# Roll back instantly
registry.activate("react.system", "1.0")

Built-in prompts¶

All pattern prompts are registered at import time:

Name	Tags	Placeholders
`react.system`	react, system	`tool_names`
`react.user`	react, user	`task`
`plan_execute.plan`	plan_execute, planning	`task`, `max_steps`
`plan_execute.execute`	plan_execute, execution	`task`, `step`, `step_num`, `total_steps`, `previous_results`
`reflexion.generate`	reflexion, generate	`task`
`reflexion.critique`	reflexion, critique	`task`, `answer`
`reflexion.refine`	reflexion, refine	`task`, `answer`, `critique`
`rag.generate`	rag, generate	`task`, `context`
`multi_agent.synthesize`	multi_agent, synthesize	`task`, `sub_results`, `n_agents`
`hitl.resume`	hitl, resume	`task`, `tool_name`, `reason`

@prompt decorator¶

Register prompts declaratively:

from brain.patterns import prompt, registry

@prompt("my_agent.system", version="1.0", tags=["my_agent"])
def _():
    return """
    You are a specialist agent for {domain}.
    Tools: {tool_names}
    Always respond in {language}.
    """

# Render it
text = registry.render("my_agent.system",
    domain="security", tool_names="nmap, shodan", language="English")

Version management¶

from brain.patterns import registry

# Register v2 without activating it
registry.register("react.system", "2.0",
    "v2 prompt with {tool_names}",
    activate=False)

# Inspect all versions
print(registry.versions("react.system"))  # ["1.0", "2.0"]

# Activate v2
registry.activate("react.system", "2.0")

# Activate v1 (rollback)
registry.activate("react.system", "1.0")

Template placeholders¶

pt = registry.get("rag.generate")
print(pt.placeholders())  # ["context", "task"]
print(pt.render(task="What is X?", context="X is ..."))

Missing placeholders are left as {placeholder} rather than raising — so partial renders work:

text = pt.render(task="What is X?")
# context placeholder left as-is: "Context:\n{context}\n\nQuestion: What is X?"

Diff between versions¶

diff = registry.diff("react.system", "1.0", "2.0")
# Returns unified diff string:
# --- react.system@1.0
# +++ react.system@2.0
# @@ ...

A/B testing pattern¶

from brain.patterns import registry, ReActAgent
from brain.providers import LocalEchoProvider

provider = LocalEchoProvider()

def run_with_version(version: str, task: str) -> str:
    registry.activate("react.system", version)
    agent = ReActAgent(tools={"search": lambda q: f"[{q}]"}, provider=provider)
    return agent.run(task).answer

# Run both versions on the same task
result_v1 = run_with_version("1.0", "Explain RAG")
result_v2 = run_with_version("2.0", "Explain RAG")

# Compare quality metrics
print(f"v1 length: {len(result_v1)}, v2 length: {len(result_v2)}")

API Reference¶

brain.patterns.prompts.PromptTemplate `dataclass` ¶

PromptTemplate(name: str, version: str, template: str, description: str = '', tags: list[str] = list())

A versioned, parameterized prompt string.

Parameters in the template use Python str.format_map syntax: {tool_names}, {context}, etc.

Parameters:

Name	Type	Description	Default
`name`	`str`	Dot-separated logical name, e.g. `"react.system"`.	required
`version`	`str`	Semver-style string, e.g. `"1.0"` or `"1.2.3"`.	required
`template`	`str`	The prompt text (may contain `{param}` placeholders).	required
`description`	`str`	Optional human-readable description of this prompt.	`''`
`tags`	`list[str]`	Optional list of labels (`["react", "system"]`).	`list()`

render ¶

render(**kwargs: Any) -> str

Render the template by substituting keyword arguments.

Unknown keys in kwargs are silently ignored. Missing placeholders that have no default produce a KeyError.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Values for `{placeholder}` slots in the template.	`{}`

Returns:

Type	Description
`str`	Rendered string.

Source code in brain/patterns/prompts.py

def render(self, **kwargs: Any) -> str:
    """Render the template by substituting keyword arguments.

    Unknown keys in ``kwargs`` are silently ignored.  Missing placeholders
    that have no default produce a ``KeyError``.

    Args:
        **kwargs: Values for ``{placeholder}`` slots in the template.

    Returns:
        Rendered string.
    """

    # Use a safe mapping that leaves missing keys as-is
    class _SafeMap(dict):
        def __missing__(self, key: str) -> str:
            return "{" + key + "}"

    return self.template.format_map(_SafeMap(**kwargs))

diff ¶

diff(other: 'PromptTemplate') -> str

Return a unified diff between this template and other.

Parameters:

Name	Type	Description	Default
`other`	`'PromptTemplate'`	Another :class:`PromptTemplate` (typically a newer version).	required

Returns:

Type	Description
`str`	Unified diff string (empty string if identical).

Source code in brain/patterns/prompts.py

def diff(self, other: "PromptTemplate") -> str:
    """Return a unified diff between this template and ``other``.

    Args:
        other: Another :class:`PromptTemplate` (typically a newer version).

    Returns:
        Unified diff string (empty string if identical).
    """
    a_lines = self.template.splitlines(keepends=True)
    b_lines = other.template.splitlines(keepends=True)
    result = list(
        difflib.unified_diff(
            a_lines,
            b_lines,
            fromfile=f"{self.name}@{self.version}",
            tofile=f"{other.name}@{other.version}",
        )
    )
    return "".join(result)

placeholders ¶

placeholders() -> list[str]

Return the list of {placeholder} names in the template.

Returns:

Type	Description
`list[str]`	Sorted list of unique placeholder names.

Source code in brain/patterns/prompts.py

def placeholders(self) -> list[str]:
    """Return the list of ``{placeholder}`` names in the template.

    Returns:
        Sorted list of unique placeholder names.
    """
    return sorted(set(re.findall(r"\{(\w+)\}", self.template)))

brain.patterns.prompts.PromptRegistry ¶

PromptRegistry()

Central registry for versioned prompt templates.

All patterns register their core prompts here at import time so that external code can override them without modifying pattern source files.

Thread-safety: reads are safe; concurrent writes should be serialised by the caller (not needed for the typical startup-then-read usage pattern).

Source code in brain/patterns/prompts.py

def __init__(self) -> None:
    self._entries: dict[str, PromptEntry] = {}

register ¶

register(name: str, version: str, template: str, *, description: str = '', tags: list[str] | None = None, activate: bool = True) -> PromptTemplate

Register a prompt template.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name (e.g. `"react.system"`).	required
`version`	`str`	Version string (e.g. `"1.0"`).	required
`template`	`str`	Prompt text with optional `{placeholder}` slots.	required
`description`	`str`	Human-readable purpose description.	`''`
`tags`	`list[str] \| None`	Optional labels.	`None`
`activate`	`bool`	If `True` (default), set this version as active.	`True`

Returns:

Type	Description
`PromptTemplate`	The registered :class:`PromptTemplate`.

Raises:

Type	Description
`ValueError`	If the same name + version is already registered.

Source code in brain/patterns/prompts.py

def register(
    self,
    name: str,
    version: str,
    template: str,
    *,
    description: str = "",
    tags: list[str] | None = None,
    activate: bool = True,
) -> PromptTemplate:
    """Register a prompt template.

    Args:
        name: Logical name (e.g. ``"react.system"``).
        version: Version string (e.g. ``"1.0"``).
        template: Prompt text with optional ``{placeholder}`` slots.
        description: Human-readable purpose description.
        tags: Optional labels.
        activate: If ``True`` (default), set this version as active.

    Returns:
        The registered :class:`PromptTemplate`.

    Raises:
        ValueError: If the same name + version is already registered.
    """
    pt = PromptTemplate(
        name=name,
        version=version,
        template=textwrap.dedent(template).strip(),
        description=description,
        tags=list(tags or []),
    )
    if name not in self._entries:
        self._entries[name] = PromptEntry(name=name)
    entry = self._entries[name]
    if version in entry.versions:
        raise ValueError(f"Prompt {name!r}@{version!r} already registered. Use override().")
    entry.versions[version] = pt
    if activate or not entry.active_version:
        entry.active_version = version
    return pt

override ¶

override(name: str, version: str, template: str, *, description: str = '', tags: list[str] | None = None, activate: bool = True) -> PromptTemplate

Register a new version of an existing prompt (or a brand-new one).

Unlike :meth:register, this never raises on duplicate name+version — it replaces the existing template for that version.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name (e.g. `"react.system"`).	required
`version`	`str`	Version string.	required
`template`	`str`	New prompt text.	required
`description`	`str`	Human-readable purpose.	`''`
`tags`	`list[str] \| None`	Optional labels.	`None`
`activate`	`bool`	If `True` (default), make this version active.	`True`

Returns:

Type	Description
`PromptTemplate`	The new :class:`PromptTemplate`.

Source code in brain/patterns/prompts.py

def override(
    self,
    name: str,
    version: str,
    template: str,
    *,
    description: str = "",
    tags: list[str] | None = None,
    activate: bool = True,
) -> PromptTemplate:
    """Register a new version of an existing prompt (or a brand-new one).

    Unlike :meth:`register`, this never raises on duplicate name+version —
    it replaces the existing template for that version.

    Args:
        name: Logical name (e.g. ``"react.system"``).
        version: Version string.
        template: New prompt text.
        description: Human-readable purpose.
        tags: Optional labels.
        activate: If ``True`` (default), make this version active.

    Returns:
        The new :class:`PromptTemplate`.
    """
    pt = PromptTemplate(
        name=name,
        version=version,
        template=textwrap.dedent(template).strip(),
        description=description,
        tags=list(tags or []),
    )
    if name not in self._entries:
        self._entries[name] = PromptEntry(name=name)
    entry = self._entries[name]
    entry.versions[version] = pt
    if activate:
        entry.active_version = version
    return pt

get ¶

get(name: str, version: str | None = None) -> PromptTemplate

Return a :class:PromptTemplate by name and optional version.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name.	required
`version`	`str \| None`	Specific version; if `None` returns the active version.	`None`

Returns:

Type	Description
`PromptTemplate`	class:`PromptTemplate` instance.

Raises:

Type	Description
`KeyError`	If the name (or version) is not found.

Source code in brain/patterns/prompts.py

def get(self, name: str, version: str | None = None) -> PromptTemplate:
    """Return a :class:`PromptTemplate` by name and optional version.

    Args:
        name: Logical name.
        version: Specific version; if ``None`` returns the active version.

    Returns:
        :class:`PromptTemplate` instance.

    Raises:
        KeyError: If the name (or version) is not found.
    """
    if name not in self._entries:
        raise KeyError(f"No prompt registered as {name!r}")
    entry = self._entries[name]
    ver = version or entry.active_version
    if ver not in entry.versions:
        raise KeyError(f"No version {ver!r} for prompt {name!r}")
    return entry.versions[ver]

render ¶

render(prompt_name: str, version: str | None = None, **kwargs: Any) -> str

Retrieve and render a prompt template.

Parameters:

Name	Type	Description	Default
`prompt_name`	`str`	Logical name.	required
`version`	`str \| None`	Specific version; if `None` uses the active version.	`None`
`**kwargs`	`Any`	Values for `{placeholder}` slots (may include `name`).	`{}`

Returns:

Type	Description
`str`	Rendered prompt string.

Source code in brain/patterns/prompts.py

def render(self, prompt_name: str, version: str | None = None, **kwargs: Any) -> str:
    """Retrieve and render a prompt template.

    Args:
        prompt_name: Logical name.
        version: Specific version; if ``None`` uses the active version.
        **kwargs: Values for ``{placeholder}`` slots (may include ``name``).

    Returns:
        Rendered prompt string.
    """
    return self.get(prompt_name, version).render(**kwargs)

activate ¶

activate(name: str, version: str) -> None

Set the active version for a prompt name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name.	required
`version`	`str`	Version to activate.	required

Raises:

Type	Description
`KeyError`	If name or version is not registered.

Source code in brain/patterns/prompts.py

def activate(self, name: str, version: str) -> None:
    """Set the active version for a prompt name.

    Args:
        name: Logical name.
        version: Version to activate.

    Raises:
        KeyError: If name or version is not registered.
    """
    entry = self._entries.get(name)
    if entry is None:
        raise KeyError(f"No prompt registered as {name!r}")
    if version not in entry.versions:
        raise KeyError(f"No version {version!r} for prompt {name!r}")
    entry.active_version = version

list ¶

list(tag: str | None = None) -> list[PromptEntry]

List all registered prompt entries.

Parameters:

Name	Type	Description	Default
`tag`	`str \| None`	If given, filter to entries whose active template has this tag.	`None`

Returns:

Type	Description
`list[PromptEntry]`	List of :class:`PromptEntry` objects.

Source code in brain/patterns/prompts.py

def list(self, tag: str | None = None) -> list[PromptEntry]:
    """List all registered prompt entries.

    Args:
        tag: If given, filter to entries whose active template has this tag.

    Returns:
        List of :class:`PromptEntry` objects.
    """
    entries = list(self._entries.values())
    if tag:
        entries = [e for e in entries if tag in e.active.tags]
    return entries

versions ¶

versions(name: str) -> list[str]

Return all registered versions for a prompt name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name.	required

Returns:

Type	Description
`list[str]`	List of version strings in registration order.

Source code in brain/patterns/prompts.py

def versions(self, name: str) -> list[str]:
    """Return all registered versions for a prompt name.

    Args:
        name: Logical name.

    Returns:
        List of version strings in registration order.
    """
    if name not in self._entries:
        raise KeyError(f"No prompt registered as {name!r}")
    return list(self._entries[name].versions.keys())

diff ¶

diff(name: str, version_a: str, version_b: str) -> str

Return a unified diff between two versions of a prompt.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name.	required
`version_a`	`str`	Earlier version.	required
`version_b`	`str`	Later version.	required

Returns:

Type	Description
`str`	Unified diff string (empty if identical).

Source code in brain/patterns/prompts.py

def diff(self, name: str, version_a: str, version_b: str) -> str:
    """Return a unified diff between two versions of a prompt.

    Args:
        name: Logical name.
        version_a: Earlier version.
        version_b: Later version.

    Returns:
        Unified diff string (empty if identical).
    """
    a = self.get(name, version_a)
    b = self.get(name, version_b)
    return a.diff(b)

names ¶

names() -> list[str]

Return all registered prompt names.

Source code in brain/patterns/prompts.py

def names(self) -> list[str]:
    """Return all registered prompt names."""
    return list(self._entries.keys())

brain.patterns.prompts.prompt ¶

prompt(name: str, version: str = '1.0', *, description: str = '', tags: list[str] | None = None, activate: bool = True) -> Callable[[Callable[..., str]], PromptTemplate]

Decorator that registers a function's return value as a prompt template.

The decorated function is called once at decoration time (with no arguments) to produce the template string, then replaced by the resulting :class:PromptTemplate in the module namespace.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name (e.g. `"react.system"`).	required
`version`	`str`	Version string (default: `"1.0"`).	`'1.0'`
`description`	`str`	Human-readable purpose.	`''`
`tags`	`list[str] \| None`	Optional labels.	`None`
`activate`	`bool`	If `True` (default), make this version active.	`True`

Returns:

Name	Type	Description
`A`	`Callable[[Callable[..., str]], PromptTemplate]`	class:`PromptTemplate` instance (replaces the decorated function).

Example::

@prompt("react.system", version="1.0", tags=["react"])
def _():
    return """
    You are a ReAct agent.
    Available tools: {tool_names}
    """

Source code in brain/patterns/prompts.py

def prompt(
    name: str,
    version: str = "1.0",
    *,
    description: str = "",
    tags: list[str] | None = None,
    activate: bool = True,
) -> Callable[[Callable[..., str]], PromptTemplate]:
    """Decorator that registers a function's return value as a prompt template.

    The decorated function is called **once** at decoration time (with no
    arguments) to produce the template string, then replaced by the resulting
    :class:`PromptTemplate` in the module namespace.

    Args:
        name: Logical name (e.g. ``"react.system"``).
        version: Version string (default: ``"1.0"``).
        description: Human-readable purpose.
        tags: Optional labels.
        activate: If ``True`` (default), make this version active.

    Returns:
        A :class:`PromptTemplate` instance (replaces the decorated function).

    Example::

        @prompt("react.system", version="1.0", tags=["react"])
        def _():
            return \"\"\"
            You are a ReAct agent.
            Available tools: {tool_names}
            \"\"\"
    """

    def decorator(fn: Callable[..., str]) -> PromptTemplate:
        template_text = fn()
        return registry.register(
            name=name,
            version=version,
            template=template_text,
            description=description or (fn.__doc__ or ""),
            tags=list(tags or []),
            activate=activate,
        )

    return decorator

brain.patterns.prompts.render ¶

render(prompt_name: str, version: str | None = None, **kwargs: Any) -> str

Module-level shortcut for :meth:PromptRegistry.render.

Parameters:

Name	Type	Description	Default
`prompt_name`	`str`	Logical name.	required
`version`	`str \| None`	Specific version; if `None` uses the active version.	`None`
`**kwargs`	`Any`	Placeholder values (may include `name`).	`{}`

Returns:

Type	Description
`str`	Rendered prompt string.

Source code in brain/patterns/prompts.py

def render(prompt_name: str, version: str | None = None, **kwargs: Any) -> str:
    """Module-level shortcut for :meth:`PromptRegistry.render`.

    Args:
        prompt_name: Logical name.
        version: Specific version; if ``None`` uses the active version.
        **kwargs: Placeholder values (may include ``name``).

    Returns:
        Rendered prompt string.
    """
    return registry.render(prompt_name, version, **kwargs)

Prompt Registry¶

Why a prompt registry?¶

Quick start¶

Built-in prompts¶

@prompt decorator¶

Version management¶

Template placeholders¶

Diff between versions¶

A/B testing pattern¶

API Reference¶

brain.patterns.prompts.PromptTemplate dataclass ¶

render ¶

diff ¶

placeholders ¶

brain.patterns.prompts.PromptRegistry ¶

register ¶

override ¶

get ¶

render ¶

activate ¶

list ¶

versions ¶

diff ¶

names ¶

brain.patterns.prompts.prompt ¶

brain.patterns.prompts.render ¶

brain.patterns.prompts.PromptTemplate `dataclass` ¶