Add prompt-management surface refinements (proposal 0033 + wishes 1, 5)

[chris-colinsky]

Summary

Implements proposal 0033 (spec v0.26.0) plus python-side wishes 1 (FilesystemPromptBackend flat layout) and 5 (Jinja Undefined opt-out).

New fields on Prompt and PromptResult:

• sampling: SamplingConfig | None — a RuntimeConfig subclass mirroring the seven declared fields plus extras. Splats directly into provider.complete(config=...) without translation.
• observability_entities: dict[str, Any] | None — spec-normative key langfuse_prompt holds the Langfuse SDK Prompt reference; replaces the implementation-defined metadata placeholder from proposal 0031's v0.23.0.

New LabelResolver primitive at openarmature.prompts.LabelResolver. Three-step fallback: per-name override > default override > spec fallback "production". MappingLabelResolver is the reference impl; the Protocol is open to JSON-file / remote-config implementations.

PromptManager knobs:

• label_resolver=... — optional resolver consulted when fetch()/get() is called without an explicit label.
• jinja_undefined=... — optional Jinja Undefined subclass; default StrictUndefined matches spec §8 (was §7). The render Environment is now per-instance so this knob bites without affecting other managers.

FilesystemPromptBackend knobs:

• layout="per-label" | "flat" — flat reads <root>/<name>.j2 ignoring label; returns the requested label on the Prompt verbatim. Wish 1.
• sampling_source="none" | "per-prompt-sidecar" | "unified" — sidecar adapter for Prompt.sampling per spec §5's informative filesystem conventions.

Import-cycle fix. A latent cycle between openarmature.llm and openarmature.prompts surfaced once prompts/prompt.py imported RuntimeConfig (for the SamplingConfig subclass). Deferred the current_prompt_group / current_prompt_result imports in openai.py to function-local; same behavior, no top-level re-entry.

Spec submodule bumped to v0.26.0; conformance.toml grows entries for proposals 0033 (this PR) and 0034 (PR 4), both not-yet pending the release PR. The fixture-parser defers prompt-management/015 and 016 (the PM-specific harness models the new shapes; the cross-capability parser doesn't) and observability/027-030 (PR 4 territory).

Second of 6 PRs in the v0.10.0 batch. Plan in coord thread 04-python-batched-impl-plan.md; spec greenlit in msg 05.

Test plan

• CI green (lint, format, types, conformance, unit, smoke, agents-md drift)
• Four new prompt-management conformance fixtures pass: 013 (sampling-from-backend), 014 (sampling-absent), 015 (label-resolver-fallback-chain, three managers + multiple captures), 016 (observability_entities-propagation, two cases)
• Six new unit tests pass: jinja_undefined opt-out renders empty, FS flat layout echoes request label, per-prompt sidecar populates sampling, unified prompt_configs.json keys by name, three MappingLabelResolver precedence cases
• All 846 tests pass (104 skipped); python3 scripts/check_conformance_manifest.py exits 0 with 30 accepted proposals / 30 manifest entries

[Copilot]

Pull request overview

Updates the prompt-management Python implementation to match spec v0.26.0 / proposal 0033, adding per-prompt sampling configuration, observability entity propagation, deployment-time label routing, and configurable Jinja undefined behavior.

Changes:

• Add SamplingConfig, Prompt.sampling, and PromptResult.sampling (plus filesystem sidecar/unified config loading).
• Add LabelResolver / MappingLabelResolver and make PromptManager.fetch/get support label resolution when label is omitted.
• Add observability_entities propagation, bump spec pin/version, and adjust conformance harness/tests accordingly.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/test_prompts.py	Adds unit tests for Jinja undefined opt-out, filesystem layouts/sampling, and label resolver precedence.
tests/test_smoke.py	Updates asserted spec version to v0.26.0.
tests/conformance/test_prompt_management.py	Extends conformance runner to handle sampling/observability entities and multi-manager/cases fixture shapes.
tests/conformance/test_fixture_parsing.py	Skips new fixtures not yet modeled by the cross-capability parser.
tests/conformance/harness/prompt_management.py	Updates prompt-management fixture schema for new directive shapes and top-level expected capture assertions.
src/openarmature/prompts/prompt.py	Introduces SamplingConfig and adds sampling + observability_entities fields to Prompt/PromptResult.
src/openarmature/prompts/manager.py	Adds label resolver + per-instance Jinja environment; propagates sampling/observability entities into PromptResult.
src/openarmature/prompts/label_resolver.py	Adds the LabelResolver protocol and MappingLabelResolver reference implementation.
src/openarmature/prompts/backends/filesystem.py	Adds layout and sampling_source options; supports sidecar/unified sampling config.
src/openarmature/prompts/init.py	Exports new prompt-management symbols (SamplingConfig, label resolver types/constants).
src/openarmature/llm/providers/openai.py	Defers prompt context imports to avoid module import cycles.
src/openarmature/AGENTS.md	Updates embedded spec version reference.
src/openarmature/init.py	Bumps __spec_version__ to v0.26.0.
pyproject.toml	Updates tool-level spec_version pin.
docs/concepts/prompts.md	Documents new knobs/fields: jinja_undefined, sampling, label resolver, observability entities.
conformance.toml	Pins spec to v0.26.0 and adds proposal entries 0033/0034 as not-yet.

---

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