feat(prompts): prompt-management core (proposal 0017)

[chris-colinsky]

Summary

• Implements spec proposal 0017 (prompt-management core) in a new openarmature.prompts subpackage. PR-3 of the five-PR batch following PR-1 (feat(llm): structured output (proposal 0016) #42, proposal 0016) and PR-2 (feat(llm): image content blocks (proposal 0015) #44, proposal 0015).
• PromptManager composes one or more PromptBackends, exposes fetch / render / get, applies the §8 fallback contract (prompt_store_unavailable falls through to the next backend; prompt_not_found stops the chain), and renders templates through Jinja2's StrictUndefined per §7.
• Prompt / PromptResult / PromptGroup Pydantic models match spec §3 / §4 / §9 exactly. PromptGroup requires len(members) >= 2.
• Three canonical errors (PromptNotFound, PromptRenderError, PromptStoreUnavailable) with category-string constants and PROMPT_TRANSIENT_CATEGORIES = frozenset({"prompt_store_unavailable"}) exported in the same shape as openarmature.llm.errors.TRANSIENT_CATEGORIES.
• FilesystemPromptBackend is the minimum local-filesystem reference backend (layout: <root>/<label>/<name>.j2; version derived from the first 12 hex chars of the template's SHA-256 hash).
• Spec §11 observability propagation is wired now (not deferred): with_active_prompt(result) and with_active_prompt_group(group) context managers + current_prompt_result() / current_prompt_group() inspectors. When an LLM call fires inside one of those contexts, the OTel observer surfaces the six normative openarmature.prompt.* attributes on the openarmature.llm.complete span. Nesting is innermost-wins.

What's new

Surface	Change
openarmature.prompts	New subpackage (__init__ re-exports the full public API).
Prompt, PromptResult, PromptGroup	Pydantic models per spec §3 / §4 / §9.
PromptBackend	Runtime-checkable Protocol with a single async fetch(name, label) method.
PromptManager	fetch (with fallback) / render (sync, Jinja2 strict) / get convenience.
FilesystemPromptBackend	Reference impl reading <root>/<label>/<name>.j2 from disk.
PromptNotFound / PromptRenderError / PromptStoreUnavailable	Three canonical error classes.
PROMPT_TRANSIENT_CATEGORIES	Frozenset for retry-middleware classifiers.
compute_template_hash, compute_rendered_hash	SHA-256 helpers with "sha256:" prefix.
with_active_prompt, with_active_prompt_group	Context managers for the §11 propagation mechanism.
OTelObserver	Reads the active prompt / group context vars on LLM-call span start.
jinja2>=3.1	New runtime dependency.
docs/concepts/prompts.md + docs/reference/prompts.md	Walk-through + API reference; nav updated.

Release gate

PR-3 of a five-PR batch (0016 → 0015 → 0017 → 0014 → 0011). Do not tag a release until all five land — the CHANGELOG [Unreleased] Notes section carries the gate from PR-1.

Commits

1. feat(prompts): error classes and category constants
2. feat(prompts): Prompt, PromptResult, PromptGroup types
3. feat(prompts): PromptBackend protocol, PromptManager, jinja2 dep
4. feat(prompts): FilesystemPromptBackend + OTel attribute propagation
5. test(conformance): prompt-management harness and 12 fixtures
6. test(unit): prompts subpackage + OTel attribute propagation
7. docs: prompts concept page, API reference, changelog

Notable implementation details

• Empty-string render boundary wrap. A template that renders cleanly to "" through Jinja2 (e.g., {{ x if x else '' }} with x=None) would construct UserMessage(content="") which Pydantic rejects. The render path catches that ValidationError and re-raises as PromptRenderError per §10's "variable's value not coercible" framing. Surfaces the prompt's identity + the variables + the underlying description.
• OTel attribute propagation included in this PR. Spec §11 marks the attribute set as MAY and the propagation mechanism as implementation-defined; bundling the context-variable + observer hook now keeps the §11 surface discoverable from the moment prompt-management lands. The six attributes (name, version, label, template_hash, rendered_hash, group_name) match the normative §11 list.
• PromptGroup observability is sibling, not replacement. When both with_active_prompt and with_active_prompt_group are active, the per-prompt attributes AND the group_name attribute fire on the span.
• FilesystemPromptBackend reads on every fetch. No caching. A future caching backend MUST preserve the original fetched_at on returned Prompts per §3; the FS backend's docstring notes the rule applies to caching backends even though FS doesn't cache.
• Single-message render output in v1. Spec §6 allows multi-message decomposition (system + user split) when the template language supports it; Jinja2 has no native message-decomposition syntax, so the v1 implementation always emits [UserMessage(content=rendered_text)]. Multi-message split convention deferred to a follow-on if real patterns surface.

Conformance harness extensions

• tests/conformance/harness/prompt_management.py adds typed YAML models for the new fixture shape (backends: + manager: + calls: with target / operation / capture_as, plus per-call and top-level expected blocks for raises / result_equivalence / prompt_group / rendered_hash_equal / rendered_hash_different).
• harness/fixtures.py registers PromptManagementFixture in the discriminated union; the discriminator recognizes top-level backends: (without mock_provider:) as the prompt-management shape.
• harness/loader.py adds prompt-management to CAPABILITIES so test_fixture_parsing.py discovers and parses the 12 new fixtures.
• tests/conformance/test_prompt_management.py parametrizes over the 12 fixtures and drives them against the real PromptManager + an in-process MockPromptBackend. No I/O.

Test plan

• uv run pytest — 602 pass, 79 skipped (up from 73; +6 new docs example snippets in prompts.md), 0 failed.
• uv run pyright — clean.
• uv run ruff check + uv run ruff format — clean.
• uv run --group docs mkdocs build --strict — clean.
• All 12 prompt-management conformance fixtures (001-fetch-success through 012-prompt-result-rendered-hash-stability) pass.
• 25 unit tests under tests/unit/test_prompts.py covering construction, error attribute carriage, hashing determinism, FilesystemPromptBackend disk I/O, context-var propagation, empty-string render boundary wrap, and PromptManager fallback semantics.
• 2 OTel observer tests under tests/unit/test_observability_otel.py covering attribute propagation (both present-with-context and absent-without-context cases).
• Manual: walk docs/concepts/prompts.md end-to-end against mkdocs serve to confirm rendering of code blocks and cross-links.

Pre-1.0 SemVer

Additive change. New subpackage; no existing surface modified except the OTel observer (which gained a no-op-when-no-active-prompt branch). Existing callers see no behavior change. Jinja2 is added to required runtime dependencies — downstream openarmature consumers will pick it up on next pip install -U / uv sync.

[Copilot]

Pull request overview

Implements proposal 0017 (prompt-management core) in a new openarmature.prompts subpackage: typed Prompt / PromptResult / PromptGroup models, a PromptBackend protocol, a PromptManager that composes backends with §8 fallback semantics and renders via Jinja2 StrictUndefined, three canonical error categories, a FilesystemPromptBackend reference implementation, and with_active_prompt / with_active_prompt_group context managers wired into the OTel observer for §11 span-attribute propagation. Adds a conformance harness shape for the 12 new prompt-management fixtures.

Changes:

• New openarmature.prompts subpackage (models, errors, manager, FS backend, hashing helpers, context vars) with jinja2>=3.1 as a new runtime dep.
• OTel observer surfaces six openarmature.prompt.* attributes on openarmature.llm.complete spans when called inside the new context managers.
• Conformance harness extended with PromptManagementFixture, a YAML model layer, and a parametrized test runner using an in-process MockPromptBackend.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/openarmature/prompts/__init__.py	Public API re-exports for the new subpackage.
src/openarmature/prompts/prompt.py	Prompt / PromptResult Pydantic models with extra="forbid".
src/openarmature/prompts/group.py	PromptGroup with N≥2 member validator.
src/openarmature/prompts/errors.py	Three canonical error classes + category constants + transient frozenset.
src/openarmature/prompts/backend.py	Runtime-checkable PromptBackend Protocol.
src/openarmature/prompts/manager.py	Fallback fetch, Jinja2 strict render with empty-string boundary wrap, get convenience.
src/openarmature/prompts/hashing.py	SHA-256 helpers (sha256: prefix) over template source and canonical message JSON.
src/openarmature/prompts/context.py	ContextVar-backed with_active_prompt / with_active_prompt_group.
src/openarmature/prompts/backends/filesystem.py	Reference FS backend; reads <root>/<label>/<name>.j2, derives version from hash prefix.
src/openarmature/prompts/backends/__init__.py	Backend re-export.
src/openarmature/observability/otel/observer.py	LLM-span attribute propagation reading the prompt/group context vars.
pyproject.toml, uv.lock	Add jinja2>=3.1 runtime dependency.
tests/conformance/harness/prompt_management.py	Typed YAML fixture models for the new shape.
tests/conformance/harness/fixtures.py	Discriminated-union registration of PromptManagementFixture.
tests/conformance/harness/loader.py	Adds prompt-management to known capabilities.
tests/conformance/test_prompt_management.py	Fixture runner with MockPromptBackend + per-call / top-level assertions.
tests/unit/test_prompts.py	Unit coverage for types, hashing, FS backend, context vars, manager edge cases.
tests/unit/test_observability_otel.py	OTel-attribute propagation present/absent cases.
docs/concepts/prompts.md, docs/reference/prompts.md, mkdocs.yml	Concept page, API reference, nav update.
CHANGELOG.md	[Unreleased] entries for the prompt-management capability and observability propagation.

Comments suppressed due to low confidence (2)

src/openarmature/prompts/backends/filesystem.py:53

• path.read_text(encoding="utf-8") can raise UnicodeDecodeError if a template file contains invalid UTF-8. UnicodeDecodeError is a subclass of ValueError, not OSError, so it bypasses both except branches and propagates as an uncategorized exception out of fetch(). This means a corrupt prompt file surfaces as a generic Python exception instead of the spec's canonical PromptStoreUnavailable (or arguably PromptNotFound), defeating the §8 fallback chain (PromptManager.fetch won't fall through to the next backend). Consider catching UnicodeDecodeError explicitly (or Exception narrowly around read_text) and mapping to PromptStoreUnavailable.

        try:
            template_source = await asyncio.to_thread(path.read_text, encoding="utf-8")
        except FileNotFoundError as exc:
            raise PromptNotFound(
                f"prompt ({name!r}, {label!r}) not found under {self._root}",
                name=name,
                label=label,
                backend=str(self._root),
            ) from exc
        except OSError as exc:
            raise PromptStoreUnavailable(
                f"filesystem I/O error reading ({name!r}, {label!r}): {exc}"
            ) from exc

src/openarmature/prompts/backends/filesystem.py:49

• name and label are passed into the backend without any path-component validation. If a caller (or upstream code that forwards user input) passes a value containing .. or an absolute path, self._root / label / f"{name}.j2" will silently traverse outside the configured root (Path("/etc") / "passwd" yields /etc/passwd, and .. segments are not normalized away by /). Even though prompt names are typically developer-controlled, this is a reference backend and the public API contract on PromptBackend.fetch doesn't forbid externally-sourced names. Consider rejecting names/labels containing path separators or .. components, or resolving and verifying path.is_relative_to(self._root.resolve()) before reading.

    async def fetch(self, name: str, label: str = "production") -> Prompt:
        path = self._root / label / f"{name}.j2"
        try:
            template_source = await asyncio.to_thread(path.read_text, encoding="utf-8")
        except FileNotFoundError as exc:
            raise PromptNotFound(
                f"prompt ({name!r}, {label!r}) not found under {self._root}",
                name=name,
                label=label,
                backend=str(self._root),
            ) from exc

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 26 changed files in this pull request and generated 4 comments.