Skip to main content

B09 - Token Accounting

GroupTechnologyStatusServiceRoadmap phaseContracts
B - LLM management and Model GatewayDevelopedto developfinops2usage-event

Back to index - Français

Role and responsibilities​

Counts input, output, reasoning and cached tokens per call and emits Usage Events.

Data model​

Usage Events follow contracts/v1/usage-event.schema.json (units, pricing, cost, source) and are stored in eai.usage_events, replicated to ClickHouse.

Tables (schema eai, every tenant table carries tenant_id uuid NOT NULL with an RLS policy on current_setting('app.tenant_id', true)::uuid): eai.usage_events, eai.price_cards, eai.fx_rates, eai.recon_imports, eai.audit_events.

API endpoints​

  • POST /v1/finops/usage
  • POST /v1/finops/usage/batch
  • GET /v1/finops/usage
POST /v1/finops/usage HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: en
Content-Type: application/json

{"schema_version": "1.0", "event_id": "6f1c2a9e-4b7d-4e2a-9c1f-2d3e4f5a6b7c", "occurred_at": "2026-10-30T09:00:00Z", "tenant_id": "18de5695-21f9-4053-a4ea-beb4bf2a5932", "agent_id": null, "session_id": null, "task_id": null, "usage_type": "llm", "provider": "openai", "model_id": "gpt-4o-eu", "region": "eu", "units": {"input_tokens": 1200, "output_tokens": 300}, "pricing": {"pricing_version": "2025-05", "currency": "USD", "effective_at": "2026-10-30T09:00:00Z"}, "cost": {"estimated": null, "measured": null, "billed": null}, "source": "gateway"}
{"id": "57120d60-19f6-49bd-b4a8-1b0012675bc2", "event": {"schema_version": "1.0", "event_id": "6f1c2a9e-4b7d-4e2a-9c1f-2d3e4f5a6b7c", "occurred_at": "2026-10-30T09:00:00Z", "tenant_id": "18de5695-21f9-4053-a4ea-beb4bf2a5932", "usage_type": "llm", "provider": "openai", "model_id": "gpt-4o-eu", "region": "eu", "units": {"input_tokens": 1200, "output_tokens": 300}, "pricing": {"price_card_id": "a9f571c4-9c05-4254-8e25-e1d5273a9b3d", "pricing_version": "2025-05", "currency": "USD", "effective_at": "2026-10-30T09:00:00Z", "reasoning_billing": "included_in_output"}, "cost": {"estimated": null, "measured": {"amount": "0.006", "currency": "USD"}, "billed": null}, "status": "measured", "source": "gateway", "labels": {}}, "breakdown": {"tier": null, "lines": [{"key": "input_tokens", "per": "1000000", "note": null, "amount": "0.003", "quantity": "1200", "unit_price": "2.5"}, {"key": "output_tokens", "per": "1000000", "note": null, "amount": "0.003", "quantity": "300", "unit_price": "10"}], "unpriced": [], "price_card": {"id": "a9f571c4-9c05-4254-8e25-e1d5273a9b3d", "version": "2025-05", "provider": "openai", "reference": false, "model_pattern": "gpt-4o*"}}, "fx": {"base": "USD", "legs": [], "rate": "1", "quote": "USD"}, "measured_in_price_currency": {"amount": "0.006", "currency": "USD"}, "user_id": "alice", "duplicate": false}

Errors use the common envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}}; lists are paginated with limit and cursor.

SDK usage​

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.finops.list_price_cards()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.finops.priceCards.list();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.finops().listPriceCards();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.FinOps.ListPriceCards(ctx)

Configuration​

  • Environment: EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
  • Helm values: controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Security controls​

  • Authentication by OIDC JWT, tenant API key with scopes, or SPIFFE mTLS; tenant resolved from the credential, never from the body.
  • Authorization through OpenFGA and OPA decisions; every mutation and decision writes a hash-chained eai.audit_events row.
  • Secrets never returned by the API; TLS everywhere; Cilium network policies restrict who can reach the service.

Observability​

  • Metrics: eai_token_accounting_requests_total, eai_token_accounting_errors_total, eai_token_accounting_latency_seconds (Prometheus).
  • Traces: OpenTelemetry spans eai.finops.* with W3C traceparent propagation, AI spans forwarded to Opik.
  • Audit actions: finops.price_card.create, finops.price_card.retire, finops.reconciliation.run, policy.evaluate.

FinOps aspects​

Operating cost is allocated per tenant and project through labels on Usage Events and Kubernetes resource requests; no direct per-call cost.

Failure modes and resilience​

  • Stateless replicas behind the API Gateway, PostgreSQL HA for state; readiness probe GET /readyz removes unhealthy pods.
  • External system unavailable: fail closed for security decisions, explicit error code, no silent bypass.

Standalone adoption (client of a client)​

A client of a client can adopt this brick alone with the Python SDK sub-client client.finops (TS eai.finops, Java client.finops(), Go client.FinOps). Minimal deployment: Control Plane API + PostgreSQL + Keycloak (or API keys), the Control Plane loads every domain of services/control-plane/src/eai/domains; the optional chart components are switched off in deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Acceptance tests​

  1. A tenant cannot read or modify another tenant's resources (RLS test).
  2. Every mutation produces an audit event verifiable by GET /v1/audit/verify.
  3. Errors are returned in English and French according to Accept-Language.