backboard-usage 0.2.0

Live token and cost visibility for Backboard apps. Run the server, open the UI, see usage in real time.

Backboard Usage

Live token and cost visibility for Backboard apps. See usage in real time as your agents run—no need to wait for the billing dashboard.

• PyPI: backboard-usage
• Docs: This README and the Wire format below. For more examples, clone this repo and see the examples folder.

---

After you install the package

pip install backboard-usage

1. Start the server

In a terminal (leave it running):

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:

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:

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):

{
  "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:

{
  "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.

---

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 folder.
• Backboard: backboard.io · Backboard SDK/docs
• Repository: 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)

git clone https://github.com/sapkota-aayush/BackboardOpenSource.git
cd BackboardOpenSource
pip install -e .

To rebuild the UI and bundle it into the package:

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:

python -m unittest tests.test_backboard_usage -v

---

License

MIT