# RunCost 💸

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

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![PyPI version](https://img.shields.io/pypi/v/runcost)](https://pypi.org/project/runcost/)
[![GitHub Stars](https://img.shields.io/github/stars/runcostai/runcost?style=social)](https://github.com/runcostai/runcost)
[![Twitter Follow](https://img.shields.io/twitter/follow/RunCostAI?style=social)](https://x.com/RunCostAI)

---

## 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

```python
# 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

```bash
pip install runcost
```

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

---

## Quick Start

```python
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

```bash
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 →](https://cost.run)

---

## 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 →](https://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](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](https://cost.run) — follow the journey at [@RunCostAI](https://x.com/RunCostAI) on X.

---

## License

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

Commercial license available for enterprise deployments.
Contact: [hello@cost.run](mailto:hello@cost.run)

---

**[cost.run](https://cost.run)** · **[@RunCostAI](https://x.com/RunCostAI)** · **[pip install runcost](https://pypi.org/project/runcost)**
