PromptManager

Manages prompt templates with loading, caching, and rendering. Supports both Jinja2 (.jinja2) and Markdown (.md) templates.

Quick Example

from mamba_agents.prompts import PromptManager

manager = PromptManager()

# Load and render a template (works with .jinja2 or .md)
prompt = manager.render("system/assistant", name="Helper", tone="friendly")

# Get template object
template = manager.get("system/assistant")
variables = template.get_variables()

# Check template type
print(template.template_type)  # TemplateType.JINJA2 or TemplateType.MARKDOWN

# Register runtime template (Jinja2 syntax)
manager.register("test/greeting", "Hello, {{ name }}!")

Key Methods

Method	Description
get(name, version)	Get a PromptTemplate by name
render(name, **vars)	Render template with variables
render_config(config)	Render from TemplateConfig
register(name, template)	Register template at runtime
list_prompts(category)	List available templates
list_versions(name)	List versions for a template
exists(name, version)	Check if template exists
clear_cache()	Clear the template cache

Caching Behavior

Templates are cached after first load (when enable_caching=True):

from mamba_agents.prompts import PromptManager, PromptConfig

# Caching enabled (default)
manager = PromptManager()
template1 = manager.get("system/assistant")  # Loads from file
template2 = manager.get("system/assistant")  # Returns cached

# Clear cache to reload
manager.clear_cache()

# Disable caching
config = PromptConfig(enable_caching=False)
manager = PromptManager(config=config)

Registered Templates

Runtime-registered templates take precedence over file-based templates:

manager = PromptManager()

# Register for testing
manager.register("system/assistant", "Test prompt: {{ name }}")

# This returns the registered template, not the file
prompt = manager.render("system/assistant", name="Test")

API Reference

PromptManager

PromptManager(config: PromptConfig | None = None)

Manages prompt templates and rendering.

The PromptManager handles loading templates from files, caching, and rendering with variables. It supports versioned templates and runtime registration for testing.

Example

manager = PromptManager() template = manager.get("system/assistant") prompt = template.render(name="Code Helper")

Or render directly

prompt = manager.render("system/assistant", name="Code Helper")

Register a test template

manager.register("test/greeting", "Hello, {{ name }}!") manager.render("test/greeting", name="World") 'Hello, World!'

Initialize the prompt manager.

PARAMETER	DESCRIPTION
config	Prompt configuration. Uses defaults if not provided. TYPE: PromptConfig | None DEFAULT: None

Source code in src/mamba_agents/prompts/manager.py

def __init__(self, config: PromptConfig | None = None) -> None:
    """Initialize the prompt manager.

    Args:
        config: Prompt configuration. Uses defaults if not provided.
    """
    self._config = config or PromptConfig()
    self._env: Environment | None = None
    self._cache: dict[str, PromptTemplate] = {}
    self._registered: dict[str, dict[str, PromptTemplate]] = {}

config property

config: PromptConfig

Get the prompt configuration.

get

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

Get a template by name.

PARAMETER	DESCRIPTION
name	Template name (e.g., "system/assistant"). TYPE: str
version	Template version. Uses default if not specified. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
PromptTemplate	PromptTemplate instance.

RAISES	DESCRIPTION
PromptNotFoundError	If template doesn't exist.

Source code in src/mamba_agents/prompts/manager.py

def get(
    self,
    name: str,
    version: str | None = None,
) -> PromptTemplate:
    """Get a template by name.

    Args:
        name: Template name (e.g., "system/assistant").
        version: Template version. Uses default if not specified.

    Returns:
        PromptTemplate instance.

    Raises:
        PromptNotFoundError: If template doesn't exist.
    """
    version = version or self._config.default_version

    # Check registered templates first (for testing)
    if name in self._registered and version in self._registered[name]:
        return self._registered[name][version]

    # Check cache
    cache_key = f"{version}/{name}"
    if self._config.enable_caching and cache_key in self._cache:
        return self._cache[cache_key]

    # Load from file
    template = self._load_template(name, version)

    # Cache if enabled
    if self._config.enable_caching:
        self._cache[cache_key] = template

    return template

render

render(
    template_name: str,
    version: str | None = None,
    **variables: Any,
) -> str

Render a template with variables.

PARAMETER	DESCRIPTION
template_name	Template name (e.g., "system/assistant"). TYPE: str
version	Template version. Uses default if not specified. TYPE: str | None DEFAULT: None
**variables	Variables to substitute in the template. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
str	Rendered template string.

RAISES	DESCRIPTION
PromptNotFoundError	If template doesn't exist.
TemplateRenderError	If rendering fails.

Source code in src/mamba_agents/prompts/manager.py

def render(
    self,
    template_name: str,
    version: str | None = None,
    **variables: Any,
) -> str:
    """Render a template with variables.

    Args:
        template_name: Template name (e.g., "system/assistant").
        version: Template version. Uses default if not specified.
        **variables: Variables to substitute in the template.

    Returns:
        Rendered template string.

    Raises:
        PromptNotFoundError: If template doesn't exist.
        TemplateRenderError: If rendering fails.
    """
    template = self.get(template_name, version)
    return template.render(**variables)

render_config

render_config(config: TemplateConfig) -> str

Render a template from a TemplateConfig.

PARAMETER	DESCRIPTION
config	Template configuration with name, version, and variables. TYPE: TemplateConfig

RETURNS	DESCRIPTION
str	Rendered template string.

RAISES	DESCRIPTION
PromptNotFoundError	If template doesn't exist.
TemplateRenderError	If rendering fails.

Source code in src/mamba_agents/prompts/manager.py

def render_config(self, config: TemplateConfig) -> str:
    """Render a template from a TemplateConfig.

    Args:
        config: Template configuration with name, version, and variables.

    Returns:
        Rendered template string.

    Raises:
        PromptNotFoundError: If template doesn't exist.
        TemplateRenderError: If rendering fails.
    """
    return self.render(
        template_name=config.name,
        version=config.version,
        **config.variables,
    )

register

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

Register a template programmatically.

This is useful for testing or dynamic template creation.

PARAMETER	DESCRIPTION
name	Template name (e.g., "test/greeting"). TYPE: str
template	Template source string or PromptTemplate instance. TYPE: str | PromptTemplate
version	Template version. Uses default if not specified. TYPE: str | None DEFAULT: None

Example

manager = PromptManager() manager.register("test/hello", "Hello, {{ name }}!") manager.render("test/hello", name="World") 'Hello, World!'

Source code in src/mamba_agents/prompts/manager.py

def register(
    self,
    name: str,
    template: str | PromptTemplate,
    version: str | None = None,
) -> None:
    """Register a template programmatically.

    This is useful for testing or dynamic template creation.

    Args:
        name: Template name (e.g., "test/greeting").
        template: Template source string or PromptTemplate instance.
        version: Template version. Uses default if not specified.

    Example:
        >>> manager = PromptManager()
        >>> manager.register("test/hello", "Hello, {{ name }}!")
        >>> manager.render("test/hello", name="World")
        'Hello, World!'
    """
    version = version or self._config.default_version

    if isinstance(template, str):
        template = PromptTemplate(
            name=name,
            version=version,
            source=template,
        )

    if name not in self._registered:
        self._registered[name] = {}
    self._registered[name][version] = template

list_prompts

list_prompts(category: str | None = None) -> list[str]

List available prompt templates.

PARAMETER	DESCRIPTION
category	Optional category filter (e.g., "system", "workflow"). TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
list[str]	List of template names (deduplicated across extensions).

Source code in src/mamba_agents/prompts/manager.py

def list_prompts(self, category: str | None = None) -> list[str]:
    """List available prompt templates.

    Args:
        category: Optional category filter (e.g., "system", "workflow").

    Returns:
        List of template names (deduplicated across extensions).
    """
    prompts: set[str] = set()

    # Add registered templates
    for name in self._registered:
        if category is None or name.startswith(f"{category}/"):
            prompts.add(name)

    # Add file-based templates (scan all extensions)
    base_dir = Path(self._config.prompts_dir)
    if base_dir.exists():
        for version_dir in base_dir.iterdir():
            if not version_dir.is_dir():
                continue
            for ext in self._config.file_extensions:
                for path in version_dir.rglob(f"*{ext}"):
                    rel_path = path.relative_to(version_dir)
                    name = str(rel_path.with_suffix(""))
                    if category is None or name.startswith(f"{category}/"):
                        prompts.add(name)

    return sorted(prompts)

list_versions

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

List available versions for a template.

PARAMETER	DESCRIPTION
name	Template name (e.g., "system/assistant"). TYPE: str

RETURNS	DESCRIPTION
list[str]	List of version strings.

Source code in src/mamba_agents/prompts/manager.py

def list_versions(self, name: str) -> list[str]:
    """List available versions for a template.

    Args:
        name: Template name (e.g., "system/assistant").

    Returns:
        List of version strings.
    """
    versions: set[str] = set()

    # Check registered versions
    if name in self._registered:
        versions.update(self._registered[name].keys())

    # Check file-based versions (all extensions)
    base_dir = Path(self._config.prompts_dir)
    if base_dir.exists():
        for version_dir in base_dir.iterdir():
            if not version_dir.is_dir():
                continue
            for ext in self._config.file_extensions:
                template_path = version_dir / f"{name}{ext}"
                if template_path.is_file():
                    versions.add(version_dir.name)
                    break  # Found in this version, no need to check other extensions

    return sorted(versions)

clear_cache

clear_cache() -> None

Clear the template cache.

Source code in src/mamba_agents/prompts/manager.py

def clear_cache(self) -> None:
    """Clear the template cache."""
    self._cache.clear()
    self._env = None

exists

exists(name: str, version: str | None = None) -> bool

Check if a template exists.

PARAMETER	DESCRIPTION
name	Template name. TYPE: str
version	Template version. Uses default if not specified. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
bool	True if template exists, False otherwise.

Source code in src/mamba_agents/prompts/manager.py

def exists(self, name: str, version: str | None = None) -> bool:
    """Check if a template exists.

    Args:
        name: Template name.
        version: Template version. Uses default if not specified.

    Returns:
        True if template exists, False otherwise.
    """
    version = version or self._config.default_version

    # Check registered templates
    if name in self._registered and version in self._registered[name]:
        return True

    # Check file system (any extension)
    base_dir = Path(self._config.prompts_dir)
    for ext in self._config.file_extensions:
        template_path = base_dir / version / f"{name}{ext}"
        if template_path.is_file():
            return True

    return False