fix: CoPilot review round-2 pass on PR #45

- CHANGELOG.md: update 12 → 16 hex chars to match the widened
  FilesystemPromptBackend.version derivation.
- prompt.py: PromptResult.messages gains Field(min_length=1) so
  the spec §4 'Ordered non-empty sequence' mandate is enforced at
  the type boundary, not just by the construction path.
- errors.py: PromptStoreUnavailable gains an optional causes
  list[BaseException] attribute carrying per-backend exceptions
  index-aligned to backends_tried.
- manager.py: aggregate raise populates causes with the
  per-backend exceptions in fallback order, while keeping the
  __cause__ chain pointing at the last unavailable for
  stack-trace continuity.
- manager.py: PromptManager carries a per-instance
  dict[str, jinja2.Template] keyed by template_hash. Render
  consults the cache and only re-parses on miss. Unbounded for
  v1 (typical apps have O(10) prompts; an LRU follow-on can
  land if benchmarks show memory pressure). template_hash is
  content-derived, so cache invalidation is automatic when a
  backend returns updated content.
- test_prompts.py: new tests for empty-messages rejection and
  for the compiled-template cache hit behavior.

Author: chris-colinsky

CHANGELOG.md

@@ -8,7 +8,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Added
 
-- **Prompt-management capability (proposal 0017, introduced in spec v0.15.0).** New `openarmature.prompts` subpackage. `PromptManager` composes one or more `PromptBackend`s, exposes `fetch` / `render` / `get`, applies the §8 fallback semantics (`prompt_store_unavailable` continues to the next backend; `prompt_not_found` stops the chain), and renders templates with Jinja2's `StrictUndefined` per §7. `Prompt` / `PromptResult` / `PromptGroup` are Pydantic models matching spec §3 / §4 / §9. Three error categories (`PromptNotFound`, `PromptRenderError`, `PromptStoreUnavailable`) with `PROMPT_TRANSIENT_CATEGORIES` exported for retry-middleware classifiers. `FilesystemPromptBackend` is the minimum local-filesystem reference backend (layout: `<root>/<label>/<name>.j2`; `version` derived from the first 12 chars of `template_hash`). New runtime dependency: `jinja2>=3.1`.
+- **Prompt-management capability (proposal 0017, introduced in spec v0.15.0).** New `openarmature.prompts` subpackage. `PromptManager` composes one or more `PromptBackend`s, exposes `fetch` / `render` / `get`, applies the §8 fallback semantics (`prompt_store_unavailable` continues to the next backend; `prompt_not_found` stops the chain), and renders templates with Jinja2's `StrictUndefined` per §7. `Prompt` / `PromptResult` / `PromptGroup` are Pydantic models matching spec §3 / §4 / §9. Three error categories (`PromptNotFound`, `PromptRenderError`, `PromptStoreUnavailable`) with `PROMPT_TRANSIENT_CATEGORIES` exported for retry-middleware classifiers. `FilesystemPromptBackend` is the minimum local-filesystem reference backend (layout: `<root>/<label>/<name>.j2`; `version` derived from the first 16 hex chars of `template_hash`). New runtime dependency: `jinja2>=3.1`.
 - **`openarmature.prompts.context` — observability propagation per spec §11.** `with_active_prompt(result)` and `with_active_prompt_group(group)` context managers + `current_prompt_result()` / `current_prompt_group()` inspectors. When the OTel observer is active and an LLM call fires inside `with_active_prompt`, the `openarmature.llm.complete` span carries the normative `openarmature.prompt.*` attributes (`name`, `version`, `label`, `template_hash`, `rendered_hash`, `group_name`). Nesting is innermost-wins.
 - **Image content blocks for user messages (proposal 0015, introduced in spec v0.13.0).** `UserMessage.content` now accepts `str | list[ContentBlock]`. The block surface introduces `TextBlock`, `ImageBlock`, `ImageSourceURL`, `ImageSourceInline`, and the `ContentBlock` / `ImageSource` discriminated unions over the block / source `type` field. `ImageBlock` carries a `media_type` (required for inline sources; ignored for URL sources; typed as `str | None` so callers MAY pass any `image/*` type the bound model supports) and an optional `detail` hint (`"auto"` / `"low"` / `"high"`; `None` default omits the field from the wire so providers apply their own default). System, assistant, and tool messages stay text-string-only; image inputs are user-only in v1.
 - **`OpenAIProvider` content-array wire mapping.** When `UserMessage.content` is a content-block sequence, the wire body uses OpenAI's `content` array per §8.1.1. `TextBlock → {type: "text", text}`. `ImageBlock` with a URL source maps to `{type: "image_url", image_url: {url, detail?}}`. `ImageBlock` with an inline source constructs an RFC 2397 `data:<media_type>;base64,<base64_data>` URI and goes through the same `image_url` entry shape. Inline bytes pass through unchanged — no inspection, transcoding, or re-encoding.

src/openarmature/prompts/errors.py

@@ -96,24 +96,30 @@ class PromptStoreUnavailable(PromptError):
     Transient: the same fetch may succeed when the backend recovers.
     ``PromptManager.fetch`` raises this only after ALL composed
     backends raise it; in that aggregate case ``backends_tried``
-    lists the backends consulted (in order) for operator visibility.
-    The ``__cause__`` chain preserves per-backend failure reasons.
+    lists the backends consulted (in order) and ``causes`` carries
+    the per-backend exceptions index-aligned to ``backends_tried``
+    so operators can distinguish "backend A 503 + backend B 503"
+    from "backend A 503 + backend B OSError". The ``__cause__`` chain
+    still points at the last unavailable for stack-trace continuity.
     """
 
     category = PROMPT_STORE_UNAVAILABLE
 
     name: str | None
     label: str | None
     backends_tried: list[str] | None
+    causes: list[BaseException] | None
 
     def __init__(
         self,
         *args: Any,
         name: str | None = None,
         label: str | None = None,
         backends_tried: list[str] | None = None,
+        causes: list[BaseException] | None = None,
     ) -> None:
         super().__init__(*args)
         self.name = name
         self.label = label
         self.backends_tried = backends_tried
+        self.causes = causes

src/openarmature/prompts/manager.py

@@ -47,6 +47,13 @@ def __init__(self, *backends: PromptBackend) -> None:
         if not backends:
             raise ValueError("PromptManager requires at least one backend")
         self._backends: tuple[PromptBackend, ...] = backends
+        # template_hash → compiled jinja2 Template. Per-manager,
+        # unbounded. Correct by construction: template_hash is
+        # content-derived, so a backend returning updated content
+        # surfaces a fresh hash and a fresh cache entry. An LRU
+        # eviction policy can land if benchmarks ever show memory
+        # pressure; typical apps have O(10) prompts.
+        self._template_cache: dict[str, jinja2.Template] = {}
 
     async def fetch(self, name: str, label: str = "production") -> Prompt:
         """Consult composed backends in order, applying §8 fallback.
@@ -59,28 +66,29 @@ async def fetch(self, name: str, label: str = "production") -> Prompt:
           next. After ALL backends are exhausted with unavailable
           failures, the manager raises ``PromptStoreUnavailable``.
         """
-        last_unavailable: PromptStoreUnavailable | None = None
+        causes: list[BaseException] = []
         for backend in self._backends:
             try:
                 return await backend.fetch(name, label)
             except PromptNotFound:
                 raise
             except PromptStoreUnavailable as exc:
-                last_unavailable = exc
+                causes.append(exc)
                 _log.warning(
                     "prompt backend %r unavailable for (%r, %r); falling back",
                     backend,
                     name,
                     label,
                 )
                 continue
-        assert last_unavailable is not None
+        assert causes
         raise PromptStoreUnavailable(
             f"all prompt backends unavailable for ({name!r}, {label!r})",
             name=name,
             label=label,
             backends_tried=[type(b).__name__ for b in self._backends],
-        ) from last_unavailable
+            causes=list(causes),
+        ) from causes[-1]
 
     def render(
         self,
@@ -103,7 +111,10 @@ def render(
 
         rendered_text: str
         try:
-            template = _RENDER_ENV.from_string(prompt.template)
+            template = self._template_cache.get(prompt.template_hash)
+            if template is None:
+                template = _RENDER_ENV.from_string(prompt.template)
+                self._template_cache[prompt.template_hash] = template
             rendered_text = template.render(**variables)
         except jinja2.UndefinedError as exc:
             raise PromptRenderError(

src/openarmature/prompts/prompt.py

@@ -5,7 +5,7 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 from openarmature.llm.messages import Message
 
@@ -83,7 +83,7 @@ class PromptResult(BaseModel):
     label: str
     template_hash: str
     rendered_hash: str
-    messages: list[Message]
+    messages: list[Message] = Field(min_length=1)
     variables: dict[str, Any]
     fetched_at: datetime
     rendered_at: datetime

tests/unit/test_prompts.py

@@ -149,6 +149,22 @@ def test_prompt_extra_fields_forbidden() -> None:
         )
 
 
+def test_prompt_result_rejects_empty_messages() -> None:
+    prompt = _make_prompt()
+    with pytest.raises(ValueError):
+        PromptResult(
+            name=prompt.name,
+            version=prompt.version,
+            label=prompt.label,
+            template_hash=prompt.template_hash,
+            rendered_hash="sha256:abc",
+            messages=[],
+            variables={},
+            fetched_at=prompt.fetched_at,
+            rendered_at=datetime.now(UTC),
+        )
+
+
 def test_prompt_group_rejects_zero_members() -> None:
     with pytest.raises(ValueError, match="at least two"):
         PromptGroup(group_name="g", members=[])
@@ -375,6 +391,22 @@ async def fetch(self, name: str, label: str = "production") -> Prompt:
     assert second.calls == 0
 
 
+def test_manager_render_caches_compiled_templates_by_hash() -> None:
+    prompt = _make_prompt()
+
+    class _Backend:
+        async def fetch(self, name: str, label: str = "production") -> Prompt:
+            return prompt
+
+    manager = PromptManager(_Backend())
+    manager.render(prompt, {"user": "Alice"})
+    assert prompt.template_hash in manager._template_cache  # noqa: SLF001
+    cached = manager._template_cache[prompt.template_hash]  # noqa: SLF001
+    # Second render reuses the same compiled Template instance.
+    manager.render(prompt, {"user": "Bob"})
+    assert manager._template_cache[prompt.template_hash] is cached  # noqa: SLF001
+
+
 async def test_manager_render_signature_returns_user_message() -> None:
     prompt = _make_prompt()