swarmkit-runtime 1.0.0__py3-none-any.whl

swarmkit_runtime/__init__.py

@@ -0,0 +1,6 @@
+"""SwarmKit runtime — topology interpreter, LangGraph compiler, governance wiring.
+
+See `design/SwarmKit-Design-v0.6.md` §9 and §14 for architectural context.
+"""
+
+__version__ = "0.0.1"

swarmkit_runtime/_workspace_runtime.py

@@ -0,0 +1,308 @@
+"""WorkspaceRuntime — the backend that CLI, HTTP server, and web UI call into.
+
+Owns the full execution lifecycle: resolve workspace → build providers →
+build governance → wire MCP → compile topology → invoke graph → close.
+The CLI is a thin interface over this; ``swarmkit serve`` (M9) and the
+v1.1 web UI will be additional interfaces over the same class.
+
+See ``design/details/workspace-runtime.md`` (to be written) and the
+architectural decision in ``memory/feedback_cli_architecture.md``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from langgraph.graph.state import CompiledStateGraph
+
+from swarmkit_runtime.governance import GovernanceProvider
+from swarmkit_runtime.governance._mock import MockGovernanceProvider
+from swarmkit_runtime.langgraph_compiler import compile_topology
+from swarmkit_runtime.mcp import MCPClientManager, MCPServerConfig, parse_mcp_servers
+from swarmkit_runtime.model_providers import (
+    AnthropicModelProvider,
+    GoogleModelProvider,
+    GroqModelProvider,
+    MockModelProvider,
+    OllamaModelProvider,
+    OpenAIModelProvider,
+    OpenRouterModelProvider,
+    ProviderRegistry,
+    TogetherModelProvider,
+)
+from swarmkit_runtime.model_providers._registry import ModelProviderProtocol
+from swarmkit_runtime.resolver import ResolvedWorkspace, resolve_workspace
+
+
+@dataclass(frozen=True)
+class RunResult:
+    """Output of a topology execution."""
+
+    output: str
+    agent_results: dict[str, str] = field(default_factory=dict)
+
+
+class MissingMCPServerError(Exception):
+    """A skill targets an MCP server that the workspace doesn't declare."""
+
+    def __init__(self, missing: list[tuple[str, str]]) -> None:
+        self.missing = missing
+        lines = [
+            f"skill '{sid}' targets MCP server '{srv}' but the workspace declares no such server"
+            for sid, srv in missing
+        ]
+        super().__init__("\n".join(lines))
+
+
+class WorkspaceRuntime:
+    """The backend that both CLI and HTTP server call into.
+
+    Holds a resolved workspace plus all the wired runtime components
+    (model providers, governance, MCP manager). Constructed via the
+    ``from_workspace_path`` classmethod.
+    """
+
+    def __init__(
+        self,
+        *,
+        workspace: ResolvedWorkspace,
+        workspace_root: Path,
+        provider_registry: ProviderRegistry,
+        governance: GovernanceProvider,
+        mcp_manager: MCPClientManager | None,
+    ) -> None:
+        self._workspace = workspace
+        self._workspace_root = workspace_root
+        self._provider_registry = provider_registry
+        self._governance = governance
+        self._mcp_manager = mcp_manager
+
+    @classmethod
+    def from_workspace_path(cls, path: Path) -> WorkspaceRuntime:
+        """Build a fully-wired runtime from a workspace directory.
+
+        Resolves the workspace, registers model providers, selects the
+        governance provider, parses MCP server config, and validates
+        that every mcp_tool skill targets a configured server.
+
+        Raises ``ResolutionErrors`` if the workspace is invalid, or
+        ``MissingMCPServerError`` if skills reference unconfigured
+        MCP servers.
+        """
+        ws_root = path.resolve()
+        workspace = resolve_workspace(ws_root)
+
+        registry = ProviderRegistry()
+        register_available_providers(registry)
+
+        governance = build_governance(workspace, ws_root)
+
+        mcp_configs = parse_mcp_servers(getattr(workspace.raw, "mcp_servers", None))
+        mcp_manager = MCPClientManager(mcp_configs, workspace_root=ws_root) if mcp_configs else None
+
+        missing = find_missing_mcp_servers(workspace, mcp_configs)
+        if missing:
+            raise MissingMCPServerError(missing)
+
+        return cls(
+            workspace=workspace,
+            workspace_root=ws_root,
+            provider_registry=registry,
+            governance=governance,
+            mcp_manager=mcp_manager,
+        )
+
+    def compile(self, topology_name: str) -> CompiledStateGraph[Any]:
+        """Compile a named topology into a LangGraph graph.
+
+        Raises ``KeyError`` if the topology doesn't exist.
+        """
+        if topology_name not in self._workspace.topologies:
+            available = sorted(self._workspace.topologies.keys())
+            raise KeyError(
+                f"Topology '{topology_name}' not found. "
+                f"Available: {', '.join(available) or '(none)'}."
+            )
+
+        topology = self._workspace.topologies[topology_name]
+        return compile_topology(
+            topology,
+            provider_registry=self._provider_registry,
+            governance=self._governance,
+            mcp_manager=self._mcp_manager,
+        )
+
+    async def run(
+        self,
+        topology_name: str,
+        user_input: str,
+        *,
+        max_steps: int = 10,
+    ) -> RunResult:
+        """Execute a topology end-to-end and return the result.
+
+        Handles MCP session lifecycle (start_all / close_all) within
+        the same async task so the SDK's anyio task groups unwind cleanly.
+        """
+        graph = self.compile(topology_name)
+
+        if self._mcp_manager is not None:
+            await self._mcp_manager.start_all()
+        try:
+            result = await graph.ainvoke(
+                {
+                    "input": user_input,
+                    "messages": [],
+                    "agent_results": {},
+                    "current_agent": "",
+                    "output": "",
+                },
+                config={"recursion_limit": max_steps},
+            )
+        finally:
+            if self._mcp_manager is not None:
+                await self._mcp_manager.close_all()
+
+        return RunResult(
+            output=result.get("output", ""),
+            agent_results={
+                k: str(v) for k, v in result.get("agent_results", {}).items() if isinstance(v, str)
+            },
+        )
+
+    async def close(self) -> None:
+        """Release all held resources."""
+        if self._mcp_manager is not None:
+            await self._mcp_manager.close_all()
+
+    @property
+    def workspace(self) -> ResolvedWorkspace:
+        return self._workspace
+
+    @property
+    def workspace_root(self) -> Path:
+        return self._workspace_root
+
+    @property
+    def governance(self) -> GovernanceProvider:
+        return self._governance
+
+    @property
+    def mcp_manager(self) -> MCPClientManager | None:
+        return self._mcp_manager
+
+    @property
+    def provider_registry(self) -> ProviderRegistry:
+        return self._provider_registry
+
+
+# ---- helpers (public — used by CLI and tests) ----------------------------
+
+
+def register_available_providers(registry: ProviderRegistry) -> None:
+    """Register all model providers whose credentials are in the environment."""
+    registry.register(MockModelProvider())
+
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        registry.register(AnthropicModelProvider())
+    if os.environ.get("GOOGLE_API_KEY"):
+        registry.register(GoogleModelProvider())
+    if os.environ.get("OPENAI_API_KEY"):
+        registry.register(OpenAIModelProvider())
+    if os.environ.get("OPENROUTER_API_KEY"):
+        registry.register(OpenRouterModelProvider())
+    if os.environ.get("GROQ_API_KEY"):
+        registry.register(GroqModelProvider())
+    if os.environ.get("TOGETHER_API_KEY"):
+        registry.register(TogetherModelProvider())
+
+    registry.register(OllamaModelProvider())
+
+
+def build_governance(workspace: ResolvedWorkspace, ws_root: Path) -> GovernanceProvider:
+    """Select the GovernanceProvider based on workspace.yaml's governance block."""
+    gov = getattr(workspace.raw, "governance", None)
+    if gov is None:
+        return MockGovernanceProvider(allow_all=True)
+
+    provider_value = gov.provider.value if hasattr(gov.provider, "value") else str(gov.provider)
+
+    if provider_value == "agt":
+        from swarmkit_runtime.governance.agt_provider import AGTGovernanceProvider  # noqa: PLC0415
+
+        config = gov.config or {}
+        policies_dir = ws_root / config.get("policies_dir", "policies")
+        audit_db = ws_root / ".swarmkit" / "audit.db"
+        audit_db.parent.mkdir(parents=True, exist_ok=True)
+        return AGTGovernanceProvider.from_config(
+            policy_dir=policies_dir,
+            audit_db=audit_db,
+        )
+
+    if provider_value == "custom":
+        print(
+            "warning: governance.provider=custom is not yet supported; "
+            "falling back to mock. See design §8.5 for the plugin path.",
+            file=sys.stderr,
+        )
+
+    return MockGovernanceProvider(allow_all=True)
+
+
+def resolve_authoring_provider(
+    registry: ProviderRegistry | None = None,
+) -> tuple[ModelProviderProtocol, str]:
+    """Resolve which model provider + model name to use for authoring.
+
+    Checks SWARMKIT_AUTHOR_MODEL (format: provider/model), then falls
+    back to SWARMKIT_PROVIDER + SWARMKIT_MODEL, then first available
+    real provider.
+    """
+    author_model = os.environ.get("SWARMKIT_AUTHOR_MODEL", "")
+    if "/" in author_model:
+        provider_id, model_name = author_model.split("/", 1)
+    else:
+        provider_id = os.environ.get("SWARMKIT_PROVIDER", "")
+        model_name = os.environ.get("SWARMKIT_MODEL", "")
+
+    if registry is None:
+        registry = ProviderRegistry()
+        register_available_providers(registry)
+
+    if provider_id:
+        provider = registry.get(provider_id)
+        if provider is not None:
+            return provider, model_name or "claude-sonnet-4-6"
+
+    for pid in registry.provider_ids:
+        if pid == "mock":
+            continue
+        provider = registry.get(pid)
+        if provider is not None:
+            return provider, model_name or "claude-sonnet-4-6"
+
+    raise RuntimeError(
+        "No model provider available. Set SWARMKIT_PROVIDER "
+        "and the corresponding API key (e.g. GROQ_API_KEY)."
+    )
+
+
+def find_missing_mcp_servers(
+    workspace: ResolvedWorkspace,
+    mcp_configs: dict[str, MCPServerConfig],
+) -> list[tuple[str, str]]:
+    """Return ``(skill_id, server_id)`` pairs whose mcp_tool target is unconfigured."""
+    missing: list[tuple[str, str]] = []
+    for skill_id, skill in workspace.skills.items():
+        impl = skill.raw.implementation
+        impl_type = impl.get("type") if isinstance(impl, dict) else getattr(impl, "type", None)
+        if impl_type != "mcp_tool":
+            continue
+        server_id = impl.get("server") if isinstance(impl, dict) else getattr(impl, "server", "")
+        if server_id and server_id not in mcp_configs:
+            missing.append((skill_id, server_id))
+    return missing

swarmkit_runtime/archetypes/__init__.py

@@ -0,0 +1,163 @@
+"""Archetype registry + skill-reference verification (M1.4 / phase 3b).
+
+Given a list of archetype ``DiscoveredArtifact`` and the already-built
+skill registry (from :mod:`swarmkit_runtime.skills`), produce a registry
+of :class:`ResolvedArchetype` keyed by archetype ID.
+
+Concrete skill references in an archetype's ``defaults.skills`` list are
+verified against the skill registry. Abstract-skill placeholders
+(``{ abstract: { category, capability? } }`` per §6.6) are left
+unchecked here — they bind to a concrete skill at topology-load time in
+phase 3c (M1.5).
+
+Design reference: ``design/details/topology-loader.md`` phase 3b.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import ValidationError as PydanticValidationError
+from swarmkit_schema.models import SwarmKitArchetype
+
+from swarmkit_runtime.errors import ResolutionError
+from swarmkit_runtime.skills import ResolvedSkill
+from swarmkit_runtime.workspace import DiscoveredArtifact
+
+
+@dataclass(frozen=True)
+class ResolvedArchetype:
+    """An archetype whose concrete skill references have been verified
+    against the workspace skill registry.
+
+    Abstract-skill placeholders in ``raw.defaults.skills`` are retained
+    as-is — the topology resolver (M1.5) binds them per-agent.
+    """
+
+    id: str
+    raw: SwarmKitArchetype
+    source_path: Path
+
+
+def build_archetype_registry(
+    artifacts: Iterable[DiscoveredArtifact],
+    skill_registry: Mapping[str, ResolvedSkill],
+) -> tuple[Mapping[str, ResolvedArchetype], list[ResolutionError]]:
+    """Build a registry of :class:`ResolvedArchetype` keyed by ID.
+
+    Returns ``(registry, errors)``. Every concrete skill reference in an
+    archetype's defaults must exist in ``skill_registry``; unknown refs
+    surface as ``archetype.unknown-skill`` entries. Duplicate archetype
+    IDs surface as ``archetype.duplicate-id``.
+    """
+    errors: list[ResolutionError] = []
+    registry: dict[str, ResolvedArchetype] = {}
+
+    for artifact in artifacts:
+        if artifact.kind != "archetype":
+            continue
+        try:
+            model = SwarmKitArchetype.model_validate(dict(artifact.raw))
+        except PydanticValidationError as exc:
+            errors.append(
+                ResolutionError(
+                    code="archetype.model-construction",
+                    message=(
+                        f"archetype at {artifact.path} could not be "
+                        "constructed as a pydantic SwarmKitArchetype model."
+                    ),
+                    artifact_path=artifact.path,
+                    suggestion=f"pydantic raised: {exc.errors()[0]['msg']}",
+                )
+            )
+            continue
+        arch_id = _identifier_str(model.metadata.id)
+        if arch_id in registry:
+            prior_path = registry[arch_id].source_path
+            errors.append(
+                ResolutionError(
+                    code="archetype.duplicate-id",
+                    message=(
+                        f"Archetype id {arch_id!r} is declared twice: "
+                        f"first at {prior_path}, again at {artifact.path}."
+                    ),
+                    artifact_path=artifact.path,
+                    yaml_pointer="/metadata/id",
+                    suggestion=(
+                        "Rename one of the archetypes so every archetype ID "
+                        "is unique within the workspace."
+                    ),
+                )
+            )
+            continue
+
+        # Verify every concrete skill reference exists. Abstract
+        # placeholders skipped here; their binding happens in phase 3c.
+        skill_errors = _check_skill_refs(arch_id, artifact.path, model, skill_registry)
+        errors.extend(skill_errors)
+        # Even with skill errors, keep the archetype in the registry so
+        # later phases can produce more useful cross-references.
+        registry[arch_id] = ResolvedArchetype(id=arch_id, raw=model, source_path=artifact.path)
+
+    return registry, errors
+
+
+def _check_skill_refs(
+    arch_id: str,
+    source: Path,
+    model: SwarmKitArchetype,
+    skill_registry: Mapping[str, ResolvedSkill],
+) -> list[ResolutionError]:
+    errors: list[ResolutionError] = []
+    defaults = model.defaults
+    skills = getattr(defaults, "skills", None)
+    if not skills:
+        return errors
+    for index, entry in enumerate(skills):
+        # Entry is either a bare identifier string or an object with
+        # ``abstract: { category, capability? }``. Only the concrete
+        # case is checked here.
+        if _is_abstract_skill(entry):
+            continue
+        skill_id = _identifier_str(entry)
+        if skill_id not in skill_registry:
+            errors.append(
+                ResolutionError(
+                    code="archetype.unknown-skill",
+                    message=(
+                        f"Archetype {arch_id!r} references skill "
+                        f"{skill_id!r} which is not defined in this workspace."
+                    ),
+                    artifact_path=source,
+                    yaml_pointer=f"/defaults/skills/{index}",
+                    suggestion=(
+                        f"Define a skill with id={skill_id!r}, or change "
+                        "the reference to an existing one. You can also "
+                        "use an abstract placeholder "
+                        "({ abstract: { category, capability? } }) if the "
+                        "archetype should be concrete-skill-agnostic."
+                    ),
+                )
+            )
+    return errors
+
+
+def _is_abstract_skill(entry: object) -> bool:
+    # The skill entry union is string | { abstract: {...} }. pydantic
+    # materialises the string branch as a plain string and the object
+    # branch as an Abstract-containing object. Duck-type check:
+    # anything with an `abstract` attribute that isn't None is abstract.
+    return getattr(entry, "abstract", None) is not None
+
+
+def _identifier_str(value: object) -> str:
+    root = getattr(value, "root", value)
+    return str(root)
+
+
+__all__ = [
+    "ResolvedArchetype",
+    "build_archetype_registry",
+]

swarmkit_runtime/audit/__init__.py

@@ -0,0 +1,13 @@
+"""Audit and skill-gap logging (design §5.4, §14.5, §16.4).
+
+Audit events flow into AGT's Agent SRE telemetry pipeline via the
+`GovernanceProvider.record_event` interface. This module adds SwarmKit-specific
+event types on top:
+
+  - skill gap events (design §12.1)
+  - review queue state changes
+  - gap surfacing decisions
+  - authoring swarm conversations
+
+All writes are append-only. No code path in this module exposes update/delete.
+"""

swarmkit_runtime/authoring/__init__.py

@@ -0,0 +1,10 @@
+"""Conversational authoring — interactive artifact generation (M3.5).
+
+See ``design/details/conversational-authoring.md``.
+"""
+
+from __future__ import annotations
+
+from ._agent import run_authoring_session
+
+__all__ = ["run_authoring_session"]