Metadata-Version: 2.4
Name: backboard-usage
Version: 0.1.0
Summary: Live token and cost visibility for Backboard apps. Run the server, open the UI, see usage in real time.
Author: Backboard Usage
License: MIT
Project-URL: Homepage, https://github.com/yourusername/backboard-usage
Project-URL: Documentation, https://github.com/yourusername/backboard-usage#readme
Project-URL: Repository, https://github.com/yourusername/backboard-usage
Keywords: backboard,usage,tokens,cost,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: backboard-sdk; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"

# Backboard Usage

Live token and cost visibility for [Backboard](https://backboard.io) apps. See usage in real time as your agents run—no need to wait for the billing dashboard.

## Install

```bash
pip install backboard-usage
```

## Quick start

1. **Start the usage server** (one terminal, leave it running):

   ```bash
   backboard-usage-server
   ```

2. **Open the UI** in your browser: **http://localhost:8766**

3. **Run your Backboard app** in another terminal. Your app must send usage data to `ws://localhost:8765` in the [expected JSON format](#wire-format) (e.g. using the pattern in the example below).

You’ll see live tokens, cost, and breakdown by agent and model. Run history is stored in the browser (last 10 runs).

## Wire format

Your app connects to the WebSocket and sends JSON messages.

**During a run** (after each message or step):

```json
{
  "event": "usage",
  "total_tokens": 1234,
  "total_cost": 0.0123,
  "by_agent": {
    "Idea Analyzer": { "tokens": 600, "cost": 0.006 },
    "Market Researcher": { "tokens": 634, "cost": 0.0063 }
  },
  "by_model": {
    "openai/gpt-4o": { "tokens": 1234, "cost": 0.0123 }
  }
}
```

**When the run finishes:**

```json
{
  "event": "done",
  "total_tokens": 1234,
  "total_cost": 0.0123,
  "by_agent": { ... },
  "by_model": { ... }
}
```

The UI shows “This run” (current session), “Total (all runs)” (aggregate from history), and “Run history” (last 10 runs).

## Example: Python

Use the Backboard SDK and send usage after each `add_message` (tokens/cost from the response, or estimate with `backboard_usage.cost.estimate_cost`). Connect to `ws://localhost:8765` and push the JSON above. See `orchestrator.py` in this repo for a full example with multiple agents.

## Optional env

| Variable      | Default              | Description                    |
|---------------|----------------------|--------------------------------|
| `USAGE_WS_URL` | `ws://localhost:8765` | WebSocket URL your app uses.   |

## Development from repo

```bash
pip install -e .
# Build UI (first time or after UI changes):
cd usage-ui && npm ci && npm run build && cd ..
# Copy UI into package (so server serves it):
# Windows PowerShell:
Copy-Item -Path usage-ui\dist\* -Destination backboard_usage\ui -Recurse -Force
# Then run:
backboard-usage-server
# Or: python usage_server.py
```

## License

MIT
