multiagentos 0.4.0__py3-none-any.whl

core/contracts/agent.py

@@ -0,0 +1,21 @@
+"""Agent contract independent of any model or vendor."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class AgentContract:
+    id: str
+    role: str
+    capabilities: frozenset[str] = frozenset()
+    tools: frozenset[str] = frozenset()
+    permissions: frozenset[str] = frozenset()
+    model_ids: tuple[str, ...] = ()
+    metadata: dict[str, object] = field(default_factory=dict)
+    kind: str = "custom"
+
+
+class AgentRuntime(Protocol):
+    def execute(self, agent: AgentContract, work_unit: object) -> object:
+        ...

core/contracts/ai.py

@@ -0,0 +1,25 @@
+"""AI provider/model contracts used by VYRELON routing."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    id: str
+    provider_id: str
+    capabilities: frozenset[str] = frozenset()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AIProvider:
+    id: str
+    kind: str
+    models: tuple[ModelSpec, ...] = ()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+class AIExecutor(Protocol):
+    def generate(self, model: ModelSpec, prompt: str, **kwargs: object) -> str:
+        ...

core/contracts/capability.py

@@ -0,0 +1,44 @@
+"""Model capability contracts for VYRELON routing."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class CapabilityConfidence(str, Enum):
+    DECLARED = "declared"
+    OBSERVED = "observed"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class ModelCapabilityProfile:
+    """Normalized capabilities exposed by one model."""
+
+    model_id: str
+    provider_id: str
+    capabilities: frozenset[str] = frozenset()
+    confidence: CapabilityConfidence = CapabilityConfidence.DECLARED
+    source: str = "model_spec"
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def supports(self, requirements: frozenset[str]) -> bool:
+        return requirements.issubset(self.capabilities)
+
+    def match_score(self, requirements: frozenset[str]) -> float:
+        if not requirements:
+            return 1.0
+        return len(self.capabilities & requirements) / len(requirements)
+
+
+@dataclass(frozen=True)
+class CapabilityMatch:
+    model_id: str
+    required: frozenset[str]
+    matched: frozenset[str]
+    missing: frozenset[str]
+    score: float
+    confidence: CapabilityConfidence
+
+    @property
+    def compatible(self) -> bool:
+        return not self.missing

core/contracts/chat_agent.py

@@ -0,0 +1,34 @@
+"""Contracts for chat-facing AI agents used with VYRELON."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ChatAgentProvider(str, Enum):
+    CHATGPT = "chatgpt"
+    GEMINI = "gemini"
+    CLAUDE = "claude"
+    OTHER = "other"
+
+
+@dataclass(frozen=True)
+class ChatAgentContract:
+    """A conversational agent that can drive or collaborate with VYRELON."""
+
+    id: str
+    provider: ChatAgentProvider
+    name: str
+    capabilities: frozenset[str] = frozenset()
+    instruction_profile: str = "default"
+    metadata: dict[str, object] = field(default_factory=dict)
+    primary: bool = False
+
+    def validate(self) -> None:
+        if not self.id.strip():
+            raise ValueError("chat agent id must not be empty")
+        if not self.name.strip():
+            raise ValueError("chat agent name must not be empty")
+        if self.primary and self.provider is not ChatAgentProvider.CHATGPT:
+            raise ValueError("the default primary chat agent must be ChatGPT")

core/contracts/checkpoint.py

@@ -0,0 +1,78 @@
+"""Durable checkpoint state for resumable VYRELON workflows."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class WorkflowCheckpoint:
+    """Serializable checkpoint describing the last durable workflow boundary."""
+
+    schema_version: int
+    work_unit_id: str
+    workflow: str
+    status: str
+    stage: str
+    sequence: int = 0
+    next_action: str | None = None
+    agent_ids: tuple[str, ...] = ()
+    model_ids: tuple[str, ...] = ()
+    artifact_ids: tuple[str, ...] = ()
+    findings: tuple[str, ...] = ()
+    resumable: bool = True
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def validate(self) -> None:
+        if self.schema_version < 1:
+            raise ValueError("checkpoint schema_version must be >= 1")
+        if not self.work_unit_id.strip():
+            raise ValueError("checkpoint work_unit_id must not be empty")
+        if not self.workflow.strip():
+            raise ValueError("checkpoint workflow must not be empty")
+        if not self.status.strip():
+            raise ValueError("checkpoint status must not be empty")
+        if not self.stage.strip():
+            raise ValueError("checkpoint stage must not be empty")
+        if self.sequence < 0:
+            raise ValueError("checkpoint sequence must be >= 0")
+
+    def to_dict(self) -> dict[str, object]:
+        self.validate()
+        return {
+            "schema_version": self.schema_version,
+            "work_unit_id": self.work_unit_id,
+            "workflow": self.workflow,
+            "status": self.status,
+            "stage": self.stage,
+            "sequence": self.sequence,
+            "next_action": self.next_action,
+            "agent_ids": list(self.agent_ids),
+            "model_ids": list(self.model_ids),
+            "artifact_ids": list(self.artifact_ids),
+            "findings": list(self.findings),
+            "resumable": self.resumable,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "WorkflowCheckpoint":
+        checkpoint = cls(
+            schema_version=int(data.get("schema_version", 1)),
+            work_unit_id=str(data["work_unit_id"]),
+            workflow=str(data["workflow"]),
+            status=str(data["status"]),
+            stage=str(data["stage"]),
+            sequence=int(data.get("sequence", 0)),
+            next_action=(
+                str(data["next_action"])
+                if data.get("next_action") is not None
+                else None
+            ),
+            agent_ids=tuple(str(value) for value in data.get("agent_ids", ())),
+            model_ids=tuple(str(value) for value in data.get("model_ids", ())),
+            artifact_ids=tuple(str(value) for value in data.get("artifact_ids", ())),
+            findings=tuple(str(value) for value in data.get("findings", ())),
+            resumable=bool(data.get("resumable", True)),
+            metadata=dict(data.get("metadata", {})),
+        )
+        checkpoint.validate()
+        return checkpoint

core/contracts/discovery.py

@@ -0,0 +1,30 @@
+"""Provider discovery contracts for VYRELON model intelligence."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from core.contracts.capability import ModelCapabilityProfile
+from core.contracts.quota import QuotaSnapshot
+
+
+@dataclass(frozen=True)
+class ProviderDiscoveryResult:
+    """Normalized discovery result returned by a provider adapter."""
+
+    provider_id: str
+    capabilities: tuple[ModelCapabilityProfile, ...] = ()
+    quotas: tuple[QuotaSnapshot, ...] = ()
+    source: str = "unknown"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DiscoveryError:
+    """Non-fatal discovery failure for one provider."""
+
+    provider_id: str
+    operation: str
+    message: str
+    retryable: bool = False

core/contracts/execution.py

@@ -0,0 +1,28 @@
+"""Vendor-neutral execution, verification, and review contracts."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from core.contracts.agent import AgentContract
+from core.contracts.work_unit import WorkUnit
+
+
+class AgentExecutor(Protocol):
+    def execute(self, *, agent: AgentContract, model_id: str, work_unit: WorkUnit) -> object:
+        ...
+
+
+class ResultVerifier(Protocol):
+    def verify(self, *, work_unit: WorkUnit, output: object) -> bool:
+        ...
+
+
+@dataclass(frozen=True)
+class ReviewDecision:
+    approved: bool
+    feedback: str = ""
+
+
+class ResultReviewer(Protocol):
+    def review(self, *, work_unit: WorkUnit, output: object) -> ReviewDecision:
+        ...

core/contracts/github.py

@@ -0,0 +1,74 @@
+"""Provider-neutral GitHub contracts."""
+
+from dataclasses import dataclass
+from typing import Protocol, Sequence
+
+
+@dataclass(frozen=True)
+class GitHubRepository:
+    full_name: str
+    default_branch: str
+    private: bool
+
+
+@dataclass(frozen=True)
+class GitHubBranch:
+    name: str
+    sha: str
+
+
+@dataclass(frozen=True)
+class GitHubFile:
+    path: str
+    content: str
+    sha: str
+
+
+@dataclass(frozen=True)
+class GitHubIssue:
+    number: int
+    title: str
+    url: str
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    number: int
+    title: str
+    url: str
+    head: str
+    base: str
+
+
+@dataclass(frozen=True)
+class ReviewResult:
+    success: bool
+    action: str
+
+
+@dataclass(frozen=True)
+class MergeResult:
+    merged: bool
+    sha: str | None
+    message: str
+
+
+@dataclass(frozen=True)
+class WorkflowRun:
+    id: int
+    status: str
+    conclusion: str | None = None
+
+
+class GitHubGateway(Protocol):
+    def get_repository(self, full_name: str) -> GitHubRepository: ...
+    def get_branch(self, full_name: str, branch: str) -> GitHubBranch: ...
+    def create_branch(self, full_name: str, branch: str, base: str) -> GitHubBranch: ...
+    def get_file(self, full_name: str, path: str, ref: str) -> GitHubFile: ...
+    def create_file(self, full_name: str, path: str, content: str, branch: str, message: str) -> str: ...
+    def update_file(self, full_name: str, path: str, content: str, sha: str, branch: str, message: str) -> str: ...
+    def create_issue(self, full_name: str, title: str, body: str = "") -> GitHubIssue: ...
+    def create_pull_request(self, full_name: str, title: str, body: str, head: str, base: str, draft: bool = False) -> PullRequest: ...
+    def review_pull_request(self, full_name: str, number: int, action: str, body: str = "") -> ReviewResult: ...
+    def merge_pull_request(self, full_name: str, number: int, method: str = "squash") -> MergeResult: ...
+    def list_workflows(self, full_name: str, ref: str) -> Sequence[WorkflowRun]: ...

core/contracts/handoff.py

@@ -0,0 +1,56 @@
+"""Handoff artifact contracts."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class HandoffArtifact:
+    work_unit_id: str
+    from_agent: str
+    to_agent: str
+    summary: str
+    artifacts: tuple[str, ...] = ()
+    findings: tuple[str, ...] = ()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ReviewContext:
+    """Structured input presented to a reviewer by VYRELON."""
+
+    work_unit_id: str
+    artifact_ids: tuple[str, ...] = ()
+    findings: tuple[str, ...] = ()
+    last_agent_id: str | None = None
+    review_cycle: int = 0
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ReviewResult:
+    approved: bool
+    reviewer_id: str
+    feedback: str
+
+
+@dataclass(frozen=True)
+class ArtifactContract:
+    """Durable artifact passed between VYRELON workflow stages."""
+
+    id: str
+    kind: str
+    producer_agent_id: str
+    content_ref: str
+    summary: str = ""
+    media_type: str = "text/plain"
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def validate(self) -> None:
+        for name, value in (
+            ("id", self.id),
+            ("kind", self.kind),
+            ("producer_agent_id", self.producer_agent_id),
+            ("content_ref", self.content_ref),
+        ):
+            if not value.strip():
+                raise ValueError(f"artifact {name} must not be empty")

core/contracts/health.py

@@ -0,0 +1,206 @@
+"""Persistent model health and cooldown registry for VYRELON."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class HealthStatus(StrEnum):
+    HEALTHY = "healthy"
+    RATE_LIMITED = "rate_limited"
+    QUOTA_EXHAUSTED = "quota_exhausted"
+    TEMPORARILY_UNAVAILABLE = "temporarily_unavailable"
+    AUTH_FAILED = "auth_failed"
+    DISABLED = "disabled"
+
+
+@dataclass(frozen=True)
+class ModelHealth:
+    model_id: str
+    provider_id: str
+    status: HealthStatus = HealthStatus.HEALTHY
+    consecutive_failures: int = 0
+    successes: int = 0
+    last_error: str | None = None
+    last_failure_at: datetime | None = None
+    last_success_at: datetime | None = None
+    cooldown_until: datetime | None = None
+    metadata: dict[str, Any] | None = None
+
+    @property
+    def available(self) -> bool:
+        if self.status in {HealthStatus.AUTH_FAILED, HealthStatus.DISABLED}:
+            return False
+        if self.cooldown_until is None:
+            return self.status is HealthStatus.HEALTHY
+        return self.cooldown_until <= datetime.now(timezone.utc)
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _parse_dt(value: object) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def classify_failure(exc: Exception) -> HealthStatus | None:
+    status = getattr(exc, "status_code", getattr(exc, "status", None))
+    code = str(getattr(exc, "code", "")).lower()
+    message = str(exc).lower()
+    combined = f"{code} {message}"
+    if status in {401, 403}:
+        return HealthStatus.AUTH_FAILED
+    if any(token in combined for token in (
+        "quota_exceeded", "quota exceeded", "daily quota",
+        "resource_exhausted", "resource exhausted",
+    )):
+        return HealthStatus.QUOTA_EXHAUSTED
+    if status == 429 or any(token in combined for token in (
+        "rate_limit", "rate-limit", "too_many_requests",
+    )):
+        return HealthStatus.RATE_LIMITED
+    if status in {408, 500, 502, 503, 504} or any(token in combined for token in (
+        "temporarily_unavailable", "service_unavailable",
+        "overloaded", "timeout",
+    )):
+        return HealthStatus.TEMPORARILY_UNAVAILABLE
+    return None
+
+
+class ModelHealthStore:
+    """Persist one health record per model without storing credentials."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def path_for(self, model_id: str) -> Path:
+        safe = "".join(c if c.isalnum() or c in "._-" else "_" for c in model_id)
+        return self.root / f"{safe}.json"
+
+    def save(self, health: ModelHealth) -> Path:
+        payload = {
+            "model_id": health.model_id,
+            "provider_id": health.provider_id,
+            "status": health.status.value,
+            "consecutive_failures": health.consecutive_failures,
+            "successes": health.successes,
+            "last_error": health.last_error,
+            "last_failure_at": health.last_failure_at.isoformat() if health.last_failure_at else None,
+            "last_success_at": health.last_success_at.isoformat() if health.last_success_at else None,
+            "cooldown_until": health.cooldown_until.isoformat() if health.cooldown_until else None,
+            "metadata": health.metadata or {},
+        }
+        path = self.path_for(health.model_id)
+        path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+        return path
+
+    def load(self, model_id: str) -> ModelHealth:
+        data = json.loads(self.path_for(model_id).read_text(encoding="utf-8"))
+        return ModelHealth(
+            model_id=data["model_id"],
+            provider_id=data["provider_id"],
+            status=HealthStatus(data.get("status", HealthStatus.HEALTHY.value)),
+            consecutive_failures=int(data.get("consecutive_failures", 0)),
+            successes=int(data.get("successes", 0)),
+            last_error=data.get("last_error"),
+            last_failure_at=_parse_dt(data.get("last_failure_at")),
+            last_success_at=_parse_dt(data.get("last_success_at")),
+            cooldown_until=_parse_dt(data.get("cooldown_until")),
+            metadata=dict(data.get("metadata", {})),
+        )
+
+    def exists(self, model_id: str) -> bool:
+        return self.path_for(model_id).exists()
+
+    def list_model_ids(self) -> tuple[str, ...]:
+        return tuple(sorted(path.stem for path in self.root.glob("*.json")))
+
+
+class ModelHealthRegistry:
+    """Track model failures independently from quota and quarantine unhealthy models."""
+
+    def __init__(self, store: ModelHealthStore) -> None:
+        self.store = store
+
+    def get(self, model_id: str) -> ModelHealth | None:
+        if not self.store.exists(model_id):
+            return None
+        return self.store.load(model_id)
+
+    def available(self, model_id: str) -> bool:
+        health = self.get(model_id)
+        return health is None or health.available
+
+    def record_success(self, model_id: str, provider_id: str) -> ModelHealth:
+        previous = self.get(model_id)
+        health = ModelHealth(
+            model_id=model_id,
+            provider_id=provider_id,
+            status=HealthStatus.HEALTHY,
+            consecutive_failures=0,
+            successes=(previous.successes if previous else 0) + 1,
+            last_error=None,
+            last_failure_at=previous.last_failure_at if previous else None,
+            last_success_at=_now(),
+            cooldown_until=None,
+            metadata=dict(previous.metadata or {}) if previous else {},
+        )
+        self.store.save(health)
+        return health
+
+    def record_failure(self, model_id: str, provider_id: str, exc: Exception) -> ModelHealth | None:
+        status = classify_failure(exc)
+        if status is None:
+            return None
+        previous = self.get(model_id)
+        failures = (previous.consecutive_failures if previous else 0) + 1
+        cooldown = self._cooldown(status, failures, exc)
+        health = ModelHealth(
+            model_id=model_id,
+            provider_id=provider_id,
+            status=status,
+            consecutive_failures=failures,
+            successes=previous.successes if previous else 0,
+            last_error=str(exc),
+            last_failure_at=_now(),
+            last_success_at=previous.last_success_at if previous else None,
+            cooldown_until=cooldown,
+            metadata={"failure_type": status.value},
+        )
+        self.store.save(health)
+        return health
+
+    @staticmethod
+    def _cooldown(status: HealthStatus, failures: int, exc: Exception) -> datetime | None:
+        now = _now()
+        if status is HealthStatus.AUTH_FAILED:
+            return None
+        reset_at = _parse_dt(getattr(exc, "reset_at", None))
+        if reset_at is None:
+            metadata = getattr(exc, "metadata", None)
+            if isinstance(metadata, dict):
+                reset_at = _parse_dt(metadata.get("reset_at"))
+                if reset_at is None:
+                    reset_seconds = metadata.get("retry_after") or metadata.get("reset_seconds")
+                    try:
+                        if reset_seconds is not None:
+                            reset_at = now + timedelta(seconds=float(reset_seconds))
+                    except (TypeError, ValueError):
+                        pass
+        if reset_at is not None and reset_at > now:
+            return reset_at
+        if status is HealthStatus.QUOTA_EXHAUSTED:
+            return None
+        seconds = min(300, 15 * (2 ** min(failures - 1, 4)))
+        return now + timedelta(seconds=seconds)

core/contracts/human_review.py

@@ -0,0 +1,20 @@
+"""Explicit human decisions for escalated VYRELON WorkUnits."""
+
+from enum import Enum
+
+
+class HumanReviewDecision(str, Enum):
+    """Decision applied to a WorkUnit waiting for human approval."""
+
+    APPROVE_COMPLETION = "approve_completion"
+    APPROVE_REWORK = "approve_rework"
+    REJECT = "reject"
+
+    @classmethod
+    def coerce(cls, value: "HumanReviewDecision | str") -> "HumanReviewDecision":
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(value)
+        except ValueError as exc:
+            raise ValueError(f"unsupported human review decision: {value}") from exc