clm-plugin 0.1.0__tar.gz

clm_plugin-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# Testing & coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.hypothesis/
+
+# IDE & editor
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Kiro AI tool specs (internal only)
+.kiro/
+
+# CLM runtime artifacts
+clm_sidecar.db
+clm.db
+*.db
+
+# Logs
+*.log

clm_plugin-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] — 2025-03-31
+
+### First public release
+
+**Core architecture**
+- 5-layer cognitive load management: Signal Collector, CLM Scorer, Chunking Engine, Action Dispatcher, Sidecar Store
+- 4 cognitive load signals: branching factor, repetition rate, uncertainty density, goal distance
+- 3-zone intervention system: Green (pass), Amber (compress), Red (interrupt)
+- Abort action for structurally unresolvable tasks (5 consecutive Red triggers)
+- Amber escalation protection (3 consecutive Amber triggers → Red)
+
+**Integration**
+- `CLM()` — zero-argument instantiation with sensible defaults
+- `observe_raw()` — single-line integration, no TaskState construction required
+- `AutoStateBuilder` — automatic task tree inference from LLM outputs
+- LangChain adapter: `CLMCallbackHandler`
+- OpenAI Agents SDK adapter: `CLMOpenAIHook`
+- Generic loop adapter: `CLMLoop` with decorator and context manager support
+
+**Observability**
+- `verbose=True` — real-time step-by-step output
+- `get_history()` — full intervention log
+- `summary()` — session aggregate stats
+- `get_score()`, `get_zone()`, `get_sidecar_stats()`
+
+**Configuration**
+- `no_embed=True` — keyword-based fallback, zero model download, works offline
+- Fully tunable weights, thresholds, and zone boundaries
+- Domain-specific configuration examples: medical, legal, voice
+
+**Storage**
+- SQLite sidecar store, auto-created on first use
+- In-memory mode (default) for ephemeral sessions
+
+**Known limitations**
+- Default weights `[0.30, 0.25, 0.25, 0.20]` are heuristic, not empirically validated
+- AutoStateBuilder uses regex heuristics for task tree inference
+- `response.context` replaces task plan section only, not full conversation history
+- Embedding model requires ~90MB download on first use (avoidable with `no_embed=True`)

clm_plugin-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to CLM
+
+CLM is an open research project. Contributions, bug reports, and real-world usage reports are the most valuable thing you can give right now.
+
+## What we need most
+
+1. **Real-world usage reports** — Did CLM fire when it shouldn't? Did it miss an overload? Open an issue with your domain, agent type, and what happened.
+2. **Domain-specific weight tuning** — Found weights that work well for medical, legal, financial, or other domains? Submit a PR with a config example.
+3. **Bug reports** — Especially integration issues with specific agent frameworks.
+4. **Adapter contributions** — CrewAI, AutoGen, LlamaIndex, smolagents adapters welcome.
+
+## Getting started
+
+```bash
+git clone https://github.com/ragul-rofi/CognitiveLoadManager
+cd CognitiveLoadManager
+pip install -e ".[dev]"
+pytest tests/unit/ -q          # fast, no internet needed
+pytest tests/integration/ -q   # also offline-safe
+```
+
+## Running tests
+
+```bash
+pytest tests/unit/        # unit tests — always offline
+pytest tests/integration/ # integration tests — offline-safe (uses no_embed=True)
+pytest tests/ --cov=clm   # with coverage
+```
+
+## Principles
+
+- CLM must never crash an agent loop. Every failure path must return a valid InterventionResponse.
+- Every new public method needs a docstring.
+- New signals or intervention types go through an issue first — discuss before building.
+- The core scoring formula is intentionally tunable. Don't hardcode domain assumptions.
+
+## Roadmap (planned for v0.2)
+
+- Empirically validated default weights from real agent failure data
+- Explicit `clm.expand(task_id)` API for agent-initiated context recovery
+- Async `aobserve()` and `aobserve_raw()` for async agent frameworks
+- CrewAI and AutoGen adapters
+- Compression cooldown to prevent amber loop

clm_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: clm-plugin
+Version: 0.1.0
+Summary: Cognitive Load Manager — real-time metacognitive middleware for LLM agents
+Project-URL: Homepage, https://github.com/ragul-rofi/CognitiveLoadManager
+Project-URL: Documentation, https://github.com/ragul-rofi/CognitiveLoadManager#readme
+Project-URL: Issues, https://github.com/ragul-rofi/CognitiveLoadManager/issues
+License: MIT
+Keywords: agent,ai,cognitive,langchain,llm,memory,metacognition,middleware,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: sentence-transformers>=2.2.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.90.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# CLM — Cognitive Load Manager
+
+Real-time metacognitive middleware for LLM agents. Detects when your agent is cognitively overloaded and intervenes before it hallucinates, drifts, or crashes.
+
+```bash
+pip install clm-agent
+```
+
+## Quickstart — 3 lines
+
+```python
+from clm import CLM
+
+clm = CLM(verbose=True)
+
+# In your agent loop, replace nothing — just add one line:
+result = clm.observe_raw(llm_output)
+```
+
+That's it. CLM automatically builds its own internal task tree from your agent's outputs.
+
+## What it does
+
+CLM wraps your agent loop and monitors 4 cognitive signals after every LLM call:
+
+- **Branching** — how many tasks are in flight simultaneously
+- **Repetition** — is the agent going in circles
+- **Uncertainty** — is the agent hedging and guessing
+- **Goal drift** — has the agent wandered from the original intent
+
+It combines these into a single CLM score (0–100) and acts:
+
+| Zone | Score | Action |
+|------|-------|--------|
+| Green | 0–40 | Pass through — no intervention |
+| Amber | 40–70 | Compress deep task branches, patch context |
+| Red | 70–100 | Full compression + goal re-anchor + clarification request |
+
+## Integration patterns
+
+### Important: Context Patch Behavior
+
+⚠️ **response.context replaces only your task plan section, not your full conversation history**
+
+When CLM returns `action="patch"`, the `response.context` field contains a compressed representation of your task tree. You should inject this into the task planning portion of your prompt, not replace your entire conversation history.
+
+**Correct usage:**
+```python
+# Maintain conversation history, update only task section
+conversation_history = [...]  # Your full conversation
+task_section = result.context if result.action == "patch" else current_task_plan
+
+prompt = f"""
+Conversation so far:
+{conversation_history}
+
+Current task structure:
+{task_section}
+
+Continue working on the task.
+"""
+```
+
+**Incorrect usage:**
+```python
+# DON'T DO THIS - overwrites entire conversation
+if result.action == "patch":
+    prompt = result.context  # ❌ Loses all conversation history
+```
+
+### Pattern 1 — Minimal (observe_raw)
+No task state construction needed. Just feed outputs.
+
+```python
+from clm import CLM
+
+clm = CLM(verbose=True)
+
+while not done:
+    output = call_llm(prompt)
+    result = clm.observe_raw(output)
+    
+    if result.action == "interrupt":
+        prompt = f"Clarification needed: {result.clarification}"
+    elif result.action == "patch":
+        context = result.context  # use compressed context in next call
+
+print(clm.summary())
+```
+
+### Pattern 2 — LangChain (one line)
+
+```python
+from clm.adapters import CLMCallbackHandler
+
+handler = CLMCallbackHandler(verbose=True)
+agent.run("your task", callbacks=[handler])
+
+print(handler.clm.summary())
+```
+
+### Pattern 3 — Decorator (raw loop)
+
+```python
+from clm.adapters import CLMLoop
+
+loop = CLMLoop(verbose=True)
+
+@loop
+def agent_step(prompt: str) -> str:
+    return openai_client.chat(prompt)
+
+# Call normally — CLM wraps every call
+for i in range(max_steps):
+    output = agent_step(current_prompt)
+    if loop.clm.get_zone() == "Red":
+        break
+```
+
+### Pattern 4 — Full control (manual TaskState)
+
+```python
+from clm import CLM, CLMConfig
+from clm.core.models import TaskState, TaskTree, TaskNode
+
+clm = CLM(CLMConfig(verbose_signals=True), verbose=True)
+
+task_state = TaskState(task_tree=your_tree, ...)
+result = clm.observe(llm_output, task_state)
+```
+
+## Observability
+
+```python
+clm.get_score()       # current CLM score (0–100)
+clm.get_zone()        # "Green" | "Amber" | "Red"
+clm.get_history()     # full step-by-step intervention log
+clm.summary()         # aggregate stats for the session
+clm.get_sidecar_stats()  # compressed task storage stats
+```
+
+## No internet? No GPU? Use no_embed mode
+
+```python
+from clm import CLM, CLMConfig
+
+clm = CLM(CLMConfig(no_embed=True))  # keyword-based signals, no model download
+```
+
+## Configuration
+
+```python
+from clm import CLMConfig
+
+config = CLMConfig(
+    branching_threshold=7,    # active tasks before normalising to 1.0
+    repetition_threshold=0.85,
+    uncertainty_threshold=0.15,
+    weights=[0.30, 0.25, 0.25, 0.20],  # must sum to 1.0
+    green_max=40.0,
+    amber_max=70.0,
+    no_embed=False,           # set True to skip model download
+    storage_type="sqlite",
+    storage_params={"db_path": "clm.db"},  # omit for in-memory
+)
+```
+
+### Tuning Weights for Your Domain
+
+⚠️ **Default weights are informed heuristics, not empirically validated. Tune them for your domain using `CLMConfig(weights=[...])`.**
+
+The default weights `[0.30, 0.25, 0.25, 0.20]` (branching, repetition, uncertainty, goal_distance) are based on reasoning about general agent behavior, not empirical validation across domains.
+
+**How to tune:**
+
+1. **Start with defaults** and observe your agent's behavior with `verbose=True`
+2. **Identify false positives**: If CLM interrupts when your agent is working correctly, reduce the weight of the signal that triggered the intervention
+3. **Identify false negatives**: If CLM doesn't intervene when your agent is struggling, increase the weight of the signal that should have triggered intervention
+
+**Example: Reducing false positives from branching**
+
+If your agent legitimately needs to track many parallel tasks (e.g., data pipeline orchestration), but CLM keeps interrupting:
+
+```python
+# Default: branching weight = 0.30
+config = CLMConfig(weights=[0.15, 0.30, 0.30, 0.25])  # Reduce branching to 0.15
+```
+
+**Example: Increasing sensitivity to goal drift**
+
+If your agent frequently wanders off-task but CLM doesn't catch it:
+
+```python
+# Default: goal_distance weight = 0.20
+config = CLMConfig(weights=[0.25, 0.20, 0.20, 0.35])  # Increase goal_distance to 0.35
+```
+
+Remember: weights must sum to 1.0.
+
+## Domain-Specific Configuration
+
+CLM's default weights are tuned for general-purpose agent tasks. Different domains benefit from different signal priorities:
+
+### Medical Diagnosis Assistant
+
+Prioritize goal distance (staying on diagnostic protocol) and minimize false interruptions:
+
+```python
+from clm import CLM, CLMConfig
+
+config = CLMConfig(
+    weights=[0.20, 0.20, 0.15, 0.45],  # Heavy weight on goal_distance
+    green_max=50.0,  # Higher tolerance before intervention
+    amber_max=75.0,
+    branching_threshold=5,  # Medical protocols are often sequential
+)
+
+clm = CLM(config, verbose=True)
+```
+
+**Rationale:** Medical diagnosis requires strict adherence to diagnostic protocols. Goal drift is the most critical signal, while branching is less concerning since medical workflows are often linear.
+
+### Legal Document Analysis
+
+Prioritize repetition detection (circular reasoning) and uncertainty (hedging language):
+
+```python
+config = CLMConfig(
+    weights=[0.15, 0.35, 0.35, 0.15],  # Heavy weight on repetition and uncertainty
+    repetition_threshold=0.75,  # Lower threshold for detecting circular reasoning
+    uncertainty_threshold=0.20,  # Higher tolerance for legal hedging language
+)
+
+clm = CLM(config, verbose=True)
+```
+
+**Rationale:** Legal analysis must avoid circular reasoning and excessive hedging. Repetition and uncertainty are critical signals, while branching (considering multiple legal precedents) is expected behavior.
+
+### Voice Assistant
+
+Prioritize branching (context switching) and goal distance (staying on user intent):
+
+```python
+config = CLMConfig(
+    weights=[0.40, 0.15, 0.15, 0.30],  # Heavy weight on branching and goal_distance
+    branching_threshold=3,  # Voice interactions should stay focused
+    green_max=35.0,  # Lower tolerance for intervention
+)
+
+clm = CLM(config, verbose=True)
+```
+
+**Rationale:** Voice assistants must maintain tight focus on user intent and avoid context switching. Branching and goal distance are critical, while repetition and uncertainty are less concerning in conversational contexts.
+
+## Architecture
+
+5 layers, each independently testable:
+
+```
+Agent loop output
+      ↓
+Signal Collector   — extracts 4 cognitive signals
+      ↓
+CLM Scorer         — weighted score → zone classification
+      ↓
+Action Dispatcher  — routes to Green / Amber / Red handler
+      ↓
+Chunking Engine    — compress · anchor · expand
+      ↓
+Sidecar Store      — SQLite persistence for compressed tasks
+```
+
+## License
+
+MIT

clm_plugin-0.1.0/README.md

@@ -0,0 +1,275 @@
+# CLM — Cognitive Load Manager
+
+Real-time metacognitive middleware for LLM agents. Detects when your agent is cognitively overloaded and intervenes before it hallucinates, drifts, or crashes.
+
+```bash
+pip install clm-agent
+```
+
+## Quickstart — 3 lines
+
+```python
+from clm import CLM
+
+clm = CLM(verbose=True)
+
+# In your agent loop, replace nothing — just add one line:
+result = clm.observe_raw(llm_output)
+```
+
+That's it. CLM automatically builds its own internal task tree from your agent's outputs.
+
+## What it does
+
+CLM wraps your agent loop and monitors 4 cognitive signals after every LLM call:
+
+- **Branching** — how many tasks are in flight simultaneously
+- **Repetition** — is the agent going in circles
+- **Uncertainty** — is the agent hedging and guessing
+- **Goal drift** — has the agent wandered from the original intent
+
+It combines these into a single CLM score (0–100) and acts:
+
+| Zone | Score | Action |
+|------|-------|--------|
+| Green | 0–40 | Pass through — no intervention |
+| Amber | 40–70 | Compress deep task branches, patch context |
+| Red | 70–100 | Full compression + goal re-anchor + clarification request |
+
+## Integration patterns
+
+### Important: Context Patch Behavior
+
+⚠️ **response.context replaces only your task plan section, not your full conversation history**
+
+When CLM returns `action="patch"`, the `response.context` field contains a compressed representation of your task tree. You should inject this into the task planning portion of your prompt, not replace your entire conversation history.
+
+**Correct usage:**
+```python
+# Maintain conversation history, update only task section
+conversation_history = [...]  # Your full conversation
+task_section = result.context if result.action == "patch" else current_task_plan
+
+prompt = f"""
+Conversation so far:
+{conversation_history}
+
+Current task structure:
+{task_section}
+
+Continue working on the task.
+"""
+```
+
+**Incorrect usage:**
+```python
+# DON'T DO THIS - overwrites entire conversation
+if result.action == "patch":
+    prompt = result.context  # ❌ Loses all conversation history
+```
+
+### Pattern 1 — Minimal (observe_raw)
+No task state construction needed. Just feed outputs.
+
+```python
+from clm import CLM
+
+clm = CLM(verbose=True)
+
+while not done:
+    output = call_llm(prompt)
+    result = clm.observe_raw(output)
+    
+    if result.action == "interrupt":
+        prompt = f"Clarification needed: {result.clarification}"
+    elif result.action == "patch":
+        context = result.context  # use compressed context in next call
+
+print(clm.summary())
+```
+
+### Pattern 2 — LangChain (one line)
+
+```python
+from clm.adapters import CLMCallbackHandler
+
+handler = CLMCallbackHandler(verbose=True)
+agent.run("your task", callbacks=[handler])
+
+print(handler.clm.summary())
+```
+
+### Pattern 3 — Decorator (raw loop)
+
+```python
+from clm.adapters import CLMLoop
+
+loop = CLMLoop(verbose=True)
+
+@loop
+def agent_step(prompt: str) -> str:
+    return openai_client.chat(prompt)
+
+# Call normally — CLM wraps every call
+for i in range(max_steps):
+    output = agent_step(current_prompt)
+    if loop.clm.get_zone() == "Red":
+        break
+```
+
+### Pattern 4 — Full control (manual TaskState)
+
+```python
+from clm import CLM, CLMConfig
+from clm.core.models import TaskState, TaskTree, TaskNode
+
+clm = CLM(CLMConfig(verbose_signals=True), verbose=True)
+
+task_state = TaskState(task_tree=your_tree, ...)
+result = clm.observe(llm_output, task_state)
+```
+
+## Observability
+
+```python
+clm.get_score()       # current CLM score (0–100)
+clm.get_zone()        # "Green" | "Amber" | "Red"
+clm.get_history()     # full step-by-step intervention log
+clm.summary()         # aggregate stats for the session
+clm.get_sidecar_stats()  # compressed task storage stats
+```
+
+## No internet? No GPU? Use no_embed mode
+
+```python
+from clm import CLM, CLMConfig
+
+clm = CLM(CLMConfig(no_embed=True))  # keyword-based signals, no model download
+```
+
+## Configuration
+
+```python
+from clm import CLMConfig
+
+config = CLMConfig(
+    branching_threshold=7,    # active tasks before normalising to 1.0
+    repetition_threshold=0.85,
+    uncertainty_threshold=0.15,
+    weights=[0.30, 0.25, 0.25, 0.20],  # must sum to 1.0
+    green_max=40.0,
+    amber_max=70.0,
+    no_embed=False,           # set True to skip model download
+    storage_type="sqlite",
+    storage_params={"db_path": "clm.db"},  # omit for in-memory
+)
+```
+
+### Tuning Weights for Your Domain
+
+⚠️ **Default weights are informed heuristics, not empirically validated. Tune them for your domain using `CLMConfig(weights=[...])`.**
+
+The default weights `[0.30, 0.25, 0.25, 0.20]` (branching, repetition, uncertainty, goal_distance) are based on reasoning about general agent behavior, not empirical validation across domains.
+
+**How to tune:**
+
+1. **Start with defaults** and observe your agent's behavior with `verbose=True`
+2. **Identify false positives**: If CLM interrupts when your agent is working correctly, reduce the weight of the signal that triggered the intervention
+3. **Identify false negatives**: If CLM doesn't intervene when your agent is struggling, increase the weight of the signal that should have triggered intervention
+
+**Example: Reducing false positives from branching**
+
+If your agent legitimately needs to track many parallel tasks (e.g., data pipeline orchestration), but CLM keeps interrupting:
+
+```python
+# Default: branching weight = 0.30
+config = CLMConfig(weights=[0.15, 0.30, 0.30, 0.25])  # Reduce branching to 0.15
+```
+
+**Example: Increasing sensitivity to goal drift**
+
+If your agent frequently wanders off-task but CLM doesn't catch it:
+
+```python
+# Default: goal_distance weight = 0.20
+config = CLMConfig(weights=[0.25, 0.20, 0.20, 0.35])  # Increase goal_distance to 0.35
+```
+
+Remember: weights must sum to 1.0.
+
+## Domain-Specific Configuration
+
+CLM's default weights are tuned for general-purpose agent tasks. Different domains benefit from different signal priorities:
+
+### Medical Diagnosis Assistant
+
+Prioritize goal distance (staying on diagnostic protocol) and minimize false interruptions:
+
+```python
+from clm import CLM, CLMConfig
+
+config = CLMConfig(
+    weights=[0.20, 0.20, 0.15, 0.45],  # Heavy weight on goal_distance
+    green_max=50.0,  # Higher tolerance before intervention
+    amber_max=75.0,
+    branching_threshold=5,  # Medical protocols are often sequential
+)
+
+clm = CLM(config, verbose=True)
+```
+
+**Rationale:** Medical diagnosis requires strict adherence to diagnostic protocols. Goal drift is the most critical signal, while branching is less concerning since medical workflows are often linear.
+
+### Legal Document Analysis
+
+Prioritize repetition detection (circular reasoning) and uncertainty (hedging language):
+
+```python
+config = CLMConfig(
+    weights=[0.15, 0.35, 0.35, 0.15],  # Heavy weight on repetition and uncertainty
+    repetition_threshold=0.75,  # Lower threshold for detecting circular reasoning
+    uncertainty_threshold=0.20,  # Higher tolerance for legal hedging language
+)
+
+clm = CLM(config, verbose=True)
+```
+
+**Rationale:** Legal analysis must avoid circular reasoning and excessive hedging. Repetition and uncertainty are critical signals, while branching (considering multiple legal precedents) is expected behavior.
+
+### Voice Assistant
+
+Prioritize branching (context switching) and goal distance (staying on user intent):
+
+```python
+config = CLMConfig(
+    weights=[0.40, 0.15, 0.15, 0.30],  # Heavy weight on branching and goal_distance
+    branching_threshold=3,  # Voice interactions should stay focused
+    green_max=35.0,  # Lower tolerance for intervention
+)
+
+clm = CLM(config, verbose=True)
+```
+
+**Rationale:** Voice assistants must maintain tight focus on user intent and avoid context switching. Branching and goal distance are critical, while repetition and uncertainty are less concerning in conversational contexts.
+
+## Architecture
+
+5 layers, each independently testable:
+
+```
+Agent loop output
+      ↓
+Signal Collector   — extracts 4 cognitive signals
+      ↓
+CLM Scorer         — weighted score → zone classification
+      ↓
+Action Dispatcher  — routes to Green / Amber / Red handler
+      ↓
+Chunking Engine    — compress · anchor · expand
+      ↓
+Sidecar Store      — SQLite persistence for compressed tasks
+```
+
+## License
+
+MIT