"""Cloud provider bundles. A Cloud provider is configuration, not code (ADR-0002): providers/.yaml lists the Skills, local tools, remote MCP servers and default models that one Cloud provider brings. Nothing outside this module names a provider. """ from __future__ import annotations from collections.abc import Mapping from dataclasses import dataclass, field from pathlib import Path from typing import Any import yaml from app.skills.agent_skills import SkillFormatError, SkillMeta, discover_skills TIERS = ("general", "cloud_read") _REPO_ROOT = Path(__file__).resolve().parent.parent class ProviderConfigError(ValueError): """A provider bundle is missing or invalid.""" @dataclass(frozen=True) class McpServerSpec: """A remote MCP server hosted by the Cloud provider. Only tools named in `allow` are ever exposed; an empty `allow` exposes nothing. """ id: str url: str tier: str allow: tuple[str, ...] preview: bool = False @dataclass(frozen=True) class ModelConfig: default: str roles: Mapping[str, str] = field(default_factory=dict) def for_role(self, role: str) -> str: return self.roles.get(role, self.default) @dataclass(frozen=True) class ProviderBundle: name: str skills_dirs: tuple[Path, ...] skills: Mapping[str, SkillMeta] output_template: Path models: ModelConfig tools: Mapping[str, tuple[str, ...]] mcp_auth: Mapping[str, Any] mcp_servers: Mapping[str, McpServerSpec] role_mcp_servers: Mapping[str, tuple[str, ...]] role_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict) pillar_skills: Mapping[str, str] = field(default_factory=dict) def mcp_servers_for_role( self, role: str, include_preview: bool = True ) -> tuple[McpServerSpec, ...]: servers = ( self.mcp_servers[server_id] for server_id in self.role_mcp_servers.get(role, ()) ) return tuple( server for server in servers if include_preview or not server.preview ) def load_provider(name: str, root: Path | None = None) -> ProviderBundle: """Load and validate providers/.yaml; relative paths resolve against `root`.""" root = root or _REPO_ROOT config_path = root / "providers" / f"{name}.yaml" if not config_path.is_file(): raise ProviderConfigError(f"No provider bundle for {name!r} at {config_path}") config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {} if not isinstance(config, dict): raise ProviderConfigError(f"{config_path}: must be a mapping") def fail(message: str) -> ProviderConfigError: return ProviderConfigError(f"{config_path}: {message}") if config.get("name") != name: raise fail(f"'name' must be {name!r}") skills_dirs = tuple(root / entry for entry in config.get("skills_dirs") or ()) if not skills_dirs: raise fail("'skills_dirs' must list at least one directory") for directory in skills_dirs: if not directory.is_dir(): raise fail(f"'skills_dirs' entry {directory} is not a directory") try: skills = discover_skills(skills_dirs) except SkillFormatError as exc: raise fail(str(exc)) from exc output_template = root / str(config.get("output_template", "")) if not config.get("output_template") or not output_template.is_file(): raise fail(f"'output_template' {output_template} does not exist") models = config.get("models") or {} if not isinstance(models.get("default"), str) or not models["default"]: raise fail("'models.default' is required") model_config = ModelConfig( default=models["default"], roles=dict(models.get("roles") or {}) ) tools = {} for tier, tool_names in (config.get("tools") or {}).items(): if tier not in TIERS: raise fail(f"'tools' tier {tier!r} must be one of {TIERS}") tools[tier] = tuple(tool_names or ()) mcp_servers = {} for server_id, spec in (config.get("mcp_servers") or {}).items(): url = spec.get("url", "") if not url.startswith("https://"): raise fail(f"MCP server {server_id!r} url must use https") if spec.get("tier") not in TIERS: raise fail(f"MCP server {server_id!r} tier must be one of {TIERS}") if not isinstance(spec.get("allow"), list): raise fail( f"MCP server {server_id!r} needs an 'allow' list (empty exposes no tools)" ) mcp_servers[server_id] = McpServerSpec( id=server_id, url=url, tier=spec["tier"], allow=tuple(spec["allow"]), preview=bool(spec.get("preview", False)), ) role_mcp_servers = {} for role, server_ids in (config.get("role_mcp_servers") or {}).items(): unknown = [ server_id for server_id in server_ids or () if server_id not in mcp_servers ] if unknown: raise fail( f"role {role!r} references unknown MCP servers: {', '.join(unknown)}" ) role_mcp_servers[role] = tuple(server_ids or ()) role_skills = {} for role, skill_names in (config.get("role_skills") or {}).items(): unknown = [skill for skill in skill_names or () if skill not in skills] if unknown: raise fail(f"role {role!r} references unknown skills: {', '.join(unknown)}") role_skills[role] = tuple(skill_names or ()) pillar_skills = {} for pillar, skill_name in (config.get("pillar_skills") or {}).items(): if skill_name not in skills: raise fail(f"pillar {pillar!r} references unknown skill {skill_name!r}") pillar_skills[str(pillar)] = skill_name return ProviderBundle( name=name, skills_dirs=skills_dirs, skills=skills, output_template=output_template, models=model_config, tools=tools, mcp_auth=dict(config.get("mcp_auth") or {}), mcp_servers=mcp_servers, role_mcp_servers=role_mcp_servers, role_skills=role_skills, pillar_skills=pillar_skills, )