entroplain 0.1.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "entroplain",
+  "version": "0.1.0",
+  "description": "Entropy-based early exit for efficient agent reasoning",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "llm",
+    "agent",
+    "entropy",
+    "early-exit",
+    "reasoning",
+    "efficiency"
+  ],
+  "author": "Entroplain Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entroplain/entroplain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/entroplain/entroplain/issues"
+  },
+  "homepage": "https://github.com/entroplain/entroplain#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "openai": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "entroplain"
+version = "0.1.0"
+description = "Entropy-based early exit for efficient agent reasoning"
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "Entroplain Contributors"}
+]
+keywords = ["llm", "agent", "entropy", "early-exit", "efficiency", "reasoning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "typing-extensions>=4.0.0;python_version<'3.10'",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.25.0"]
+google = ["google-generativeai>=0.3.0"]
+nvidia = ["requests>=2.28.0", "aiohttp>=3.8.0"]
+ollama = ["requests>=2.28.0", "aiohttp>=3.8.0"]
+llama-cpp = ["llama-cpp-python>=0.2.0"]
+all = [
+    "openai>=1.0.0",
+    "anthropic>=0.25.0",
+    "google-generativeai>=0.3.0",
+    "requests>=2.28.0",
+    "aiohttp>=3.8.0",
+    "llama-cpp-python>=0.2.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "isort>=5.0.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/entroplain/entroplain"
+Documentation = "https://github.com/entroplain/entroplain#readme"
+Repository = "https://github.com/entroplain/entroplain.git"
+Issues = "https://github.com/entroplain/entroplain/issues"
+
+[project.scripts]
+entroplain = "entroplain.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["entroplain*"]
+
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311", "py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/src/hooks.ts

@@ -0,0 +1,130 @@
+/**
+ * Hooks for agent framework integration
+ */
+
+import { EntropyMonitor } from './monitor';
+import { EntropyPoint, MonitorStats } from './types';
+
+// Global monitor instance
+let monitor: EntropyMonitor | null = null;
+let config: Record<string, unknown> = {};
+
+/**
+ * Initialize entropy hooks
+ */
+export function initHooks(userConfig: Record<string, unknown> = {}): void {
+  config = userConfig;
+  monitor = new EntropyMonitor({
+    entropyThreshold: (config.entropyThreshold as number) ?? 0.15,
+    minValleys: (config.minValleys as number) ?? 2,
+    velocityThreshold: (config.velocityThreshold as number) ?? 0.05,
+    minTokens: (config.minTokens as number) ?? 50,
+  });
+}
+
+/**
+ * Hook to track entropy for each token
+ */
+export function trackEntropy(token: string, entropy: number): {
+  token: string;
+  entropy: number;
+  index: number;
+  isValley: boolean;
+  velocity: number;
+  shouldExit: boolean;
+  stats: MonitorStats;
+} {
+  if (!monitor) {
+    initHooks();
+  }
+
+  const point = monitor!.track(token, entropy);
+
+  return {
+    token,
+    entropy,
+    index: point.index,
+    isValley: point.isValley,
+    velocity: point.velocity,
+    shouldExit: monitor!.shouldExit(),
+    stats: monitor!.getStats(),
+  };
+}
+
+/**
+ * Hook to check if reasoning has converged
+ */
+export function earlyExit(): boolean {
+  if (!monitor) {
+    return false;
+  }
+  return monitor.shouldExit();
+}
+
+/**
+ * Reset the global monitor state
+ */
+export function resetHooks(): void {
+  if (monitor) {
+    monitor.reset();
+  }
+}
+
+/**
+ * Get the current monitor instance
+ */
+export function getMonitor(): EntropyMonitor | null {
+  return monitor;
+}
+
+/**
+ * Class-based hook for frameworks that prefer class instances
+ */
+export class EntropyHook {
+  private monitor: EntropyMonitor;
+  private config: Record<string, unknown>;
+
+  constructor(userConfig: Record<string, unknown> = {}) {
+    this.config = userConfig;
+    this.monitor = new EntropyMonitor({
+      entropyThreshold: (this.config.entropyThreshold as number) ?? 0.15,
+      minValleys: (this.config.minValleys as number) ?? 2,
+      velocityThreshold: (this.config.velocityThreshold as number) ?? 0.05,
+      minTokens: (this.config.minTokens as number) ?? 50,
+    });
+  }
+
+  onToken(token: string, entropy: number): {
+    token: string;
+    entropy: number;
+    index: number;
+    isValley: boolean;
+    velocity: number;
+    shouldExit: boolean;
+    stats: MonitorStats;
+  } {
+    const point = this.monitor.track(token, entropy);
+
+    return {
+      token,
+      entropy,
+      index: point.index,
+      isValley: point.isValley,
+      velocity: point.velocity,
+      shouldExit: this.monitor.shouldExit(),
+      stats: this.monitor.getStats(),
+    };
+  }
+
+  shouldExit(): boolean {
+    return this.monitor.shouldExit();
+  }
+
+  reset(): void {
+    this.monitor.reset();
+  }
+
+  getStats(): MonitorStats {
+    return this.monitor.getStats();
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Entroplain — Entropy-based early exit for efficient agent reasoning
+ * 
+ * @packageDocumentation
+ */
+
+export { EntropyMonitor, calculateEntropy } from './monitor';
+export { EntropyHook, trackEntropy, earlyExit } from './hooks';
+export * from './types';

package/src/monitor.ts

@@ -0,0 +1,252 @@
+/**
+ * Entropy Monitor — Core entropy tracking and early exit logic
+ */
+
+import { EntropyPoint, MonitorConfig, MonitorStats, ExitCondition } from './types';
+
+export class EntropyMonitor {
+  private config: MonitorConfig;
+  private trajectory: EntropyPoint[] = [];
+  private valleys: EntropyPoint[] = [];
+  private index: number = 0;
+
+  constructor(options: Partial<MonitorConfig> = {}) {
+    this.config = {
+      entropyThreshold: options.entropyThreshold ?? 0.15,
+      minValleys: options.minValleys ?? 2,
+      velocityThreshold: options.velocityThreshold ?? 0.05,
+      minTokens: options.minTokens ?? 50,
+      valleyWindow: options.valleyWindow ?? 5,
+      plateauThreshold: options.plateauThreshold ?? 3,
+      exitCondition: options.exitCondition ?? 'combined',
+    };
+  }
+
+  /**
+   * Calculate Shannon entropy from log probabilities
+   */
+  calculateEntropy(logprobs: number[], fromProbs: boolean = false): number {
+    if (!logprobs || logprobs.length === 0) {
+      return 0.0;
+    }
+
+    let entropy = 0.0;
+    for (const lp of logprobs) {
+      const prob = fromProbs ? lp : Math.exp(lp);
+      if (prob > 0) {
+        entropy -= prob * Math.log2(prob + 1e-10);
+      }
+    }
+
+    return entropy;
+  }
+
+  /**
+   * Track a token and its entropy value
+   */
+  track(token: string, entropy: number): EntropyPoint {
+    const point: EntropyPoint = {
+      index: this.index,
+      token,
+      entropy,
+      isValley: false,
+      velocity: 0.0,
+    };
+
+    // Calculate velocity
+    if (this.trajectory.length > 0) {
+      const prev = this.trajectory[this.trajectory.length - 1];
+      point.velocity = Math.abs(entropy - prev.entropy);
+    }
+
+    // Detect valley (local minimum)
+    if (this.trajectory.length >= 2) {
+      const prev2 = this.trajectory[this.trajectory.length - 2];
+      const prev1 = this.trajectory[this.trajectory.length - 1];
+      if (prev1.entropy < prev2.entropy && prev1.entropy < entropy) {
+        prev1.isValley = true;
+        this.valleys.push(prev1);
+      }
+    }
+
+    this.trajectory.push(point);
+    this.index++;
+
+    return point;
+  }
+
+  /**
+   * Get all entropy valleys (local minima)
+   */
+  getValleys(): Array<[number, number]> {
+    return this.valleys.map(v => [v.index, v.entropy]);
+  }
+
+  /**
+   * Get current entropy velocity
+   */
+  getVelocity(): number {
+    if (this.trajectory.length < 2) {
+      return 0.0;
+    }
+    return this.trajectory[this.trajectory.length - 1].velocity;
+  }
+
+  /**
+   * Get mean entropy over the trajectory
+   */
+  getMeanEntropy(): number {
+    if (this.trajectory.length === 0) {
+      return 0.0;
+    }
+    const sum = this.trajectory.reduce((acc, p) => acc + p.entropy, 0);
+    return sum / this.trajectory.length;
+  }
+
+  /**
+   * Get the number of detected valleys
+   */
+  getValleyCount(): number {
+    return this.valleys.length;
+  }
+
+  /**
+   * Check if valley count has plateaued
+   */
+  isValleysPlateau(): boolean {
+    if (this.valleys.length < this.config.minValleys) {
+      return false;
+    }
+
+    if (this.valleys.length < this.config.plateauThreshold) {
+      return false;
+    }
+
+    const recent = this.valleys.slice(-this.config.plateauThreshold);
+    const spacings: number[] = [];
+    for (let i = 0; i < recent.length - 1; i++) {
+      spacings.push(recent[i + 1].index - recent[i].index);
+    }
+
+    if (spacings.length === 0) return false;
+
+    const meanSpacing = spacings.reduce((a, b) => a + b, 0) / spacings.length;
+    const variance = spacings.reduce((acc, s) => acc + (s - meanSpacing) ** 2, 0) / spacings.length;
+
+    return variance < 10;
+  }
+
+  /**
+   * Check if current entropy is below threshold
+   */
+  isEntropyLow(): boolean {
+    if (this.trajectory.length === 0) {
+      return false;
+    }
+    return this.trajectory[this.trajectory.length - 1].entropy < this.config.entropyThreshold;
+  }
+
+  /**
+   * Check if velocity is below threshold
+   */
+  isVelocityStable(): boolean {
+    return this.getVelocity() < this.config.velocityThreshold;
+  }
+
+  /**
+   * Determine if reasoning has converged
+   */
+  shouldExit(): boolean {
+    // Always require minimum tokens
+    if (this.trajectory.length < this.config.minTokens) {
+      return false;
+    }
+
+    // Always require minimum valleys
+    if (this.valleys.length < this.config.minValleys) {
+      return false;
+    }
+
+    switch (this.config.exitCondition) {
+      case 'valleys_plateau':
+        return this.isValleysPlateau();
+      case 'entropy_drop':
+        return this.isEntropyLow();
+      case 'velocity_zero':
+        return this.isVelocityStable();
+      case 'combined':
+        return (this.isEntropyLow() || this.isValleysPlateau()) && this.isVelocityStable();
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Alias for shouldExit()
+   */
+  isConverged(): boolean {
+    return this.shouldExit();
+  }
+
+  /**
+   * Get full entropy trajectory
+   */
+  getTrajectory(): number[] {
+    return this.trajectory.map(p => p.entropy);
+  }
+
+  /**
+   * Get all tracked tokens
+   */
+  getTokens(): string[] {
+    return this.trajectory.map(p => p.token);
+  }
+
+  /**
+   * Get summary statistics
+   */
+  getStats(): MonitorStats {
+    if (this.trajectory.length === 0) {
+      return {
+        tokenCount: 0,
+        valleyCount: 0,
+        meanEntropy: 0,
+        minEntropy: 0,
+        maxEntropy: 0,
+        currentEntropy: 0,
+        currentVelocity: 0,
+        isConverged: false,
+      };
+    }
+
+    const entropies = this.trajectory.map(p => p.entropy);
+
+    return {
+      tokenCount: this.trajectory.length,
+      valleyCount: this.valleys.length,
+      meanEntropy: this.getMeanEntropy(),
+      minEntropy: Math.min(...entropies),
+      maxEntropy: Math.max(...entropies),
+      currentEntropy: entropies[entropies.length - 1],
+      currentVelocity: this.getVelocity(),
+      isConverged: this.shouldExit(),
+    };
+  }
+
+  /**
+   * Clear all tracked data
+   */
+  reset(): void {
+    this.trajectory = [];
+    this.valleys = [];
+    this.index = 0;
+  }
+}
+
+/**
+ * Standalone function to calculate Shannon entropy
+ */
+export function calculateEntropy(logprobs: number[], fromProbs: boolean = false): number {
+  const monitor = new EntropyMonitor();
+  return monitor.calculateEntropy(logprobs, fromProbs);
+}

package/src/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Type definitions for Entroplain
+ */
+
+export interface EntropyPoint {
+  index: number;
+  token: string;
+  entropy: number;
+  isValley: boolean;
+  velocity: number;
+}
+
+export interface MonitorConfig {
+  entropyThreshold: number;
+  minValleys: number;
+  velocityThreshold: number;
+  minTokens: number;
+  valleyWindow: number;
+  plateauThreshold: number;
+  exitCondition: ExitCondition;
+}
+
+export type ExitCondition = 
+  | 'valleys_plateau' 
+  | 'entropy_drop' 
+  | 'velocity_zero' 
+  | 'combined';
+
+export interface MonitorStats {
+  tokenCount: number;
+  valleyCount: number;
+  meanEntropy: number;
+  minEntropy: number;
+  maxEntropy: number;
+  currentEntropy: number;
+  currentVelocity: number;
+  isConverged: boolean;
+}
+
+export interface TokenWithEntropy {
+  token: string;
+  entropy: number;
+  logprob: number;
+  topLogprobs: Array<{ token: string; logprob: number }>;
+}
+
+export interface ProviderConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+}
+
+export interface StreamOptions {
+  model?: string;
+  messages?: Array<{ role: string; content: string }>;
+  maxTokens?: number;
+  topLogprobs?: number;
+}