How-to guides
Step-by-step walkthroughs for every shipped feature. Each guide follows the same shape:
- What it does — one-paragraph overview.
- Prerequisites — what must already be set up.
- Steps — numbered, with the exact API call / UI click for each.
- Verify — how to confirm it worked.
- Common issues — things that will go wrong on first try, and the fix.
- Related — links to the next guide(s) in the cycle.
Every API example uses
$BIGWAVE_TOKEN(the bearer token from.env). Set it once:export BIGWAVE_TOKEN=$(grep ^BIGWAVE_ADMIN_TOKEN .env | cut -d= -f2).
The Bigwave loop, end-to-end
If you're new, walk through the guides in this order — each unlocks the next:
| # | Guide | Time |
|---|---|---|
| 1 | Send a chat message | 30 s |
| 2 | Inspect inferences (Observability) | 1 min |
| 3 | Capture user feedback (👍/👎) | 30 s |
| 4 | Build a dataset from feedback | 2 min |
| 5 | Train a LoRA adapter (DPO) | 5–30 min |
| 6 | Promote an adapter | 10 s |
| 7 | Run an eval against a golden set | 2 min |
Standalone features
Reachable without going through the loop above:
- Overview dashboard
- Knowledge bases (RAG)
- Cost dashboard + price tables
- Tool calls inspector
- Model catalog
- Run multiple models + shadow mode
Operator how-tos
The engineering runbooks under github.com/bigwaveml/bigwave/tree/main/docs/runbooks cover operator-tier topics:
- Single-GPU deploy — end-to-end install, GPU sizing, install-mode + serving choice, model pull, reconfigure / switch.
- Agent harness — agent runtime
- sandbox + tool registry + per-workspace policy.
- Feedback loop — chat → feedback → DPO → eval → promote.
- Anthropic messages adapter — Anthropic-compatible surface on top of the gateway.
- Log rotation — operator hygiene for the audit log + inference log.
Per-feature operator how-tos (reconfigure, sqlite→postgres, observability sidecar wiring) are a follow-up batch — track in docs/issues/.