Broker Service

Relays and records LLM usage, prices each call, tracks cache and routing savings, and enforces a default-plus-override budget per person.

Broker is the service that knows what models cost and who has spent what. It holds the provider and model catalog, writes one usage row per call, and applies a default budget to everyone automatically. The review screens are the Broker workspace in the intelligence app.

Domain: Services
Kind: Go HTTP service
Lifecycle: Active
flowctl project: None
Stacks: Runs on its own
Source: services/broker

Run it locally

Port 8125, Dev Auth, reporting a call, and reading the catalog.

Architecture

Catalog, usage rollup, budgets, and why caching is accounted only.

API

Relay, report, usage, savings, budgets, and routing.

Operations

Local port, provider keys, and why it is not deployed yet.

Two ways in, one table

A caller can ask broker to forward the request, or it can report a call that already happened. Relay checks the budget first, calls Anthropic / OpenAI / xAI / OpenRouter, and writes the row from the provider usage block. Report writes the same table so the existing data-broker can keep relaying and still fill these screens.

Diagram. Text representation: flowchart LR Caller[Client or data-broker] Relay["POST /v1/relay/*"] Report["POST /v1/usage"] Budget[budget check] Provider[Anthropic / OpenAI / xAI / OpenRouter] Usage[(usage_records + usage_daily)] UI[intelligence-app Broker workspace] Caller --> Relay --> Budget --> Provider --> Usage Caller --> Report --> Usage Usage --> UI

Diagram source

flowchart LR
  Caller[Client or data-broker]
  Relay["POST /v1/relay/*"]
  Report["POST /v1/usage"]
  Budget[budget check]
  Provider[Anthropic / OpenAI / xAI / OpenRouter]
  Usage[(usage_records + usage_daily)]
  UI[intelligence-app Broker workspace]

  Caller --> Relay --> Budget --> Provider --> Usage
  Caller --> Report --> Usage
  Usage --> UI

What it owns

The provider and model catalog, with versioned prices in USD micros per million tokens
Usage records and the trigger-maintained daily rollup
Realized prompt-cache savings and estimated routing savings, stored at write time
One default budget and per-person overrides
Smart-routing rules that substitute a cheaper model for a named model
Automatic routing, on for everyone unless an admin turns it off: a Go check, Jev, or a cheap model on the same provider grades the request, and broker may send it to a cheaper model in that family. Every decision is recorded for the tier split
The people roster, created the first time a request arrives, or when Foundry registers an agent mailbox (${slug}@ai.flow.life / ${slug}@dev-ai.flow.life). Agent mailboxes and service credential identities record who created them

What it does not own

Money in the legal-entity sense. Accounting and billing are not involved; see ADR 0044. A usage row is tokens, a model, and a priced cost, not a journal line.

It also does not cache prompts. The provider already reports cache-read tokens. Broker stores the dollars that difference is worth and nothing else.

Canonical service README: services/broker/README.md.