amacs 0.2.0__py3-none-any.whl

amacs/__init__.py

@@ -0,0 +1,88 @@
+"""AMACS — Adaptive Multi-Agent Coordination System.
+
+Add multi-agent AI coordination to any function with a single decorator::
+
+    from amacs import amacs
+
+    @amacs(max_agents=8, strategy="performance")
+    def research_task(topic: str) -> str:
+        return f"Research on {topic}"
+
+    result = research_task("Renewable Energy")
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+from amacs.agents.base_agent import AgentResult, BaseAgent, SubTask
+from amacs.communication import CommunicationBus, LogEntry
+from amacs.config import AMACSConfig, Strategy
+from amacs.decorator import amacs
+from amacs.exceptions import (
+    AdaptationError,
+    AgentError,
+    AgentTimeoutError,
+    AggregationError,
+    AMACSError,
+    CommunicationError,
+    ConfigurationError,
+    LLMProviderError,
+    OrchestrationError,
+    RetryExhaustedError,
+)
+from amacs.integrations.llm_providers import (
+    LLMProvider,
+    LLMResponse,
+    Message,
+    get_provider,
+    register_provider,
+)
+from amacs.orchestrator.agent_selector import (
+    get_registered_agents,
+    register_agent,
+)
+from amacs.pipeline import Pipeline
+from amacs.results import AMACSResult
+
+__all__ = [
+    # Decorator & Pipeline
+    "amacs",
+    "Pipeline",
+    # Config
+
+    "AMACSConfig",
+    "Strategy",
+    # Results & Inspection
+    "AMACSResult",
+    "AgentResult",
+    "LogEntry",
+    "SubTask",
+    # Agents
+    "BaseAgent",
+    "get_registered_agents",
+    "register_agent",
+    # LLM
+    "get_provider",
+    "register_provider",
+    "LLMProvider",
+    "Message",
+    "LLMResponse",
+    # Communication
+    "CommunicationBus",
+    # Exceptions
+    "AMACSError",
+    "AgentError",
+    "AgentTimeoutError",
+    "AggregationError",
+    "CommunicationError",
+    "ConfigurationError",
+    "LLMProviderError",
+    "OrchestrationError",
+    "RetryExhaustedError",
+    "AdaptationError",
+    # Meta
+    "__version__",
+]

amacs/adaptive/__init__.py

@@ -0,0 +1,32 @@
+"""Adaptive control loop sub-package."""
+
+from amacs.adaptive.adaptation_engine import (
+    ActionType,
+    AdaptationAction,
+    AdaptationEngine,
+)
+from amacs.adaptive.evaluator import (
+    AgentEvaluation,
+    EvaluationReport,
+    Evaluator,
+    HealthStatus,
+    ThresholdConfig,
+)
+from amacs.adaptive.monitor import AgentMetrics, Monitor, SystemSnapshot
+from amacs.adaptive.reconfigurator import ReconfigurationResult, Reconfigurator
+
+__all__ = [
+    "ActionType",
+    "AdaptationAction",
+    "AdaptationEngine",
+    "AgentEvaluation",
+    "AgentMetrics",
+    "EvaluationReport",
+    "Evaluator",
+    "HealthStatus",
+    "Monitor",
+    "ReconfigurationResult",
+    "Reconfigurator",
+    "SystemSnapshot",
+    "ThresholdConfig",
+]

amacs/adaptive/adaptation_engine.py

@@ -0,0 +1,116 @@
+"""Adaptation engine — decides what remedial action to take based on evaluations.
+
+Translates :class:`EvaluationReport` findings into concrete :class:`AdaptationAction`
+directives that the :class:`Reconfigurator` can apply.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List
+
+from amacs.adaptive.evaluator import EvaluationReport, HealthStatus
+
+
+class ActionType(str, Enum):
+    RETRY_WITH_DIFFERENT_AGENT = "retry_with_different_agent"
+    SWITCH_MODEL = "switch_model"
+    ADD_AGENT = "add_agent"
+    REMOVE_AGENT = "remove_agent"
+    REDUCE_TEAM = "reduce_team"
+    SWAP_AGENT = "swap_agent"
+    SKIP_TASK = "skip_task"
+    NO_ACTION = "no_action"
+
+
+@dataclass
+class AdaptationAction:
+    """A single remedial action to be executed by the reconfigurator."""
+
+    action_type: ActionType
+    target_agent_id: str
+    reason: str
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+class AdaptationEngine:
+    """Decides what changes to make based on evaluation results."""
+
+    def decide(
+        self,
+        report: EvaluationReport,
+        total_agents: int = 0,
+    ) -> List[AdaptationAction]:
+        """Return an ordered list of actions to take."""
+        actions: List[AdaptationAction] = []
+
+        if report.system_healthy:
+            return [
+                AdaptationAction(
+                    action_type=ActionType.NO_ACTION,
+                    target_agent_id="",
+                    reason="System is healthy — no adaptation needed.",
+                )
+            ]
+
+        failing_count = 0
+        for agent_id in report.underperforming:
+            ev = report.evaluations[agent_id]
+            params = {
+                "original_type": ev.agent_type,
+                "trigger": ev.trigger,
+                "signal_values": ev.signal_values,
+            }
+
+            if ev.status == HealthStatus.FAILING:
+                failing_count += 1
+                actions.append(
+                    AdaptationAction(
+                        action_type=ActionType.SWAP_AGENT,
+                        target_agent_id=agent_id,
+                        reason="; ".join(ev.reasons),
+                        params=params,
+                    )
+                )
+            elif ev.status == HealthStatus.DEGRADED:
+                # Quality triggers lead to RETRY_WITH_DIFFERENT_AGENT / SWITCH_MODEL
+                if ev.trigger.startswith("quality_signal:"):
+                    if ev.signal_values.get("quality_score", 1.0) < 0.35 and ev.signal_values.get("critical", False):
+                        actions.append(
+                            AdaptationAction(
+                                action_type=ActionType.ADD_AGENT,
+                                target_agent_id=agent_id,
+                                reason="Critical task has a persistently low quality signal.",
+                                params=params,
+                            )
+                        )
+                    actions.append(
+                        AdaptationAction(
+                            action_type=ActionType.RETRY_WITH_DIFFERENT_AGENT,
+                            target_agent_id=agent_id,
+                            reason="; ".join(ev.reasons),
+                            params=params,
+                        )
+                    )
+                else:
+                    actions.append(
+                        AdaptationAction(
+                            action_type=ActionType.SKIP_TASK,
+                            target_agent_id=agent_id,
+                            reason="; ".join(ev.reasons),
+                            params=params,
+                        )
+                    )
+
+        # systemic issue: reduce team
+        if total_agents > 0 and failing_count > total_agents / 2:
+            actions.append(
+                AdaptationAction(
+                    action_type=ActionType.REDUCE_TEAM,
+                    target_agent_id="",
+                    reason=f"{failing_count}/{total_agents} agents are failing — reducing team.",
+                )
+            )
+
+        return actions

amacs/adaptive/evaluator.py

@@ -0,0 +1,210 @@
+"""Evaluator — compares agent performance against configurable thresholds.
+
+Flags agents as "underperforming" when they exceed failure, latency, or quality
+signal limits, feeding actionable signals to the :class:`AdaptationEngine`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from amacs.adaptive.monitor import AgentMetrics, Monitor
+
+REFUSAL_PATTERNS = [
+    "i cannot",
+    "i am unable to",
+    "as an ai",
+    "i apologize, but",
+    "i can't fulfill",
+    "i'm sorry, but i cannot",
+    "as a language model",
+]
+
+
+def is_repeated_text(text: str) -> bool:
+    lines = [l.strip() for l in text.splitlines() if l.strip()]
+    if len(lines) >= 3 and len(set(lines)) == 1:
+        return True
+    words = text.split()
+    if len(words) >= 12:
+        chunk_len = 3
+        chunks = [tuple(words[i : i + chunk_len]) for i in range(len(words) - chunk_len + 1)]
+        if len(chunks) >= 4 and len(set(chunks)) * 3 <= len(chunks):
+            return True
+    return False
+
+
+class HealthStatus(str, Enum):
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    FAILING = "failing"
+
+
+@dataclass
+class ThresholdConfig:
+    """Configurable thresholds for the evaluator."""
+
+    max_failures: int = 2
+    max_latency_seconds: float = 30.0
+    max_error_rate: float = 0.5  # 50 %
+    min_calls_for_evaluation: int = 1
+    min_output_length: int = 20
+    min_llm_judge_score: float = 0.6
+    max_budget_burn_rate: float = 0.8
+    detect_refusal: bool = True
+    detect_repeated: bool = True
+
+
+@dataclass
+class AgentEvaluation:
+    """Evaluation result for a single agent."""
+
+    agent_id: str
+    agent_type: str
+    status: HealthStatus
+    reasons: List[str] = field(default_factory=list)
+    metrics: Optional[AgentMetrics] = None
+    trigger: str = ""
+    signal_values: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EvaluationReport:
+    """Full evaluation report across all agents."""
+
+    evaluations: Dict[str, AgentEvaluation] = field(default_factory=dict)
+    underperforming: List[str] = field(default_factory=list)  # agent_ids
+    system_healthy: bool = True
+
+
+class Evaluator:
+    """Evaluates agent health against thresholds and quality signals."""
+
+    def __init__(
+        self,
+        thresholds: Optional[ThresholdConfig] = None,
+    ) -> None:
+        self._thresholds = thresholds or ThresholdConfig()
+
+    def evaluate(self, monitor: Monitor) -> EvaluationReport:
+        """Produce an :class:`EvaluationReport` from current monitor state."""
+        snap = monitor.snapshot()
+        report = EvaluationReport()
+
+        for agent_id, metrics in snap.agent_metrics.items():
+            if metrics is None:
+                continue
+            ev = self._evaluate_agent(metrics)
+            report.evaluations[agent_id] = ev
+            if ev.status != HealthStatus.HEALTHY:
+                report.underperforming.append(agent_id)
+
+        report.system_healthy = len(report.underperforming) == 0
+        return report
+
+    def _evaluate_agent(self, m: AgentMetrics) -> AgentEvaluation:
+        reasons: List[str] = []
+        status = HealthStatus.HEALTHY
+        trigger = ""
+
+        if m.total_calls < self._thresholds.min_calls_for_evaluation:
+            return AgentEvaluation(
+                agent_id=m.agent_id,
+                agent_type=m.agent_type,
+                status=HealthStatus.HEALTHY,
+                metrics=m,
+                trigger="healthy",
+            )
+
+        # 1. failure count
+        if m.failed_calls >= self._thresholds.max_failures:
+            reasons.append(
+                f"Too many failures: {m.failed_calls} >= {self._thresholds.max_failures}"
+            )
+            status = HealthStatus.FAILING
+            trigger = trigger or "failure:max_failures"
+
+        # 2. error rate
+        error_rate = m.failed_calls / m.total_calls if m.total_calls > 0 else 0
+        if error_rate >= self._thresholds.max_error_rate:
+            reasons.append(
+                f"High error rate: {error_rate:.0%} >= {self._thresholds.max_error_rate:.0%}"
+            )
+            status = HealthStatus.FAILING
+            trigger = trigger or "failure:error_rate"
+
+        # 3. latency
+        avg_latency = m.total_latency / m.total_calls if m.total_calls > 0 else 0
+        if avg_latency > self._thresholds.max_latency_seconds:
+            reasons.append(
+                f"High avg latency: {avg_latency:.1f}s > {self._thresholds.max_latency_seconds}s"
+            )
+            if status == HealthStatus.HEALTHY:
+                status = HealthStatus.DEGRADED
+            trigger = trigger or "latency:high"
+
+        # 4. Quality Signals (trigger even when nothing failed!)
+        if m.last_content is not None and m.successful_calls > 0:
+            content_stripped = m.last_content.strip()
+            if len(content_stripped) < self._thresholds.min_output_length:
+                reasons.append(
+                    f"Empty or very short output ({len(content_stripped)} chars < {self._thresholds.min_output_length})"
+                )
+                status = HealthStatus.FAILING if len(content_stripped) == 0 else HealthStatus.DEGRADED
+                trigger = trigger or "quality_signal:short_output"
+
+            if self._thresholds.detect_refusal and content_stripped:
+                content_lower = content_stripped.lower()
+                if any(pat in content_lower for pat in REFUSAL_PATTERNS):
+                    reasons.append("Refusal pattern detected in response")
+                    status = HealthStatus.FAILING
+                    trigger = trigger or "quality_signal:refusal_pattern"
+
+            if (
+                self._thresholds.detect_repeated
+                and content_stripped
+                and is_repeated_text(content_stripped)
+            ):
+                reasons.append("Repeated output pattern detected")
+                if status == HealthStatus.HEALTHY:
+                    status = HealthStatus.DEGRADED
+                trigger = trigger or "quality_signal:repeated_output"
+
+        if m.quality_scores:
+            latest_score = m.quality_scores[-1]
+            if latest_score < self._thresholds.min_llm_judge_score:
+                reasons.append(
+                    f"Low LLM judge score: {latest_score:.2f} < {self._thresholds.min_llm_judge_score:.2f}"
+                )
+                if status == HealthStatus.HEALTHY:
+                    status = HealthStatus.DEGRADED
+                trigger = trigger or "quality_signal:low_judge_score"
+
+        if m.burn_rate > self._thresholds.max_budget_burn_rate:
+            reasons.append(
+                f"High budget burn rate: {m.burn_rate:.2f} > {self._thresholds.max_budget_burn_rate:.2f}"
+            )
+            if status == HealthStatus.HEALTHY:
+                status = HealthStatus.DEGRADED
+            trigger = trigger or "quality_signal:budget_burn_rate"
+
+        signal_values = {
+            "failed_calls": m.failed_calls,
+            "error_rate": error_rate,
+            "avg_latency": avg_latency,
+            "content_length": len(m.last_content.strip()) if m.last_content else 0,
+            "quality_scores": m.quality_scores,
+            "burn_rate": m.burn_rate,
+        }
+
+        return AgentEvaluation(
+            agent_id=m.agent_id,
+            agent_type=m.agent_type,
+            status=status,
+            reasons=reasons,
+            metrics=m,
+            trigger=trigger or ("healthy" if status == HealthStatus.HEALTHY else "degraded"),
+            signal_values=signal_values,
+        )

amacs/adaptive/monitor.py

@@ -0,0 +1,153 @@
+"""Monitor — tracks latency, token usage, error rates, and agent health.
+
+Provides a real-time view of how each agent is performing during an
+orchestrated execution so the :class:`Evaluator` can flag problems.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class AgentMetrics:
+    """Accumulated metrics for a single agent instance."""
+
+    agent_id: str
+    agent_type: str
+    total_calls: int = 0
+    successful_calls: int = 0
+    failed_calls: int = 0
+    total_latency: float = 0.0
+    total_tokens: int = 0
+    last_latency: float = 0.0
+    last_error: Optional[str] = None
+    timestamps: List[float] = field(default_factory=list)
+    last_content: Optional[str] = None
+    quality_scores: List[float] = field(default_factory=list)
+    burn_rate: float = 0.0
+
+
+@dataclass
+class SystemSnapshot:
+    """Point-in-time snapshot of the entire system's health."""
+
+    timestamp: float
+    active_agents: int
+    total_calls: int
+    total_failures: int
+    avg_latency: float
+    total_tokens: int
+    agent_metrics: Dict[str, AgentMetrics] = field(default_factory=dict)
+
+
+class Monitor:
+    """Thread-safe performance monitor for the adaptive control loop."""
+
+    def __init__(self) -> None:
+        self._metrics: Dict[str, AgentMetrics] = {}
+        self._lock = threading.RLock()
+        self._start_time = time.time()
+
+    def record_success(
+        self,
+        agent_id: str,
+        agent_type: str,
+        latency: float,
+        tokens: int = 0,
+        content: Optional[str] = None,
+        quality_score: Optional[float] = None,
+        burn_rate: float = 0.0,
+    ) -> None:
+        """Record a successful agent execution."""
+        with self._lock:
+            m = self._get_or_create(agent_id, agent_type)
+            m.total_calls += 1
+            m.successful_calls += 1
+            m.total_latency += latency
+            m.last_latency = latency
+            m.total_tokens += tokens
+            if content is not None:
+                m.last_content = content
+            m.timestamps.append(time.time())
+            if quality_score is not None:
+                m.quality_scores.append(quality_score)
+            if burn_rate > 0:
+                m.burn_rate = burn_rate
+
+    def record_failure(
+        self,
+        agent_id: str,
+        agent_type: str,
+        latency: float,
+        error: str,
+        content: Optional[str] = None,
+    ) -> None:
+        """Record a failed agent execution."""
+        with self._lock:
+            m = self._get_or_create(agent_id, agent_type)
+            m.total_calls += 1
+            m.failed_calls += 1
+            m.total_latency += latency
+            m.last_latency = latency
+            m.last_error = error
+            if content is not None:
+                m.last_content = content
+            m.timestamps.append(time.time())
+
+    def get_agent_metrics(self, agent_id: str) -> Optional[AgentMetrics]:
+        """Return metrics for a specific agent."""
+        with self._lock:
+            m = self._metrics.get(agent_id)
+            if m is None:
+                return None
+            return AgentMetrics(
+                agent_id=m.agent_id,
+                agent_type=m.agent_type,
+                total_calls=m.total_calls,
+                successful_calls=m.successful_calls,
+                failed_calls=m.failed_calls,
+                total_latency=m.total_latency,
+                total_tokens=m.total_tokens,
+                last_latency=m.last_latency,
+                last_error=m.last_error,
+                timestamps=list(m.timestamps),
+                last_content=m.last_content,
+                quality_scores=list(m.quality_scores),
+                burn_rate=m.burn_rate,
+            )
+
+    def snapshot(self) -> SystemSnapshot:
+        """Capture a point-in-time snapshot of all agent metrics."""
+        with self._lock:
+            total_calls = sum(m.total_calls for m in self._metrics.values())
+            total_failures = sum(m.failed_calls for m in self._metrics.values())
+            total_latency = sum(m.total_latency for m in self._metrics.values())
+            total_tokens = sum(m.total_tokens for m in self._metrics.values())
+            avg_latency = total_latency / total_calls if total_calls > 0 else 0.0
+
+            return SystemSnapshot(
+                timestamp=time.time(),
+                active_agents=len(self._metrics),
+                total_calls=total_calls,
+                total_failures=total_failures,
+                avg_latency=avg_latency,
+                total_tokens=total_tokens,
+                agent_metrics={k: self.get_agent_metrics(k) for k in self._metrics},  # type: ignore[misc]
+            )
+
+    def reset(self) -> None:
+        """Reset all metrics."""
+        with self._lock:
+            self._metrics.clear()
+            self._start_time = time.time()
+
+    def _get_or_create(self, agent_id: str, agent_type: str) -> AgentMetrics:
+        if agent_id not in self._metrics:
+            self._metrics[agent_id] = AgentMetrics(
+                agent_id=agent_id, agent_type=agent_type
+            )
+        return self._metrics[agent_id]