Metadata-Version: 2.4
Name: backboard-usage
Version: 0.2.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-Expression: MIT
Project-URL: Homepage, https://github.com/sapkota-aayush/BackboardOpenSource
Project-URL: Documentation, https://github.com/sapkota-aayush/BackboardOpenSource#readme
Project-URL: Repository, https://github.com/sapkota-aayush/BackboardOpenSource
Keywords: backboard,usage,tokens,cost,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
License-File: LICENSE
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: backboard-sdk; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Dynamic: license-file

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

---

## 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 3 lines to your Backboard app

Use **`UsageTracker`** so you only add a few lines:

```python
from backboard_usage import UsageTracker

tracker = UsageTracker()

# After each agent response:
response = await client.add_message(...)
await tracker.record(response, agent="Idea Analyzer")  # use your agent name

# At the end of your run:
await tracker.finish()
```

That’s it. Open http://localhost:8766 and you’ll see all agents and token usage.

---

**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. |

---

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