agent-killswitch 0.1.0__py3-none-any.whl

agent_killswitch/__init__.py

@@ -0,0 +1,76 @@
+"""agent-killswitch: Operational safety controls for autonomous AI agents.
+
+Zero-dependency kill switch, heartbeat monitor, circuit breaker, and
+budget controls for AI agents. Works with any framework (LangChain,
+LangGraph, CrewAI, OpenAI Agents SDK, asyncio) or standalone.
+
+Quick start::
+
+    from agent_killswitch import KillSwitch, KillLevel, KillScope
+
+    ks = KillSwitch()
+    ks.activate(KillLevel.KILL, KillScope.GLOBAL, reason="emergency")
+    status = ks.check()
+    assert status.is_killed
+
+Core classes:
+    KillSwitch: Main kill switch with tiered levels and scoped targets.
+    HeartbeatMonitor: Track agent health via periodic heartbeats.
+    CircuitBreaker: Protect against cascading failures.
+    BudgetKillTrigger: Kill agents that exceed their budget.
+    CascadingTerminator: Propagate kills through agent hierarchies.
+
+Decorators:
+    killswitch_protected: Check kill switch before/after function calls.
+    with_heartbeat: Send heartbeats during long-running operations.
+    circuit_breaker: Wrap functions with circuit breaker protection.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .core.budget_kill import BudgetKillTrigger
+from .core.cascading import CascadingTerminator
+from .core.circuit_breaker import CircuitBreaker, CircuitBreakerOpen
+from .core.enums import CircuitState, HeartbeatStatus, KillLevel, KillScope
+from .core.heartbeat import HeartbeatMonitor
+from .core.killswitch import KillSwitch
+from .core.models import (
+    AgentRegistration,
+    BudgetStatus,
+    CircuitBreakerState,
+    HeartbeatRecord,
+    KillEvent,
+    KillStatus,
+)
+from .decorators import KillSwitchTriggered, killswitch_protected, with_heartbeat
+from .decorators import circuit_breaker as circuit_breaker_decorator
+
+__all__ = [
+    "AgentRegistration",
+    "BudgetKillTrigger",
+    "BudgetStatus",
+    "CascadingTerminator",
+    "CircuitBreaker",
+    "CircuitBreakerOpen",
+    "CircuitBreakerState",
+    "CircuitState",
+    "HeartbeatMonitor",
+    "HeartbeatRecord",
+    "HeartbeatStatus",
+    # Models
+    "KillEvent",
+    # Enums
+    "KillLevel",
+    "KillScope",
+    "KillStatus",
+    # Core classes
+    "KillSwitch",
+    "KillSwitchTriggered",
+    # Version
+    "__version__",
+    "circuit_breaker_decorator",
+    # Decorators
+    "killswitch_protected",
+    "with_heartbeat",
+]

agent_killswitch/_version.py

@@ -0,0 +1,5 @@
+"""Version information for agent-killswitch."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

agent_killswitch/backends/__init__.py

@@ -0,0 +1,21 @@
+"""Backend implementations for kill switch state storage.
+
+Available backends:
+- InMemoryBackend: Zero-dependency, thread-safe, dict-based (default)
+- RedisBackend: Distributed, Redis-backed (optional dependency)
+- KillSwitchBackend: Protocol for custom backends
+"""
+
+from __future__ import annotations
+
+from .base import KillSwitchBackend
+from .memory import InMemoryBackend
+
+__all__ = [
+    "InMemoryBackend",
+    "KillSwitchBackend",
+]
+
+# RedisBackend is intentionally not imported here to avoid
+# requiring the redis dependency. Import it directly:
+#   from agent_killswitch.backends.redis import RedisBackend

agent_killswitch/backends/base.py

@@ -0,0 +1,95 @@
+"""Abstract backend protocol for kill switch state storage.
+
+Backends provide the storage layer for kill switch state. The protocol
+defines the minimal interface that any backend must implement.
+
+Two implementations are provided:
+- InMemoryBackend: Zero-dependency, dict-based (default)
+- RedisBackend: Distributed, Redis-backed (optional)
+
+Custom backends can be created by implementing this protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class KillSwitchBackend(Protocol):
+    """Protocol for kill switch state backends.
+
+    All methods are synchronous. For async usage, wrap in an executor
+    or use an async-native backend.
+
+    The backend MUST be fail-closed: if any operation fails, the caller
+    should treat the agent as KILLED for safety.
+    """
+
+    def get(self, key: str) -> str | None:
+        """Get a value by key.
+
+        Args:
+            key: The storage key.
+
+        Returns:
+            The stored value as a string, or None if not found.
+        """
+        ...
+
+    def set(self, key: str, value: str) -> None:
+        """Set a value by key. No TTL -- explicit deletion required.
+
+        Args:
+            key: The storage key.
+            value: The value to store.
+        """
+        ...
+
+    def delete(self, key: str) -> None:
+        """Delete a key.
+
+        Args:
+            key: The storage key to delete.
+        """
+        ...
+
+    def get_many(self, keys: list[str]) -> list[str | None]:
+        """Get multiple values in a single operation.
+
+        Args:
+            keys: List of storage keys.
+
+        Returns:
+            List of values (or None) in the same order as keys.
+        """
+        ...
+
+    def keys(self, pattern: str) -> list[str]:
+        """Find keys matching a pattern.
+
+        The pattern uses simple prefix matching (not glob).
+        Pass "prefix*" to match all keys starting with "prefix".
+
+        Args:
+            pattern: Key pattern to match (prefix with trailing *).
+
+        Returns:
+            List of matching keys.
+        """
+        ...
+
+    def exists(self, key: str) -> bool:
+        """Check if a key exists.
+
+        Args:
+            key: The storage key.
+
+        Returns:
+            True if the key exists.
+        """
+        ...
+
+    def clear(self) -> None:
+        """Remove all keys. Use with caution -- primarily for testing."""
+        ...

agent_killswitch/backends/memory.py

@@ -0,0 +1,120 @@
+"""In-memory backend for kill switch state storage.
+
+Zero-dependency, thread-safe, dict-based backend. This is the default
+backend and is suitable for:
+- Single-process applications
+- Testing and development
+- Applications that don't need distributed state
+
+For distributed systems, use the RedisBackend instead.
+"""
+
+from __future__ import annotations
+
+import threading
+
+
+class InMemoryBackend:
+    """Thread-safe in-memory backend using a dictionary.
+
+    All operations are protected by a reentrant lock for thread safety.
+    This backend is the default when no external backend is configured.
+
+    Example::
+
+        from agent_killswitch.backends.memory import InMemoryBackend
+
+        backend = InMemoryBackend()
+        backend.set("killswitch:global", "kill")
+        assert backend.get("killswitch:global") == "kill"
+    """
+
+    def __init__(self) -> None:
+        """Initialize the in-memory backend."""
+        self._store: dict[str, str] = {}
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> str | None:
+        """Get a value by key.
+
+        Args:
+            key: The storage key.
+
+        Returns:
+            The stored value, or None if not found.
+        """
+        with self._lock:
+            return self._store.get(key)
+
+    def set(self, key: str, value: str) -> None:
+        """Set a value by key.
+
+        Args:
+            key: The storage key.
+            value: The value to store.
+        """
+        with self._lock:
+            self._store[key] = value
+
+    def delete(self, key: str) -> None:
+        """Delete a key.
+
+        Args:
+            key: The storage key to delete.
+        """
+        with self._lock:
+            self._store.pop(key, None)
+
+    def get_many(self, keys: list[str]) -> list[str | None]:
+        """Get multiple values atomically.
+
+        Args:
+            keys: List of storage keys.
+
+        Returns:
+            List of values in the same order as keys.
+        """
+        with self._lock:
+            return [self._store.get(k) for k in keys]
+
+    def keys(self, pattern: str) -> list[str]:
+        """Find keys matching a prefix pattern.
+
+        Args:
+            pattern: Key pattern. If it ends with '*', matches prefix.
+                    Otherwise, matches exact key.
+
+        Returns:
+            List of matching keys.
+        """
+        with self._lock:
+            if pattern.endswith("*"):
+                prefix = pattern[:-1]
+                return [k for k in self._store if k.startswith(prefix)]
+            return [k for k in self._store if k == pattern]
+
+    def exists(self, key: str) -> bool:
+        """Check if a key exists.
+
+        Args:
+            key: The storage key.
+
+        Returns:
+            True if the key exists.
+        """
+        with self._lock:
+            return key in self._store
+
+    def clear(self) -> None:
+        """Remove all keys."""
+        with self._lock:
+            self._store.clear()
+
+    def __len__(self) -> int:
+        """Return the number of stored keys."""
+        with self._lock:
+            return len(self._store)
+
+    def __repr__(self) -> str:
+        with self._lock:
+            return f"InMemoryBackend(keys={len(self._store)})"

agent_killswitch/backends/redis.py

@@ -0,0 +1,230 @@
+"""Redis backend for distributed kill switch state storage.
+
+Requires the `redis` optional dependency:
+    pip install agent-killswitch[redis]
+
+This backend is suitable for:
+- Multi-process applications
+- Distributed systems
+- Production deployments where multiple services need shared kill state
+
+The backend uses Redis pipelines for efficient multi-key operations
+and falls back to fail-closed behavior on connection errors.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class RedisBackend:
+    """Redis-backed storage for kill switch state.
+
+    Uses Redis for sub-millisecond flag checks across distributed systems.
+    All keys use a configurable prefix (default: "killswitch:") to avoid
+    collisions with other Redis users.
+
+    Fail-closed behavior: If Redis is unreachable, operations raise
+    exceptions. The KillSwitch class interprets backend failures as
+    KILLED state for safety.
+
+    Example::
+
+        import redis
+        from agent_killswitch.backends.redis import RedisBackend
+
+        client = redis.Redis(host="localhost", port=6379, db=0)
+        backend = RedisBackend(client, prefix="myapp:killswitch:")
+
+    Args:
+        redis_client: A redis.Redis or redis.StrictRedis instance.
+        prefix: Key prefix for all kill switch keys.
+            Defaults to "killswitch:".
+    """
+
+    def __init__(
+        self,
+        redis_client: Any,
+        prefix: str = "killswitch:",
+    ) -> None:
+        """Initialize the Redis backend.
+
+        Args:
+            redis_client: A Redis client instance. Must support get, set,
+                delete, pipeline, scan_iter, and exists methods.
+            prefix: Key prefix for namespacing. Defaults to "killswitch:".
+        """
+        self._redis = redis_client
+        self._prefix = prefix
+
+    def _prefixed(self, key: str) -> str:
+        """Add prefix to a key if not already prefixed.
+
+        Args:
+            key: The raw key.
+
+        Returns:
+            The prefixed key.
+        """
+        if key.startswith(self._prefix):
+            return key
+        return f"{self._prefix}{key}"
+
+    def _unprefixed(self, key: str) -> str:
+        """Remove prefix from a key.
+
+        Args:
+            key: The prefixed key.
+
+        Returns:
+            The raw key without prefix.
+        """
+        if key.startswith(self._prefix):
+            return key[len(self._prefix) :]
+        return key
+
+    def get(self, key: str) -> str | None:
+        """Get a value from Redis.
+
+        Args:
+            key: The storage key.
+
+        Returns:
+            The stored value as a string, or None if not found.
+
+        Raises:
+            Exception: On Redis connection failure (fail-closed).
+        """
+        try:
+            val = self._redis.get(self._prefixed(key))
+            if val is not None and isinstance(val, bytes):
+                return val.decode("utf-8")
+            return val
+        except Exception:
+            logger.error("Redis GET failed for key=%s", key, exc_info=True)
+            raise
+
+    def set(self, key: str, value: str) -> None:
+        """Set a value in Redis. No TTL -- explicit deletion required.
+
+        Args:
+            key: The storage key.
+            value: The value to store.
+
+        Raises:
+            Exception: On Redis connection failure.
+        """
+        try:
+            self._redis.set(self._prefixed(key), value)
+        except Exception:
+            logger.error("Redis SET failed for key=%s", key, exc_info=True)
+            raise
+
+    def delete(self, key: str) -> None:
+        """Delete a key from Redis.
+
+        Args:
+            key: The storage key to delete.
+
+        Raises:
+            Exception: On Redis connection failure.
+        """
+        try:
+            self._redis.delete(self._prefixed(key))
+        except Exception:
+            logger.error("Redis DELETE failed for key=%s", key, exc_info=True)
+            raise
+
+    def get_many(self, keys: list[str]) -> list[str | None]:
+        """Get multiple values using a Redis pipeline (single round-trip).
+
+        Args:
+            keys: List of storage keys.
+
+        Returns:
+            List of values (or None) in the same order as keys.
+
+        Raises:
+            Exception: On Redis connection failure.
+        """
+        try:
+            pipe = self._redis.pipeline(transaction=False)
+            for key in keys:
+                pipe.get(self._prefixed(key))
+            results = pipe.execute()
+            return [r.decode("utf-8") if isinstance(r, bytes) else r for r in results]
+        except Exception:
+            logger.error("Redis pipeline GET failed for keys=%s", keys, exc_info=True)
+            raise
+
+    def keys(self, pattern: str) -> list[str]:
+        """Find keys matching a pattern using Redis SCAN.
+
+        Args:
+            pattern: Key pattern. If it ends with '*', uses SCAN with
+                    the prefixed pattern. Otherwise matches exact key.
+
+        Returns:
+            List of matching keys (without prefix).
+
+        Raises:
+            Exception: On Redis connection failure.
+        """
+        try:
+            if pattern.endswith("*"):
+                redis_pattern = self._prefixed(pattern)
+                found: list[str] = []
+                for key in self._redis.scan_iter(match=redis_pattern):
+                    if isinstance(key, bytes):
+                        key = key.decode("utf-8")
+                    found.append(self._unprefixed(key))
+                return found
+            else:
+                prefixed = self._prefixed(pattern)
+                if self._redis.exists(prefixed):
+                    return [pattern]
+                return []
+        except Exception:
+            logger.error("Redis KEYS failed for pattern=%s", pattern, exc_info=True)
+            raise
+
+    def exists(self, key: str) -> bool:
+        """Check if a key exists in Redis.
+
+        Args:
+            key: The storage key.
+
+        Returns:
+            True if the key exists.
+
+        Raises:
+            Exception: On Redis connection failure.
+        """
+        try:
+            return bool(self._redis.exists(self._prefixed(key)))
+        except Exception:
+            logger.error("Redis EXISTS failed for key=%s", key, exc_info=True)
+            raise
+
+    def clear(self) -> None:
+        """Remove all keys with our prefix. Use with caution.
+
+        Raises:
+            Exception: On Redis connection failure.
+        """
+        try:
+            pattern = f"{self._prefix}*"
+            keys_to_delete: list[Any] = []
+            for key in self._redis.scan_iter(match=pattern):
+                keys_to_delete.append(key)
+            if keys_to_delete:
+                self._redis.delete(*keys_to_delete)
+        except Exception:
+            logger.error("Redis CLEAR failed", exc_info=True)
+            raise
+
+    def __repr__(self) -> str:
+        return f"RedisBackend(prefix={self._prefix!r})"

agent_killswitch/core/__init__.py

@@ -0,0 +1,36 @@
+"""Core kill switch components.
+
+This package contains the core functionality:
+- killswitch: Main KillSwitch class (unified API)
+- heartbeat: HeartbeatMonitor for agent health tracking
+- circuit_breaker: Circuit breaker pattern
+- budget_kill: Budget-based kill triggers
+- cascading: Cascading termination for agent hierarchies
+- models: Data models
+- enums: Enumerations
+"""
+
+from __future__ import annotations
+
+from .enums import CircuitState, HeartbeatStatus, KillLevel, KillScope
+from .models import (
+    AgentRegistration,
+    BudgetStatus,
+    CircuitBreakerState,
+    HeartbeatRecord,
+    KillEvent,
+    KillStatus,
+)
+
+__all__ = [
+    "AgentRegistration",
+    "BudgetStatus",
+    "CircuitBreakerState",
+    "CircuitState",
+    "HeartbeatRecord",
+    "HeartbeatStatus",
+    "KillEvent",
+    "KillLevel",
+    "KillScope",
+    "KillStatus",
+]