Metadata-Version: 2.4
Name: runcost
Version: 0.3
Summary: Drop-in cost intelligence for Python AI agent frameworks.
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://cost.run
Project-URL: Repository, https://github.com/Picasso976/runcostai
Keywords: ai,agents,llm,cost,openai,crewai,langgraph
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# 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/Picasso976/runcostai?style=social)](https://github.com/Picasso976/runcostai)
[![Twitter Follow](https://img.shields.io/twitter/follow/RunCostAI?style=social)](https://x.com/RunCostAI)

---

## The Problem

You are building with CrewAI, LangGraph, AutoGen, MiroFish, or the OpenAI Agents SDK. The framework is powerful. The demos are impressive.

Then you run it at scale and see the bill.

A 500-agent simulation costs **$40-$80 per run**. A recursive loop that nobody catches costs **$200 before you notice**. An overnight batch job costs **$600 by morning**.

None of these frameworks warn you. None of them stop it. You find out when you get an email from your API provider.

**Every major agent framework has the same blind spot: zero native cost controls.**

RunCost is that missing layer.

---

## 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 is it. Your existing code works exactly as before.

Works with any OpenAI-compatible framework: CrewAI, LangGraph, AutoGen, MiroFish, LangChain, DeepSeek, Grok.

---

## What Happens When You Run It

```
RunCost  //  Live Agent Cost Monitor          cost.run
------------------------------------------------------
  OK  researcher_01  ->  llama-3-8b   $0.001    11ms
  OK  analyst_04     ->  gpt-4o       $0.047   780ms
  OK  writer_02      ->  mistral-7b   $0.002    43ms
  XX  crawler_07     ->  BLOCKED      $0.000  loop@13
  OK  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
------------------------------------------------------
```

---

## Install

```bash
pip install runcost
```

**Supported providers:** OpenAI · DeepSeek · Grok / xAI · Any OpenAI-compatible API

**Coming in v0.3:** Claude (Anthropic SDK) · Gemini (Google SDK)

---

## Quick Start

```python
from runcost import OpenAI, BudgetConfig

client = OpenAI(budget=BudgetConfig(
    hard_limit_usd=5.00,     # Hard stop -- never exceed this per run
    warn_at_usd=2.00,        # Alert when approaching limit
    log_to_db=True           # Save full history to runcost.db
))

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

**For DeepSeek:**
```python
client = OpenAI(
    api_key="your-deepseek-key",
    base_url="https://api.deepseek.com",
    budget=BudgetConfig(hard_limit_usd=5.00)
)
```

**For Grok:**
```python
client = OpenAI(
    api_key="your-grok-key",
    base_url="https://api.x.ai/v1",
    budget=BudgetConfig(hard_limit_usd=5.00)
)
```

---

## Web Dashboard

Launch a live web dashboard in your browser:

```bash
runcost server
```

Opens `http://localhost:8080` automatically. Shows:
- Real-time spend and API call tracking
- Pre-flight cost calculator — know your bill before you run
- Spend by model with visual breakdown
- Hourly spend chart
- Getting started guide built in
- Dark / light mode

---

## Terminal Dashboard

```bash
runcost dashboard
runcost dashboard --live   # auto-refreshes every 2 seconds
```

---

## Spend Summary

```bash
runcost summary
```

---

## The Numbers

> Same simulation. Same output quality. Up to 98% cheaper.

| Workload | Without RunCost | With RunCost | Saved |
|---|---|---|---|
| 1,000-agent simulation (GPT-4o) | ~$180-$200 | **~$2-$4** | ~98% |
| 500-agent CrewAI workflow | ~$40-$80 | **~$4-$8** | ~90% |
| AutoGen research pipeline | ~$15-$20 | **~$1-$2** | ~90% |
| Recursive loop (caught) | $200+ | **$0.00** | 100% |

> Savings based on routing simple tasks to Groq Llama-3 (~$0.05/1M tokens) vs GPT-4o ($2.50/1M tokens).

---

## Current Pricing (March 2026)

| Model | Input /1M | Output /1M |
|---|---|---|
| GPT-4o | $2.50 | $10.00 |
| GPT-4.1 | $2.00 | $8.00 |
| GPT-5 | $1.25 | $10.00 |
| Claude Sonnet 4.6 | $3.00 | $15.00 |
| DeepSeek Chat | $0.27 | $1.10 |
| Llama-3 8B (Groq) | $0.05 | $0.08 |
| Mistral 7B | $0.25 | $0.25 |

---

## Roadmap

| Status | Feature |
|--------|---------|
| ✅ | OpenAI SDK wrapper |
| ✅ | Real-time cost tracking |
| ✅ | Hard budget limits |
| ✅ | SQLite call logging |
| ✅ | Terminal dashboard |
| ✅ | Web dashboard (runcost server) |
| ✅ | Pre-flight cost calculator |
| ✅ | DeepSeek support |
| ✅ | Grok / xAI support |
| 🔜 | Auto-routing (cheap model selection) |
| 🔜 | Recursive loop detection |
| 🔜 | Claude (Anthropic SDK) support |
| 🔜 | Gemini (Google SDK) support |
| 🔜 | CrewAI native plugin |
| 🔜 | LangGraph native plugin |
| 🔜 | Slack / Discord spend alerts |
| 🔜 | AgentLedger -- audit trail for every agent action |

---

## Why Open Source?

Because every developer deserves to see exactly what their agents are spending -- before it is 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

---

## Why This Exists

Multi-agent AI frameworks are powerful. But none of them ship with cost controls. RunCost is the layer that should have existed from day one -- built in public, open source, free to use.


---

## License

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

Commercial license available for enterprise deployments.

---


