entroplain 0.2.0 → 0.2.1

package/README.md

@@ -1,476 +1,478 @@
-# Entroplain
-
-**Entropy-based early exit for efficient agent reasoning.**
-
-Stop burning tokens. Know when your agent has finished thinking.
-
----
-
-## What It Does
-
-Entroplain monitors your LLM's **predictive entropy** — the uncertainty in its output distribution — to detect when reasoning has converged.
-
-```text
-High entropy → Model is searching, exploring, uncertain
-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.
-
----
-
-## Quick Start
-
-### Install
-
-```bash
-# Python (pip)
-pip install entroplain
-
-# Node.js (npm)
-npm install entroplain
-```
-
-### Requirements
-
-**Python:** 3.8+
-
-**Node.js:** 18+
-
-**For cloud providers:** Set API keys via environment variables:
-
-```bash
-export OPENAI_API_KEY=sk-...
-export ANTHROPIC_API_KEY=sk-ant-...
-export NVIDIA_API_KEY=nvapi-...
-```
-
-**For local models:** Install [Ollama](https://ollama.ai) or [llama.cpp](https://github.com/ggerganov/llama.cpp)
-
----
-
-## 🚀 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 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="")
-
-    if monitor.should_exit():
-        print("\n[Early exit - reasoning converged]")
-        break
-
-print(f"\nStats: {monitor.get_stats()}")
-```
-
----
-
-## How It Works
-
-### 1. Track Entropy Per Token
-
-Every token has an entropy value derived from the model's output distribution:
-
-```python
-entropy = -sum(p * log2(p) for p in probabilities if p > 0)
-```
-
-### 2. Detect Valleys
-
-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
-```
-
-### 3. Exit at the Right Moment
-
-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:
-
-| Difficulty | Avg Valleys | Avg Entropy | Avg Velocity |
-|------------|-------------|-------------|--------------|
-| Easy       | 61.3        | 0.3758      | 0.4852       |
-| Medium     | 53.0        | 0.3267      | 0.4394       |
-| Hard       | 70.2        | 0.2947      | 0.4095       |
-
-**Finding:** Hard problems have more entropy valleys (70.2 vs 61.3) — valleys correlate with reasoning complexity.
-
----
-
-## Platform Support
-
-| Platform | Support | How to Enable |
-|----------|---------|---------------|
-| **Local (llama.cpp, Ollama)** | ✅ Full | Built-in, no config |
-| **OpenAI** | ✅ Yes | `logprobs: true` |
-| **Anthropic Claude** | ✅ Yes (Claude 4) | `logprobs: True` |
-| **Google Gemini** | ✅ Yes | `response_logprobs=True` |
-| **NVIDIA NIM** | ✅ Yes | `logprobs: true` |
-| **OpenRouter** | ⚠️ Partial | ~23% of models support it |
-
----
-
-## Integration Examples
-
-### OpenAI / NVIDIA / OpenRouter
-
-```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": "Solve this step by step..."}],
-    logprobs=True,
-    top_logprobs=5,
-    stream=True
-)
-
-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="")
-```
-
-### Ollama (Local)
-
-```python
-import ollama
-from entroplain import EntropyMonitor
-
-monitor = EntropyMonitor()
-
-response = ollama.generate(
-    model="llama3.1",
-    prompt="Think through this carefully...",
-    options={"num_ctx": 4096}
-)
-
-for token_data in response.get("token_probs", []):
-    entropy = monitor.calculate_from_logits(token_data["logits"])
-    monitor.track(token_data["token"], entropy)
-```
-
-### Anthropic Claude
-
-```python
-from anthropic import Anthropic
-from entroplain import EntropyMonitor
-
-client = Anthropic()
-monitor = EntropyMonitor()
-
-with client.messages.stream(
-    model="claude-sonnet-4-20250514",
-    max_tokens=1024,
-    messages=[{"role": "user", "content": "Analyze this..."}],
-) as stream:
-    for text in stream.text_stream:
-        entropy = monitor.get_entropy()
-
-        if monitor.should_exit():
-            break
-
-        print(text, end="", flush=True)
-```
-
----
-
-## CLI
-
-```bash
-# Analyze a prompt's entropy trajectory
-entroplain analyze "What is 2+2?" --model gpt-4o
-
-# Stream with early exit
-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
-```
-
----
-
-## API Reference
-
-### `EntropyMonitor`
-
-```python
-class EntropyMonitor:
-    def __init__(
-        self,
-        entropy_threshold: float = 0.15,
-        min_valleys: int = 2,
-        velocity_threshold: float = 0.05,
-        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 should_exit(self) -> bool:
-        """Determine if reasoning has converged."""
-
-    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."""
-```
-
-### `CostTracker`
-
-```python
-class CostTracker:
-    def __init__(self, model: str = "default"):
-        ...
-
-    def track_input(self, tokens: int):
-        """Track input tokens."""
-
-    def track_output(self, tokens: int):
-        """Track output tokens."""
-
-    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
-```
-
----
-
-## Research
-
-### Paper
-
-See [`paper.md`](./paper.md) for the full research proposal:
-
-**"Entropy-Based Early Exit for Efficient Agent Reasoning"**
-
-### Key Findings
-
-1. **H1 Supported:** Entropy valleys correlate with reasoning complexity (70.2 valleys for hard problems vs 61.3 for easy)
-2. **H2 Supported:** Entropy velocity differs by difficulty (0.4852 easy vs 0.4095 hard)
-3. **Potential:** 40-60% compute reduction with 95%+ accuracy retention
-
-### Citation
-
-```bibtex
-@software{entroplain2026,
-  title = {Entroplain: Entropy-Based Early Exit for Efficient Agent Reasoning},
-  author = {Entroplain Contributors},
-  year = {2026},
-  url = {https://github.com/entroplain/entroplain}
-}
-```
-
----
-
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-### Development Setup
-
-```bash
-git clone https://github.com/entroplain/entroplain.git
-cd entroplain
-pip install -e ".[dev]"
-pytest
-```
-
----
-
-## License
-
-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
-- Experimental validation using NVIDIA NIM API
-- Built for the agent-first future of AI
+# Entroplain
+
+**Entropy-based early exit for efficient agent reasoning.**
+
+Stop burning tokens. Know when your agent has finished thinking.
+
+🌐 **Website:** https://entroplain.vercel.app/
+
+---
+
+## What It Does
+
+Entroplain monitors your LLM's **predictive entropy** — the uncertainty in its output distribution — to detect when reasoning has converged.
+
+```text
+High entropy → Model is searching, exploring, uncertain
+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.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+# Python (pip)
+pip install entroplain
+
+# Node.js (npm)
+npm install entroplain
+```
+
+### Requirements
+
+**Python:** 3.8+
+
+**Node.js:** 18+
+
+**For cloud providers:** Set API keys via environment variables:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export NVIDIA_API_KEY=nvapi-...
+```
+
+**For local models:** Install [Ollama](https://ollama.ai) or [llama.cpp](https://github.com/ggerganov/llama.cpp)
+
+---
+
+## 🚀 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 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="")
+
+    if monitor.should_exit():
+        print("\n[Early exit - reasoning converged]")
+        break
+
+print(f"\nStats: {monitor.get_stats()}")
+```
+
+---
+
+## How It Works
+
+### 1. Track Entropy Per Token
+
+Every token has an entropy value derived from the model's output distribution:
+
+```python
+entropy = -sum(p * log2(p) for p in probabilities if p > 0)
+```
+
+### 2. Detect Valleys
+
+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
+```
+
+### 3. Exit at the Right Moment
+
+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:
+
+| Difficulty | Avg Valleys | Avg Entropy | Avg Velocity |
+|------------|-------------|-------------|--------------|
+| Easy       | 61.3        | 0.3758      | 0.4852       |
+| Medium     | 53.0        | 0.3267      | 0.4394       |
+| Hard       | 70.2        | 0.2947      | 0.4095       |
+
+**Finding:** Hard problems have more entropy valleys (70.2 vs 61.3) — valleys correlate with reasoning complexity.
+
+---
+
+## Platform Support
+
+| Platform | Support | How to Enable |
+|----------|---------|---------------|
+| **Local (llama.cpp, Ollama)** | ✅ Full | Built-in, no config |
+| **OpenAI** | ✅ Yes | `logprobs: true` |
+| **Anthropic Claude** | ✅ Yes (Claude 4) | `logprobs: True` |
+| **Google Gemini** | ✅ Yes | `response_logprobs=True` |
+| **NVIDIA NIM** | ✅ Yes | `logprobs: true` |
+| **OpenRouter** | ⚠️ Partial | ~23% of models support it |
+
+---
+
+## Integration Examples
+
+### OpenAI / NVIDIA / OpenRouter
+
+```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": "Solve this step by step..."}],
+    logprobs=True,
+    top_logprobs=5,
+    stream=True
+)
+
+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="")
+```
+
+### Ollama (Local)
+
+```python
+import ollama
+from entroplain import EntropyMonitor
+
+monitor = EntropyMonitor()
+
+response = ollama.generate(
+    model="llama3.1",
+    prompt="Think through this carefully...",
+    options={"num_ctx": 4096}
+)
+
+for token_data in response.get("token_probs", []):
+    entropy = monitor.calculate_from_logits(token_data["logits"])
+    monitor.track(token_data["token"], entropy)
+```
+
+### Anthropic Claude
+
+```python
+from anthropic import Anthropic
+from entroplain import EntropyMonitor
+
+client = Anthropic()
+monitor = EntropyMonitor()
+
+with client.messages.stream(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Analyze this..."}],
+) as stream:
+    for text in stream.text_stream:
+        entropy = monitor.get_entropy()
+
+        if monitor.should_exit():
+            break
+
+        print(text, end="", flush=True)
+```
+
+---
+
+## CLI
+
+```bash
+# Analyze a prompt's entropy trajectory
+entroplain analyze "What is 2+2?" --model gpt-4o
+
+# Stream with early exit
+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
+```
+
+---
+
+## API Reference
+
+### `EntropyMonitor`
+
+```python
+class EntropyMonitor:
+    def __init__(
+        self,
+        entropy_threshold: float = 0.15,
+        min_valleys: int = 2,
+        velocity_threshold: float = 0.05,
+        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 should_exit(self) -> bool:
+        """Determine if reasoning has converged."""
+
+    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."""
+```
+
+### `CostTracker`
+
+```python
+class CostTracker:
+    def __init__(self, model: str = "default"):
+        ...
+
+    def track_input(self, tokens: int):
+        """Track input tokens."""
+
+    def track_output(self, tokens: int):
+        """Track output tokens."""
+
+    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
+```
+
+---
+
+## Research
+
+### Paper
+
+See [`paper.md`](./paper.md) for the full research proposal:
+
+**"Entropy-Based Early Exit for Efficient Agent Reasoning"**
+
+### Key Findings
+
+1. **H1 Supported:** Entropy valleys correlate with reasoning complexity (70.2 valleys for hard problems vs 61.3 for easy)
+2. **H2 Supported:** Entropy velocity differs by difficulty (0.4852 easy vs 0.4095 hard)
+3. **Potential:** 40-60% compute reduction with 95%+ accuracy retention
+
+### Citation
+
+```bibtex
+@software{entroplain2026,
+  title = {Entroplain: Entropy-Based Early Exit for Efficient Agent Reasoning},
+  author = {Entroplain Contributors},
+  year = {2026},
+  url = {https://github.com/entroplain/entroplain}
+}
+```
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+
+```bash
+git clone https://github.com/entroplain/entroplain.git
+cd entroplain
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## License
+
+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
+- Experimental validation using NVIDIA NIM API
+- Built for the agent-first future of AI