backboard-usage 0.2.5

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.

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