Configuration & Prompts

HooksSettings

Base settings class for hook configuration, backed by environment variables with HOOKS_ prefix.

Usage

Source

HooksSettings()

build_settings()

Build settings from a conf module via an explicit HooksSettings subclass or auto-inferred fields.

Usage

Source

build_settings(module, prefix="HOOKS_")

Prompt

Fluent builder for structured LLM prompts with system text, XML context sections, and a question.

Usage

Source

Prompt(*, system_text="", contexts=(), ask_text="")

Chain .system(), .context(tag, content), and .ask() to build prompts. str() renders the full prompt with XML-wrapped context blocks. Context content is treated as untrusted data: any occurrence of a block’s own tag delimiters inside its content is entity-escaped at render time, so embedded text can never close the block early and inject instructions outside it.

Parameter Attributes

system_text: str = ""

contexts: tuple[tuple[str, str], …] = ()


ask_text: str = ""

Methods

Name	Description
from_template()	Render text into a system-only prompt, substituting {identifier} placeholders from vars.
load()	Load a prompt from a .md file and render it via from_template().

from_template()

Render text into a system-only prompt, substituting {identifier} placeholders from vars.

Usage

Source

from_template(text, **vars)

Only {identifier} (a brace-wrapped Python identifier) is a placeholder; every other brace is literal. JavaScript object braces ({model: 'sonnet'}), ${shell} interpolations, empty {}, and doubled {x} braces all pass through unchanged — there is no escape sequence and format specs are not placeholders. Substitution is single-pass, so inserted values are never re-scanned for further placeholders.

Parameters

text: str

Template text; {identifier} placeholders are replaced, all other braces stay literal.

**vars: object

Values for the {identifier} placeholders.

Returns

A: Prompt

class:Prompt whose system text is the rendered template.

Raises

KeyError

If an {identifier} placeholder has no matching entry in vars.

load()

Load a prompt from a .md file and render it via from_template().

Usage

Source

load(name, *, base=None, **vars)

Resolution searches directories in order, returning the first existing file: the base directory if given (otherwise a prompts/ directory beside the calling module), then the framework’s bundled captain_hook/prompts/. The file path is <dir>/<name>.md; name may contain / to nest.

Parameters

name: str

Prompt name without the .md suffix; may include / for nesting.

base: str | Path | None = None

Optional directory to search instead of the caller-relative prompts/.

**vars: object

Values for the file’s {identifier} placeholders; every other brace (JS objects, ${...}, {...}) stays literal (see from_template()).

Returns

A: Prompt

class:Prompt whose system text is the rendered file contents.

Raises

FileNotFoundError

If no matching file exists in any searched directory.

KeyError

If the file references an {identifier} placeholder not supplied in **vars.