backboard-usage 0.2.6
Live token and cost visibility for Backboard apps. Run the server, open the UI, see usage in real time.
Requires Python: >=3.10
Keywords: backboard, usage, tokens, cost, observability

# 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.

- **PyPI:** [backboard-usage](https://pypi.org/project/backboard-usage/)
- **Docs:** This README and the [Wire format](#wire-format) below. For more examples, clone this repo and see the [examples](examples/) folder.

### Quick start

```bash
pip install backboard-usage
backboard-usage-server    # Terminal 1; open http://localhost:8766
```

In your app: `from backboard_usage import UsageTracker` → create tracker → `await tracker.record(response, agent="Name")` → `await tracker.finish()`

---

## After you install the package

```bash
pip install backboard-usage
```

### 1. Start the server

In a terminal (leave it running):

```bash
backboard-usage-server
```

You should see: **Live usage UI: http://localhost:8766**

### 2. Open the UI

In your browser open: **http://localhost:8766**

You’ll see the usage dashboard (empty until your app sends data).

### 3. Add a few lines to your Backboard app

**Basic usage** (~5 lines):

```python
from backboard_usage import UsageTracker

tracker = UsageTracker()
response = await client.add_message(...)
await tracker.record(response, agent="Idea Analyzer")  # repeat per agent
await tracker.finish()
```

**Context manager** (finish called automatically):

```python
async with UsageTracker() as tracker:
    response = await client.add_message(...)
    await tracker.record(response, agent="Agent Name")
```

**Sync apps (Streamlit, etc.):**

```python
from backboard_usage import run_with_tracker

async def my_flow(tracker, prompt):
    response = await client.add_message(prompt)
    await tracker.record(response, agent="Analyzer")
    return response

result = run_with_tracker(my_flow)("Hello")
```

Open http://localhost:8766 to see agents and token usage. If the server isn’t running, the app still runs; a warning is logged.

---

**Optional:** To try the UI without writing an app, clone this repo and run:

```bash
pip install websockets
python examples/demo_usage.py
```

(with the server and http://localhost:8766 open). You’ll see a fake run appear in the UI.

---

## Wire format

Your app sends JSON over the WebSocket.

**During a run** (e.g. after each agent or message):

```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**, **Total (all runs)**, and **Run history**.

---

## Example: try the UI without an app

Clone this repo and run **`examples/demo_usage.py`** (with the server and http://localhost:8766 open). It sends fake usage so you can see the UI update—no Backboard API key needed. See [examples/README.md](examples/README.md).

---

## Optional env

| Variable       | Default               | Description                 |
|----------------|-----------------------|-----------------------------|
| `USAGE_WS_URL` | `ws://localhost:8765` | WebSocket URL for your app. |

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| No agents in UI | Ensure `backboard-usage-server` is running and http://localhost:8766 is open before running your app. |
| Warning: "Usage server not running" | Start `backboard-usage-server` in another terminal. The app continues without tracking. |
| `record()` doesn't extract tokens | Use `await tracker.record_manual("Agent Name", tokens=500, cost=0.005)` instead. |
| websockets conflict with google-genai/realtime | Run `pip install "websockets>=12.0,<16"` |

---

## Documentation and links

- **This README** is the main documentation.
- **Wire format** is above; no separate docs site. For more examples, clone the repo and see the [examples](examples/) folder.
- **Backboard:** [backboard.io](https://backboard.io) · [Backboard SDK/docs](https://docs.backboard.io)
- **Repository:** [github.com/sapkota-aayush/BackboardOpenSource](https://github.com/sapkota-aayush/BackboardOpenSource)

When you push this repo to GitHub, update the repository URL in `pyproject.toml` (`project.urls`) and use it as the “Documentation” link (e.g. `https://github.com/sapkota-aayush/BackboardOpenSource#readme`).

---

## For contributors (development from repo)

```bash
git clone https://github.com/sapkota-aayush/BackboardOpenSource.git
cd BackboardOpenSource
pip install -e .
```

To rebuild the UI and bundle it into the package:

```bash
cd usage-ui && npm ci && npm run build && cd ..
# Windows:
Copy-Item -Path usage-ui\dist\* -Destination backboard_usage\ui -Recurse -Force
# macOS/Linux:
cp -r usage-ui/dist/* backboard_usage/ui/
```

Then run `backboard-usage-server` or `python usage_server.py`.

Run tests:

```bash
python -m unittest tests.test_backboard_usage -v
```

---

## License

MIT