clm-plugin 0.1.0__py3-none-any.whl

clm/__init__.py

@@ -0,0 +1,59 @@
+"""
+Cognitive Load Manager (CLM) v0.1
+
+A metacognitive middleware layer for LLM-based agent loops that monitors
+cognitive load, detects overload conditions, and intervenes through task
+compression, goal anchoring, and clarification requests.
+"""
+
+__version__ = "0.1.0"
+
+from clm.cognitive_load_manager import CognitiveLoadManager
+from clm.core.config import CLMConfig
+from clm.core.models import TaskState, TaskTree, TaskNode, InterventionResponse
+from clm.utils.auto_state import AutoStateBuilder
+from clm.exceptions import (
+    CLMError,
+    ConfigurationError,
+    StorageError,
+    EmbeddingError,
+    ValidationError,
+    ExpansionError,
+)
+
+# Shorthand alias — users write CLM() not CognitiveLoadManager()
+CLM = CognitiveLoadManager
+
+# Import adapters with graceful fallback for missing optional dependencies
+try:
+    from clm.adapters.langchain_adapter import CLMCallbackHandler
+except ImportError:
+    pass  # LangChain not installed, adapter unavailable
+
+try:
+    from clm.adapters.openai_adapter import CLMOpenAIHook
+except ImportError:
+    pass
+
+from clm.adapters.loop_adapter import CLMLoop
+
+__all__ = [
+    "CognitiveLoadManager",
+    "CLM",
+    "CLMConfig",
+    "TaskState",
+    "TaskTree",
+    "TaskNode",
+    "InterventionResponse",
+    "AutoStateBuilder",
+    "CLMError",
+    "ConfigurationError",
+    "StorageError",
+    "EmbeddingError",
+    "ValidationError",
+    "ExpansionError",
+    "CLMCallbackHandler",
+    "CLMOpenAIHook",
+    "CLMLoop",
+]
+

clm/adapters/__init__.py

@@ -0,0 +1,11 @@
+from clm.adapters.loop_adapter import CLMLoop
+
+try:
+    from clm.adapters.langchain_adapter import CLMCallbackHandler
+except ImportError:
+    pass
+
+try:
+    from clm.adapters.openai_adapter import CLMOpenAIHook
+except ImportError:
+    pass

clm/adapters/langchain_adapter.py

@@ -0,0 +1,121 @@
+"""
+LangChain adapter for CLM.
+Usage:
+    from clm.adapters import CLMCallbackHandler
+    agent.run(input, callbacks=[CLMCallbackHandler(verbose=True)])
+"""
+import uuid
+from typing import Any
+
+try:
+    from langchain.callbacks.base import BaseCallbackHandler
+except ImportError:
+    raise ImportError(
+        "LangChain is required for CLMCallbackHandler. "
+        "Install it with: pip install clm-agent[langchain]"
+    )
+
+from clm import CognitiveLoadManager, CLMConfig
+from clm.core.models import TaskState, TaskTree, TaskNode
+
+
+class CLMCallbackHandler(BaseCallbackHandler):
+    """
+    Drop-in CLM integration for any LangChain agent or chain.
+    
+    Automatically builds a TaskTree from LLM calls and tool invocations.
+    No manual task state construction required.
+    
+    Usage:
+        clm_handler = CLMCallbackHandler(verbose=True)
+        agent.run("your task", callbacks=[clm_handler])
+        
+        # After run, inspect what CLM did:
+        print(clm_handler.clm.summary())
+    """
+    
+    def __init__(self, config: CLMConfig = None, verbose: bool = False):
+        super().__init__()
+        self.clm = CognitiveLoadManager(config, verbose=verbose)
+        self._history: list[str] = []
+        self._tool_calls: list[str] = []
+        self._root_intent: str = ""
+        self._session_id = str(uuid.uuid4())[:8]
+        
+        # Build a live task tree that grows as the agent runs
+        root_id = f"root_{self._session_id}"
+        self._task_tree = TaskTree(
+            root=TaskNode(
+                task_id=root_id,
+                parent_id=None,
+                description="agent_session",
+                status="active",
+                depth=0
+            ),
+            root_intent=""
+        )
+        self._current_task_id = root_id
+    
+    def on_llm_start(self, serialized: dict, prompts: list[str], **kwargs) -> None:
+        """Capture root intent from first prompt."""
+        if not self._root_intent and prompts:
+            self._root_intent = prompts[0][:300]
+            self._task_tree.root_intent = self._root_intent
+            self._task_tree.root.description = self._root_intent[:100]
+    
+    def on_llm_end(self, response: Any, **kwargs) -> None:
+        """Observe after every LLM call — the core integration point."""
+        try:
+            output = response.generations[0][0].text
+        except (IndexError, AttributeError):
+            return
+        
+        self._history.append(output)
+        
+        task_state = TaskState(
+            task_tree=self._task_tree,
+            current_task_id=self._current_task_id,
+            reasoning_history=self._history[-3:]
+        )
+        
+        result = self.clm.observe(output, task_state)
+        
+        # If patch: update task tree with compressed context
+        if result.action == "patch" and result.context:
+            self._task_tree.root.description = result.context[:200]
+    
+    def on_tool_start(self, serialized: dict, input_str: str, **kwargs) -> None:
+        """Each tool call is a new sub-task node in the tree."""
+        tool_name = serialized.get("name", "unknown_tool")
+        task_id = f"tool_{tool_name}_{len(self._tool_calls)}"
+        self._tool_calls.append(task_id)
+        
+        new_node = TaskNode(
+            task_id=task_id,
+            parent_id=self._task_tree.root.task_id,
+            description=f"{tool_name}: {input_str[:100]}",
+            status="active",
+            depth=1
+        )
+        self._task_tree.root.children.append(new_node)
+        self._current_task_id = task_id
+    
+    def on_tool_end(self, output: str, **kwargs) -> None:
+        """Mark tool task complete, return focus to root."""
+        current = self._task_tree.find_node(self._current_task_id)
+        if current:
+            current.status = "completed"
+        self._current_task_id = self._task_tree.root.task_id
+    
+    def on_chain_end(self, outputs: dict, **kwargs) -> None:
+        """Chain finished — print summary if verbose."""
+        if self.clm.verbose:
+            s = self.clm.summary()
+            print(
+                f"\n[CLM] Session complete — "
+                f"{s['steps']} steps | avg score {s['avg_score']} | "
+                f"peak {s['peak_score']} | "
+                f"patches={s['interventions']['patch']} "
+                f"interrupts={s['interventions']['interrupt']}",
+                flush=True
+            )

clm/adapters/loop_adapter.py

@@ -0,0 +1,135 @@
+"""
+Generic loop adapter for CLM. Works with any LLM: OpenAI, Anthropic, Gemini, local models.
+
+Usage:
+    from clm.adapters import CLMLoop
+    
+    @CLMLoop(verbose=True)
+    def my_agent_step(prompt: str) -> str:
+        return openai_client.chat(prompt)  # or any LLM call
+    
+    # Now call it normally — CLM wraps every step automatically
+    for i in range(10):
+        response = my_agent_step(current_prompt)
+"""
+import uuid
+import functools
+from clm import CognitiveLoadManager, CLMConfig
+from clm.core.models import TaskState, TaskTree, TaskNode
+
+
+class CLMLoop:
+    """
+    Decorator that wraps any agent step function with CLM.
+    
+    The decorated function must accept a string prompt and return a string output.
+    CLM observes every call automatically, maintaining its own internal task tree.
+    
+    Usage as decorator:
+        @CLMLoop(verbose=True)
+        def agent_step(prompt: str) -> str:
+            return llm_call(prompt)
+    
+    Usage as context manager:
+        with CLMLoop(verbose=True) as loop:
+            for step in range(max_steps):
+                output = loop.step(prompt, task_description="current subtask")
+                if loop.should_stop():
+                    break
+    
+    Access CLM internals any time:
+        loop.clm.summary()
+        loop.clm.get_history()
+        loop.clm.get_score()
+    """
+    
+    def __init__(self, config: CLMConfig = None, verbose: bool = False):
+        self.clm = CognitiveLoadManager(config, verbose=verbose)
+        self._history: list[str] = []
+        self._session_id = str(uuid.uuid4())[:8]
+        self._step_count = 0
+        self._root_intent = ""
+        
+        root_id = f"root_{self._session_id}"
+        self._task_tree = TaskTree(
+            root=TaskNode(root_id, None, "loop_root", "active", depth=0),
+            root_intent=""
+        )
+        self._current_task_id = root_id
+    
+    def __call__(self, fn):
+        """Decorator usage: @CLMLoop()"""
+        @functools.wraps(fn)
+        def wrapper(prompt: str, *args, **kwargs) -> str:
+            output = fn(prompt, *args, **kwargs)
+            self._observe(prompt, output)
+            return output
+        wrapper.clm = self.clm
+        wrapper.summary = self.clm.summary
+        wrapper.get_history = self.clm.get_history
+        return wrapper
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, *args):
+        self.clm.close()
+    
+    def step(self, prompt: str, output: str = None,
+             task_description: str = None) -> dict:
+        """
+        Manually advance one step. Pass prompt + output, get CLM result back.
+        If output is None, returns a partial state (pre-LLM call marker).
+        
+        Returns the InterventionResponse as a dict so callers can branch on it.
+        """
+        if output is None:
+            # pre-call: just record the intent
+            if not self._root_intent:
+                self._root_intent = prompt[:300]
+                self._task_tree.root_intent = self._root_intent
+            return {"action": "pending"}
+        
+        result = self._observe(prompt, output, task_description)
+        return {
+            "action": result.action,
+            "zone": result.zone,
+            "score": result.clm_score,
+            "context": result.context,
+            "clarification": result.clarification,
+        }
+    
+    def should_stop(self) -> bool:
+        """
+        Returns True if CLM is in Red zone — useful for agents that want to
+        pause and ask for clarification rather than continuing blind.
+        """
+        return self.clm.get_zone() == "Red"
+    
+    def _observe(self, prompt: str, output: str,
+                 task_description: str = None) -> object:
+        self._step_count += 1
+        self._history.append(output)
+        
+        if not self._root_intent:
+            self._root_intent = prompt[:300]
+            self._task_tree.root_intent = self._root_intent
+        
+        # Add step as a child node
+        step_id = f"step_{self._step_count}"
+        node = TaskNode(
+            task_id=step_id,
+            parent_id=self._task_tree.root.task_id,
+            description=task_description or output[:100],
+            status="active",
+            depth=1
+        )
+        self._task_tree.root.children.append(node)
+        self._current_task_id = step_id
+        
+        state = TaskState(
+            task_tree=self._task_tree,
+            current_task_id=self._current_task_id,
+            reasoning_history=self._history[-3:]
+        )
+        return self.clm.observe(output, state)

clm/adapters/openai_adapter.py

@@ -0,0 +1,94 @@
+"""
+OpenAI Agents SDK adapter for CLM.
+
+Usage:
+    from clm.adapters import CLMOpenAIHook
+    
+    hook = CLMOpenAIHook(verbose=True)
+    # Pass hook.on_message as a callback to your OpenAI agent runner
+    # OR use hook.wrap(runner) to auto-attach
+"""
+import uuid
+from clm import CognitiveLoadManager, CLMConfig
+from clm.core.models import TaskState, TaskTree, TaskNode
+
+
+class CLMOpenAIHook:
+    """
+    Lifecycle hooks for OpenAI Agents SDK.
+    
+    Compatible with openai-agents SDK on_message_end and on_tool_call hooks.
+    
+    Usage:
+        hook = CLMOpenAIHook(verbose=True)
+        
+        # Manual hook attachment:
+        result = await Runner.run(agent, input,
+                                  hooks=hook.get_hooks())
+        
+        # After run:
+        print(hook.clm.summary())
+    """
+    
+    def __init__(self, config: CLMConfig = None, verbose: bool = False):
+        self.clm = CognitiveLoadManager(config, verbose=verbose)
+        self._history: list[str] = []
+        self._tool_nodes: list[str] = []
+        session_id = str(uuid.uuid4())[:8]
+        root_id = f"root_{session_id}"
+        self._task_tree = TaskTree(
+            root=TaskNode(root_id, None, "openai_agent_session", "active", depth=0),
+            root_intent=""
+        )
+        self._current_task_id = root_id
+    
+    def on_message_end(self, message) -> None:
+        """Hook: fires after each agent message/LLM response."""
+        content = ""
+        if hasattr(message, "content"):
+            content = str(message.content)
+        elif hasattr(message, "text"):
+            content = str(message.text)
+        
+        if not content:
+            return
+        
+        self._history.append(content)
+        if not self._task_tree.root_intent:
+            self._task_tree.root_intent = content[:300]
+        
+        state = TaskState(
+            task_tree=self._task_tree,
+            current_task_id=self._current_task_id,
+            reasoning_history=self._history[-3:]
+        )
+        self.clm.observe(content, state)
+    
+    def on_tool_call(self, tool_name: str, tool_input: dict) -> None:
+        """Hook: fires before each tool call."""
+        task_id = f"tool_{tool_name}_{len(self._tool_nodes)}"
+        self._tool_nodes.append(task_id)
+        node = TaskNode(
+            task_id=task_id,
+            parent_id=self._task_tree.root.task_id,
+            description=f"{tool_name}: {str(tool_input)[:100]}",
+            status="active",
+            depth=1
+        )
+        self._task_tree.root.children.append(node)
+        self._current_task_id = task_id
+    
+    def on_tool_end(self, tool_name: str, output: str) -> None:
+        """Hook: fires after each tool call."""
+        node = self._task_tree.find_node(self._current_task_id)
+        if node:
+            node.status = "completed"
+        self._current_task_id = self._task_tree.root.task_id
+    
+    def get_hooks(self) -> dict:
+        """Return hooks dict compatible with OpenAI Agents SDK Runner."""
+        return {
+            "on_message_end": self.on_message_end,
+            "on_tool_call": self.on_tool_call,
+            "on_tool_end": self.on_tool_end,
+        }