Merge branch 'main' into feat/audio-input

Signed-off-by: jakelorocco <59755218+jakelorocco@users.noreply.github.com>

Author: jakelorocco

AGENTS.md

@@ -97,6 +97,17 @@ mkdir -p .bob && ln -s ../.agents/skills .bob/skills
 
 Pre-commit runs: ruff, mypy, uv-lock, codespell, license-headers
 
+**Pull request template**: opening a PR fills the body from [`.github/pull_request_template.md`](.github/pull_request_template.md), which ends with four type checkboxes - `Component`, `Requirement`, `Sampling Strategy`, `Tool`. If your PR adds or modifies one of those, check the matching box; the `PR Bot` workflow ([`.github/workflows/pr-update.yml`](.github/workflows/pr-update.yml)) then posts a comment with the type-specific review checklist from `.github/PULL_REQUEST_TEMPLATE/`:
+
+| Checked box | Checklist template |
+|-------------|--------------------|
+| `Component` | `.github/PULL_REQUEST_TEMPLATE/component.md` |
+| `Requirement` | `.github/PULL_REQUEST_TEMPLATE/requirement.md` |
+| `Sampling Strategy` | `.github/PULL_REQUEST_TEMPLATE/sampling.md` |
+| `Tool` | `.github/PULL_REQUEST_TEMPLATE/tool.md` |
+
+This matters when a PR is opened outside the GitHub UI (`gh pr create --body`, from a fork, or by an agent): the template isn't applied automatically. When you open such a PR and it adds or modifies one of the four types, build the body from `.github/pull_request_template.md` with the matching box checked (if relevant) so the bot posts the checklist.
+
 **Review states**: when reviewing a PR, see [CONTRIBUTING.md → Review States](CONTRIBUTING.md#review-states) for when to use `APPROVE` vs `REQUEST CHANGES` vs `COMMENT`.
 
 For AI attribution trailers, see [Section 7 (AI Attribution)](#7-ai-attribution).

docs/docs/advanced/lora-and-alora-adapters.md

@@ -179,8 +179,10 @@ adapter is preferred whenever one is loaded, with three exceptions:
    asking for LLM-as-a-judge regardless of what adapters are loaded.
 3. The adapter is unavailable (e.g. cannot be loaded) — Mellea falls back to
    LLM-as-a-judge automatically. This is the *only* fallback case: if the
-   adapter runs but its output fails schema validation, the error propagates
-   rather than silently falling back.
+   adapter runs but its output fails schema validation, `validate()` does not
+   fall back. Instead it surfaces the schema error on `ValidationResult.error`
+   and fails the check closed (`bool(result)` is `False`), so callers can tell
+   an unparsable adapter response apart from an ordinary "requirement not met".
 
 If you want to force the adapter path even when using `generate_from_context`
 directly (bypassing the normal `validate()` call), use `ALoraRequirement` from

docs/docs/concepts/requirements-system.md

@@ -162,6 +162,7 @@ last output.
 | `score` | `float \| None` | Optional numeric score from your validator. |
 | `thunk` | `ModelOutputThunk \| None` | The model output used, if your validator ran a backend call. |
 | `context` | `Context \| None` | The context snapshot at validation time. |
+| `error` | `Exception \| None` | The exception raised while parsing validator output, if any. When set, `bool(result)` is `False` (fails closed) and `reason` is `None`; lets callers tell an unparsable response apart from an ordinary "requirement not met". |
 
 The `reason` field is the most useful in practice — a clear reason string helps the
 model make a targeted repair rather than regenerating blindly.

docs/examples/aLora/101_example.py

@@ -35,8 +35,9 @@
 # whose prompt asks for a plain "yes"/"no" answer — but the result is still
 # parsed as JSON by requirement_check_to_bool: a plain yes/no reply raises
 # json.JSONDecodeError (it is not JSON), and a JSON reply that doesn't match
-# the schema raises AdapterSchemaMismatchError — either way the error
-# propagates out of validate() instead of returning a failed check. The ALORA
+# the schema raises AdapterSchemaMismatchError — either way validate() surfaces
+# the error on ValidationResult.error and fails the check closed rather than
+# returning an ordinary failed check or propagating the exception. The ALORA
 # type is also load-bearing here: routing only looks up ("alora",), so
 # registering the LORA variant instead would hit the same failure.
 backend.add_adapter(

docs/examples/provider_fields.py

@@ -0,0 +1,72 @@
+# pytest: unit
+"""Emit a provider-specific wire field without a core-type change.
+
+A component author can attach `provider_fields` to a `Message` to declare extra
+keys that Mellea does not model, targeted at a specific provider. The fields are
+merged into the wire message at serialization time. Mellea's known fields always
+win on a collision, and a declaration that names a provider the request never
+reaches raises a `ValueError` (add `"*"` to opt out of that check).
+
+See issue #1565 for the design.
+"""
+
+import pytest
+
+from mellea.helpers.openai_compatible_helpers import message_to_openai_message
+from mellea.stdlib.components import Message
+
+
+def targeted_provider_field() -> dict:
+    """Attach an OpenAI-only `prediction` field and serialize for OpenAI.
+
+    The `"openai"` key matches the OpenAI wire family (openai, litellm, watsonx,
+    huggingface), so the field lands on the wire message for any of them.
+    """
+    msg = Message(
+        "user",
+        "Refactor this function.",
+        provider_fields={"openai": {"prediction": {"type": "content"}}},
+    )
+    wire = message_to_openai_message(msg, provider="openai")
+    assert wire["prediction"] == {"type": "content"}
+    return wire
+
+
+def portable_field_with_wildcard() -> dict:
+    """Use `"*"` to declare a field valid on every backend.
+
+    A `"*"` target never raises on a provider mismatch — it is the author's
+    portability contract that the field is safe to send everywhere.
+    """
+    msg = Message("user", "Hello", provider_fields={"*": {"metadata_tag": "demo"}})
+    wire = message_to_openai_message(msg, provider="openai")
+    assert wire["metadata_tag"] == "demo"
+    return wire
+
+
+def known_fields_always_win() -> dict:
+    """An author key that collides with a Mellea-known field is dropped."""
+    msg = Message(
+        "user",
+        "real content",
+        provider_fields={"openai": {"content": "hijacked", "extra": "kept"}},
+    )
+    wire = message_to_openai_message(msg, provider="openai")
+    assert wire["content"] == "real content"  # Mellea's field wins
+    assert wire["extra"] == "kept"  # non-colliding author field lands
+    return wire
+
+
+def provider_mismatch_raises() -> None:
+    """Targeting a provider the request never reaches is a hard error."""
+    msg = Message("user", "Hi", provider_fields={"ollama": {"keep_alive": "5m"}})
+    with pytest.raises(ValueError):
+        message_to_openai_message(msg, provider="openai")
+
+
+if __name__ == "__main__":
+    print("Targeted field:", targeted_provider_field())
+    print("Wildcard field:", portable_field_with_wildcard())
+    print("Known fields win:", known_fields_always_win())
+    provider_mismatch_raises()
+    print("Provider mismatch raised as expected.")

mellea/backends/adapters/adapter.py

@@ -16,8 +16,11 @@
 
 import abc
 import contextlib
+import hashlib
 import pathlib
 import re
+import shutil
+import tempfile
 import time
 import warnings
 from collections.abc import Callable
@@ -1096,8 +1099,20 @@ def from_hub(
     ) -> list["EmbeddedIntrinsicAdapter"]:
         """Load embedded adapters from a Granite Switch model on Hugging Face Hub.
 
-        Downloads `adapter_index.json` and the `io_configs/` directory, then
-        delegates to :meth:`from_model_directory`.
+        Downloads `adapter_index.json` and the `io_configs/` directory into a
+        persistent self-contained local directory, then delegates to
+        `from_model_directory`.
+
+        `huggingface_hub.snapshot_download`'s default cache-backed snapshot
+        directory populates `io_configs/` with symlinks that resolve into a
+        sibling `blobs/` directory *outside* the snapshot root. That breaks the
+        contract `from_model_directory` expects (a self-contained model
+        directory) and trips its path-escape check. To satisfy that contract,
+        the downloaded snapshot is materialised under the Hugging Face cache
+        into a self-contained directory keyed by its immutable revision, so
+        `io_configs/` contains real files rather than symlinks escaping the
+        directory. This preserves standard Hugging Face Hub cache reuse and
+        offline loading while preventing stale files from a mutable revision.
 
         Args:
             repo_id (str): Hugging Face Hub repository ID
@@ -1118,10 +1133,11 @@ def from_hub(
                 `adapter_index.json` (wrong repo/revision, not a Granite Switch
                 model, or a stale cache).
             ValueError: If no adapters are found (delegated from
-                :meth:`from_model_directory`).
+                `from_model_directory`).
         """
         try:
             import huggingface_hub
+            from huggingface_hub.constants import HF_HUB_CACHE
             from huggingface_hub.errors import GatedRepoError, RepositoryNotFoundError
         except ImportError as e:
             raise ImportError(
@@ -1130,11 +1146,13 @@ def from_hub(
             ) from e
 
         try:
-            local_root = huggingface_hub.snapshot_download(
-                repo_id=repo_id,
-                allow_patterns=["adapter_index.json", "io_configs/**"],
-                cache_dir=cache_dir,
-                revision=revision,
+            snapshot_root = pathlib.Path(
+                huggingface_hub.snapshot_download(
+                    repo_id=repo_id,
+                    allow_patterns=["adapter_index.json", "io_configs/**"],
+                    cache_dir=cache_dir,
+                    revision=revision,
+                )
             )
         except (GatedRepoError, RepositoryNotFoundError) as e:
             auth_hint = (
@@ -1146,7 +1164,57 @@ def from_hub(
             )
             raise PermissionError(auth_hint) from e
 
+        cache_root = pathlib.Path(cache_dir or HF_HUB_CACHE)
+        cache_key = hashlib.sha256(
+            f"{repo_id}\0{snapshot_root.name}".encode()
+        ).hexdigest()
+        local_root = cache_root / "mellea" / "embedded-adapter-configs" / cache_key
+
         try:
+            if not local_root.is_dir():
+                local_root.parent.mkdir(parents=True, exist_ok=True)
+                temporary_dir = pathlib.Path(
+                    tempfile.mkdtemp(dir=local_root.parent, prefix=f"{cache_key}-")
+                )
+                try:
+                    import json as _json
+
+                    index_path = snapshot_root / "adapter_index.json"
+                    with open(index_path, encoding="utf-8") as f:
+                        index = _json.load(f)
+                    shutil.copyfile(index_path, temporary_dir / "adapter_index.json")
+
+                    snapshot_cache_root = snapshot_root.parent.parent.resolve()
+                    for entry in index.get("adapters", []):
+                        io_config_rel = entry.get("io_config")
+                        if io_config_rel is None:
+                            continue
+                        io_config_path = (snapshot_root / io_config_rel).resolve(
+                            strict=True
+                        )
+                        if not io_config_path.is_relative_to(snapshot_cache_root):
+                            raise ValueError(
+                                f"io_config path '{io_config_rel}' escapes "
+                                "the downloaded Hugging Face snapshot"
+                            )
+                        destination = temporary_dir / io_config_rel
+                        destination.parent.mkdir(parents=True, exist_ok=True)
+                        shutil.copyfile(io_config_path, destination)
+
+                    adapters = EmbeddedIntrinsicAdapter.from_model_directory(
+                        temporary_dir, intrinsic_name=intrinsic_name
+                    )
+                    try:
+                        temporary_dir.replace(local_root)
+                    except OSError:
+                        if not local_root.is_dir():
+                            raise
+                    else:
+                        return adapters
+                finally:
+                    if temporary_dir.exists():
+                        shutil.rmtree(temporary_dir)
+
             return EmbeddedIntrinsicAdapter.from_model_directory(
                 local_root, intrinsic_name=intrinsic_name
             )