entroplain 0.1.0 → 0.2.0

package/CONTRIBUTING.md

@@ -1,103 +1,103 @@
-# Contributing to Entroplain
-
-Thanks for your interest in contributing! 🎉
-
-## Development Setup
-
-```bash
-# Clone the repo
-git clone https://github.com/entroplain/entroplain.git
-cd entroplain
-
-# Create virtual environment
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-
-# Install in development mode
-pip install -e ".[dev]"
-
-# Run tests
-pytest
-```
-
-## Project Structure
-
-```
-entroplain/
-├── entroplain/
-│   ├── __init__.py      # Package exports
-│   ├── monitor.py       # Core entropy monitor
-│   ├── providers.py     # LLM provider integrations
-│   ├── hooks.py         # Agent framework hooks
-│   └── cli.py           # Command-line interface
-├── tests/
-│   └── test_monitor.py  # Unit tests
-├── pyproject.toml       # Package config
-├── README.md            # Documentation
-└── LICENSE              # MIT License
-```
-
-## Adding a New Provider
-
-1. Create a new provider class in `providers.py`:
-
-```python
-class MyProvider(BaseProvider):
-    def calculate_entropy(self, logprobs_data: Dict) -> float:
-        # Parse provider-specific format
-        ...
-    
-    def stream_with_entropy(self, **kwargs) -> Iterator[TokenWithEntropy]:
-        # Stream tokens with entropy
-        ...
-```
-
-2. Export it in `__init__.py`
-
-3. Add tests in `tests/test_providers.py`
-
-## Code Style
-
-- Use **Black** for formatting
-- Use **isort** for imports
-- Use **mypy** for type checking
-
-```bash
-black entroplain/ tests/
-isort entroplain/ tests/
-mypy entroplain/
-```
-
-## Testing
-
-Run all tests:
-
-```bash
-pytest
-```
-
-Run with coverage:
-
-```bash
-pytest --cov=entroplain
-```
-
-## Pull Request Process
-
-1. Fork the repo
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Add tests for new functionality
-5. Ensure all tests pass (`pytest`)
-6. Format code (`black .`)
-7. Commit changes (`git commit -m 'Add amazing feature'`)
-8. Push to branch (`git push origin feature/amazing-feature`)
-9. Open a Pull Request
-
-## Questions?
-
-Open an issue or join our Discord: https://discord.gg/entroplain
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the MIT License.
+# Contributing to Entroplain
+
+Thanks for your interest in contributing! 🎉
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/entroplain/entroplain.git
+cd entroplain
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+## Project Structure
+
+```
+entroplain/
+├── entroplain/
+│   ├── __init__.py      # Package exports
+│   ├── monitor.py       # Core entropy monitor
+│   ├── providers.py     # LLM provider integrations
+│   ├── hooks.py         # Agent framework hooks
+│   └── cli.py           # Command-line interface
+├── tests/
+│   └── test_monitor.py  # Unit tests
+├── pyproject.toml       # Package config
+├── README.md            # Documentation
+└── LICENSE              # MIT License
+```
+
+## Adding a New Provider
+
+1. Create a new provider class in `providers.py`:
+
+```python
+class MyProvider(BaseProvider):
+    def calculate_entropy(self, logprobs_data: Dict) -> float:
+        # Parse provider-specific format
+        ...
+    
+    def stream_with_entropy(self, **kwargs) -> Iterator[TokenWithEntropy]:
+        # Stream tokens with entropy
+        ...
+```
+
+2. Export it in `__init__.py`
+
+3. Add tests in `tests/test_providers.py`
+
+## Code Style
+
+- Use **Black** for formatting
+- Use **isort** for imports
+- Use **mypy** for type checking
+
+```bash
+black entroplain/ tests/
+isort entroplain/ tests/
+mypy entroplain/
+```
+
+## Testing
+
+Run all tests:
+
+```bash
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=entroplain
+```
+
+## Pull Request Process
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`pytest`)
+6. Format code (`black .`)
+7. Commit changes (`git commit -m 'Add amazing feature'`)
+8. Push to branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+## Questions?
+
+Open an issue
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/README.md

@@ -12,7 +12,7 @@ Entroplain monitors your LLM's **predictive entropy** — the uncertainty in its
 
 ```text
 High entropy → Model is searching, exploring, uncertain
-Low entropy  → Model is confident, converged, ready to output
+Low entropy → Model is confident, converged, ready to output
 ```
 
 **Key insight:** Reasoning follows a multi-modal entropy trajectory. Local minima ("valleys") mark reasoning milestones. Exit at the right valley, save 40-60% compute with minimal accuracy loss.
@@ -38,6 +38,7 @@ npm install entroplain
 **Node.js:** 18+
 
 **For cloud providers:** Set API keys via environment variables:
+
 ```bash
 export OPENAI_API_KEY=sk-...
 export ANTHROPIC_API_KEY=sk-ant-...
@@ -46,20 +47,127 @@ export NVIDIA_API_KEY=nvapi-...
 
 **For local models:** Install [Ollama](https://ollama.ai) or [llama.cpp](https://github.com/ggerganov/llama.cpp)
 
-### Use with Any Agent
+---
+
+## 🚀 Works With Any Agent (Proxy Method)
+
+The **proxy** is the easiest way to use Entroplain with OpenClaw, Claude Code, or any other agent framework:
+
+### How It Works
+
+```
+Your Agent → Proxy (localhost:8765) → Real API
+               │
+               ▼
+         Entropy Monitor
+               │
+               ▼
+         Early Exit Check
+```
+
+The proxy intercepts all LLM API calls, monitors entropy, and terminates streams when reasoning converges.
+
+### Setup (One-Time)
+
+```bash
+# Install with proxy support
+pip install entroplain[proxy]
+
+# Start the proxy
+entroplain-proxy --port 8765 --log-entropy
+
+# Point your agent to the proxy
+export OPENAI_BASE_URL=http://localhost:8765/v1
+
+# or for NVIDIA:
+export NVIDIA_BASE_URL=http://localhost:8765/v1
+
+# or for Anthropic:
+export ANTHROPIC_BASE_URL=http://localhost:8765/v1
+```
+
+That's it! Now run your agent normally and entropy monitoring is automatic.
+
+### Proxy Options
+
+```bash
+# Monitor only, don't exit early
+entroplain-proxy --port 8765 --no-early-exit
+
+# Custom thresholds
+entroplain-proxy --port 8765 --entropy-threshold 0.2 --min-valleys 3
+
+# Enable cost tracking
+entroplain-proxy --port 8765 --model gpt-4o --log-entropy
+
+# Launch dashboard
+entroplain-dashboard --port 8050
+```
+
+---
+
+## 🎯 Dashboard
+
+Real-time entropy visualization:
+
+```bash
+# Start the dashboard
+entroplain-dashboard --port 8050
+
+# Open in browser
+open http://localhost:8050
+```
+
+The dashboard shows:
+- **Live entropy curve** with valley markers
+- **Token count** and valleys detected
+- **Cost savings** in real-time
+- **Status badges** (active/idle/exited)
+
+---
+
+## 💰 Cost Tracking
+
+Track actual savings from early exit:
 
 ```python
-from entroplain import EntropyMonitor
+from entroplain import CostTracker
+
+tracker = CostTracker(model="gpt-4o")
+tracker.track_input(100)   # 100 input tokens
+tracker.track_output(50)   # 50 output tokens
+tracker.set_full_estimate(150)  # Would have been 150
+
+estimate = tracker.get_estimate()
+print(f"Saved ${estimate.cost_saved_usd:.4f} ({estimate.savings_percent:.1f}%)")
+```
+
+**Supported pricing:** GPT-4o, GPT-4-turbo, Claude 4, Llama 3.1 (NVIDIA), or custom rates.
+
+---
+
+## Direct Usage (Python)
+
+If you want more control, use Entroplain directly:
+
+```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="")
 
-# Stream tokens with entropy tracking
-async for token, entropy in monitor.stream(agent.generate()):
-    print(f"{token} (entropy: {entropy:.3f})")
-    
-    # Detect reasoning convergence
-    if monitor.is_converged():
-        break  # Early exit — reasoning complete
+    if monitor.should_exit():
+        print("\n[Early exit - reasoning converged]")
+        break
+
+print(f"\nStats: {monitor.get_stats()}")
 ```
 
 ---
@@ -80,8 +188,8 @@ Local minima in the entropy trajectory indicate reasoning milestones:
 
 ```text
 Entropy: 0.8 → 0.6 → 0.3* → 0.5 → 0.2* → 0.1*
-                       ↑           ↑
-                    Valley 1    Valley 2
+                      ↑             ↑
+                  Valley 1      Valley 2
 ```
 
 ### 3. Exit at the Right Moment
@@ -90,6 +198,28 @@ When valley count plateaus and velocity stabilizes, reasoning is complete.
 
 ---
 
+## Exit Strategies
+
+Choose how Entroplain detects convergence:
+
+| Strategy | Description |
+|----------|-------------|
+| `combined` | Entropy low OR valleys plateau, AND velocity stable (default) |
+| `valleys_plateau` | Exit when reasoning milestones stabilize |
+| `entropy_drop` | Exit when model confidence is high |
+| `velocity_zero` | Exit when entropy stops changing |
+| `repetition` | Exit when model starts repeating itself |
+| `confidence` | Exit when top token prob > 95% for N tokens |
+
+```python
+monitor = EntropyMonitor(
+    exit_condition="repetition",  # or "confidence", "combined", etc.
+    repetition_threshold=0.3,      # Exit when 30% of recent tokens repeat
+)
+```
+
+---
+
 ## Experimental Evidence
 
 Tested on Llama-3.1-70b via NVIDIA API:
@@ -140,11 +270,11 @@ for chunk in response:
     if chunk.choices[0].delta.content:
         token = chunk.choices[0].delta.content
         entropy = monitor.calculate_entropy(chunk.choices[0].logprobs)
-        
+
         if monitor.should_exit():
             print("\n[Early exit — reasoning converged]")
             break
-        
+
         print(token, end="")
 ```
 
@@ -156,14 +286,12 @@ from entroplain import EntropyMonitor
 
 monitor = EntropyMonitor()
 
-# Ollama exposes logits for local models
 response = ollama.generate(
     model="llama3.1",
     prompt="Think through this carefully...",
     options={"num_ctx": 4096}
 )
 
-# Direct access to token probabilities
 for token_data in response.get("token_probs", []):
     entropy = monitor.calculate_from_logits(token_data["logits"])
     monitor.track(token_data["token"], entropy)
@@ -185,88 +313,32 @@ with client.messages.stream(
 ) as stream:
     for text in stream.text_stream:
         entropy = monitor.get_entropy()
+
         if monitor.should_exit():
             break
-        print(text, end="", flush=True)
-```
-
-### Agent Frameworks
-
-**OpenClaw:**
-
-```python
-# In your agent config
-entropy_monitor:
-  enabled: true
-  exit_threshold: 0.15  # Exit when entropy drops below this
-  min_valleys: 3        # Require at least N reasoning milestones
-```
-
-**Claude Code:**
 
-```json
-{
-  "hooks": {
-    "on_token": "entroplain.hooks.track_entropy",
-    "on_converge": "entroplain.hooks.early_exit"
-  }
-}
-```
-
----
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# For cloud providers
-ENTROPPLAIN_OPENAI_API_KEY=sk-...
-ENTROPPLAIN_ANTHROPIC_API_KEY=sk-ant-...
-ENTROPPLAIN_NVIDIA_API_KEY=nvapi-...
-
-# For local models
-ENTROPPLAIN_LOCAL_PROVIDER=ollama  # or llama.cpp
-ENTROPPLAIN_LOCAL_MODEL=llama3.1
-```
-
-### Exit Conditions
-
-```python
-monitor = EntropyMonitor(
-    # Exit when entropy drops below threshold
-    entropy_threshold=0.15,
-    
-    # Require minimum valleys before exit
-    min_valleys=2,
-    
-    # Exit when velocity stabilizes (change < this)
-    velocity_threshold=0.05,
-    
-    # Don't exit before N tokens
-    min_tokens=50,
-    
-    # Custom exit condition
-    exit_condition="valleys_plateau"  # or "entropy_drop", "velocity_zero"
-)
+        print(text, end="", flush=True)
 ```
 
 ---
 
-## CLI Usage
+## CLI
 
 ```bash
 # Analyze a prompt's entropy trajectory
 entroplain analyze "What is 2+2?" --model gpt-4o
 
 # Stream with early exit
-entroplain stream "Solve this step by step: x^2 = 16" --exit-on-converge
+entroplain stream "Explain quantum computing" --exit-on-converge
+
+# Run the proxy (works with any agent)
+entroplain-proxy --port 8765 --log-entropy --model gpt-4o
+
+# Launch the dashboard
+entroplain-dashboard --port 8050
 
 # Benchmark entropy patterns
 entroplain benchmark --problems gsm8k --output results.json
-
-# Visualize entropy trajectory
-entroplain visualize results.json --output entropy_plot.png
 ```
 
 ---
@@ -282,45 +354,60 @@ class EntropyMonitor:
         entropy_threshold: float = 0.15,
         min_valleys: int = 2,
         velocity_threshold: float = 0.05,
-        min_tokens: int = 50
-    ): ...
-    
-    def calculate_entropy(self, logprobs: List[float]) -> float:
-        """Calculate Shannon entropy from log probabilities."""
-    
-    def track(self, token: str, entropy: float) -> None:
+        min_tokens: int = 50,
+        exit_condition: str = "combined"
+    ):
+        ...
+
+    def track(self, token: str, entropy: float, confidence: float = 0.0) -> EntropyPoint:
         """Track a token and its entropy value."""
-    
-    def get_valleys(self) -> List[Tuple[int, float]]:
-        """Get all entropy valleys (local minima)."""
-    
-    def get_velocity(self) -> float:
-        """Get current entropy velocity (rate of change)."""
-    
+
     def should_exit(self) -> bool:
         """Determine if reasoning has converged."""
-    
-    def is_converged(self) -> bool:
-        """Alias for should_exit()."""
-    
-    def get_trajectory(self) -> List[float]:
-        """Get full entropy trajectory."""
-    
+
+    def get_valleys(self) -> List[Tuple[int, float]]:
+        """Get all entropy valleys (local minima)."""
+
+    def get_stats(self) -> Dict:
+        """Get current statistics."""
+
     def reset(self) -> None:
         """Clear all tracked data."""
 ```
 
-### `calculate_entropy(logprobs)`
+### `CostTracker`
 
 ```python
-from entroplain import calculate_entropy
+class CostTracker:
+    def __init__(self, model: str = "default"):
+        ...
+
+    def track_input(self, tokens: int):
+        """Track input tokens."""
 
-# From log probabilities
-entropy = calculate_entropy([-0.5, -2.1, -0.1, -5.2])
-# Returns: 0.847
+    def track_output(self, tokens: int):
+        """Track output tokens."""
 
-# From probabilities
-entropy = calculate_entropy([0.6, 0.125, 0.9, 0.005], from_probs=True)
+    def set_full_estimate(self, tokens: int):
+        """Set estimated output if no early exit."""
+
+    def get_estimate(self) -> CostEstimate:
+        """Get cost estimate with savings."""
+```
+
+### `EntropyProxy`
+
+```bash
+# Run the proxy
+entroplain-proxy --port 8765 --log-entropy --model gpt-4o
+
+# Options
+--entropy-threshold 0.15    # Exit threshold
+--min-valleys 2             # Minimum valleys
+--no-early-exit             # Monitor only, don't exit
+--log-entropy               # Log entropy values
+--model gpt-4o              # Model for cost tracking
+--no-cost-tracking          # Disable cost tracking
 ```
 
 ---
@@ -329,7 +416,9 @@ entropy = calculate_entropy([0.6, 0.125, 0.9, 0.005], from_probs=True)
 
 ### Paper
 
-See [`paper.md`](./paper.md) for the full research proposal: **"Entropy-Based Early Exit for Efficient Agent Reasoning"**
+See [`paper.md`](./paper.md) for the full research proposal:
+
+**"Entropy-Based Early Exit for Efficient Agent Reasoning"**
 
 ### Key Findings
 
@@ -350,17 +439,6 @@ See [`paper.md`](./paper.md) for the full research proposal: **"Entropy-Based Ea
 
 ---
 
-## Roadmap
-
-- [ ] v0.1.0 — Core entropy tracking (Python)
-- [ ] v0.2.0 — Multi-provider support (OpenAI, Anthropic, Gemini, NVIDIA)
-- [ ] v0.3.0 — Local model support (llama.cpp, Ollama)
-- [ ] v0.4.0 — Agent framework integrations (OpenClaw, Claude Code)
-- [ ] v0.5.0 — JavaScript/Node.js SDK
-- [ ] v1.0.0 — Production release with benchmarks
-
----
-
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
@@ -382,6 +460,15 @@ MIT License — see [LICENSE](./LICENSE) for details.
 
 ---
 
+## Links
+
+- **PyPI:** https://pypi.org/project/entroplain/
+- **npm:** https://www.npmjs.com/package/entroplain
+- **GitHub:** https://github.com/entroplain/entroplain
+- **Issues:** https://github.com/entroplain/entroplain/issues
+
+---
+
 ## Acknowledgments
 
 - Research inspired by early exit architectures in transformers