capybala 0.8.0__py3-none-any.whl

capybala/__init__.py

@@ -0,0 +1,68 @@
+"""
+🦫 Capybala: Autonomous Agent Self-Healing & Deadlock-Resolution Runtime
+Context-Aware Pruning for Yielding & Backtrack-Aligned Loop Avoidance
+"""
+
+# The Requests-Grade Core API (Clean, Zero-Magic)
+from .api import watch, heal, validate, repair
+
+# Core Engine
+from .detector import DeadlockDetector, DeadlockEvent, DeadlockEmergencyStop
+from .pruner import ContextPruner, PruneResult
+from .healer import AgentHealer, HealingPrescription
+
+# Proactive Engine, Adaptive Policy & Semantic Attractor Manifold
+from .validator import SchemaValidator, repair_json_string
+from .proactive import SearchOptimizer
+from .policy import DeadlockPolicy, DeadlockMode
+from .attractor import SemanticAttractorDetector
+
+# Framework Integrations (Universal ABS Middleware)
+from .integrations import (
+    CapybalaLangGraphMiddleware,
+    capybala_node,
+    CapybalaCrewCallback,
+    CapybalaAutoGenFilter,
+)
+
+# Legacy / Base Adapters
+from .adapters import (
+    BaseAgentAdapter,
+    CapybalaGuard,
+    LlamaStackCapybalaMiddleware,
+    CapybalaCallbackHandler
+)
+
+__version__ = "0.8.0"
+__all__ = [
+    # Top-Level DX
+    "watch",
+    "heal",
+    "validate",
+    "repair",
+    # Core Engine
+    "DeadlockDetector",
+    "DeadlockEvent",
+    "DeadlockEmergencyStop",
+    "ContextPruner",
+    "PruneResult",
+    "AgentHealer",
+    "HealingPrescription",
+    # Proactive, Adaptive & Manifold
+    "SchemaValidator",
+    "repair_json_string",
+    "SearchOptimizer",
+    "DeadlockPolicy",
+    "DeadlockMode",
+    "SemanticAttractorDetector",
+    # Universal Integrations
+    "CapybalaLangGraphMiddleware",
+    "capybala_node",
+    "CapybalaCrewCallback",
+    "CapybalaAutoGenFilter",
+    # Adapters
+    "BaseAgentAdapter",
+    "CapybalaGuard",
+    "LlamaStackCapybalaMiddleware",
+    "CapybalaCallbackHandler",
+]

capybala/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""
+Universal Agent Adapters for Capybala.
+"""
+
+from .base import BaseAgentAdapter
+from .generic import CapybalaGuard, capybala_watch
+from .llama_stack import LlamaStackCapybalaMiddleware
+from .langchain import CapybalaCallbackHandler
+
+__all__ = [
+    "BaseAgentAdapter",
+    "CapybalaGuard",
+    "capybala_watch",
+    "LlamaStackCapybalaMiddleware",
+    "CapybalaCallbackHandler"
+]
+

capybala/adapters/base.py

@@ -0,0 +1,101 @@
+"""
+capybala.adapters.base
+~~~~~~~~~~~~~~~~~~~~~~
+Abstract Base Adapter for universal agent framework integration.
+Combines Detector, Pruner, and Healer into a unified lifecycle interceptor.
+Enforces Circuit Breakers against infinite healing loops.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Tuple, Optional
+from ..detector import DeadlockDetector, DeadlockEvent, DeadlockEmergencyStop
+from ..pruner import ContextPruner, PruneResult
+from ..healer import AgentHealer, HealingPrescription
+
+
+class BaseAgentAdapter(ABC):
+    """
+    Base lifecycle adapter connecting Capybala to any AI agent runtime.
+    """
+
+    def __init__(
+        self,
+        repetition_threshold: int = 3,
+        oscillation_threshold: int = 2,
+        supervisor_model: str = "meta-llama/llama-3.2-1b-instruct",
+        supervisor_client: Optional[Any] = None,
+        use_supervisor_llm: bool = False,
+        max_interventions: int = 5,
+        circuit_breaker_enabled: bool = True,
+    ):
+        self.detector = DeadlockDetector(
+            repetition_threshold=repetition_threshold,
+            oscillation_threshold=oscillation_threshold,
+            max_interventions=max_interventions,
+            circuit_breaker_enabled=circuit_breaker_enabled,
+        )
+        self.pruner = ContextPruner()
+        self.healer = AgentHealer(
+            supervisor_client=supervisor_client,
+            supervisor_model=supervisor_model,
+        )
+        self.use_supervisor_llm = use_supervisor_llm
+        self.interventions_count = 0
+        self.total_tokens_recovered = 0
+        self.is_circuit_broken = False
+
+    def intercept_step(
+        self,
+        action: str,
+        observation: str,
+        messages: List[Dict[str, Any]],
+        task_prompt: str = ""
+    ) -> Tuple[bool, List[Dict[str, Any]], Optional[HealingPrescription]]:
+        """
+        Intercepts an agent's execution step.
+
+        Parameters:
+        - action: The tool call or terminal command the agent executed.
+        - observation: The environment response / traceback output.
+        - messages: The running conversation history.
+        - task_prompt: The initial objective description.
+
+        Returns:
+        - (is_rescued, updated_messages, optional_prescription)
+        """
+        event = self.detector.check(action, observation)
+
+        if not event.is_deadlock:
+            return False, messages, None
+
+        # Deadlock detected! Execute Capybala self-healing protocol:
+        self.interventions_count += 1
+        if event.is_circuit_broken:
+            self.is_circuit_broken = True
+
+        # 1. Formulate strategic Doctor Prescription with progressive escalation
+        rx = self.healer.prescribe(
+            deadlock_pattern=event.pattern_type or "unknown",
+            failing_action=action,
+            error_signature=observation,
+            task_prompt=task_prompt,
+            use_supervisor_llm=self.use_supervisor_llm,
+            escalation_level=event.consecutive_deadlocks or 1,
+        )
+
+        # 2. Execute Atomic Checkpoint Rollback with Domain Guidance
+        prune_result = self.pruner.rollback_and_reflect(
+            messages=messages,
+            failing_action=action,
+            deadlock_details=event.details,
+            reflection_guidance=rx.recommended_pivot,
+            rollback_turns=event.repetition_count * 2,
+        )
+        self.total_tokens_recovered += prune_result.tokens_saved_estimate
+
+        return True, prune_result.pruned_messages, rx
+
+    def reset(self):
+        """Resets detector state for a new conversation turn."""
+        self.detector.reset()
+        self.is_circuit_broken = False

capybala/adapters/generic.py

@@ -0,0 +1,114 @@
+"""
+capybala.adapters.generic
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Generic adapter for raw message lists, OpenAI API, Anthropic, Ollama, and custom agent loops.
+Provides both an object wrapper (`CapybalaGuard`) and a decorator (`@capybala_watch`).
+"""
+
+import functools
+from typing import List, Dict, Any, Optional, Callable
+from .base import BaseAgentAdapter
+from ..healer import HealingPrescription
+
+
+class CapybalaGuard(BaseAgentAdapter):
+    """
+    Lightweight runtime guard wrapping an agent's active conversation messages.
+    """
+
+    def __init__(
+        self,
+        messages: List[Dict[str, Any]],
+        task_prompt: str = "",
+        repetition_threshold: int = 3,
+        oscillation_threshold: int = 2,
+        supervisor_model: str = "meta-llama/llama-3.2-1b-instruct",
+        supervisor_client: Optional[Any] = None,
+        use_supervisor_llm: bool = False,
+        max_interventions: int = 5,
+        circuit_breaker_enabled: bool = True,
+    ):
+        super().__init__(
+            repetition_threshold=repetition_threshold,
+            oscillation_threshold=oscillation_threshold,
+            supervisor_model=supervisor_model,
+            supervisor_client=supervisor_client,
+            use_supervisor_llm=use_supervisor_llm,
+            max_interventions=max_interventions,
+            circuit_breaker_enabled=circuit_breaker_enabled,
+        )
+        self.messages = messages
+        self.task_prompt = task_prompt
+        self.latest_prescription: Optional[HealingPrescription] = None
+        self.is_deadlocked: bool = False
+
+    def step(self, action: str, observation: str) -> bool:
+        """
+        Record an action and observation turn.
+        If a deadlock is identified, self-heals in-place and updates `self.messages`.
+
+        Returns:
+        - True if a deadlock was intercepted and healed, False otherwise.
+        """
+        is_rescued, updated_msgs, rx = self.intercept_step(
+            action=action,
+            observation=observation,
+            messages=self.messages,
+            task_prompt=self.task_prompt
+        )
+
+        if is_rescued:
+            self.messages.clear()
+            self.messages.extend(updated_msgs)
+            self.latest_prescription = rx
+            self.is_deadlocked = True
+            return True
+
+        self.is_deadlocked = False
+        return False
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+
+def capybala_watch(
+    repetition_threshold: int = 3,
+    use_supervisor_llm: bool = False,
+    supervisor_model: str = "meta-llama/llama-3.2-1b-instruct"
+):
+    """
+    Function decorator to automatically attach Capybala deadlock detection
+    and self-healing to an autonomous agent step function.
+    """
+    def decorator(func: Callable):
+        adapter = BaseAgentAdapter(
+            repetition_threshold=repetition_threshold,
+            use_supervisor_llm=use_supervisor_llm,
+            supervisor_model=supervisor_model
+        )
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Expecting kwargs or args containing 'action', 'observation', and 'messages'
+            action = kwargs.get("action", "")
+            observation = kwargs.get("observation", "")
+            messages = kwargs.get("messages", None)
+
+            if messages is not None and action:
+                rescued, updated_msgs, rx = adapter.intercept_step(
+                    action=action,
+                    observation=observation,
+                    messages=messages
+                )
+                if rescued:
+                    kwargs["messages"] = updated_msgs
+                    kwargs["capybala_healed"] = True
+                    kwargs["prescription"] = rx
+
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+

capybala/adapters/langchain.py

@@ -0,0 +1,78 @@
+"""
+capybala.adapters.langchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+LangChain & LangGraph integration for Capybala.
+Provides a drop-in CallbackHandler that tracks tool loops and alerts/heals agents.
+"""
+
+from typing import Dict, Any, List, Optional
+from .base import BaseAgentAdapter
+from ..healer import HealingPrescription
+
+# Optional duck-typed inheritance from langchain_core if installed
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+except ImportError:
+    class BaseCallbackHandler:  # type: ignore
+        """Fallback base class when langchain is not installed."""
+        pass
+
+
+class CapybalaCallbackHandler(BaseCallbackHandler, BaseAgentAdapter):
+    """
+    Drop-in LangChain CallbackHandler that watches tool calls for cognitive deadlocks.
+    Usage:
+        agent_executor = create_react_agent(..., callbacks=[CapybalaCallbackHandler()])
+    """
+
+    def __init__(
+        self,
+        repetition_threshold: int = 3,
+        supervisor_model: str = "meta-llama/llama-3.2-1b-instruct",
+        use_supervisor_llm: bool = False,
+    ):
+        BaseCallbackHandler.__init__(self)
+        BaseAgentAdapter.__init__(
+            self,
+            repetition_threshold=repetition_threshold,
+            supervisor_model=supervisor_model,
+            use_supervisor_llm=use_supervisor_llm,
+        )
+        self.last_action_name: str = ""
+        self.last_action_input: str = ""
+        self.deadlock_triggered: bool = False
+        self.last_prescription: Optional[HealingPrescription] = None
+
+    def on_tool_start(self, serialized: Dict[str, Any], input_str: str, **kwargs: Any) -> None:
+        """Called when a LangChain tool starts running."""
+        self.last_action_name = serialized.get("name", "tool")
+        self.last_action_input = str(input_str)
+
+    def on_tool_end(self, output: str, **kwargs: Any) -> None:
+        """Called when a LangChain tool finishes running."""
+        action = f"{self.last_action_name}: {self.last_action_input}"
+        event = self.detector.check(action, str(output))
+
+        if event.is_deadlock:
+            self.deadlock_triggered = True
+            rx = self.healer.prescribe(
+                deadlock_pattern=event.pattern_type or "tool_loop",
+                failing_action=action,
+                error_signature=str(output)
+            )
+            self.last_prescription = rx
+
+    def on_tool_error(self, error: BaseException, **kwargs: Any) -> None:
+        """Called when a LangChain tool encounters an unhandled exception."""
+        action = f"{self.last_action_name}: {self.last_action_input}"
+        event = self.detector.check(action, f"{type(error).__name__}: {str(error)}")
+
+        if event.is_deadlock:
+            self.deadlock_triggered = True
+            rx = self.healer.prescribe(
+                deadlock_pattern=event.pattern_type or "tool_error_loop",
+                failing_action=action,
+                error_signature=str(error)
+            )
+            self.last_prescription = rx
+

capybala/adapters/llama_stack.py

@@ -0,0 +1,72 @@
+"""
+capybala.adapters.llama_stack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Native Meta Llama Stack Agent Middleware.
+Seamlessly integrates with Llama Stack Agent sessions, intercepting runaway
+tool loops and pruning context windows on Llama-3.1-70B/405B agents using
+an out-of-band Llama-3.2-1B/3B supervisor.
+"""
+
+from typing import List, Dict, Any, Optional, Tuple
+from .base import BaseAgentAdapter
+from ..healer import HealingPrescription
+
+
+class LlamaStackCapybalaMiddleware(BaseAgentAdapter):
+    """
+    Middleware for Meta Llama Stack Agent runtimes.
+    Can be used as a turn interceptor in Llama Stack Agent loops.
+    """
+
+    def __init__(
+        self,
+        repetition_threshold: int = 3,
+        supervisor_model: str = "meta-llama/llama-3.2-1b-instruct",
+        supervisor_client: Optional[Any] = None,
+        use_supervisor_llm: bool = False,
+    ):
+        super().__init__(
+            repetition_threshold=repetition_threshold,
+            supervisor_model=supervisor_model,
+            supervisor_client=supervisor_client,
+            use_supervisor_llm=use_supervisor_llm,
+        )
+
+    def on_tool_step(
+        self,
+        tool_name: str,
+        tool_arguments: Dict[str, Any],
+        tool_output: str,
+        session_turns: List[Dict[str, Any]]
+    ) -> Tuple[bool, List[Dict[str, Any]], Optional[HealingPrescription]]:
+        """
+        Intercepts a Llama Stack tool execution step.
+
+        Parameters:
+        - tool_name: Name of tool called (e.g. 'execute_code', 'terminal')
+        - tool_arguments: Dict of arguments passed to tool
+        - tool_output: The environment response or stdout/stderr
+        - session_turns: Llama Stack message list for current agent session
+
+        Returns:
+        - (is_deadlocked, rescued_turns, optional_prescription)
+        """
+        # Create a canonical representation of the action
+        action_signature = f"{tool_name}({tool_arguments})"
+
+        return self.intercept_step(
+            action=action_signature,
+            observation=tool_output,
+            messages=session_turns
+        )
+
+    def wrap_turn_request(self, agent_client: Any, session_id: str, turn_request: Dict[str, Any]) -> Any:
+        """
+        Helper method to wrap a Llama Stack client agent.turn.create call.
+        """
+        # Standalone pass-through hook for Llama Stack client integration
+        return agent_client.agents.turn.create(
+            session_id=session_id,
+            **turn_request
+        )
+