friday-framework-runtime 0.1.0a0__tar.gz → 0.1.0a2__tar.gz

{friday_framework_runtime-0.1.0a0 → friday_framework_runtime-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: friday-framework-runtime
-Version: 0.1.0a0
+Version: 0.1.0a2
 Summary: Headless runtime kernel for the Friday Agent Framework
 Project-URL: Homepage, https://github.com/CIChuck/agent-framework
 Project-URL: Repository, https://github.com/CIChuck/agent-framework
@@ -10,12 +10,13 @@ Project-URL: Source, https://github.com/CIChuck/agent-framework/tree/main/packag
 Author: Friday Team
 License-Expression: MIT
 Requires-Python: >=3.10
-Requires-Dist: friday-framework-agent==0.1.0a0
-Requires-Dist: friday-framework-core==0.1.0a0
-Requires-Dist: friday-framework-llm==0.1.0a0
-Requires-Dist: friday-framework-memory==0.1.0a0
-Requires-Dist: friday-framework-telemetry==0.1.0a0
-Requires-Dist: friday-framework-transcript==0.1.0a0
+Requires-Dist: friday-framework-agent==0.1.0a2
+Requires-Dist: friday-framework-core==0.1.0a2
+Requires-Dist: friday-framework-llm==0.1.0a2
+Requires-Dist: friday-framework-mcp==0.1.0a2
+Requires-Dist: friday-framework-memory==0.1.0a2
+Requires-Dist: friday-framework-telemetry==0.1.0a2
+Requires-Dist: friday-framework-transcript==0.1.0a2
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'

{friday_framework_runtime-0.1.0a0 → friday_framework_runtime-0.1.0a2}/pyproject.toml

@@ -1,18 +1,19 @@
 [project]
 name = "friday-framework-runtime"
-version = "0.1.0a0"
+version = "0.1.0a2"
 description = "Headless runtime kernel for the Friday Agent Framework"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 authors = [{ name = "Friday Team" }]
 dependencies = [
-    "friday-framework-core==0.1.0a0",
-    "friday-framework-memory==0.1.0a0",
-    "friday-framework-llm==0.1.0a0",
-    "friday-framework-telemetry==0.1.0a0",
-    "friday-framework-agent==0.1.0a0",
-    "friday-framework-transcript==0.1.0a0",
+    "friday-framework-core==0.1.0a2",
+    "friday-framework-memory==0.1.0a2",
+    "friday-framework-llm==0.1.0a2",
+    "friday-framework-telemetry==0.1.0a2",
+    "friday-framework-agent==0.1.0a2",
+    "friday-framework-transcript==0.1.0a2",
+    "friday-framework-mcp==0.1.0a2",
 ]
 
 [project.urls]
@@ -47,3 +48,4 @@ friday-framework-llm = { workspace = true }
 friday-framework-telemetry = { workspace = true }
 friday-framework-agent = { workspace = true }
 friday-framework-transcript = { workspace = true }
+friday-framework-mcp = { workspace = true }

{friday_framework_runtime-0.1.0a0 → friday_framework_runtime-0.1.0a2}/src/friday_runtime/config.py

@@ -14,9 +14,20 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal, cast
 
-import yaml  # type: ignore[import-untyped]
+import yaml
+from friday_llm import (
+    ChatServiceBinding,
+    EmbeddingServiceBinding,
+    EmbeddingServiceSpec,
+    LLMServiceSpec,
+    ModelLibrary,
+    resolve_chat_service,
+    resolve_embedding_service,
+)
 from friday_mcp.config import MCPConfig
 
+from friday_runtime.model_library import load_model_library
+
 
 def _coerce_bool(value: str) -> bool:
     return value.strip().lower() in {"1", "true", "yes", "on"}
@@ -265,7 +276,7 @@ class LLMServiceConfig:
 @dataclass(frozen=True)
 class LLMPoolConfig:
     default_service: str
-    services: dict[str, LLMServiceConfig]
+    services: dict[str, LLMServiceConfig | ChatServiceBinding]
 
 
 @dataclass(frozen=True)
@@ -307,7 +318,7 @@ class EmbeddingServiceConfig:
 @dataclass(frozen=True)
 class EmbeddingPoolConfig:
     default_service: str
-    services: dict[str, EmbeddingServiceConfig]
+    services: dict[str, EmbeddingServiceConfig | EmbeddingServiceBinding]
 
 
 @dataclass(frozen=True)
@@ -373,15 +384,26 @@ class RuntimeConfig:
     llm_api_key: str | None = None
     llm_api_base: str | None = None
     llm_pool_default_service: str = "default"
-    llm_pool_services: dict[str, LLMServiceConfig] = field(default_factory=dict)
+    llm_pool_services: dict[str, LLMServiceConfig | ChatServiceBinding] = field(
+        default_factory=dict
+    )
+    llm_service_specs: dict[str, LLMServiceSpec] = field(default_factory=dict)
 
     # Embedding Configuration
     embedding_model: str = "text-embedding-3-small"
     embedding_pool_default_service: str = "default"
-    embedding_pool_services: dict[str, EmbeddingServiceConfig] = field(
+    embedding_pool_services: dict[
+        str,
+        EmbeddingServiceConfig | EmbeddingServiceBinding,
+    ] = field(default_factory=dict)
+    embedding_service_specs: dict[str, EmbeddingServiceSpec] = field(
         default_factory=dict
     )
 
+    # Canonical model-library configuration
+    model_library_path: str | None = None
+    model_library: ModelLibrary | None = None
+
     # Prompting Configuration
     prompting_base_system_prompt: str | None = None
 
@@ -482,28 +504,54 @@ class RuntimeConfig:
 
         if self.llm_pool_default_service not in self.llm_pool_services:
             raise ValueError("llm_pool.default_service must reference a configured service")
+        for name, service in self.llm_pool_services.items():
+            if isinstance(service, ChatServiceBinding) and name not in self.llm_service_specs:
+                raise ValueError(
+                    f"canonical llm service {name!r} has no resolved service spec"
+                )
 
         self.embedding_pool_services = {
             name: self._coerce_embedding_service_config(service)
             for name, service in self.embedding_pool_services.items()
         }
         if not self.embedding_pool_services:
-            default_llm_service = self.get_llm_service_config()
-            self.embedding_pool_services = {
-                self.embedding_pool_default_service: EmbeddingServiceConfig(
-                    provider=default_llm_service.provider,
-                    model=self.embedding_model,
-                    api_key=default_llm_service.api_key,
-                    api_base=default_llm_service.api_base,
+            default_llm_service = self.llm_pool_services[
+                self.llm_pool_default_service
+            ]
+            if isinstance(default_llm_service, LLMServiceConfig):
+                self.embedding_pool_services = {
+                    self.embedding_pool_default_service: EmbeddingServiceConfig(
+                        provider=default_llm_service.provider,
+                        model=self.embedding_model,
+                        api_key=default_llm_service.api_key,
+                        api_base=default_llm_service.api_base,
+                    )
+                }
+            else:
+                raise ValueError(
+                    "canonical model-library configuration requires an explicit "
+                    "embedding_pool service"
                 )
-            }
 
         if self.embedding_pool_default_service not in self.embedding_pool_services:
             raise ValueError(
                 "embedding_pool.default_service must reference a configured service"
             )
 
-        self.embedding_model = self.get_embedding_service_config().model
+        default_embedding = self.embedding_pool_services[
+            self.embedding_pool_default_service
+        ]
+        if isinstance(default_embedding, EmbeddingServiceConfig):
+            self.embedding_model = default_embedding.model
+        else:
+            try:
+                self.embedding_model = self.embedding_service_specs[
+                    self.embedding_pool_default_service
+                ].model
+            except KeyError as error:
+                raise ValueError(
+                    "canonical default embedding service has no resolved service spec"
+                ) from error
 
         if self.memory_extraction_llm_service is None:
             self.memory_extraction_llm_service = self.llm_pool_default_service
@@ -530,20 +578,32 @@ class RuntimeConfig:
         self.validate_transcript_path()
 
     @staticmethod
-    def _coerce_service_config(value: LLMServiceConfig | Mapping[str, Any]) -> LLMServiceConfig:
+    def _coerce_service_config(
+        value: LLMServiceConfig | ChatServiceBinding | Mapping[str, Any],
+    ) -> LLMServiceConfig | ChatServiceBinding:
         if isinstance(value, LLMServiceConfig):
             return value
+        if isinstance(value, ChatServiceBinding):
+            return value
         if isinstance(value, Mapping):
+            if "profile" in value:
+                return ChatServiceBinding.model_validate(value)
             return LLMServiceConfig.from_dict(value)
         raise ValueError("llm_pool.services entries must be objects")
 
     @staticmethod
     def _coerce_embedding_service_config(
-        value: EmbeddingServiceConfig | Mapping[str, Any]
-    ) -> EmbeddingServiceConfig:
+        value: EmbeddingServiceConfig
+        | EmbeddingServiceBinding
+        | Mapping[str, Any],
+    ) -> EmbeddingServiceConfig | EmbeddingServiceBinding:
         if isinstance(value, EmbeddingServiceConfig):
             return value
+        if isinstance(value, EmbeddingServiceBinding):
+            return value
         if isinstance(value, Mapping):
+            if "profile" in value:
+                return EmbeddingServiceBinding.model_validate(value)
             return EmbeddingServiceConfig.from_dict(value)
         raise ValueError("embedding_pool.services entries must be objects")
 
@@ -648,9 +708,12 @@ class RuntimeConfig:
     def get_llm_service_config(self, service_name: str | None = None) -> LLMServiceConfig:
         selected = service_name or self.llm_pool_default_service
         try:
-            return self.llm_pool_services[selected]
+            service = self.llm_pool_services[selected]
         except KeyError as exc:
             raise ValueError(f"Unknown llm service: {selected}") from exc
+        if not isinstance(service, LLMServiceConfig):
+            raise ValueError(f"LLM service {selected!r} uses a canonical profile")
+        return service
 
     def get_embedding_service_config(
         self,
@@ -658,9 +721,14 @@ class RuntimeConfig:
     ) -> EmbeddingServiceConfig:
         selected = service_name or self.embedding_pool_default_service
         try:
-            return self.embedding_pool_services[selected]
+            service = self.embedding_pool_services[selected]
         except KeyError as exc:
             raise ValueError(f"Unknown embedding service: {selected}") from exc
+        if not isinstance(service, EmbeddingServiceConfig):
+            raise ValueError(
+                f"Embedding service {selected!r} uses a canonical profile"
+            )
+        return service
 
     def validate_runtime_roots(self) -> None:
         """
@@ -808,6 +876,12 @@ class RuntimeConfig:
         if yaml_path is not None:
             yaml_data = cls._load_yaml(pathlib_path=Path(yaml_path))
             cls._deep_merge(merged, yaml_data)
+            for pool_name in ("llm_pool", "embedding_pool"):
+                yaml_pool = yaml_data.get(pool_name)
+                if isinstance(yaml_pool, Mapping) and "services" in yaml_pool:
+                    cast(dict[str, Any], merged[pool_name])["services"] = dict(
+                        cast(Mapping[str, Any], yaml_pool["services"])
+                    )
 
         allow_env = yaml_path is None or bool(
             merged["config_policy"]["allow_env_override"]
@@ -818,7 +892,63 @@ class RuntimeConfig:
         if overrides:
             cls._apply_flat_overrides(merged, overrides)
 
-        return cls(**cls._nested_to_flat_kwargs(merged))
+        flat = cls._nested_to_flat_kwargs(merged)
+        canonical_llm = {
+            name: service
+            for name, service in cast(
+                dict[str, LLMServiceConfig | ChatServiceBinding],
+                flat["llm_pool_services"],
+            ).items()
+            if isinstance(service, ChatServiceBinding)
+        }
+        canonical_embeddings = {
+            name: service
+            for name, service in cast(
+                dict[str, EmbeddingServiceConfig | EmbeddingServiceBinding],
+                flat["embedding_pool_services"],
+            ).items()
+            if isinstance(service, EmbeddingServiceBinding)
+        }
+        model_library_section = cast(
+            Mapping[str, Any],
+            merged.get("model_library", {}),
+        )
+        configured_catalog_path = model_library_section.get("path")
+        if canonical_llm or canonical_embeddings:
+            if yaml_path is None or not isinstance(configured_catalog_path, str):
+                raise ValueError(
+                    "canonical service bindings require model_library.path in a "
+                    "Runtime YAML file"
+                )
+            loaded = load_model_library(
+                configured_catalog_path,
+                runtime_config_path=yaml_path,
+                environment=env_map,
+                allow_env_override=allow_env,
+            )
+            flat["model_library_path"] = str(loaded.path)
+            flat["model_library"] = loaded.library
+            flat["llm_service_specs"] = {
+                name: resolve_chat_service(loaded.library, binding, env_map)
+                for name, binding in canonical_llm.items()
+            }
+            flat["embedding_service_specs"] = {
+                name: resolve_embedding_service(loaded.library, binding, env_map)
+                for name, binding in canonical_embeddings.items()
+            }
+        elif configured_catalog_path is not None:
+            if yaml_path is None or not isinstance(configured_catalog_path, str):
+                raise ValueError("model_library.path must be a string in Runtime YAML")
+            loaded = load_model_library(
+                configured_catalog_path,
+                runtime_config_path=yaml_path,
+                environment=env_map,
+                allow_env_override=allow_env,
+            )
+            flat["model_library_path"] = str(loaded.path)
+            flat["model_library"] = loaded.library
+
+        return cls(**flat)
 
     @classmethod
     def _default_source_data(cls) -> dict[str, Any]:
@@ -832,6 +962,7 @@ class RuntimeConfig:
                 "workflow_mode": "canonical",
                 "unknown_key_policy": "fail",
             },
+            "model_library": {"path": None},
             "llm": {
                 "provider": "openai",
                 "model": "gpt-4",
@@ -1122,6 +1253,7 @@ class RuntimeConfig:
     @classmethod
     def _validate_yaml_keys(cls, payload: Mapping[str, Any]) -> None:
         allowed_top_level = {
+            "model_library",
             "llm_pool",
             "llm",
             "embedding_pool",
@@ -1143,6 +1275,7 @@ class RuntimeConfig:
             raise ValueError(f"Unknown runtime config keys: {sorted(unknown_top)}")
 
         section_keys: dict[str, set[str]] = {
+            "model_library": {"path"},
             "llm": {"provider", "model", "api_key", "api_base"},
             "embedding": {"model"},
             "prompting": {"base_system_prompt"},
@@ -1199,6 +1332,12 @@ class RuntimeConfig:
             if not isinstance(role_bindings, dict):
                 raise ValueError("agents.role_bindings must be an object")
 
+        model_library = payload.get("model_library", {})
+        if isinstance(model_library, dict):
+            path_value = model_library.get("path")
+            if path_value is not None and not isinstance(path_value, str):
+                raise ValueError("model_library.path must be a string")
+
         tools = payload.get("tools", {})
         if isinstance(tools, dict):
             providers = tools.get("providers")
@@ -1269,11 +1408,28 @@ class RuntimeConfig:
             services = llm_pool["services"]
             if not isinstance(services, dict):
                 raise ValueError("llm_pool.services must be an object")
-            allowed_service_keys = {"provider", "model", "api_key", "api_base", "resilience"}
+            allowed_legacy_service_keys = {
+                "provider",
+                "model",
+                "api_key",
+                "api_base",
+                "resilience",
+            }
+            allowed_profile_service_keys = {
+                "profile",
+                "credential",
+                "resilience_overrides",
+                "generation_overrides",
+            }
             allowed_resilience_keys = {"timeout_seconds", "max_retries"}
             for service_name, config in services.items():
                 if not isinstance(config, dict):
                     raise ValueError(f"llm_pool.services.{service_name} must be an object")
+                allowed_service_keys = (
+                    allowed_profile_service_keys
+                    if "profile" in config
+                    else allowed_legacy_service_keys
+                )
                 unknown_service = set(config) - allowed_service_keys
                 if unknown_service:
                     raise ValueError(
@@ -1298,13 +1454,29 @@ class RuntimeConfig:
             services = embedding_pool["services"]
             if not isinstance(services, dict):
                 raise ValueError("embedding_pool.services must be an object")
-            allowed_service_keys = {"provider", "model", "api_key", "api_base", "resilience"}
+            allowed_legacy_service_keys = {
+                "provider",
+                "model",
+                "api_key",
+                "api_base",
+                "resilience",
+            }
+            allowed_profile_service_keys = {
+                "profile",
+                "credential",
+                "resilience_overrides",
+            }
             allowed_resilience_keys = {"timeout_seconds", "max_retries"}
             for service_name, config in services.items():
                 if not isinstance(config, dict):
                     raise ValueError(
                         f"embedding_pool.services.{service_name} must be an object"
                     )
+                allowed_service_keys = (
+                    allowed_profile_service_keys
+                    if "profile" in config
+                    else allowed_legacy_service_keys
+                )
                 unknown_service = set(config) - allowed_service_keys
                 if unknown_service:
                     raise ValueError(
@@ -1545,14 +1717,18 @@ class RuntimeConfig:
             "llm_api_base": data["llm"].get("api_base"),
             "llm_pool_default_service": default_service_name,
             "llm_pool_services": {
-                name: LLMServiceConfig.from_dict(cast(Mapping[str, Any], config))
+                name: cls._coerce_service_config(
+                    cast(Mapping[str, Any], config)
+                )
                 for name, config in llm_services.items()
             },
             "embedding_pool_default_service": embedding_pool_data.get(
                 "default_service", "default"
             ),
             "embedding_pool_services": {
-                name: EmbeddingServiceConfig.from_dict(cast(Mapping[str, Any], config))
+                name: cls._coerce_embedding_service_config(
+                    cast(Mapping[str, Any], config)
+                )
                 for name, config in embedding_services.items()
             },
             "embedding_model": data["embedding"]["model"],

{friday_framework_runtime-0.1.0a0 → friday_framework_runtime-0.1.0a2}/src/friday_runtime/di.py

@@ -42,7 +42,11 @@ from friday_memory import (
 )
 from friday_transcript import SQLiteTranscriptStore
 
-from friday_runtime.config import RuntimeConfig
+from friday_runtime.config import (
+    EmbeddingServiceConfig,
+    LLMServiceConfig,
+    RuntimeConfig,
+)
 from friday_runtime.tool_loading import register_runtime_tools
 
 logger = logging.getLogger(__name__)
@@ -136,49 +140,78 @@ class DIContainer:
         """Create LLM and embedding services."""
         self.llm_pool = {}
         for service_name, service_config in self._config.llm_pool.services.items():
-            self.llm_pool[service_name] = LiteLLMService(
-                model_name=service_config.model,
-                api_key=service_config.api_key,
-                api_base=service_config.api_base,
-                telemetry=self.telemetry,
-                resilience=ResilienceConfig(
-                    max_retries=service_config.resilience.max_retries,
-                    timeout_seconds=float(service_config.resilience.timeout_seconds),
-                ),
-            )
+            chat_spec = self._config.llm_service_specs.get(service_name)
+            if chat_spec is not None:
+                self.llm_pool[service_name] = LiteLLMService.from_spec(
+                    chat_spec,
+                    telemetry=self.telemetry,
+                )
+            else:
+                if not isinstance(service_config, LLMServiceConfig):
+                    raise RuntimeError(
+                        f"LLM service {service_name!r} has no resolved specification"
+                    )
+                self.llm_pool[service_name] = LiteLLMService(
+                    model_name=service_config.model,
+                    api_key=service_config.api_key,
+                    api_base=service_config.api_base,
+                    telemetry=self.telemetry,
+                    resilience=ResilienceConfig(
+                        max_retries=service_config.resilience.max_retries,
+                        timeout_seconds=float(
+                            service_config.resilience.timeout_seconds
+                        ),
+                    ),
+                )
 
         self.llm = self.llm_pool[self._config.llm_pool.default_service]
-        default_service = self._config.get_llm_service_config()
 
         self.embedding_pool = {}
         for (
             service_name,
             embedding_service_config,
         ) in self._config.embedding_pool.services.items():
-            self.embedding_pool[service_name] = LiteLLMEmbeddingService(
-                model_name=embedding_service_config.model,
-                api_key=embedding_service_config.api_key,
-                api_base=embedding_service_config.api_base,
-                telemetry=self.telemetry,
-                resilience=ResilienceConfig(
-                    max_retries=embedding_service_config.resilience.max_retries,
-                    timeout_seconds=float(
-                        embedding_service_config.resilience.timeout_seconds
+            embedding_spec = self._config.embedding_service_specs.get(service_name)
+            if embedding_spec is not None:
+                self.embedding_pool[service_name] = (
+                    LiteLLMEmbeddingService.from_spec(
+                        embedding_spec,
+                        telemetry=self.telemetry,
+                    )
+                )
+            else:
+                if not isinstance(
+                    embedding_service_config,
+                    EmbeddingServiceConfig,
+                ):
+                    raise RuntimeError(
+                        f"Embedding service {service_name!r} has no resolved "
+                        "specification"
+                    )
+                self.embedding_pool[service_name] = LiteLLMEmbeddingService(
+                    model_name=embedding_service_config.model,
+                    api_key=embedding_service_config.api_key,
+                    api_base=embedding_service_config.api_base,
+                    telemetry=self.telemetry,
+                    resilience=ResilienceConfig(
+                        max_retries=(
+                            embedding_service_config.resilience.max_retries
+                        ),
+                        timeout_seconds=float(
+                            embedding_service_config.resilience.timeout_seconds
+                        ),
                     ),
-                ),
-            )
+                )
 
         self.embeddings = self.embedding_pool[self._config.embedding_pool.default_service]
-        default_embedding_service = self._config.get_embedding_service_config()
-
         logger.info(
             "LLM pool configured with default service '%s' (%s) across %d services; "
             "embedding pool default '%s' (%s) across %d services",
             self._config.llm_pool.default_service,
-            default_service.model,
+            self.llm.model,
             len(self.llm_pool),
             self._config.embedding_pool.default_service,
-            default_embedding_service.model,
+            self.embeddings.model,
             len(self.embedding_pool),
         )
 

friday_framework_runtime-0.1.0a2/src/friday_runtime/model_library.py

@@ -0,0 +1,172 @@
+"""Strict local-file loading for Friday LLM model libraries."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import yaml
+from friday_llm import ModelLibrary
+
+MAX_MODEL_LIBRARY_BYTES = 1024 * 1024
+MAX_MODEL_LIBRARY_DEPTH = 12
+MAX_MODEL_LIBRARY_NODES = 10_000
+MAX_MODEL_LIBRARY_STRING = 4096
+
+
+class ModelLibraryLoadError(ValueError):
+    """Raised when a model-library file violates Runtime loading policy."""
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedModelLibrary:
+    """Validated catalog and the canonical path used to load it."""
+
+    path: Path
+    library: ModelLibrary
+
+
+class _StrictLoader(yaml.SafeLoader):
+    """Safe YAML loader that rejects duplicate mapping keys."""
+
+    def construct_mapping(
+        self,
+        node: yaml.MappingNode,
+        deep: bool = False,
+    ) -> dict[object, object]:
+        seen: set[object] = set()
+        for key_node, _ in node.value:
+            if key_node.tag == "tag:yaml.org,2002:merge":
+                raise ModelLibraryLoadError("YAML merge keys are not allowed")
+            key = self.construct_object(key_node, deep=False)
+            try:
+                duplicate = key in seen
+            except TypeError as error:
+                raise ModelLibraryLoadError("mapping keys must be scalar") from error
+            if duplicate:
+                raise ModelLibraryLoadError(f"duplicate YAML mapping key: {key!r}")
+            seen.add(key)
+        return super().construct_mapping(node, deep=deep)
+
+
+def load_model_library(
+    configured_path: str,
+    *,
+    runtime_config_path: str | Path,
+    environment: Mapping[str, str],
+    allow_env_override: bool,
+) -> LoadedModelLibrary:
+    """Load one bounded local model library relative to its Runtime YAML."""
+
+    selected_path = configured_path
+    if allow_env_override:
+        override = environment.get("FRIDAY_MODELS_CONFIG")
+        if override is not None and override.strip():
+            selected_path = override
+    resolved_path = _resolve_catalog_path(
+        selected_path,
+        runtime_config_path=Path(runtime_config_path),
+    )
+    try:
+        file_size = resolved_path.stat().st_size
+    except OSError as error:
+        raise ModelLibraryLoadError(
+            f"unable to inspect model library: {resolved_path}"
+        ) from error
+    if file_size > MAX_MODEL_LIBRARY_BYTES:
+        raise ModelLibraryLoadError(
+            f"model library exceeds {MAX_MODEL_LIBRARY_BYTES} bytes"
+        )
+    try:
+        document = resolved_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        raise ModelLibraryLoadError(
+            f"unable to read model library: {resolved_path}"
+        ) from error
+    _reject_yaml_references(document)
+    try:
+        payload = yaml.load(document, Loader=_StrictLoader)
+    except ModelLibraryLoadError:
+        raise
+    except yaml.YAMLError as error:
+        raise ModelLibraryLoadError("invalid model-library YAML") from error
+    if not isinstance(payload, dict):
+        raise ModelLibraryLoadError("model library must be a YAML mapping")
+    _validate_structure_bounds(payload)
+    try:
+        library = ModelLibrary.model_validate(payload)
+    except ValueError as error:
+        raise ModelLibraryLoadError("invalid model-library schema") from error
+    return LoadedModelLibrary(path=resolved_path, library=library)
+
+
+def _resolve_catalog_path(
+    configured_path: str,
+    *,
+    runtime_config_path: Path,
+) -> Path:
+    if not configured_path.strip():
+        raise ModelLibraryLoadError("model_library.path must be non-empty")
+    parsed = urlsplit(configured_path)
+    if parsed.scheme or parsed.netloc:
+        raise ModelLibraryLoadError("model_library.path must be a local file path")
+    raw_path = Path(configured_path).expanduser()
+    candidate = (
+        raw_path
+        if raw_path.is_absolute()
+        else runtime_config_path.expanduser().resolve().parent / raw_path
+    )
+    try:
+        resolved = candidate.resolve(strict=True)
+    except OSError as error:
+        raise ModelLibraryLoadError(
+            f"model library does not exist: {candidate}"
+        ) from error
+    if not resolved.is_file():
+        raise ModelLibraryLoadError(
+            f"model library is not a regular file: {resolved}"
+        )
+    return resolved
+
+
+def _reject_yaml_references(document: str) -> None:
+    try:
+        events = yaml.parse(document, Loader=yaml.SafeLoader)
+        for event in events:
+            if isinstance(event, yaml.AliasEvent) or getattr(event, "anchor", None):
+                raise ModelLibraryLoadError(
+                    "YAML anchors and aliases are not allowed"
+                )
+    except ModelLibraryLoadError:
+        raise
+    except yaml.YAMLError as error:
+        raise ModelLibraryLoadError("invalid model-library YAML") from error
+
+
+def _validate_structure_bounds(payload: dict[object, object]) -> None:
+    nodes = 0
+    pending: list[tuple[object, int]] = [(payload, 1)]
+    while pending:
+        value, depth = pending.pop()
+        nodes += 1
+        if nodes > MAX_MODEL_LIBRARY_NODES:
+            raise ModelLibraryLoadError(
+                f"model library exceeds {MAX_MODEL_LIBRARY_NODES} YAML nodes"
+            )
+        if depth > MAX_MODEL_LIBRARY_DEPTH:
+            raise ModelLibraryLoadError(
+                f"model library exceeds YAML depth {MAX_MODEL_LIBRARY_DEPTH}"
+            )
+        if isinstance(value, str) and len(value) > MAX_MODEL_LIBRARY_STRING:
+            raise ModelLibraryLoadError(
+                f"model library string exceeds {MAX_MODEL_LIBRARY_STRING} characters"
+            )
+        if isinstance(value, dict):
+            for key, child in value.items():
+                pending.append((key, depth + 1))
+                pending.append((child, depth + 1))
+        elif isinstance(value, list):
+            for child in value:
+                pending.append((child, depth + 1))

friday_framework_runtime-0.1.0a2/tests_runtime/test_model_library.py

@@ -0,0 +1,192 @@
+"""Runtime model-library file-policy tests."""
+
+from pathlib import Path
+
+import pytest
+from friday_core.profiles import MemoryProfile
+from friday_runtime.config import RuntimeConfig
+from friday_runtime.di import DIContainer
+from friday_runtime.model_library import ModelLibraryLoadError, load_model_library
+
+
+def _write_catalog(path: Path, *, marker: str = "local") -> None:
+    path.write_text(
+        f"""
+schema: friday.model-library/v1
+endpoints:
+  {marker}:
+    api_base: http://127.0.0.1:1234/v1
+    provider: openai_compatible
+profiles:
+  chat:
+    kind: chat
+    endpoint: {marker}
+    dialect: openai_chat_completions
+    model: openai/qwen3.8
+    model_target:
+      model_id: qwen3.8
+      family: qwen3_8
+      revision: exact
+""".strip()
+    )
+
+
+def test_relative_catalog_path_is_resolved_against_runtime_yaml(tmp_path: Path) -> None:
+    config_dir = tmp_path / "configuration"
+    config_dir.mkdir()
+    runtime_path = config_dir / "config.yaml"
+    runtime_path.write_text("model_library:\n  path: models-config.yaml\n")
+    catalog_path = config_dir / "models-config.yaml"
+    _write_catalog(catalog_path)
+
+    loaded = load_model_library(
+        "models-config.yaml",
+        runtime_config_path=runtime_path,
+        environment={},
+        allow_env_override=False,
+    )
+
+    assert loaded.path == catalog_path.resolve()
+    assert "chat" in loaded.library.profiles
+
+
+def test_environment_path_override_requires_policy_opt_in(tmp_path: Path) -> None:
+    runtime_path = tmp_path / "config.yaml"
+    default_path = tmp_path / "default.yaml"
+    override_path = tmp_path / "override.yaml"
+    _write_catalog(default_path, marker="default")
+    _write_catalog(override_path, marker="override")
+    environment = {"FRIDAY_MODELS_CONFIG": str(override_path)}
+
+    disabled = load_model_library(
+        str(default_path),
+        runtime_config_path=runtime_path,
+        environment=environment,
+        allow_env_override=False,
+    )
+    enabled = load_model_library(
+        str(default_path),
+        runtime_config_path=runtime_path,
+        environment=environment,
+        allow_env_override=True,
+    )
+
+    assert disabled.path == default_path.resolve()
+    assert enabled.path == override_path.resolve()
+
+
+@pytest.mark.parametrize(
+    "document",
+    (
+        "schema: friday.model-library/v1\nschema: friday.model-library/v1\n",
+        "schema: &schema friday.model-library/v1\ncopy: *schema\n",
+        "schema: friday.model-library/v1\nvalue: !custom tagged\n",
+        "schema: friday.model-library/v1\nbase: &base {provider: openai}\nmerged: {<<: *base}\n",
+    ),
+)
+def test_strict_loader_rejects_ambiguous_yaml(
+    tmp_path: Path,
+    document: str,
+) -> None:
+    catalog_path = tmp_path / "models.yaml"
+    catalog_path.write_text(document)
+
+    with pytest.raises(ModelLibraryLoadError):
+        load_model_library(
+            str(catalog_path),
+            runtime_config_path=tmp_path / "config.yaml",
+            environment={},
+            allow_env_override=False,
+        )
+
+
+def test_remote_catalog_is_rejected(tmp_path: Path) -> None:
+    with pytest.raises(ModelLibraryLoadError, match="local file"):
+        load_model_library(
+            "https://example.test/models.yaml",
+            runtime_config_path=tmp_path / "config.yaml",
+            environment={},
+            allow_env_override=False,
+        )
+
+
+def test_runtime_resolves_canonical_pools_and_di_uses_factories(
+    tmp_path: Path,
+) -> None:
+    install_root = tmp_path / "install"
+    runtime_parent = tmp_path / "runtime"
+    workspace_root = tmp_path / "workspace"
+    install_root.mkdir()
+    runtime_parent.mkdir()
+    workspace_root.mkdir()
+    catalog_path = tmp_path / "models-config.yaml"
+    catalog_path.write_text(
+        """
+schema: friday.model-library/v1
+credentials:
+  local_key:
+    env: FRIDAY_TEST_LLM_KEY
+endpoints:
+  local:
+    api_base: http://127.0.0.1:1234/v1
+    provider: openai_compatible
+    serving_engine: lm_studio
+    default_credential: local_key
+profiles:
+  chat:
+    kind: chat
+    endpoint: local
+    dialect: openai_chat_completions
+    model: openai/qwen3.8
+    model_target:
+      model_id: qwen3.8
+      family: qwen3_8
+      revision: exact
+  embedding:
+    kind: embedding
+    endpoint: local
+    dialect: openai_embeddings
+    model: openai/nomic-embed
+    model_target:
+      model_id: nomic-embed
+      family: nomic_embed
+      revision: exact
+""".strip()
+    )
+    runtime_path = tmp_path / "config.yaml"
+    runtime_path.write_text(
+        f"""
+model_library:
+  path: ./models-config.yaml
+runtime_paths:
+  install_root: {install_root}
+  runtime_data_root: {runtime_parent / "friday"}
+  workspace_root: {workspace_root}
+llm_pool:
+  default_service: default
+  services:
+    default:
+      profile: chat
+embedding_pool:
+  default_service: default
+  services:
+    default:
+      profile: embedding
+""".strip()
+    )
+
+    config = RuntimeConfig.from_sources(
+        yaml_path=runtime_path,
+        env={"FRIDAY_TEST_LLM_KEY": "redacted-local-key"},
+    )
+    container = DIContainer(config, MemoryProfile.FULL)
+    container._create_llm_services()
+
+    assert config.model_library_path == str(catalog_path.resolve())
+    assert config.llm_api_key is None
+    assert container.llm is not None
+    assert container.llm.model == "openai/qwen3.8"
+    assert container.llm.api_key == "redacted-local-key"
+    assert container.llm.execution_target is not None
+    assert container.embeddings is not None
+    assert container.embeddings.execution_target is not None