Skip to content

API reference

Generated from the apogee-ai-templates source with mkdocstrings. Every symbol below is exported from apogee_ai_templates, so it is part of the supported public surface.

Application

RenderedFile dataclass

Python
RenderedFile(path: str, content: str, executable: bool = False)

path instance-attribute

Python
path: str

content instance-attribute

Python
content: str

executable class-attribute instance-attribute

Python
executable: bool = False

Application · DTOs

BenchDTO dataclass

Python
BenchDTO(renders: int = 1000)

renders class-attribute instance-attribute

Python
renders: int = 1000

RenderDTO dataclass

Python
RenderDTO(template_name: str, variables: dict[str, str] = dict(), renderer: str = 'simple')

template_name instance-attribute

Python
template_name: str

variables class-attribute instance-attribute

Python
variables: dict[str, str] = field(default_factory=dict)

renderer class-attribute instance-attribute

Python
renderer: str = 'simple'

ScaffoldDTO dataclass

Python
ScaffoldDTO(blueprint_code: str, output_dir: str, variables: dict[str, str] = dict(), renderer: str = 'simple')

blueprint_code instance-attribute

Python
blueprint_code: str

output_dir instance-attribute

Python
output_dir: str

variables class-attribute instance-attribute

Python
variables: dict[str, str] = field(default_factory=dict)

renderer class-attribute instance-attribute

Python
renderer: str = 'simple'

Application · Use cases

BenchRenderUseCase

execute async

Python
execute(renders: int) -> dict[str, float]
Source code in apogee_ai_templates/application/use_cases/bench_render_use_case.py
Python
async def execute(self, renders: int) -> dict[str, float]:
    if renders <= 0:
        raise ValueError("renders must be positive")
    renderer = SimpleRenderer()
    ctx = RenderContext(variables={
        "name": "Madson", "product": "apogee", "version": "0.1.0",
    })
    start = time.perf_counter()
    for _ in range(renders):
        renderer.render(_TEMPLATE, ctx)
    elapsed = (time.perf_counter() - start) * 1000.0
    return {
        "renders": float(renders),
        "elapsed_ms": elapsed,
        "renders_per_second": (renders / elapsed * 1000.0) if elapsed > 0 else 0.0,
    }

ListBlueprintsUseCase

Python
ListBlueprintsUseCase(blueprint_repo)
Source code in apogee_ai_templates/application/use_cases/list_templates_use_case.py
Python
def __init__(self, blueprint_repo) -> None:
    self._blueprints = blueprint_repo

execute async

Python
execute() -> list
Source code in apogee_ai_templates/application/use_cases/list_templates_use_case.py
Python
async def execute(self) -> list:
    return list(self._blueprints.list())

ListTemplatesUseCase

Python
ListTemplatesUseCase(template_repo)
Source code in apogee_ai_templates/application/use_cases/list_templates_use_case.py
Python
def __init__(self, template_repo) -> None:
    self._templates = template_repo

execute async

Python
execute() -> list
Source code in apogee_ai_templates/application/use_cases/list_templates_use_case.py
Python
async def execute(self) -> list:
    return list(self._templates.list())

RenderTemplateUseCase

Python
RenderTemplateUseCase(template_repo, renderer)
Source code in apogee_ai_templates/application/use_cases/render_template_use_case.py
Python
def __init__(self, template_repo, renderer) -> None:
    self._templates = template_repo
    self._renderer = renderer

execute async

Python
execute(name: str, context: RenderContext) -> str
Source code in apogee_ai_templates/application/use_cases/render_template_use_case.py
Python
async def execute(self, name: str, context: RenderContext) -> str:
    template = self._templates.get(name)
    for required in template.required_vars:
        if required not in context.variables:
            raise MissingVariableError(required)
    return self._renderer.render(template.body, context)

ScaffoldProjectUseCase

Python
ScaffoldProjectUseCase(blueprint_repo, renderer)

Renders every TemplateFile of a Blueprint into RenderedFiles.

Renders both file paths and bodies through the same renderer so paths can use placeholders like {{project_name}}/main.py.

Source code in apogee_ai_templates/application/use_cases/scaffold_project_use_case.py
Python
def __init__(self, blueprint_repo, renderer) -> None:
    self._blueprints = blueprint_repo
    self._renderer = renderer

execute async

Python
execute(blueprint_code: str, context: RenderContext) -> list[RenderedFile]
Source code in apogee_ai_templates/application/use_cases/scaffold_project_use_case.py
Python
async def execute(
    self, blueprint_code: str, context: RenderContext
) -> list[RenderedFile]:
    blueprint = self._blueprints.get(blueprint_code)
    for required in blueprint.required_vars:
        if required not in context.variables:
            raise MissingVariableError(required)
    out: list[RenderedFile] = []
    for f in blueprint.files:
        rendered_path = self._renderer.render(f.path, context)
        rendered_body = self._renderer.render(f.template, context)
        out.append(RenderedFile(
            path=rendered_path,
            content=rendered_body,
            executable=f.executable,
        ))
    return out

Domain

Blueprint dataclass

Python
Blueprint(code: str, name: str, kind: BlueprintKind = CUSTOM, description: str = '', files: tuple[TemplateFile, ...] = (), required_vars: tuple[str, ...] = (), metadata: dict[str, str] = dict())

code instance-attribute

Python
code: str

name instance-attribute

Python
name: str

kind class-attribute instance-attribute

Python
kind: BlueprintKind = CUSTOM

description class-attribute instance-attribute

Python
description: str = ''

files class-attribute instance-attribute

Python
files: tuple[TemplateFile, ...] = ()

required_vars class-attribute instance-attribute

Python
required_vars: tuple[str, ...] = ()

metadata class-attribute instance-attribute

Python
metadata: dict[str, str] = field(default_factory=dict)

RenderContext dataclass

Python
RenderContext(variables: dict[str, str] = dict(), strict: bool = True)

variables class-attribute instance-attribute

Python
variables: dict[str, str] = field(default_factory=dict)

strict class-attribute instance-attribute

Python
strict: bool = True

get

Python
get(key: str, default: str | None = None) -> str | None
Source code in apogee_ai_templates/domain/value_objects/render_context.py
Python
def get(self, key: str, default: str | None = None) -> str | None:
    return self.variables.get(key, default)

Template dataclass

Python
Template(name: str, body: str, description: str = '', required_vars: tuple[str, ...] = (), metadata: dict[str, str] = dict())

name instance-attribute

Python
name: str

body instance-attribute

Python
body: str

description class-attribute instance-attribute

Python
description: str = ''

required_vars class-attribute instance-attribute

Python
required_vars: tuple[str, ...] = ()

metadata class-attribute instance-attribute

Python
metadata: dict[str, str] = field(default_factory=dict)

TemplateFile dataclass

Python
TemplateFile(path: str, template: str, executable: bool = False)

One file inside a Blueprint — relative path + body template.

path instance-attribute

Python
path: str

template instance-attribute

Python
template: str

executable class-attribute instance-attribute

Python
executable: bool = False

Domain · Enums

BlueprintKind

Bases: str, Enum

AGENT class-attribute instance-attribute

Python
AGENT = 'agent'

RAG_PIPELINE class-attribute instance-attribute

Python
RAG_PIPELINE = 'rag-pipeline'

TOOL class-attribute instance-attribute

Python
TOOL = 'tool'

CHATBOT class-attribute instance-attribute

Python
CHATBOT = 'chatbot'

CUSTOM class-attribute instance-attribute

Python
CUSTOM = 'custom'

RendererKind

Bases: str, Enum

SIMPLE class-attribute instance-attribute

Python
SIMPLE = 'simple'

JINJA class-attribute instance-attribute

Python
JINJA = 'jinja'

Domain · Exceptions

BlueprintNotFoundException

Python
BlueprintNotFoundException(code: str)

Bases: TemplateError

Source code in apogee_ai_templates/domain/exceptions/template_exceptions.py
Python
def __init__(self, code: str) -> None:
    super().__init__(f"Blueprint not found: {code!r}")
    self.code = code

code instance-attribute

Python
code = code

MissingVariableError

Python
MissingVariableError(variable: str)

Bases: TemplateError

Source code in apogee_ai_templates/domain/exceptions/template_exceptions.py
Python
def __init__(self, variable: str) -> None:
    super().__init__(f"Missing template variable: {variable!r}")
    self.variable = variable

variable instance-attribute

Python
variable = variable

TemplateError

Bases: Exception

Base for apogee-ai-templates errors.

TemplateNotFoundException

Python
TemplateNotFoundException(name: str)

Bases: TemplateError

Source code in apogee_ai_templates/domain/exceptions/template_exceptions.py
Python
def __init__(self, name: str) -> None:
    super().__init__(f"Template not found: {name!r}")
    self.name = name

name instance-attribute

Python
name = name

Domain · Protocols (ports)

IBlueprintRepository

Bases: Protocol

register

Python
register(blueprint: Blueprint) -> None
Source code in apogee_ai_templates/domain/services/i_blueprint_repository.py
Python
def register(self, blueprint: Blueprint) -> None: ...

get

Python
get(code: str) -> Blueprint
Source code in apogee_ai_templates/domain/services/i_blueprint_repository.py
Python
def get(self, code: str) -> Blueprint: ...

list

Python
list() -> Iterable[Blueprint]
Source code in apogee_ai_templates/domain/services/i_blueprint_repository.py
Python
def list(self) -> Iterable[Blueprint]: ...

IRenderer

Bases: Protocol

name instance-attribute

Python
name: str

render

Python
render(source: str, context: RenderContext) -> str
Source code in apogee_ai_templates/domain/services/i_renderer.py
Python
def render(self, source: str, context: RenderContext) -> str: ...

ITemplateRepository

Bases: Protocol

register

Python
register(template: Template) -> None
Source code in apogee_ai_templates/domain/services/i_template_repository.py
Python
def register(self, template: Template) -> None: ...

get

Python
get(name: str) -> Template
Source code in apogee_ai_templates/domain/services/i_template_repository.py
Python
def get(self, name: str) -> Template: ...

list

Python
list() -> Iterable[Template]
Source code in apogee_ai_templates/domain/services/i_template_repository.py
Python
def list(self) -> Iterable[Template]: ...

Infrastructure

BlueprintRegistry

Python
BlueprintRegistry(blueprints: Iterable[Blueprint] = ())
Source code in apogee_ai_templates/infrastructure/repositories/blueprint_registry.py
Python
def __init__(self, blueprints: Iterable[Blueprint] = ()) -> None:
    self._blueprints: dict[str, Blueprint] = {b.code: b for b in blueprints}

name class-attribute instance-attribute

Python
name = 'blueprint_registry'

builtin classmethod

Python
builtin() -> 'BlueprintRegistry'
Source code in apogee_ai_templates/infrastructure/repositories/blueprint_registry.py
Python
@classmethod
def builtin(cls) -> "BlueprintRegistry":
    return cls(builtin_blueprints())

register

Python
register(blueprint: Blueprint) -> None
Source code in apogee_ai_templates/infrastructure/repositories/blueprint_registry.py
Python
def register(self, blueprint: Blueprint) -> None:
    self._blueprints[blueprint.code] = blueprint

get

Python
get(code: str) -> Blueprint
Source code in apogee_ai_templates/infrastructure/repositories/blueprint_registry.py
Python
def get(self, code: str) -> Blueprint:
    if code not in self._blueprints:
        raise BlueprintNotFoundException(code)
    return self._blueprints[code]

list

Python
list() -> list[Blueprint]
Source code in apogee_ai_templates/infrastructure/repositories/blueprint_registry.py
Python
def list(self) -> list[Blueprint]:
    return list(self._blueprints.values())

InMemoryTemplateRepository

Python
InMemoryTemplateRepository(templates: Iterable[Template] | None = None)
Source code in apogee_ai_templates/infrastructure/repositories/in_memory_template_repository.py
Python
def __init__(self, templates: Iterable[Template] | None = None) -> None:
    self._templates: dict[str, Template] = {
        t.name: t for t in (templates if templates is not None else _BUILTIN_TEMPLATES)
    }

name class-attribute instance-attribute

Python
name = 'in_memory_template'

builtin classmethod

Python
builtin() -> 'InMemoryTemplateRepository'
Source code in apogee_ai_templates/infrastructure/repositories/in_memory_template_repository.py
Python
@classmethod
def builtin(cls) -> "InMemoryTemplateRepository":
    return cls()

register

Python
register(template: Template) -> None
Source code in apogee_ai_templates/infrastructure/repositories/in_memory_template_repository.py
Python
def register(self, template: Template) -> None:
    self._templates[template.name] = template

get

Python
get(name: str) -> Template
Source code in apogee_ai_templates/infrastructure/repositories/in_memory_template_repository.py
Python
def get(self, name: str) -> Template:
    if name not in self._templates:
        raise TemplateNotFoundException(name)
    return self._templates[name]

list

Python
list() -> list[Template]
Source code in apogee_ai_templates/infrastructure/repositories/in_memory_template_repository.py
Python
def list(self) -> list[Template]:
    return list(self._templates.values())

JinjaRenderer

Python
JinjaRenderer()

Lazy Jinja2 adapter — install via extras=jinja.

Source code in apogee_ai_templates/infrastructure/renderers/jinja_renderer.py
Python
def __init__(self) -> None:
    self._env = None

name class-attribute instance-attribute

Python
name = 'jinja'

render

Python
render(source: str, context: RenderContext) -> str
Source code in apogee_ai_templates/infrastructure/renderers/jinja_renderer.py
Python
def render(self, source: str, context: RenderContext) -> str:
    self._ensure_env()
    try:
        template = self._env.from_string(source)  # type: ignore[union-attr]
        return template.render(**context.variables)
    except Exception as exc:  # pragma: no cover - depends on Jinja
        try:
            from jinja2 import UndefinedError  # type: ignore

            if isinstance(exc, UndefinedError):
                raise MissingVariableError(str(exc)) from exc
        except ImportError:
            pass
        raise TemplateError(str(exc)) from exc

SimpleRenderer

{{var}} substitution. No control flow, no escapes — keeps blueprints readable and deterministic. Strict mode raises MissingVariableError on unknown placeholder; lenient mode leaves it untouched.

name class-attribute instance-attribute

Python
name = 'simple'

render

Python
render(source: str, context: RenderContext) -> str
Source code in apogee_ai_templates/infrastructure/renderers/simple_renderer.py
Python
def render(self, source: str, context: RenderContext) -> str:
    def _resolve(match: re.Match[str]) -> str:
        key = match.group(1)
        value = context.variables.get(key)
        if value is None:
            if context.strict:
                raise MissingVariableError(key)
            return match.group(0)
        return str(value)

    return _PLACEHOLDER.sub(_resolve, source)

builtin_blueprints

Python
builtin_blueprints() -> tuple[Blueprint, ...]
Source code in apogee_ai_templates/infrastructure/blueprints/builtin.py
Python
def builtin_blueprints() -> tuple[Blueprint, ...]:
    return (
        _agent_blueprint(),
        _rag_blueprint(),
        _tool_blueprint(),
        _chatbot_blueprint(),
    )