multiagentos 0.4.0__py3-none-any.whl

core/registry.py

@@ -0,0 +1,44 @@
+"""Registries for agents and AI providers."""
+
+from core.contracts.agent import AgentContract
+from core.contracts.ai import AIProvider, ModelSpec
+
+
+class AgentRegistry:
+    def __init__(self) -> None:
+        self._agents: dict[str, AgentContract] = {}
+
+    def register(self, agent: AgentContract) -> None:
+        if agent.id in self._agents:
+            raise ValueError(f"Agent already registered: {agent.id}")
+        self._agents[agent.id] = agent
+
+    def get(self, agent_id: str) -> AgentContract:
+        return self._agents[agent_id]
+
+    def list(self) -> tuple[AgentContract, ...]:
+        return tuple(self._agents.values())
+
+
+class AIRegistry:
+    def __init__(self) -> None:
+        self._providers: dict[str, AIProvider] = {}
+        self._models: dict[str, ModelSpec] = {}
+
+    def register(self, provider: AIProvider) -> None:
+        if provider.id in self._providers:
+            raise ValueError(f"Provider already registered: {provider.id}")
+        self._providers[provider.id] = provider
+        for model in provider.models:
+            if model.id in self._models:
+                raise ValueError(f"Model already registered: {model.id}")
+            self._models[model.id] = model
+
+    def provider(self, provider_id: str) -> AIProvider:
+        return self._providers[provider_id]
+
+    def model(self, model_id: str) -> ModelSpec:
+        return self._models[model_id]
+
+    def models(self) -> tuple[ModelSpec, ...]:
+        return tuple(self._models.values())

core/routing.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from core.contracts.agent import AgentContract
+from core.contracts.ai import ModelSpec
+from core.contracts.health import ModelHealth
+from core.contracts.quota import QuotaSnapshot
+if TYPE_CHECKING:
+    from runtime.capability import CapabilityRegistry
+
+
+class RoutingStrategy(str, Enum):
+    EXPLICIT = "explicit"
+    POOL = "pool"
+    AUTO = "auto"
+
+
+@dataclass(frozen=True)
+class Assignment:
+    agent_id: str
+    model_id: str
+
+
+@dataclass(frozen=True)
+class RoutingCandidate:
+    model_id: str
+    provider_id: str
+    selected: bool
+    compatible: bool
+    health_available: bool
+    quota_available: bool
+    capability_score: float
+    quota_score: float
+    missing_capabilities: frozenset[str]
+    rejection_reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RoutingExplanation:
+    agent_id: str
+    strategy: RoutingStrategy
+    selected_model_id: str | None
+    candidates: tuple[RoutingCandidate, ...]
+
+    @property
+    def assignment(self) -> Assignment:
+        if self.selected_model_id is None:
+            raise LookupError(f"No compatible available model for agent: {self.agent_id}")
+        return Assignment(self.agent_id, self.selected_model_id)
+
+
+class AIRouter:
+    def assign(
+        self,
+        agent: AgentContract,
+        models: list[ModelSpec],
+        preferred_model_ids: list[str] | None = None,
+        strategy: RoutingStrategy | str = RoutingStrategy.POOL,
+        quota_snapshots: dict[str, QuotaSnapshot] | None = None,
+        health_snapshots: dict[str, ModelHealth] | None = None,
+        capability_registry: CapabilityRegistry | None = None,
+    ) -> Assignment:
+        return self.explain(
+            agent,
+            models,
+            preferred_model_ids=preferred_model_ids,
+            strategy=strategy,
+            quota_snapshots=quota_snapshots,
+            health_snapshots=health_snapshots,
+            capability_registry=capability_registry,
+        ).assignment
+
+    def explain(
+        self,
+        agent: AgentContract,
+        models: list[ModelSpec],
+        preferred_model_ids: list[str] | None = None,
+        strategy: RoutingStrategy | str = RoutingStrategy.POOL,
+        quota_snapshots: dict[str, QuotaSnapshot] | None = None,
+        health_snapshots: dict[str, ModelHealth] | None = None,
+        capability_registry: CapabilityRegistry | None = None,
+    ) -> RoutingExplanation:
+        """Explain model eligibility, rejection reasons, and the selected model."""
+        from runtime.quota import quota_available, quota_score
+
+        strategy = RoutingStrategy(strategy)
+        preferred = preferred_model_ids if preferred_model_ids is not None else list(agent.model_ids)
+        preferred_set = set(preferred)
+        quota_snapshots = quota_snapshots or {}
+        health_snapshots = health_snapshots or {}
+        requirements = frozenset(agent.capabilities)
+
+        def capability_match(model: ModelSpec):
+            if capability_registry is None:
+                matched = requirements & model.capabilities
+                return matched, requirements - model.capabilities, (
+                    len(matched) / len(requirements) if requirements else 1.0
+                )
+            match = capability_registry.match(model, requirements)
+            return match.matched, match.missing, match.score
+
+        candidates = []
+        for model in models:
+            _, missing, cap_score = capability_match(model)
+            health = health_snapshots.get(model.id)
+            health_ok = health is None or health.available
+            quota = quota_snapshots.get(model.id)
+            quota_ok = quota is None or quota_available(quota)
+            reasons = []
+            if missing:
+                reasons.append("missing_capabilities")
+            if not health_ok:
+                reasons.append("unhealthy")
+            if not quota_ok:
+                reasons.append("quota_unavailable")
+            if strategy is RoutingStrategy.EXPLICIT and model.id not in preferred_set:
+                reasons.append("not_explicitly_selected")
+            candidates.append(
+                RoutingCandidate(
+                    model_id=model.id,
+                    provider_id=model.provider_id,
+                    selected=False,
+                    compatible=not missing,
+                    health_available=health_ok,
+                    quota_available=quota_ok,
+                    capability_score=cap_score,
+                    quota_score=quota_score(quota) if quota is not None else 0.5,
+                    missing_capabilities=frozenset(missing),
+                    rejection_reasons=tuple(reasons),
+                )
+            )
+
+        by_id = {model.id: model for model in models}
+        selected_model_id = None
+
+        if strategy in {RoutingStrategy.EXPLICIT, RoutingStrategy.POOL}:
+            for model_id in preferred:
+                model = by_id.get(model_id)
+                if model is None:
+                    continue
+                candidate = next(item for item in candidates if item.model_id == model.id)
+                if candidate.compatible and candidate.health_available and candidate.quota_available:
+                    selected_model_id = model.id
+                    break
+            if selected_model_id is None and strategy is RoutingStrategy.EXPLICIT:
+                raise LookupError(f"No explicitly assigned available model for agent: {agent.id}")
+
+        if selected_model_id is None and strategy in {RoutingStrategy.POOL, RoutingStrategy.AUTO}:
+            eligible = [
+                item for item in candidates
+                if item.compatible and item.health_available and item.quota_available
+            ]
+            eligible.sort(
+                key=lambda item: (item.capability_score, item.quota_score),
+                reverse=True,
+            )
+            if eligible:
+                selected_model_id = eligible[0].model_id
+
+        if selected_model_id is None:
+            raise LookupError(f"No compatible available model for agent: {agent.id}")
+
+        explained = tuple(
+            RoutingCandidate(
+                model_id=item.model_id,
+                provider_id=item.provider_id,
+                selected=item.model_id == selected_model_id,
+                compatible=item.compatible,
+                health_available=item.health_available,
+                quota_available=item.quota_available,
+                capability_score=item.capability_score,
+                quota_score=item.quota_score,
+                missing_capabilities=item.missing_capabilities,
+                rejection_reasons=tuple(
+                    reason for reason in item.rejection_reasons
+                    if reason != "not_explicitly_selected" or item.model_id != selected_model_id
+                ),
+            )
+            for item in candidates
+        )
+        return RoutingExplanation(
+            agent_id=agent.id,
+            strategy=strategy,
+            selected_model_id=selected_model_id,
+            candidates=explained,
+        )
+
+    @staticmethod
+    def compatible(agent: AgentContract, model: ModelSpec) -> bool:
+        return not agent.capabilities or agent.capabilities.issubset(model.capabilities)
+
+    _compatible = compatible

core/state.py

@@ -0,0 +1,155 @@
+"""Persistent WorkUnit state store."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from core.contracts.checkpoint import WorkflowCheckpoint
+from core.contracts.work_unit import WorkStatus, WorkUnit
+from core.contracts.vyrelon_runtime import SessionSpec, SessionState
+
+
+class WorkStateStore:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.checkpoint_root = self.root.parent / "checkpoints"
+        self.checkpoint_root.mkdir(parents=True, exist_ok=True)
+
+    def save(self, work_unit: WorkUnit) -> Path:
+        path = self.root / f"{work_unit.id}.json"
+        payload = {
+            "id": work_unit.id,
+            "objective": work_unit.objective,
+            "status": work_unit.status.value,
+            "inputs": work_unit.inputs,
+            "artifacts": work_unit.artifacts,
+            "assigned_agents": work_unit.assigned_agents,
+            "metadata": work_unit.metadata,
+        }
+        path.write_text(
+            json.dumps(payload, indent=2, default=str) + "\n",
+            encoding="utf-8",
+        )
+        return path
+
+    def exists(self, work_unit_id: str) -> bool:
+        return (self.root / f"{work_unit_id}.json").exists()
+
+    def list_ids(self) -> tuple[str, ...]:
+        return tuple(sorted(path.stem for path in self.root.glob("*.json")))
+
+    def load(self, work_unit_id: str) -> WorkUnit:
+        path = self.root / f"{work_unit_id}.json"
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return WorkUnit(
+            id=data["id"],
+            objective=data["objective"],
+            status=WorkStatus(data["status"]),
+            inputs=dict(data.get("inputs", {})),
+            artifacts=list(data.get("artifacts", [])),
+            assigned_agents=list(data.get("assigned_agents", [])),
+            metadata=dict(data.get("metadata", {})),
+        )
+
+    def save_checkpoint(self, checkpoint: WorkflowCheckpoint) -> Path:
+        """Persist a durable checkpoint independently of transient model output."""
+        checkpoint.validate()
+        path = self.checkpoint_root / f"{checkpoint.work_unit_id}.json"
+        path.write_text(
+            json.dumps(checkpoint.to_dict(), indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+        return path
+
+
+    def load_checkpoint(self, work_unit_id: str) -> WorkflowCheckpoint:
+        """Load the latest durable checkpoint for a WorkUnit."""
+        path = self.checkpoint_root / f"{work_unit_id}.json"
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return WorkflowCheckpoint.from_dict(data)
+
+
+    def checkpoint(
+        self,
+        work_unit: WorkUnit,
+        *,
+        workflow: str,
+        stage: str,
+        sequence: int = 0,
+        next_action: str | None = None,
+        agent_ids: tuple[str, ...] = (),
+        model_ids: tuple[str, ...] = (),
+        resumable: bool = True,
+        metadata: dict[str, object] | None = None,
+    ) -> WorkflowCheckpoint:
+        """Persist WorkUnit state and a normalized checkpoint atomically at the API level."""
+        self.save(work_unit)
+        checkpoint = WorkflowCheckpoint(
+            schema_version=1,
+            work_unit_id=work_unit.id,
+            workflow=workflow,
+            status=work_unit.status.value,
+            stage=stage,
+            sequence=sequence,
+            next_action=next_action,
+            agent_ids=agent_ids,
+            model_ids=model_ids,
+            artifact_ids=tuple(work_unit.artifacts),
+            findings=tuple(
+                str(value) for value in work_unit.metadata.get("findings", ())
+            ),
+            resumable=resumable,
+            metadata=dict(metadata or {}),
+        )
+        self.save_checkpoint(checkpoint)
+        return checkpoint
+
+
+
+class SessionStateStore:
+    """Persist SessionState independently from WorkUnit state."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def save(self, state: SessionState) -> Path:
+        path = self.root / f"{state.spec.id}.json"
+        payload = {
+            "spec": {
+                "id": state.spec.id,
+                "project_root": state.spec.project_root,
+                "agent_id": state.spec.agent_id,
+                "model_id": state.spec.model_id,
+                "checkpoint_id": state.spec.checkpoint_id,
+                "metadata": state.spec.metadata,
+            },
+            "work_unit_ids": state.work_unit_ids,
+            "status": state.status,
+            "metadata": state.metadata,
+        }
+        path.write_text(json.dumps(payload, indent=2, default=str) + "\n", encoding="utf-8")
+        return path
+
+    def exists(self, session_id: str) -> bool:
+        return (self.root / f"{session_id}.json").exists()
+
+    def load(self, session_id: str) -> SessionState:
+        data = json.loads((self.root / f"{session_id}.json").read_text(encoding="utf-8"))
+        raw = data["spec"]
+        spec = SessionSpec(
+            id=raw["id"],
+            project_root=raw["project_root"],
+            agent_id=raw.get("agent_id"),
+            model_id=raw.get("model_id"),
+            checkpoint_id=raw.get("checkpoint_id"),
+            metadata=dict(raw.get("metadata", {})),
+        )
+        return SessionState(
+            spec=spec,
+            work_unit_ids=list(data.get("work_unit_ids", [])),
+            status=data.get("status", "active"),
+            metadata=dict(data.get("metadata", {})),
+        )

installer/__init__.py

@@ -0,0 +1 @@
+"""VYRELON project installer."""

installer/init.py

@@ -0,0 +1,71 @@
+"""Apply VYRELON project bootstrap files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agents.catalog import build_agent_catalog
+from core.contracts.profile import DetectionResult
+from runtime.execution_config import write_default_execution_config
+from runtime.chat_config import write_default_chat_config
+
+
+class ProjectInitializer:
+    COMPONENTS = frozenset({"vyrelon", "multi-agent", "all"})
+
+    def apply(
+        self,
+        project_root: Path,
+        detections: tuple[DetectionResult, ...],
+        component: str = "all",
+    ) -> Path:
+        if component not in self.COMPONENTS:
+            raise ValueError(f"unsupported component: {component}")
+        target = project_root / ".multiagentos"
+        target.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": 1,
+            "profiles": [
+                {
+                    "id": result.profile_id,
+                    "confidence": result.confidence,
+                    "evidence": list(result.evidence),
+                }
+                for result in detections
+            ],
+        }
+        config = target / "profile.json"
+        config.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+        (target / "components.json").write_text(
+            json.dumps({"version": 1, "components": [component]}, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+        if component in {"vyrelon", "all"}:
+            write_default_execution_config(project_root)
+            write_default_chat_config(project_root)
+
+        if component == "vyrelon":
+            return config
+
+        agents = build_agent_catalog(tuple(result.profile_id for result in detections))
+        agent_payload = {
+            "version": 1,
+            "agents": [
+                {
+                    "id": agent.id,
+                    "role": agent.role,
+                    "kind": agent.kind,
+                    "capabilities": sorted(agent.capabilities),
+                    "tools": sorted(agent.tools),
+                    "permissions": sorted(agent.permissions),
+                    "models": list(agent.model_ids),
+                }
+                for agent in agents
+            ],
+        }
+        (target / "agents.json").write_text(
+            json.dumps(agent_payload, indent=2) + "\n", encoding="utf-8"
+        )
+        return config

integrations/github/__init__.py

@@ -0,0 +1,3 @@
+from .gateway import GitHubGatewayClient
+
+__all__ = ["GitHubGatewayClient"]

integrations/github/gateway.py

@@ -0,0 +1,164 @@
+"""GitHub adapter using the locally authenticated GitHub CLI."""
+
+from __future__ import annotations
+
+import base64
+import json
+import subprocess
+from typing import Any
+
+from core.contracts.github import (
+    GitHubBranch,
+    GitHubFile,
+    GitHubGateway,
+    GitHubIssue,
+    GitHubRepository,
+    MergeResult,
+    PullRequest,
+    ReviewResult,
+    WorkflowRun,
+)
+
+
+class GitHubGatewayClient:
+    def __init__(self, gh_binary: str = "gh") -> None:
+        self.gh_binary = gh_binary
+
+    def _run(self, *args: str) -> Any:
+        result = subprocess.run(
+            [self.gh_binary, *args],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"gh command failed ({result.returncode}): "
+                f"{' '.join(args)}\n{result.stderr.strip()}"
+            )
+        output = result.stdout.strip()
+        return json.loads(output) if output else None
+
+    def get_repository(self, full_name: str) -> GitHubRepository:
+        data = self._run(
+            "repo", "view", full_name,
+            "--json", "nameWithOwner,defaultBranchRef,isPrivate",
+        )
+        return GitHubRepository(
+            full_name=data["nameWithOwner"],
+            default_branch=data["defaultBranchRef"]["name"],
+            private=data["isPrivate"],
+        )
+
+    def get_branch(self, full_name: str, branch: str) -> GitHubBranch:
+        data = self._run(
+            "api", f"repos/{full_name}/branches/{branch}",
+            "--jq", "{name: .name, sha: .commit.sha}",
+        )
+        return GitHubBranch(name=data["name"], sha=data["sha"])
+
+    def create_branch(self, full_name: str, branch: str, base: str) -> GitHubBranch:
+        base_ref = self.get_branch(full_name, base)
+        self._run(
+            "api", f"repos/{full_name}/git/refs", "--method", "POST",
+            "-f", f"ref=refs/heads/{branch}", "-f", f"sha={base_ref.sha}",
+        )
+        return GitHubBranch(name=branch, sha=base_ref.sha)
+
+    def get_file(self, full_name: str, path: str, ref: str) -> GitHubFile:
+        data = self._run(
+            "api", f"repos/{full_name}/contents/{path}",
+            "-f", f"ref={ref}",
+        )
+        content = base64.b64decode(data["content"]).decode("utf-8")
+        return GitHubFile(path=data["path"], content=content, sha=data["sha"])
+
+    def create_file(
+        self, full_name: str, path: str, content: str,
+        branch: str, message: str,
+    ) -> str:
+        encoded = base64.b64encode(content.encode()).decode()
+        data = self._run(
+            "api", f"repos/{full_name}/contents/{path}", "--method", "PUT",
+            "-f", f"message={message}", "-f", f"content={encoded}",
+            "-f", f"branch={branch}",
+        )
+        return data["commit"]["sha"]
+
+    def update_file(
+        self, full_name: str, path: str, content: str, sha: str,
+        branch: str, message: str,
+    ) -> str:
+        encoded = base64.b64encode(content.encode()).decode()
+        data = self._run(
+            "api", f"repos/{full_name}/contents/{path}", "--method", "PUT",
+            "-f", f"message={message}", "-f", f"content={encoded}",
+            "-f", f"sha={sha}", "-f", f"branch={branch}",
+        )
+        return data["commit"]["sha"]
+
+    def create_issue(self, full_name: str, title: str, body: str = "") -> GitHubIssue:
+        data = self._run(
+            "api", f"repos/{full_name}/issues", "--method", "POST",
+            "-f", f"title={title}", "-f", f"body={body}",
+        )
+        return GitHubIssue(number=data["number"], title=data["title"], url=data["html_url"])
+
+    def create_pull_request(
+        self, full_name: str, title: str, body: str,
+        head: str, base: str, draft: bool = False,
+    ) -> PullRequest:
+        args = [
+            "pr", "create", "--repo", full_name,
+            "--title", title, "--body", body,
+            "--head", head, "--base", base,
+        ]
+        if draft:
+            args.append("--draft")
+        data = self._run(*args, "--json", "number,title,url,headRefName,baseRefName")
+        return PullRequest(
+            number=data["number"],
+            title=data["title"],
+            url=data["url"],
+            head=data["headRefName"],
+            base=data["baseRefName"],
+        )
+
+    def review_pull_request(
+        self, full_name: str, number: int, action: str, body: str = "",
+    ) -> ReviewResult:
+        flags = {"approve": "--approve", "comment": "--comment", "request_changes": "--request-changes"}
+        try:
+            flag = flags[action]
+        except KeyError as exc:
+            raise ValueError(f"Unsupported review action: {action}") from exc
+        args = ["pr", "review", str(number), "--repo", full_name, flag]
+        if body:
+            args.extend(["--body", body])
+        self._run(*args)
+        return ReviewResult(success=True, action=action)
+
+    def merge_pull_request(
+        self, full_name: str, number: int, method: str = "squash",
+    ) -> MergeResult:
+        if method not in {"merge", "squash", "rebase"}:
+            raise ValueError(f"Unsupported merge method: {method}")
+        data = self._run(
+            "api", f"repos/{full_name}/pulls/{number}/merge",
+            "--method", "PUT", "-f", f"merge_method={method}",
+        )
+        return MergeResult(
+            merged=bool(data.get("merged")),
+            sha=data.get("sha"),
+            message=data.get("message", ""),
+        )
+
+    def list_workflows(self, full_name: str, ref: str) -> list[WorkflowRun]:
+        data = self._run(
+            "run", "list", "--repo", full_name, "--branch", ref,
+            "--json", "databaseId,status,conclusion",
+        )
+        return [
+            WorkflowRun(item["databaseId"], item["status"], item["conclusion"])
+            for item in data
+        ]

integrations/openai/__init__.py

@@ -0,0 +1 @@
+"""OpenAI provider adapters for VYRELON Chat Agents."""