entroplain 0.1.0 → 0.1.1

package/docs/AGENT_USAGE.md

@@ -0,0 +1,178 @@
+# Entroplain Usage Guide for Agents
+
+## Quick Setup
+
+### For OpenClaw/Claude Code (Proxy Method)
+
+Run the entropy proxy and point your agent to it:
+
+```bash
+# Start the proxy (monitors entropy, enables early exit)
+python -m entroplain.proxy --port 8765 --log-entropy
+
+# Set environment to use proxy
+export OPENAI_BASE_URL=http://localhost:8765/v1
+# or for NVIDIA:
+export NVIDIA_BASE_URL=http://localhost:8765/v1
+```
+
+Now OpenClaw/Claude Code will automatically have entropy monitoring!
+
+### How the Proxy Works
+
+```
+Agent -> Proxy (localhost:8765) -> Real API
+           |
+           v
+      Entropy Monitor
+           |
+           v
+      Early Exit Check
+```
+
+The proxy:
+1. Intercepts all chat completion requests
+2. Enables logprobs automatically
+3. Calculates entropy for each token
+4. Terminates stream when reasoning converges
+5. Passes everything through unchanged to the agent
+
+---
+
+## Direct Usage (Python)
+
+```python
+from entroplain import EntropyMonitor, NVIDIAProvider
+
+monitor = EntropyMonitor()
+provider = NVIDIAProvider()
+
+for token in provider.stream_with_entropy(
+    model="meta/llama-3.1-70b-instruct",
+    messages=[{"role": "user", "content": "Solve: x^2 = 16"}]
+):
+    monitor.track(token.token, token.entropy)
+    print(token.token, end="")
+    
+    if monitor.should_exit():
+        print("\n[Early exit - reasoning converged]")
+        break
+
+print(f"\nStats: {monitor.get_stats()}")
+```
+
+---
+
+## Supported Providers
+
+| Provider | Works? | How |
+|----------|--------|-----|
+| OpenAI | YES | `logprobs: true` |
+| NVIDIA NIM | YES | OpenAI-compatible |
+| Anthropic Claude 4 | YES | `logprobs: True` |
+| Google Gemini | YES | `response_logprobs=True` |
+| Ollama (local) | YES | Built-in logit access |
+| llama.cpp | YES | Built-in logit access |
+
+---
+
+## Configuration
+
+### Exit Conditions
+
+```python
+monitor = EntropyMonitor(
+    entropy_threshold=0.15,  # Exit when entropy drops below this
+    min_valleys=2,           # Require N reasoning milestones
+    min_tokens=50,           # Don't exit before this many tokens
+    velocity_threshold=0.05, # Exit when change rate stabilizes
+    exit_condition="combined"  # or: "valleys_plateau", "entropy_drop", "velocity_zero"
+)
+```
+
+### Environment Variables
+
+```bash
+# API keys (used by providers)
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export NVIDIA_API_KEY=nvapi-...
+export GOOGLE_API_KEY=...
+
+# For proxy
+export ENTROPPLAIN_PORT=8765
+export ENTROPPLAIN_LOG_ENTROPY=true
+```
+
+---
+
+## CLI
+
+```bash
+# Analyze a prompt
+entroplain analyze "What is 2+2?" --model gpt-4o
+
+# Stream with early exit
+entroplain stream "Explain quantum computing" --exit-on-converge
+
+# Run proxy
+entroplain proxy --port 8765 --log-entropy
+```
+
+---
+
+## Agent Integration Examples
+
+### OpenClaw with Proxy
+
+```yaml
+# In config.yaml
+llm:
+  provider: openai-compatible
+  base_url: http://localhost:8765/v1  # Point to proxy
+  primary_model: meta/llama-3.1-70b-instruct
+```
+
+### Claude Code with Proxy
+
+Set environment before running:
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8765/v1
+claude
+```
+
+### Custom Agent
+
+```python
+from entroplain.hooks import EntropyHook
+
+hook = EntropyHook(config={"entropy_threshold": 0.15})
+
+for token in your_agent.generate_stream():
+    result = hook.on_token(token.text, token.entropy)
+    
+    if result["should_exit"]:
+        print(f"Early exit at token {result['index']}")
+        break
+```
+
+---
+
+## Troubleshooting
+
+### "No logprobs returned"
+Some models don't support logprobs. Try a different model or check provider docs.
+
+### "Entropy is always 0"
+Make sure `logprobs: true` and `top_logprobs: 5` are set in your API request.
+
+### "Proxy won't start"
+Install dependencies: `pip install entroplain[all] fastapi uvicorn httpx`
+
+---
+
+## Learn More
+
+- GitHub: https://github.com/entroplain/entroplain
+- PyPI: https://pypi.org/project/entroplain/
+- npm: https://www.npmjs.com/package/entroplain

package/entroplain/__init__.py

@@ -2,7 +2,7 @@
 Entroplain — Entropy-based early exit for efficient agent reasoning.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __author__ = "Entroplain Contributors"
 
 from .monitor import EntropyMonitor, calculate_entropy
@@ -15,6 +15,7 @@ from .providers import (
     LlamaCppProvider,
 )
 from .hooks import track_entropy, early_exit
+from .proxy import EntropyProxy, ProxyConfig
 
 __all__ = [
     "EntropyMonitor",
@@ -27,4 +28,6 @@ __all__ = [
     "LlamaCppProvider",
     "track_entropy",
     "early_exit",
+    "EntropyProxy",
+    "ProxyConfig",
 ]

package/entroplain/proxy.py

@@ -0,0 +1,278 @@
+"""
+Entropy Monitoring Proxy for OpenClaw/Claude Code.
+
+This proxy intercepts LLM API calls and adds entropy monitoring,
+enabling early exit without modifying the agent framework itself.
+
+Usage:
+    # Set as your API endpoint
+    export OPENAI_BASE_URL=http://localhost:8765
+    
+    # Run the proxy
+    python -m entroplain.proxy --port 8765 --provider openai
+"""
+
+import json
+import asyncio
+import logging
+from typing import Optional, Dict, Any, AsyncIterator
+from dataclasses import dataclass
+import httpx
+from fastapi import FastAPI, Request, Response
+from fastapi.responses import StreamingResponse
+import uvicorn
+
+from .monitor import EntropyMonitor
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProxyConfig:
+    """Configuration for the entropy proxy."""
+    port: int = 8765
+    provider: str = "openai"  # openai, anthropic, nvidia
+    api_base: str = "https://api.openai.com/v1"
+    entropy_threshold: float = 0.15
+    min_valleys: int = 2
+    min_tokens: int = 50
+    velocity_threshold: float = 0.05
+    enable_early_exit: bool = True
+    log_entropy: bool = True
+
+
+class EntropyProxy:
+    """
+    Proxy that adds entropy monitoring to LLM API calls.
+    
+    Intercepts streaming responses, calculates entropy, and can
+    terminate early when reasoning has converged.
+    """
+    
+    def __init__(self, config: ProxyConfig):
+        self.config = config
+        self.monitor = EntropyMonitor(
+            entropy_threshold=config.entropy_threshold,
+            min_valleys=config.min_valleys,
+            min_tokens=config.min_tokens,
+            velocity_threshold=config.velocity_threshold
+        )
+        self.app = FastAPI(title="Entroplain Proxy")
+        self._setup_routes()
+    
+    def _setup_routes(self):
+        @self.app.post("/v1/chat/completions")
+        async def chat_completions(request: Request):
+            return await self._handle_chat(request)
+        
+        @self.app.get("/health")
+        async def health():
+            return {"status": "ok", "monitor": self.monitor.get_stats()}
+        
+        @self.app.post("/reset")
+        async def reset():
+            self.monitor.reset()
+            return {"status": "reset"}
+    
+    async def _handle_chat(self, request: Request):
+        """Handle chat completion requests with entropy monitoring."""
+        body = await request.json()
+        
+        # Ensure logprobs are enabled for entropy calculation
+        if "logprobs" not in body:
+            body["logprobs"] = True
+        if "top_logprobs" not in body:
+            body["top_logprobs"] = 5
+        
+        # Reset monitor for new request
+        self.monitor.reset()
+        
+        # Forward request to actual API
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.config.api_base}/chat/completions",
+                json=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": request.headers.get("Authorization", "")
+                },
+                timeout=120.0
+            )
+        
+        if not body.get("stream", False):
+            # Non-streaming: just return response
+            return Response(
+                content=response.content,
+                status_code=response.status_code,
+                headers=dict(response.headers)
+            )
+        
+        # Streaming: monitor entropy and potentially exit early
+        return StreamingResponse(
+            self._stream_with_entropy(response),
+            media_type="text/event-stream"
+        )
+    
+    async def _stream_with_entropy(
+        self, response: httpx.Response
+    ) -> AsyncIterator[str]:
+        """Stream response with entropy monitoring."""
+        exited_early = False
+        full_content = ""
+        
+        async for line in response.aiter_lines():
+            if not line.startswith("data: "):
+                yield line + "\n"
+                continue
+            
+            data = line[6:]  # Remove "data: " prefix
+            if data == "[DONE]":
+                yield line + "\n"
+                break
+            
+            try:
+                chunk = json.loads(data)
+            except json.JSONDecodeError:
+                yield line + "\n"
+                continue
+            
+            # Extract token and logprobs
+            if chunk.get("choices"):
+                choice = chunk["choices"][0]
+                
+                # Get token content
+                if choice.get("delta", {}).get("content"):
+                    token = choice["delta"]["content"]
+                    full_content += token
+                
+                # Calculate entropy from logprobs
+                if choice.get("logprobs", {}).get("content"):
+                    logprobs_data = choice["logprobs"]["content"]
+                    if logprobs_data:
+                        entropy = self._calculate_entropy(logprobs_data[0])
+                        self.monitor.track(token, entropy)
+                        
+                        if self.config.log_entropy:
+                            logger.info(
+                                f"Token: {repr(token)}, Entropy: {entropy:.4f}, "
+                                f"Valleys: {len(self.monitor.get_valleys())}"
+                            )
+                        
+                        # Check for early exit
+                        if (
+                            self.config.enable_early_exit 
+                            and self.monitor.should_exit()
+                        ):
+                            logger.info(
+                                f"Early exit triggered! "
+                                f"Tokens: {len(full_content)}, "
+                                f"Valleys: {len(self.monitor.get_valleys())}"
+                            )
+                            exited_early = True
+                            yield "data: [DONE]\n\n"
+                            break
+            
+            yield line + "\n"
+        
+        if not exited_early:
+            logger.info(
+                f"Stream completed. "
+                f"Tokens: {self.monitor.get_stats()['token_count']}, "
+                f"Valleys: {len(self.monitor.get_valleys())}"
+            )
+    
+    def _calculate_entropy(self, logprobs_data: Dict) -> float:
+        """Calculate Shannon entropy from logprobs."""
+        import math
+        
+        if not logprobs_data or "top_logprobs" not in logprobs_data:
+            return 0.0
+        
+        entropy = 0.0
+        for lp in logprobs_data["top_logprobs"]:
+            prob = math.exp(lp["logprob"])
+            if prob > 0:
+                entropy -= prob * math.log2(prob + 1e-10)
+        
+        return entropy
+    
+    def run(self):
+        """Start the proxy server."""
+        uvicorn.run(self.app, host="0.0.0.0", port=self.config.port)
+
+
+def main():
+    """CLI entry point for running the proxy."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Entropy Monitoring Proxy")
+    parser.add_argument("--port", type=int, default=8765, help="Proxy port")
+    parser.add_argument(
+        "--provider", 
+        default="openai", 
+        choices=["openai", "anthropic", "nvidia"],
+        help="LLM provider"
+    )
+    parser.add_argument(
+        "--api-base",
+        default="https://api.openai.com/v1",
+        help="API base URL"
+    )
+    parser.add_argument(
+        "--entropy-threshold",
+        type=float,
+        default=0.15,
+        help="Entropy threshold for early exit"
+    )
+    parser.add_argument(
+        "--min-valleys",
+        type=int,
+        default=2,
+        help="Minimum valleys before early exit"
+    )
+    parser.add_argument(
+        "--no-early-exit",
+        action="store_true",
+        help="Disable early exit (monitor only)"
+    )
+    parser.add_argument(
+        "--log-entropy",
+        action="store_true",
+        help="Log entropy values to console"
+    )
+    
+    args = parser.parse_args()
+    
+    config = ProxyConfig(
+        port=args.port,
+        provider=args.provider,
+        api_base=args.api_base,
+        entropy_threshold=args.entropy_threshold,
+        min_valleys=args.min_valleys,
+        enable_early_exit=not args.no_early_exit,
+        log_entropy=args.log_entropy
+    )
+    
+    proxy = EntropyProxy(config)
+    
+    print(f"""
+╔═══════════════════════════════════════════════════════════╗
+║           ENTROPPLAIN ENTROPY MONITORING PROXY            ║
+╠═══════════════════════════════════════════════════════════╣
+║  Proxy running on: http://localhost:{args.port}                ║
+║  Provider: {args.provider:<10}                                ║
+║  API Base: {args.api_base:<30}     ║
+║  Early Exit: {'DISABLED' if args.no_early_exit else 'ENABLED'}                               ║
+╠═══════════════════════════════════════════════════════════╣
+║  Set your agent's API endpoint to:                        ║
+║    export OPENAI_BASE_URL=http://localhost:{args.port}          ║
+║    # or for NVIDIA:                                        ║
+║    export NVIDIA_BASE_URL=http://localhost:{args.port}         ║
+╚═══════════════════════════════════════════════════════════╝
+    """)
+    
+    proxy.run()
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entroplain",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Entropy-based early exit for efficient agent reasoning",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "entroplain"
-version = "0.1.0"
+version = "0.1.1"
 description = "Entropy-based early exit for efficient agent reasoning"
 readme = "README.md"
 license = "MIT"
@@ -44,6 +44,9 @@ all = [
     "requests>=2.28.0",
     "aiohttp>=3.8.0",
     "llama-cpp-python>=0.2.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.23.0",
+    "httpx>=0.24.0",
 ]
 dev = [
     "pytest>=7.0.0",
@@ -61,6 +64,7 @@ Issues = "https://github.com/entroplain/entroplain/issues"
 
 [project.scripts]
 entroplain = "entroplain.cli:main"
+entroplain-proxy = "entroplain.proxy:main"
 
 [tool.setuptools.packages.find]
 where = ["."]