multiagentos 0.4.0__py3-none-any.whl

core/contracts/ide.py

@@ -0,0 +1,113 @@
+"""Provider-neutral IDE integration contracts for VYRELON."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol
+
+
+class IDEKind(StrEnum):
+    XCODE = "xcode"
+    VS_CODE = "vs_code"
+    ANDROID_STUDIO = "android_studio"
+
+
+class IDEEventKind(StrEnum):
+    CONTEXT_CHANGED = "context_changed"
+    SELECTION_CHANGED = "selection_changed"
+    FILE_OPENED = "file_opened"
+    FILE_SAVED = "file_saved"
+    WORKSPACE_OPENED = "workspace_opened"
+
+
+class IDECommandKind(StrEnum):
+    OPEN_WORKSPACE = "open_workspace"
+    OPEN_FILE = "open_file"
+    INSERT_TEXT = "insert_text"
+    REPLACE_SELECTION = "replace_selection"
+    RUN_COMMAND = "run_command"
+    START_WORK = "start_work"
+    SHOW_MESSAGE = "show_message"
+    SHOW_DIFF = "show_diff"
+
+
+@dataclass(frozen=True)
+class IDEContext:
+    """Normalized editor/workspace context supplied by an IDE adapter."""
+
+    kind: IDEKind
+    project_root: str
+    workspace_id: str | None = None
+    file_path: str | None = None
+    selection_start: int | None = None
+    selection_end: int | None = None
+    language_id: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class IDEEvent:
+    """Normalized event sent from an IDE adapter to VYRELON."""
+
+    kind: IDEEventKind
+    context: IDEContext
+    payload: dict[str, object] = field(default_factory=dict)
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class IDEWorkRequest:
+    """Explicit user/IDE request that asks VYRELON to execute agent work."""
+
+    context: IDEContext
+    objective: str
+    agent_id: str
+    model_ids: tuple[str, ...] = ()
+    apply_changes: bool = False
+    validation_commands: tuple[str, ...] = ()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class IDECommand:
+    """Normalized command sent from VYRELON to an IDE adapter."""
+
+    kind: IDECommandKind
+    arguments: dict[str, object] = field(default_factory=dict)
+    context: IDEContext | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class IDECommandResult:
+    """Normalized result returned by an IDE adapter."""
+
+    ok: bool
+    output: object = None
+    error: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+class IDEAdapter(Protocol):
+    """Thin IDE-specific bridge; VYRELON never imports an IDE SDK."""
+
+    @property
+    def kind(self) -> IDEKind:
+        ...
+
+    def capabilities(self) -> frozenset[str]:
+        ...
+
+    def context(self) -> IDEContext:
+        ...
+
+    def execute(self, command: IDECommand) -> IDECommandResult:
+        ...
+
+
+class IDEEventSink(Protocol):
+    """Consumer for normalized IDE events flowing into VYRELON."""
+
+    def handle(self, event: IDEEvent) -> object:
+        ...

core/contracts/mcp.py

@@ -0,0 +1,76 @@
+"""Provider-neutral MCP runtime contracts for VYRELON."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from core.contracts.vyrelon_runtime import ToolSideEffect
+
+@dataclass(frozen=True)
+class MCPServerSpec:
+    id: str
+    command: tuple[str, ...] = ()
+    args: tuple[str, ...] = ()
+    env: dict[str, str] = field(default_factory=dict)
+    transport: str = "stdio"
+    endpoint: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+    enabled: bool = True
+    metadata: dict[str, object] = field(default_factory=dict)
+    source: str = "built-in"
+    cost_policy: str = "no_external_billing"
+    requires_explicit_enable: bool = False
+
+@dataclass(frozen=True)
+class MCPSession:
+    id: str
+    server_id: str
+    protocol_version: str = "2025-03-26"
+    metadata: dict[str, object] = field(default_factory=dict)
+
+@dataclass(frozen=True)
+class MCPTool:
+    name: str
+    description: str = ""
+    input_schema: dict[str, object] = field(default_factory=dict)
+    server_id: str = ""
+    side_effect: ToolSideEffect = ToolSideEffect.READ
+    permissions: frozenset[str] = frozenset()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+@dataclass(frozen=True)
+class MCPToolCall:
+    server_id: str
+    tool_name: str
+    arguments: dict[str, object] = field(default_factory=dict)
+    session_id: str | None = None
+
+@dataclass(frozen=True)
+class MCPToolResult:
+    server_id: str
+    tool_name: str
+    content: tuple[object, ...] = ()
+    is_error: bool = False
+    raw: object = None
+
+@dataclass(frozen=True)
+class MCPToolProfile:
+    """Agent-facing MCP access policy."""
+    id: str
+    server_ids: frozenset[str] = frozenset()
+    allowed_tools: frozenset[str] = frozenset()
+    denied_tools: frozenset[str] = frozenset()
+    required_permissions: frozenset[str] = frozenset()
+    allowed_side_effects: frozenset[ToolSideEffect] = frozenset({ToolSideEffect.READ})
+    metadata: dict[str, object] = field(default_factory=dict)
+    tool_side_effects: dict[str, ToolSideEffect] = field(default_factory=dict)
+
+    def allows(self, tool: MCPTool, permissions: frozenset[str] = frozenset()) -> bool:
+        if self.server_ids and tool.server_id not in self.server_ids:
+            return False
+        qualified = f"{tool.server_id}:{tool.name}"
+        if qualified in self.denied_tools or tool.name in self.denied_tools:
+            return False
+        if self.allowed_tools and qualified not in self.allowed_tools and tool.name not in self.allowed_tools:
+            return False
+        effective_side_effect = self.tool_side_effects.get(qualified, self.tool_side_effects.get(tool.name, tool.side_effect))
+        if effective_side_effect not in self.allowed_side_effects:
+            return False
+        return self.required_permissions.issubset(permissions) and tool.permissions.issubset(permissions)

core/contracts/model_runtime.py

@@ -0,0 +1,25 @@
+"""Provider-neutral model invocation contracts."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from core.contracts.ai import ModelSpec
+
+
+@dataclass(frozen=True)
+class ModelRequest:
+    prompt: str
+    system: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ModelResponse:
+    text: str
+    model_id: str
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+class ModelAdapter(Protocol):
+    def generate(self, model: ModelSpec, request: ModelRequest) -> ModelResponse:
+        ...

core/contracts/planning.py

@@ -0,0 +1,25 @@
+"""Provider-neutral planning contracts."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PlanStep:
+    id: str
+    objective: str
+    agent_id: str | None = None
+    depends_on: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class WorkPlan:
+    work_unit_id: str
+    objective: str
+    steps: tuple[PlanStep, ...]
+
+    def validate(self) -> None:
+        known = {step.id for step in self.steps}
+        for step in self.steps:
+            missing = set(step.depends_on) - known
+            if missing:
+                raise ValueError(f"Unknown plan dependencies: {sorted(missing)}")

core/contracts/profile.py

@@ -0,0 +1,66 @@
+"""Technology, project, and agent profile contracts for VYRELON."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ProfileSpec:
+    id: str
+    display_name: str
+    detect_files: frozenset[str] = frozenset()
+    detect_markers: frozenset[str] = frozenset()
+    roles: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class DetectionResult:
+    profile_id: str
+    confidence: float
+    evidence: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    """Stable agent identity derived from a project technology profile."""
+
+    id: str
+    role: str
+    profile_ids: tuple[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)
+
+    def to_contract(self):
+        from core.contracts.agent import AgentContract
+
+        return AgentContract(
+            id=self.id,
+            role=self.role,
+            capabilities=self.capabilities,
+            tools=self.tools,
+            permissions=self.permissions,
+            model_ids=self.model_ids,
+            metadata={
+                **self.metadata,
+                "profiles": list(self.profile_ids),
+                "agent_profile_id": self.id,
+            },
+            kind="profile",
+        )
+
+
+@dataclass(frozen=True)
+class ProjectProfile:
+    """Resolved project identity shared by VYRELON integrations."""
+
+    id: str
+    root: str
+    technology_profile_ids: tuple[str, ...] = ()
+    agent_profile_ids: tuple[str, ...] = ()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    @property
+    def primary_technology_profile(self) -> str | None:
+        return self.technology_profile_ids[0] if self.technology_profile_ids else None

core/contracts/quota.py

@@ -0,0 +1,62 @@
+"""Provider-neutral quota and rate-limit contracts for VYRELON."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+
+class QuotaConfidence(StrEnum):
+    ACTUAL = "actual"
+    OBSERVED = "observed"
+    ESTIMATED = "estimated"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class QuotaDimension:
+    """One quota/rate-limit dimension such as requests or tokens."""
+
+    name: str
+    limit: int | float | None = None
+    used: int | float | None = None
+    remaining: int | float | None = None
+    reset_at: datetime | None = None
+    window_seconds: int | None = None
+    confidence: QuotaConfidence = QuotaConfidence.UNKNOWN
+    source: str = "unknown"
+
+    @property
+    def utilization(self) -> float | None:
+        if self.limit is None or self.limit <= 0 or self.used is None:
+            return None
+        return min(1.0, max(0.0, float(self.used) / float(self.limit)))
+
+
+@dataclass(frozen=True)
+class QuotaSnapshot:
+    """Latest quota intelligence for one configured model."""
+
+    model_id: str
+    provider_id: str
+    observed_at: datetime
+    dimensions: tuple[QuotaDimension, ...] = ()
+    scope: str = "model"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def dimension(self, name: str) -> QuotaDimension | None:
+        for item in self.dimensions:
+            if item.name == name:
+                return item
+        return None
+
+    @property
+    def confidence(self) -> QuotaConfidence:
+        if any(item.confidence is QuotaConfidence.ACTUAL for item in self.dimensions):
+            return QuotaConfidence.ACTUAL
+        if any(item.confidence is QuotaConfidence.ESTIMATED for item in self.dimensions):
+            return QuotaConfidence.ESTIMATED
+        if any(item.confidence is QuotaConfidence.OBSERVED for item in self.dimensions):
+            return QuotaConfidence.OBSERVED
+        return QuotaConfidence.UNKNOWN

core/contracts/repository.py

@@ -0,0 +1,34 @@
+"""Repository-level contracts for VYRELON."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class RepositoryCheckpoint:
+    id: str
+    project_root: str
+    marker: str
+    status: str
+    diff: str
+    created_at: str
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RepositoryEvidence:
+    checkpoint_id: str | None
+    git_status: str
+    git_diff: str
+    workflows: tuple[object, ...] = ()
+    validation: dict[str, object] | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RecoveryResult:
+    checkpoint_id: str
+    restored: bool
+    output: str
+    error: str = ""

core/contracts/resume.py

@@ -0,0 +1,55 @@
+"""Durable context required to resume a VYRELON workflow."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WorkflowResumeContext:
+    """Serializable execution context recorded before a resumable boundary."""
+
+    workflow: str
+    work_unit_id: str
+    review_cycle: int
+    max_review_cycles: int
+    developer_id: str
+    tester_id: str
+    reviewer_ids: tuple[str, ...] = ()
+    model_ids: tuple[str, ...] = ()
+    artifact_ids: tuple[str, ...] = ()
+    findings: tuple[str, ...] = ()
+    last_agent_id: str | None = None
+
+    def to_metadata(self) -> dict[str, object]:
+        return {
+            "workflow": self.workflow,
+            "work_unit_id": self.work_unit_id,
+            "review_cycle": self.review_cycle,
+            "max_review_cycles": self.max_review_cycles,
+            "developer_id": self.developer_id,
+            "tester_id": self.tester_id,
+            "reviewer_ids": list(self.reviewer_ids),
+            "model_ids": list(self.model_ids),
+            "artifact_ids": list(self.artifact_ids),
+            "findings": list(self.findings),
+            "last_agent_id": self.last_agent_id,
+        }
+
+    @classmethod
+    def from_metadata(cls, data: dict[str, object]) -> "WorkflowResumeContext":
+        return cls(
+            workflow=str(data["workflow"]),
+            work_unit_id=str(data["work_unit_id"]),
+            review_cycle=int(data["review_cycle"]),
+            max_review_cycles=int(data["max_review_cycles"]),
+            developer_id=str(data["developer_id"]),
+            tester_id=str(data["tester_id"]),
+            reviewer_ids=tuple(str(v) for v in data.get("reviewer_ids", ())),
+            model_ids=tuple(str(v) for v in data.get("model_ids", ())),
+            artifact_ids=tuple(str(v) for v in data.get("artifact_ids", ())),
+            findings=tuple(str(v) for v in data.get("findings", ())),
+            last_agent_id=(
+                str(data["last_agent_id"])
+                if data.get("last_agent_id") is not None
+                else None
+            ),
+        )

core/contracts/runtime.py

@@ -0,0 +1,19 @@
+"""Runtime contracts for executing work without coupling to a vendor."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from core.contracts.agent import AgentContract
+from core.contracts.work_unit import WorkUnit
+
+
+@dataclass(frozen=True)
+class ExecutionRequest:
+    agent: AgentContract
+    model_id: str
+    work_unit: WorkUnit
+
+
+class RuntimeExecutor(Protocol):
+    def execute(self, request: ExecutionRequest) -> object:
+        ...

core/contracts/vyrelon_runtime.py

@@ -0,0 +1,118 @@
+"""Provider-neutral runtime contracts for the VYRELON core."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol
+
+
+class ToolSideEffect(StrEnum):
+    READ = "read"
+    WRITE = "write"
+    EXECUTE = "execute"
+    NETWORK = "network"
+
+
+class RuntimeEventKind(StrEnum):
+    REQUEST = "request"
+    DELTA = "delta"
+    REASONING = "reasoning"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    MESSAGE = "message"
+    USAGE = "usage"
+    ERROR = "error"
+    COMPLETED = "completed"
+
+
+@dataclass(frozen=True)
+class SessionSpec:
+    """Continuity policy for an active VYRELON development session."""
+
+    id: str
+    project_root: str
+    agent_id: str | None = None
+    model_id: str | None = None
+    checkpoint_id: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass
+class SessionState:
+    """Persisted development-session state spanning multiple WorkUnits."""
+
+    spec: SessionSpec
+    work_unit_ids: list[str] = field(default_factory=list)
+    status: str = "active"
+    metadata: dict[str, object] = field(default_factory=dict)
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """Explicit executable capability exposed to an agent."""
+
+    id: str
+    description: str
+    side_effect: ToolSideEffect = ToolSideEffect.READ
+    permissions: frozenset[str] = frozenset()
+    input_schema: dict[str, object] = field(default_factory=dict)
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ToolRequest:
+    """Normalized request to invoke a VYRELON tool."""
+
+    tool_id: str
+    arguments: dict[str, object] = field(default_factory=dict)
+    session_id: str | None = None
+    work_unit_id: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """Normalized result returned by a VYRELON tool."""
+
+    tool_id: str
+    ok: bool
+    output: object = None
+    error: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RuntimeEvent:
+    """Normalized event emitted by an AI, tool, or execution runtime."""
+
+    kind: RuntimeEventKind
+    session_id: str | None = None
+    work_unit_id: str | None = None
+    payload: object = None
+    sequence: int | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+class ProtocolAdapter(Protocol):
+    """Translate between provider wire formats and VYRELON requests/events."""
+
+    def encode_request(self, request: object) -> object:
+        ...
+
+    def decode_event(self, payload: object) -> RuntimeEvent:
+        ...
+
+
+@dataclass(frozen=True)
+class FallbackPolicy:
+    """Ordered model/provider fallback behavior."""
+
+    model_ids: tuple[str, ...] = ()
+    max_attempts: int | None = None
+    retryable_errors: frozenset[str] = frozenset()
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def candidates(self) -> tuple[str, ...]:
+        if self.max_attempts is None:
+            return self.model_ids
+        return self.model_ids[: max(self.max_attempts, 0)]

core/contracts/work_unit.py

@@ -0,0 +1,48 @@
+"""Provider-neutral work unit contract for VYRELON."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+class WorkStatus(str, Enum):
+    PENDING = "pending"
+    PLANNING = "planning"
+    EXECUTING = "executing"
+    VERIFYING = "verifying"
+    REVIEWING = "reviewing"
+    WAITING_HUMAN_APPROVAL = "waiting_human_approval"
+    HANDOFF = "handoff"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+_ALLOWED_TRANSITIONS: dict[WorkStatus, frozenset[WorkStatus]] = {
+    WorkStatus.PENDING: frozenset({WorkStatus.PLANNING, WorkStatus.EXECUTING, WorkStatus.FAILED}),
+    WorkStatus.PLANNING: frozenset({WorkStatus.EXECUTING, WorkStatus.FAILED}),
+    WorkStatus.EXECUTING: frozenset({WorkStatus.VERIFYING, WorkStatus.COMPLETED, WorkStatus.FAILED}),
+    WorkStatus.VERIFYING: frozenset({WorkStatus.EXECUTING, WorkStatus.REVIEWING, WorkStatus.HANDOFF, WorkStatus.COMPLETED, WorkStatus.FAILED}),
+    WorkStatus.REVIEWING: frozenset({WorkStatus.EXECUTING, WorkStatus.WAITING_HUMAN_APPROVAL, WorkStatus.HANDOFF, WorkStatus.COMPLETED, WorkStatus.FAILED}),
+    WorkStatus.WAITING_HUMAN_APPROVAL: frozenset({WorkStatus.EXECUTING, WorkStatus.HANDOFF, WorkStatus.COMPLETED, WorkStatus.FAILED}),
+    WorkStatus.HANDOFF: frozenset({WorkStatus.EXECUTING, WorkStatus.COMPLETED, WorkStatus.FAILED}),
+    WorkStatus.COMPLETED: frozenset(),
+    WorkStatus.FAILED: frozenset({WorkStatus.EXECUTING}),
+}
+
+@dataclass
+class WorkUnit:
+    id: str
+    objective: str
+    status: WorkStatus = WorkStatus.PENDING
+    inputs: dict[str, object] = field(default_factory=dict)
+    artifacts: list[str] = field(default_factory=list)
+    assigned_agents: list[str] = field(default_factory=list)
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def assign(self, agent_id: str) -> None:
+        if agent_id not in self.assigned_agents:
+            self.assigned_agents.append(agent_id)
+
+    def transition(self, status: WorkStatus) -> None:
+        if status == self.status:
+            return
+        if status not in _ALLOWED_TRANSITIONS[self.status]:
+            raise ValueError(f"Invalid WorkUnit transition: {self.status.value} -> {status.value}")
+        self.status = status

core/delegation.py

@@ -0,0 +1,33 @@
+"""Agent delegation engine for VYRELON."""
+
+from dataclasses import dataclass
+
+from core.contracts.agent import AgentContract
+from core.contracts.ai import ModelSpec
+from core.contracts.work_unit import WorkStatus, WorkUnit
+from core.routing import AIRouter, Assignment, RoutingStrategy
+
+
+@dataclass(frozen=True)
+class Delegation:
+    work_unit_id: str
+    agent_id: str
+    assignment: Assignment
+
+
+class DelegationEngine:
+    def __init__(self, router: AIRouter | None = None) -> None:
+        self.router = router or AIRouter()
+
+    def delegate(
+        self,
+        work_unit: WorkUnit,
+        agent: AgentContract,
+        models: list[ModelSpec],
+        preferred_model_ids: list[str] | None = None,
+        strategy: RoutingStrategy | str = RoutingStrategy.POOL,
+    ) -> Delegation:
+        assignment = self.router.assign(agent, models, preferred_model_ids, strategy)
+        work_unit.assign(agent.id)
+        work_unit.transition(WorkStatus.EXECUTING)
+        return Delegation(work_unit.id, agent.id, assignment)