techrevati-runtime 0.1.0__py3-none-any.whl

techrevati/runtime/__init__.py

@@ -0,0 +1,177 @@
+"""
+techrevati.runtime — Runtime primitives for multi-step LLM agent loops.
+
+Reliability, cost tracking, and lifecycle for multi-step agent execution.
+Zero runtime dependencies.
+
+>>> from techrevati.runtime import Orchestrator, UsageSnapshot
+>>> from techrevati.runtime import classify_exception, attempt_recovery, RecoveryContext
+>>> from techrevati.runtime import CircuitBreaker, PolicyEngine
+"""
+
+__version__ = "0.1.0"
+
+from techrevati.runtime.agent_events import (
+    AgentEvent,
+    AgentEventName,
+    AgentEventStatus,
+    AgentFailureClass,
+)
+from techrevati.runtime.agent_lifecycle import (
+    AgentRegistry,
+    AgentStatus,
+    AgentWorker,
+    AgentWorkerEvent,
+    InvalidTransitionError,
+)
+from techrevati.runtime.circuit_breaker import (
+    AsyncCircuitBreaker,
+    CircuitBreaker,
+    CircuitOpenError,
+    CircuitState,
+)
+from techrevati.runtime.guardrails import (
+    AllowAllGuardrail,
+    Guardrail,
+    GuardrailOutcome,
+    GuardrailStage,
+    GuardrailViolatedError,
+)
+from techrevati.runtime.handoffs import Handoff
+from techrevati.runtime.orchestrator import (
+    AgentSession,
+    AsyncOrchestrationSession,
+    MaxIterationsExceededError,
+    OrchestrationSession,
+    Orchestrator,
+    PermissionDeniedError,
+    TurnTimeoutError,
+)
+from techrevati.runtime.permissions import (
+    PermissionEnforcer,
+    PermissionMode,
+    PermissionOutcome,
+    PermissionPolicy,
+    RolePermissionConfig,
+)
+from techrevati.runtime.policy_engine import (
+    PhaseContext,
+    PolicyAction,
+    PolicyActionData,
+    PolicyCondition,
+    PolicyEngine,
+    PolicyRule,
+)
+from techrevati.runtime.quality_gate import (
+    QualityGate,
+    QualityGateOutcome,
+    QualityLevel,
+)
+from techrevati.runtime.retry_policy import (
+    EscalationPolicy,
+    FailureScenario,
+    RecoveryContext,
+    RecoveryEvent,
+    RecoveryRecipe,
+    RecoveryResult,
+    RecoveryStep,
+    aattempt_recovery,
+    attempt_recovery,
+    backoff_delay,
+    classify_exception,
+    next_provider,
+    recipe_for,
+    smaller_context_budget,
+)
+from techrevati.runtime.sinks import (
+    DEFAULT_RING_CAPACITY,
+    EventSink,
+    NoopEventSink,
+    NoopUsageSink,
+    RingBufferEventSink,
+    RingBufferUsageSink,
+    UsageSink,
+)
+from techrevati.runtime.usage_tracking import (
+    PRICING_TABLE,
+    BudgetExceededError,
+    ModelPricing,
+    UsageSnapshot,
+    UsageTracker,
+    has_pricing,
+    load_pricing_from_file,
+    register_pricing,
+)
+
+__all__ = [
+    "AgentEvent",
+    "AgentEventName",
+    "AgentEventStatus",
+    "AgentFailureClass",
+    "AgentRegistry",
+    "AgentSession",
+    "AgentStatus",
+    "AgentWorker",
+    "AgentWorkerEvent",
+    "AllowAllGuardrail",
+    "AsyncCircuitBreaker",
+    "AsyncOrchestrationSession",
+    "BudgetExceededError",
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "CircuitState",
+    "DEFAULT_RING_CAPACITY",
+    "EscalationPolicy",
+    "EventSink",
+    "FailureScenario",
+    "Guardrail",
+    "GuardrailOutcome",
+    "GuardrailStage",
+    "GuardrailViolatedError",
+    "Handoff",
+    "InvalidTransitionError",
+    "MaxIterationsExceededError",
+    "ModelPricing",
+    "NoopEventSink",
+    "NoopUsageSink",
+    "OrchestrationSession",
+    "Orchestrator",
+    "PermissionDeniedError",
+    "PermissionEnforcer",
+    "PermissionMode",
+    "PermissionOutcome",
+    "PermissionPolicy",
+    "PhaseContext",
+    "PolicyAction",
+    "PolicyActionData",
+    "PolicyCondition",
+    "PolicyEngine",
+    "PolicyRule",
+    "PRICING_TABLE",
+    "QualityGate",
+    "QualityGateOutcome",
+    "QualityLevel",
+    "RecoveryContext",
+    "RecoveryEvent",
+    "RecoveryRecipe",
+    "RecoveryResult",
+    "RecoveryStep",
+    "RingBufferEventSink",
+    "RingBufferUsageSink",
+    "RolePermissionConfig",
+    "TurnTimeoutError",
+    "UsageSink",
+    "UsageSnapshot",
+    "UsageTracker",
+    "__version__",
+    "aattempt_recovery",
+    "attempt_recovery",
+    "backoff_delay",
+    "classify_exception",
+    "has_pricing",
+    "load_pricing_from_file",
+    "next_provider",
+    "recipe_for",
+    "register_pricing",
+    "smaller_context_budget",
+]

techrevati/runtime/agent_events.py

@@ -0,0 +1,270 @@
+"""
+Agent Events — Typed lifecycle events with a failure taxonomy.
+
+Provides a structured event schema for agent execution. Events are
+JSON-serializable and include both an 'event' (full path) and 'type'
+(short tail) field so they can be routed by either consumers.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+
+class AgentEventName(str, Enum):
+    """Typed event names for agent and phase lifecycle."""
+
+    # Agent lifecycle
+    AGENT_STARTED = "agent.started"
+    AGENT_READY = "agent.ready"
+    AGENT_BLOCKED = "agent.blocked"
+    AGENT_TOOL_CALLED = "agent.tool_called"
+    AGENT_TOOL_COMPLETED = "agent.tool_completed"
+    AGENT_COMPLETED = "agent.completed"
+    AGENT_FAILED = "agent.failed"
+    # Phase lifecycle
+    PHASE_STARTED = "phase.started"
+    PHASE_COMPLETED = "phase.completed"
+    PHASE_GATE_EVALUATED = "phase.gate_evaluated"
+    PHASE_GATE_PASSED = "phase.gate_passed"
+    PHASE_GATE_FAILED = "phase.gate_failed"
+    # Recovery
+    RECOVERY_ATTEMPTED = "agent.recovery.attempted"
+    RECOVERY_SUCCEEDED = "agent.recovery.succeeded"
+    RECOVERY_FAILED = "agent.recovery.failed"
+    RECOVERY_ESCALATED = "agent.recovery.escalated"
+    RECOVERY_PROVIDER_SWITCHED = "agent.recovery.provider_switched"
+    # Hooks
+    HOOK_PRE_TOOL = "hook.pre_tool"
+    HOOK_POST_TOOL = "hook.post_tool"
+
+
+class AgentEventStatus(str, Enum):
+    """Current status at time of event emission."""
+
+    RUNNING = "running"
+    READY = "ready"
+    BLOCKED = "blocked"
+    GREEN = "green"
+    RED = "red"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class AgentFailureClass(str, Enum):
+    """Failure taxonomy for structured error classification."""
+
+    LLM_TIMEOUT = "llm_timeout"
+    LLM_ERROR = "llm_error"
+    TOOL_ERROR = "tool_error"
+    CONTEXT_OVERFLOW = "context_overflow"
+    RATE_LIMIT = "rate_limit"
+    DEPENDENCY_FAILED = "dependency_failed"
+    MEMORY_CORRUPTION = "memory_corruption"
+    VALIDATION_ERROR = "validation_error"
+    PROMPT_REJECTION = "prompt_rejection"
+    UNKNOWN = "unknown"
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+@dataclass(frozen=True)
+class AgentEvent:
+    """A typed lifecycle event for agent orchestration."""
+
+    event: AgentEventName
+    status: AgentEventStatus
+    emitted_at: str = field(default_factory=_now_iso)
+    role: str | None = None
+    phase: str | None = None
+    project_id: int | None = None
+    failure_class: AgentFailureClass | None = None
+    detail: str | None = None
+    data: dict[str, Any] | None = None
+
+    # -- Builder methods (return new instances) --
+
+    def with_failure_class(self, fc: AgentFailureClass) -> AgentEvent:
+        return replace(self, failure_class=fc)
+
+    def with_detail(self, detail: str) -> AgentEvent:
+        return replace(self, detail=detail)
+
+    def with_data(self, data: dict[str, Any]) -> AgentEvent:
+        return replace(self, data=data)
+
+    def with_project(self, project_id: int) -> AgentEvent:
+        return replace(self, project_id=project_id)
+
+    # -- Convenience constructors --
+
+    @classmethod
+    def started(cls, role: str, phase: str) -> AgentEvent:
+        return cls(
+            event=AgentEventName.AGENT_STARTED,
+            status=AgentEventStatus.RUNNING,
+            role=role,
+            phase=phase,
+        )
+
+    @classmethod
+    def completed(cls, role: str, phase: str, detail: str | None = None) -> AgentEvent:
+        return cls(
+            event=AgentEventName.AGENT_COMPLETED,
+            status=AgentEventStatus.COMPLETED,
+            role=role,
+            phase=phase,
+            detail=detail,
+        )
+
+    @classmethod
+    def failed(
+        cls,
+        role: str,
+        phase: str,
+        failure_class: AgentFailureClass,
+        detail: str | None = None,
+    ) -> AgentEvent:
+        return cls(
+            event=AgentEventName.AGENT_FAILED,
+            status=AgentEventStatus.FAILED,
+            role=role,
+            phase=phase,
+            failure_class=failure_class,
+            detail=detail,
+        )
+
+    @classmethod
+    def phase_started(cls, phase: str) -> AgentEvent:
+        return cls(
+            event=AgentEventName.PHASE_STARTED,
+            status=AgentEventStatus.RUNNING,
+            phase=phase,
+        )
+
+    @classmethod
+    def gate_passed(cls, phase: str, detail: str | None = None) -> AgentEvent:
+        return cls(
+            event=AgentEventName.PHASE_GATE_PASSED,
+            status=AgentEventStatus.GREEN,
+            phase=phase,
+            detail=detail,
+        )
+
+    @classmethod
+    def gate_failed(cls, phase: str, detail: str | None = None) -> AgentEvent:
+        return cls(
+            event=AgentEventName.PHASE_GATE_FAILED,
+            status=AgentEventStatus.RED,
+            phase=phase,
+            detail=detail,
+        )
+
+    @classmethod
+    def recovery_attempted(
+        cls, role: str, phase: str, detail: str | None = None
+    ) -> AgentEvent:
+        return cls(
+            event=AgentEventName.RECOVERY_ATTEMPTED,
+            status=AgentEventStatus.RUNNING,
+            role=role,
+            phase=phase,
+            detail=detail,
+        )
+
+    # -- Serialization --
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON-serializable dict. Includes 'type' for backward compat."""
+        d: dict[str, Any] = {
+            "event": self.event.value,
+            "type": self.event.value.split(".")[-1],  # backward compat
+            "status": self.status.value,
+            "emitted_at": self.emitted_at,
+        }
+        if self.role is not None:
+            d["role"] = self.role
+        if self.phase is not None:
+            d["phase"] = self.phase
+        if self.project_id is not None:
+            d["project_id"] = self.project_id
+        if self.failure_class is not None:
+            d["failure_class"] = self.failure_class.value
+        if self.detail is not None:
+            d["detail"] = self.detail
+        if self.data is not None:
+            d["data"] = self.data
+        return d
+
+    def to_json(self) -> str:
+        """JSON string representation."""
+        return json.dumps(self.to_dict(), ensure_ascii=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentEvent:
+        """Reconstruct AgentEvent from dict. Handles enum conversions."""
+        event_raw = data.get("event")
+        if isinstance(event_raw, AgentEventName):
+            event = event_raw
+        elif isinstance(event_raw, str):
+            event = AgentEventName(event_raw)
+        else:
+            raise ValueError(f"event field missing or invalid: {event_raw!r}")
+
+        status_raw = data.get("status")
+        if isinstance(status_raw, AgentEventStatus):
+            status = status_raw
+        elif isinstance(status_raw, str):
+            status = AgentEventStatus(status_raw)
+        else:
+            raise ValueError(f"status field missing or invalid: {status_raw!r}")
+
+        failure_class: AgentFailureClass | None = None
+        fc_raw = data.get("failure_class")
+        if isinstance(fc_raw, AgentFailureClass):
+            failure_class = fc_raw
+        elif isinstance(fc_raw, str):
+            failure_class = AgentFailureClass(fc_raw)
+
+        return cls(
+            event=event,
+            status=status,
+            emitted_at=data.get("emitted_at", _now_iso()),
+            role=data.get("role"),
+            phase=data.get("phase"),
+            project_id=data.get("project_id"),
+            failure_class=failure_class,
+            detail=data.get("detail"),
+            data=data.get("data"),
+        )
+
+    @classmethod
+    def from_json(cls, s: str) -> AgentEvent:
+        """Reconstruct AgentEvent from JSON string."""
+        data = json.loads(s)
+        return cls.from_dict(data)
+
+    def to_otel_attributes(self) -> dict[str, str | int | float]:
+        """Convert to OpenTelemetry semantic convention attributes."""
+        attrs: dict[str, str | int | float] = {
+            "agent.event": self.event.value,
+            "agent.event.status": self.status.value,
+            "agent.event.timestamp": self.emitted_at,
+        }
+        if self.role is not None:
+            attrs["agent.role"] = self.role
+        if self.phase is not None:
+            attrs["agent.phase"] = self.phase
+        if self.project_id is not None:
+            attrs["agent.project_id"] = self.project_id
+        if self.failure_class is not None:
+            attrs["agent.failure_class"] = self.failure_class.value
+        if self.detail is not None:
+            attrs["agent.detail"] = self.detail
+        return attrs

techrevati/runtime/agent_lifecycle.py

@@ -0,0 +1,224 @@
+"""
+Agent Lifecycle — Agent state machine with event log.
+
+Explicit agent lifecycle states with validated transitions. Every
+state change is recorded as an event with timestamp and detail.
+AgentRegistry provides thread-safe concurrent access.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger("techrevati.runtime.lifecycle")
+logger.addHandler(logging.NullHandler())
+
+
+class AgentStatus(str, Enum):
+    """Agent lifecycle states with valid transition paths."""
+
+    IDLE = "idle"
+    INITIALIZING = "initializing"
+    WAITING_FOR_INPUT = "waiting_for_input"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+# Valid state transitions. CANCELLED is reachable from any non-terminal state
+# (caller-driven cancellation, asyncio.CancelledError, timeout, etc.).
+_VALID_TRANSITIONS: dict[AgentStatus, set[AgentStatus]] = {
+    AgentStatus.IDLE: {
+        AgentStatus.INITIALIZING,
+        AgentStatus.FAILED,
+        AgentStatus.CANCELLED,
+    },
+    AgentStatus.INITIALIZING: {
+        AgentStatus.WAITING_FOR_INPUT,
+        AgentStatus.RUNNING,
+        AgentStatus.FAILED,
+        AgentStatus.CANCELLED,
+    },
+    AgentStatus.WAITING_FOR_INPUT: {
+        AgentStatus.RUNNING,
+        AgentStatus.FAILED,
+        AgentStatus.CANCELLED,
+    },
+    AgentStatus.RUNNING: {
+        AgentStatus.WAITING_FOR_INPUT,
+        AgentStatus.COMPLETED,
+        AgentStatus.FAILED,
+        AgentStatus.CANCELLED,
+    },
+    AgentStatus.COMPLETED: set(),  # terminal
+    AgentStatus.FAILED: set(),  # terminal
+    AgentStatus.CANCELLED: set(),  # terminal
+}
+
+
+class InvalidTransitionError(Exception):
+    """Raised when an invalid state transition is attempted."""
+
+    def __init__(self, current: AgentStatus, target: AgentStatus) -> None:
+        self.current = current
+        self.target = target
+        super().__init__(f"Invalid transition: {current.value} → {target.value}")
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+@dataclass(frozen=True)
+class AgentWorkerEvent:
+    """Immutable record of a state transition."""
+
+    seq: int
+    kind: str
+    status: str
+    detail: str | None
+    timestamp: str
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "seq": self.seq,
+            "kind": self.kind,
+            "status": self.status,
+            "timestamp": self.timestamp,
+        }
+        if self.detail:
+            d["detail"] = self.detail
+        return d
+
+
+@dataclass
+class AgentWorker:
+    """Tracks an agent's lifecycle through execution."""
+
+    worker_id: str
+    role: str
+    phase: str
+    project_id: int | None = None
+    status: AgentStatus = AgentStatus.IDLE
+    events: list[AgentWorkerEvent] = field(default_factory=list)
+    retry_count: int = 0
+    last_error: dict[str, Any] | None = None
+    provider_used: str | None = None
+    created_at: str = field(default_factory=_now_iso)
+    updated_at: str = field(default_factory=_now_iso)
+
+    def transition(
+        self, new_status: AgentStatus, detail: str | None = None
+    ) -> AgentWorkerEvent:
+        """Validate and execute a state transition. Returns the new event."""
+        valid = _VALID_TRANSITIONS.get(self.status, set())
+        if new_status not in valid:
+            raise InvalidTransitionError(self.status, new_status)
+
+        event = AgentWorkerEvent(
+            seq=len(self.events) + 1,
+            kind=new_status.value,
+            status=new_status.value,
+            detail=detail,
+            timestamp=_now_iso(),
+        )
+        self.events.append(event)
+        self.status = new_status
+        self.updated_at = event.timestamp
+
+        if new_status == AgentStatus.FAILED and detail:
+            self.last_error = {"message": detail, "timestamp": event.timestamp}
+
+        return event
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in (
+            AgentStatus.COMPLETED,
+            AgentStatus.FAILED,
+            AgentStatus.CANCELLED,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "worker_id": self.worker_id,
+            "role": self.role,
+            "phase": self.phase,
+            "project_id": self.project_id,
+            "status": self.status.value,
+            "retry_count": self.retry_count,
+            "last_error": self.last_error,
+            "provider_used": self.provider_used,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "events": [e.to_dict() for e in self.events],
+        }
+
+
+class AgentRegistry:
+    """Thread-safe registry of active AgentWorker instances."""
+
+    def __init__(self) -> None:
+        self._workers: dict[str, AgentWorker] = {}
+        self._lock = threading.Lock()
+
+    def create(
+        self,
+        role: str,
+        phase: str,
+        project_id: int | None = None,
+    ) -> AgentWorker:
+        worker_id = f"{role}-{phase}-{uuid.uuid4().hex[:8]}"
+        worker = AgentWorker(
+            worker_id=worker_id,
+            role=role,
+            phase=phase,
+            project_id=project_id,
+        )
+        with self._lock:
+            self._workers[worker_id] = worker
+        return worker
+
+    def get(self, worker_id: str) -> AgentWorker | None:
+        with self._lock:
+            return self._workers.get(worker_id)
+
+    def transition(
+        self,
+        worker_id: str,
+        status: AgentStatus,
+        detail: str | None = None,
+    ) -> AgentWorker:
+        with self._lock:
+            worker = self._workers.get(worker_id)
+            if worker is None:
+                raise KeyError(f"Worker not found: {worker_id}")
+            worker.transition(status, detail)
+            return worker
+
+    def list_active(self) -> list[AgentWorker]:
+        with self._lock:
+            return [w for w in self._workers.values() if not w.is_terminal]
+
+    def get_by_role_phase(self, role: str, phase: str) -> AgentWorker | None:
+        with self._lock:
+            for w in self._workers.values():
+                if w.role == role and w.phase == phase and not w.is_terminal:
+                    return w
+            return None
+
+    def get_by_project(self, project_id: int) -> list[AgentWorker]:
+        with self._lock:
+            return [w for w in self._workers.values() if w.project_id == project_id]
+
+    def clear(self) -> None:
+        """Clear all workers (for testing)."""
+        with self._lock:
+            self._workers.clear()