agentarmour-toolkit 0.1.1__py3-none-any.whl

agentarmour/__init__.py

@@ -0,0 +1,3 @@
+"""AgentArmour — production reliability suite for LangChain/LangGraph multi-agent systems."""
+
+__version__ = "0.1.0"

agentarmour/cascadebreaker/__init__.py

@@ -0,0 +1,34 @@
+"""
+CascadeBreaker — Circuit breaker and self-healing layer for LangGraph multi-agent systems.
+"""
+
+from agentarmour.cascadebreaker.breaker import CircuitBreaker
+from agentarmour.cascadebreaker.config import BreakerConfig
+from agentarmour.cascadebreaker.states import BreakerState, FailureRecord, StateTransition
+from agentarmour.cascadebreaker.strategies import (
+    FallbackStrategy,
+    FallbackResult,
+    DegradeStrategy,
+    CacheStrategy,
+    EscalateStrategy,
+    DecomposeStrategy,
+)
+from agentarmour.cascadebreaker.guard import CascadeGuard
+from agentarmour.cascadebreaker.registry import BreakerRegistry, get_registry
+
+__all__ = [
+    "CircuitBreaker",
+    "BreakerConfig",
+    "BreakerState",
+    "FailureRecord",
+    "StateTransition",
+    "FallbackStrategy",
+    "FallbackResult",
+    "DegradeStrategy",
+    "CacheStrategy",
+    "EscalateStrategy",
+    "DecomposeStrategy",
+    "CascadeGuard",
+    "BreakerRegistry",
+    "get_registry",
+]

agentarmour/cascadebreaker/breaker.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import time
+import traceback
+from typing import Any, Callable, Awaitable, TypeVar, Optional, TYPE_CHECKING
+import structlog
+
+if TYPE_CHECKING:
+    from agentarmour.cascadebreaker.storage.base import AuditLedger
+
+from agentarmour.cascadebreaker.config import BreakerConfig
+from agentarmour.cascadebreaker.states import (
+    BreakerState,
+    BreakerStateMachine,
+    FailureCategory,
+    FailureRecord,
+)
+from agentarmour.cascadebreaker.strategies import (
+    BaseFallbackStrategy,
+    CacheStrategy,
+    DegradeStrategy,
+    DecomposeStrategy,
+    EscalateStrategy,
+    FallbackResult,
+    FallbackStrategy,
+)
+
+logger = structlog.get_logger(__name__)
+
+NodeFn = TypeVar("NodeFn", bound=Callable[..., Awaitable[dict[str, Any]]])
+
+
+def _classify_exception(exc: Exception) -> FailureCategory:
+    exc_type = type(exc).__name__.lower()
+    msg = str(exc).lower()
+
+    if "timeout" in exc_type or "timeout" in msg:
+        return FailureCategory.LATENCY_BREACH
+    if "recursion" in exc_type or "loop" in msg:
+        return FailureCategory.REASONING_LOOP
+    if "token" in msg or "context" in msg or "length" in msg:
+        return FailureCategory.CONTEXT_OVERFLOW
+    if "tool" in msg or "function" in msg:
+        return FailureCategory.TOOL_CALL_FAILURE
+    if "invalid" in msg and "state" in msg:
+        return FailureCategory.STATE_CORRUPTION
+    return FailureCategory.EXCEPTION
+
+
+class CircuitBreaker:
+    def __init__(
+        self,
+        name: str,
+        config: Optional[BreakerConfig] = None,
+        fallback_strategy: Any = FallbackStrategy.CACHE,
+        on_open: Optional[Callable[[str], Awaitable[None]]] = None,
+        on_close: Optional[Callable[[str], Awaitable[None]]] = None,
+        on_half_open: Optional[Callable[[str], Awaitable[None]]] = None,
+        ledger: Optional["AuditLedger"] = None,
+    ) -> None:
+        self.name = name
+        self.config = config or BreakerConfig()
+
+        if isinstance(fallback_strategy, FallbackStrategy):
+            self._strategy_enum = fallback_strategy
+            self._strategy = self._build_default_strategy(fallback_strategy)
+        else:
+            self._strategy_enum = None
+            self._strategy = fallback_strategy
+
+        self._state_machine = BreakerStateMachine(
+            breaker_name=name,
+            failure_threshold=self.config.failure_threshold,
+            recovery_timeout=self.config.recovery_timeout,
+            window_seconds=self.config.window_seconds,
+            half_open_max_calls=self.config.half_open_max_calls,
+            audit_ledger=ledger,
+        )
+
+        self._on_open = on_open
+        self._on_close = on_close
+        self._on_half_open = on_half_open
+        self._prev_state: BreakerState = BreakerState.CLOSED
+
+        logger.info(
+            "circuit_breaker.created",
+            name=name,
+            strategy=str(fallback_strategy),
+            failure_threshold=self.config.failure_threshold,
+        )
+
+    @property
+    def state(self) -> BreakerState:
+        return self._state_machine.state
+
+    @property
+    def metrics(self) -> dict[str, Any]:
+        return self._state_machine.metrics
+
+    @property
+    def is_open(self) -> bool:
+        return self._state_machine.state is BreakerState.OPEN
+
+    @property
+    def is_closed(self) -> bool:
+        return self._state_machine.state is BreakerState.CLOSED
+
+    def protect(self, fn: NodeFn) -> NodeFn:
+        if not asyncio.iscoroutinefunction(fn):
+            raise TypeError(
+                f"CircuitBreaker.protect requires an async function; "
+                f"'{fn.__name__}' is synchronous."
+            )
+
+        @functools.wraps(fn)
+        async def _wrapper(*args: Any, **kwargs: Any) -> dict[str, Any]:
+            state = kwargs.get("state") or (args[0] if args else {})
+            if not isinstance(state, dict):
+                state = {}
+            return await self.call(fn, state, *args[1:], **kwargs)
+
+        _wrapper.__cascadebreaker__ = self
+        _wrapper.__wrapped__ = fn
+        return _wrapper
+
+    async def call(
+        self,
+        fn: Callable[..., Awaitable[dict[str, Any]]],
+        state: dict[str, Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        if not self.config.enabled:
+            return await fn(state, *args, **kwargs)
+
+        permitted = await self._state_machine.is_call_permitted()
+        prev_state = self._prev_state
+
+        if not permitted:
+            logger.info(
+                "circuit_breaker.short_circuited",
+                name=self.name,
+                state=self.state.value,
+            )
+            await self._state_machine.record_fallback()
+            result = await self._invoke_fallback(state, {})
+            return result.state
+
+        t0 = time.monotonic()
+        try:
+            if self.config.call_timeout is not None:
+                result_state = await asyncio.wait_for(
+                    fn(state, *args, **kwargs),
+                    timeout=self.config.call_timeout,
+                )
+            else:
+                result_state = await fn(state, *args, **kwargs)
+
+            if isinstance(self._strategy, CacheStrategy):
+                self._strategy.store(self.name, result_state)
+
+            await self._state_machine.record_success()
+            await self._fire_transition_callbacks(prev_state)
+            self._prev_state = self.state
+            return result_state
+
+        except asyncio.TimeoutError as exc:
+            latency_ms = (time.monotonic() - t0) * 1000
+            return await self._handle_failure(
+                exc=exc,
+                state=state,
+                latency_ms=latency_ms,
+                category=FailureCategory.LATENCY_BREACH,
+                prev_state=prev_state,
+            )
+
+        except Exception as exc:
+            latency_ms = (time.monotonic() - t0) * 1000
+            return await self._handle_failure(
+                exc=exc,
+                state=state,
+                latency_ms=latency_ms,
+                category=_classify_exception(exc),
+                prev_state=prev_state,
+            )
+
+    async def _handle_failure(
+        self,
+        exc: Exception,
+        state: dict[str, Any],
+        latency_ms: float,
+        category: FailureCategory,
+        prev_state: BreakerState,
+    ) -> dict[str, Any]:
+        tb_str = traceback.format_exc()
+        record = FailureRecord(
+            breaker_name=self.name,
+            category=category,
+            error_type=f"{type(exc).__module__}.{type(exc).__name__}",
+            error_message=str(exc),
+            traceback_str=tb_str,
+            latency_ms=latency_ms,
+            metadata=self.config.extra_metadata,
+        )
+        await self._state_machine.record_failure(record)
+        await self._state_machine.record_fallback()
+        await self._fire_transition_callbacks(prev_state)
+        self._prev_state = self.state
+
+        failure_context = {
+            "last_error": str(exc),
+            "failure_count": self._state_machine.failure_count,
+            "category": category.value,
+            "traceback": tb_str,
+        }
+        result = await self._invoke_fallback(state, failure_context)
+        result_state = result.state
+        result_state["__cascadebreaker_traceback__"] = tb_str
+        return result_state
+
+    async def _invoke_fallback(
+        self,
+        state: dict[str, Any],
+        failure_context: dict[str, Any],
+    ) -> FallbackResult:
+        try:
+            return await self._strategy.execute(
+                state=state,
+                breaker_name=self.name,
+                failure_context=failure_context,
+            )
+        except Exception as exc:
+            logger.error(
+                "circuit_breaker.fallback_strategy_error",
+                name=self.name,
+                error=str(exc),
+            )
+            safe_state = dict(state)
+            safe_state["__cascadebreaker_fallback_failed__"] = str(exc)
+            return FallbackResult(
+                state=safe_state,
+                strategy_used=FallbackStrategy.CACHE,
+                degraded=True,
+                confidence=0.0,
+            )
+
+    async def _fire_transition_callbacks(self, prev_state: BreakerState) -> None:
+        current = self.state
+        if current == prev_state:
+            return
+        try:
+            if current is BreakerState.OPEN and self._on_open:
+                await self._on_open(self.name)
+            elif current is BreakerState.CLOSED and self._on_close:
+                await self._on_close(self.name)
+            elif current is BreakerState.HALF_OPEN and self._on_half_open:
+                await self._on_half_open(self.name)
+        except Exception as exc:
+            logger.warning(
+                "circuit_breaker.callback_error",
+                name=self.name,
+                error=str(exc),
+            )
+
+    async def reset(self) -> None:
+        await self._state_machine.reset()
+        self._prev_state = BreakerState.CLOSED
+
+    def _build_default_strategy(
+        self, strategy_enum: FallbackStrategy
+    ) -> BaseFallbackStrategy:
+        if strategy_enum is FallbackStrategy.CACHE:
+            return CacheStrategy()
+
+        if strategy_enum is FallbackStrategy.DEGRADE:
+            async def _noop_backup(state: dict[str, Any]) -> dict[str, Any]:
+                return state
+            return DegradeStrategy(backup_fn=_noop_backup, confidence_override=0.1)
+
+        if strategy_enum is FallbackStrategy.ESCALATE:
+            async def _noop_escalate(
+                breaker_name: str,
+                state: dict[str, Any],
+                context: dict[str, Any],
+            ) -> Optional[dict[str, Any]]:
+                return None
+            return EscalateStrategy(
+                escalation_fn=_noop_escalate,
+                notification_only=True,
+            )
+
+        if strategy_enum is FallbackStrategy.DECOMPOSE:
+            async def _noop_decompose(state: dict[str, Any]) -> list[dict[str, Any]]:
+                return [state]
+            async def _noop_execute(sub: dict[str, Any]) -> dict[str, Any]:
+                return sub
+            return DecomposeStrategy(
+                decompose_fn=_noop_decompose,
+                execute_fn=_noop_execute,
+            )
+
+        raise ValueError(f"Unknown FallbackStrategy: {strategy_enum}")
+
+    def __repr__(self) -> str:
+        return (
+            f"CircuitBreaker(name={self.name!r}, "
+            f"state={self.state.value})"
+        )

agentarmour/cascadebreaker/cli.py

@@ -0,0 +1,183 @@
+"""
+Command-line interface for CascadeBreaker.
+
+Lets you inspect a SQLite audit ledger from the terminal without writing
+a throwaway script every time. Uses only the standard library.
+
+Usage:
+    agentarmour --version
+    agentarmour ledger summary
+    agentarmour ledger failures --limit 10
+    agentarmour ledger transitions --breaker research_agent
+"""
+
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import sys
+
+from agentarmour import __version__
+
+
+def _connect(db_path: str, table_prefix: str) -> sqlite3.Connection:
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _table_exists(conn: sqlite3.Connection, table_name: str) -> bool:
+    cursor = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+        (table_name,),
+    )
+    return cursor.fetchone() is not None
+
+
+def cmd_summary(args: argparse.Namespace) -> int:
+    prefix = args.table_prefix
+    conn = _connect(args.db, prefix)
+
+    failures_table = f"{prefix}failures"
+    transitions_table = f"{prefix}transitions"
+
+    if not _table_exists(conn, failures_table):
+        print(f"No audit data found in '{args.db}'. Has the breaker run yet?")
+        return 1
+
+    total_failures = conn.execute(f"SELECT COUNT(*) FROM {failures_table}").fetchone()[0]
+    total_transitions = conn.execute(f"SELECT COUNT(*) FROM {transitions_table}").fetchone()[0]
+
+    breakers = conn.execute(
+        f"SELECT DISTINCT breaker_name FROM {failures_table}"
+    ).fetchall()
+    breaker_names = [row["breaker_name"] for row in breakers]
+
+    print(f"Audit ledger: {args.db}")
+    print(f"Breakers seen: {', '.join(breaker_names) if breaker_names else '(none)'}")
+    print(f"Total failures recorded:    {total_failures}")
+    print(f"Total state transitions:    {total_transitions}")
+
+    for name in breaker_names:
+        count = conn.execute(
+            f"SELECT COUNT(*) FROM {failures_table} WHERE breaker_name = ?", (name,)
+        ).fetchone()[0]
+        print(f"  {name}: {count} failure(s)")
+
+    conn.close()
+    return 0
+
+
+def cmd_failures(args: argparse.Namespace) -> int:
+    prefix = args.table_prefix
+    conn = _connect(args.db, prefix)
+    table = f"{prefix}failures"
+
+    if not _table_exists(conn, table):
+        print(f"No audit data found in '{args.db}'.")
+        return 1
+
+    query = f"SELECT breaker_name, category, error_message, timestamp FROM {table}"
+    params: list[str] = []
+    if args.breaker:
+        query += " WHERE breaker_name = ?"
+        params.append(args.breaker)
+    query += " ORDER BY timestamp DESC LIMIT ?"
+    params.append(str(args.limit))
+
+    rows = conn.execute(query, params).fetchall()
+
+    if not rows:
+        print("No failures found matching that filter.")
+        return 0
+
+    for row in rows:
+        print(f"[{row['breaker_name']}] {row['category']}: {row['error_message']}")
+
+    conn.close()
+    return 0
+
+
+def cmd_transitions(args: argparse.Namespace) -> int:
+    prefix = args.table_prefix
+    conn = _connect(args.db, prefix)
+    table = f"{prefix}transitions"
+
+    if not _table_exists(conn, table):
+        print(f"No audit data found in '{args.db}'.")
+        return 1
+
+    query = f"SELECT breaker_name, from_state, to_state, reason, timestamp FROM {table}"
+    params: list[str] = []
+    if args.breaker:
+        query += " WHERE breaker_name = ?"
+        params.append(args.breaker)
+    query += " ORDER BY timestamp DESC LIMIT ?"
+    params.append(str(args.limit))
+
+    rows = conn.execute(query, params).fetchall()
+
+    if not rows:
+        print("No transitions found matching that filter.")
+        return 0
+
+    for row in rows:
+        print(
+            f"[{row['breaker_name']}] {row['from_state']} -> {row['to_state']}: "
+            f"{row['reason']}"
+        )
+
+    conn.close()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentarmour",
+        description="CascadeBreaker CLI — inspect your circuit breaker audit ledger.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"agentarmour {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    ledger_parser = subparsers.add_parser("ledger", help="Inspect the audit ledger")
+    ledger_sub = ledger_parser.add_subparsers(dest="ledger_command")
+
+
+    summary_parser = ledger_sub.add_parser("summary", help="Show a high-level summary")
+    summary_parser.add_argument("--db", default="cascadebreaker.db")
+    summary_parser.add_argument("--table-prefix", default="cb_")
+    summary_parser.set_defaults(func=cmd_summary)
+
+    failures_parser = ledger_sub.add_parser("failures", help="List recorded failures")
+    failures_parser.add_argument("--db", default="cascadebreaker.db")
+    failures_parser.add_argument("--table-prefix", default="cb_")
+    failures_parser.add_argument("--breaker", default=None, help="Filter by breaker name")
+    failures_parser.add_argument("--limit", type=int, default=20)
+    failures_parser.set_defaults(func=cmd_failures)
+
+    transitions_parser = ledger_sub.add_parser("transitions", help="List state transitions")
+    transitions_parser.add_argument("--db", default="cascadebreaker.db")
+    transitions_parser.add_argument("--table-prefix", default="cb_")
+    transitions_parser.add_argument("--breaker", default=None, help="Filter by breaker name")
+    transitions_parser.add_argument("--limit", type=int, default=20)
+    transitions_parser.set_defaults(func=cmd_transitions)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        sys.exit(1)
+
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

agentarmour/cascadebreaker/config.py

@@ -0,0 +1,43 @@
+"""
+Pydantic configuration models for CascadeBreaker.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from pydantic import BaseModel, Field, model_validator
+
+
+class StorageConfig(BaseModel):
+
+
+    backend: Literal["sqlite", "postgres"] = "sqlite"
+    sqlite_path: str = "cascadebreaker.db"
+    postgres_dsn: str | None = None
+    table_prefix: str = "cb_"
+
+    @model_validator(mode="after")
+    def validate_postgres_dsn(self) -> "StorageConfig":
+        if self.backend == "postgres" and not self.postgres_dsn:
+            raise ValueError(
+                "postgres_dsn is required when storage backend is 'postgres'"
+            )
+        return self
+
+
+class BreakerConfig(BaseModel):
+
+    
+    failure_threshold: int = Field(default=3, ge=1, le=100)
+    recovery_timeout: float = Field(default=30.0, gt=0)
+    window_seconds: float = Field(default=60.0, gt=0)
+    half_open_max_calls: int = Field(default=1, ge=1)
+    call_timeout: float | None = Field(default=30.0, gt=0)
+    exclude_exceptions: list[str] = Field(default_factory=list)
+    include_exceptions: list[str] = Field(default_factory=list)
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    enabled: bool = True
+    name_prefix: str = ""
+    extra_metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"frozen": True}