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.

Quick start

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

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 a few lines to your Backboard app

Basic usage (~5 lines):

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

async with UsageTracker() as tracker:
    response = await client.add_message(...)
    await tracker.record(response, agent="Agent Name")

Sync apps (Streamlit, etc.):

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:

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.

---

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