genesis-llm-cost-circuit-breaker

genesis-llm-cost-circuit-breaker

Hard token & budget circuit breaker preventing runaway LLM billing loops.

---

The Problem

Autonomous agent loops, recursive reflection, and untamed retries frequently cause massive unexpected API bills. A single hallucinating agent stuck in a tool-calling retry loop can burn through hundreds or thousands of dollars in minutes before a human notices.

The Solution

genesis-llm-cost-circuit-breaker provides a deterministic circuit-breaker pattern for LLM API calls. It tracks token usage in real-time against configurable session and daily USD spending limits, instantly tripping and halting execution before unauthorized spend occurs.

---

Key Features

• Zero External Dependencies: Runs on standard Node.js runtime (v18+).
• Built-in Model Rate Cards: Pre-configured pricing for OpenAI (GPT-4o, o1, o3-mini), Anthropic (Claude 3.5 Sonnet/Haiku, Opus), Google (Gemini 1.5/2.0), and DeepSeek.
• Multi-Level Thresholds:
• Max Daily Budget (e.g. $10.00/day)
• Max Session Budget (e.g. $2.00/run)
• Max Per-Call Token Limit (e.g. 128,000 tokens)
• Persistent Local Ledger: Remembers accumulated daily spend across script restarts.
• Fail-Closed Architecture: Any limit breach throws CircuitBreakerError and blocks subsequent network dispatches.

---

Quickstart

# Clone the repository
git clone git@github.com:genesiscode2026/genesis-llm-cost-circuit-breaker.git
cd genesis-llm-cost-circuit-breaker

# Inspect current circuit breaker status
./bin/genesis-cost-breaker.js

# Simulate and record an API call
./bin/genesis-cost-breaker.js --simulate gpt-4o,25000,4000

# Reset daily ledger
./bin/genesis-cost-breaker.js --reset

Library Usage

const { LLMCostCircuitBreaker } = require('genesis-llm-cost-circuit-breaker');

const breaker = new LLMCostCircuitBreaker({
  maxDailyBudgetUsd: 15.00,
  maxSessionBudgetUsd: 3.00,
  maxPerCallTokens: 64000,
  ledgerPath: './.llm_costs.json'
});

// Before calling LLM API:
breaker.checkAllowed('claude-3-5-sonnet', estimatedInputTokens);

// After receiving LLM response:
breaker.recordUsage('claude-3-5-sonnet', actualInputTokens, actualOutputTokens);

---

Commercial Distribution

• Product Name: genesis-llm-cost-circuit-breaker
• Catalog ID: P09
• Price: $39
• Seller: genesiscode2026
• Authorized Payout Rail: USDC on Base (0xC6F86e170411182114FcCdb28793dC76B5e8D144)
• License: MIT