runcost 0.1.1

Run a 1,000-agent simulation for $2 instead of $200. Drop-in cost intelligence for Python AI agent frameworks.

RunCost 💸

Run a 1,000-agent simulation for $2 instead of $200. Drop-in cost intelligence for Python AI agent frameworks.

---

The Problem

You built a multi-agent system. It works beautifully in testing.

Then you ran it for real and saw the bill.

A 500-agent simulation on GPT-4o costs $40–$80 per run. A recursive loop that nobody catches costs $200 before you notice. An overnight batch job you forgot about costs $600 by morning.

Nobody warns you. No framework stops it. You just get an email from OpenAI.

Multi-agent AI is the future. Uncontrolled spend is the tax on building it.

---

The Fix: One Line

# Before RunCost
from openai import OpenAI
client = OpenAI()

# After RunCost — nothing else changes
from runcost import OpenAI
client = OpenAI()

Drop it in. That's it. Your existing code works exactly as before — except now every API call is intercepted, measured, and intelligently routed before it costs you money.

---

What Happens When You Run It

RunCost  //  Live Agent Cost Monitor          cost.run
──────────────────────────────────────────────────────
  ✓  researcher_01  →  llama-3-8b   $0.001    11ms
  ✓  analyst_04     →  gpt-4o       $0.047   780ms
  ✓  writer_02      →  mistral-7b   $0.002    43ms
  ✗  crawler_07     →  BLOCKED      $0.000  loop@13
  ✓  researcher_14  →  llama-3-8b   $0.001     9ms
──────────────────────────────────────────────────────
  Spent:    $1.82 / $5.00   [====      ]  36%
  Saved:   $41.30            Efficiency: 95.7%
  Blocked:  3 loops          Calls:       847
──────────────────────────────────────────────────────

RunCost intercepts every LLM call and:

• Estimates the cost before spending a dollar
• Routes simple tasks to cheap models (Groq, Llama 3, Mistral) automatically
• Routes reasoning-heavy tasks to GPT-4o or Claude only when needed
• Detects recursive loops and kills them before they drain your account
• Enforces hard spending limits — when you hit your cap, everything stops
• Logs every call to a local SQLite database
• Shows a live terminal dashboard of spend vs. savings in real time

---

The Numbers

Same simulation. Same output quality. 10x cheaper.

Workload	Without RunCost	With RunCost	Saved
1,000-agent MiroFish sim	$197.40	$2.10	98.9%
500-agent CrewAI workflow	$43.20	$4.80	88.9%
AutoGen research pipeline	$18.70	$1.90	89.8%
Recursive loop (caught)	$200+	$0.00	100%

---

Install

pip install runcost

Supported frameworks: OpenAI SDK · CrewAI · LangGraph · AutoGen · LangChain · MiroFish · any OpenAI-compatible client

---

Quick Start

from runcost import OpenAI, BudgetConfig

config = BudgetConfig(
    hard_limit_usd=5.00,     # Hard stop — never exceed this per run
    warn_at_usd=2.00,        # Alert when approaching limit
    auto_route=True,          # Auto-route cheap tasks to Llama/Groq
    block_loops=True,         # Kill recursive agent loops instantly
    log_to_db=True            # Save full history to runcost.db
)

client = OpenAI(budget=config)

# Use exactly as normal — RunCost works silently underneath
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze these 500 documents"}]
)

---

How Routing Works

RunCost classifies each call by complexity before sending it:

Complexity	Model Used	Typical Cost
Simple: formatting, lookup, summarization	Groq Llama-3 8B	~$0.001
Medium: research, extraction, classification	Mistral 7B	~$0.002
Complex: reasoning, code, multi-step logic	GPT-4o / Claude	~$0.04–0.09
Detected loop / budget exceeded	BLOCKED	$0.000

You can override routing per agent, per task type, or per model preference.

---

The Dashboard

runcost dashboard

Opens a live terminal view showing real-time spend, savings, active agents, blocked loops, and full call history. Dark mode. No browser required.

A web dashboard is coming in v0.3. Join the waitlist →

---

Why Open Source?

Because every developer deserves to see exactly what their agents are spending — before it's too late.

The core engine is AGPL-3.0. Run it yourself, audit it, fork it, build on it.

RunCost Pro (coming soon): team dashboards · multi-project tracking · SSO · compliance exports · Slack/Discord alerts · SLA support

Join the Pro waitlist at cost.run →

---

Roadmap

Status	Feature
✅	OpenAI SDK wrapper
✅	Groq / Llama-3 auto-routing
✅	Recursive loop detection
✅	Hard budget limits
✅	SQLite call logging
✅	Live terminal dashboard
🔜	Web dashboard (v0.3)
🔜	CrewAI native plugin
🔜	LangGraph native plugin
🔜	MiroFish native plugin
🔜	Pre-flight cost estimator
🔜	Slack / Discord spend alerts
🔜	Team spend analytics
🔜	AgentLedger plugin — audit trail for every agent action

---

Contributing

PRs welcome. See CONTRIBUTING.md.

If RunCost saved you money, a ⭐ on GitHub costs nothing and means everything.

---

The Story

I was building AI agent simulations and got hit with a $47 API bill for a single test run that didn't even produce useful output. A recursive loop had quietly fired 200 API calls before I noticed.

There was no tool that warned me. No framework stopped it. Just a bill.

RunCost is that warning. Built in public at cost.run — follow the journey at @RunCostAI on X.

---

License

AGPL-3.0 — free for individuals and open source projects.

Commercial license available for enterprise deployments. Contact: [e-mail]

---

cost.run · @RunCostAI · pip install runcost