Cohere AI Spend Control for Budget-Conscious SMBs

Enforce daily AI spend limits, automatically downgrade to cheaper Cohere models, and get real-time cost dashboards without modifying existing agent code.

cohere cost-control budget-enforcement llm-router typescript express cli

The problem

Small businesses deploying AI agents often see unpredictable monthly bills because every customer interaction triggers expensive model calls. They need a way to cap spending, pick the right model for each query, and audit costs without hiring an MLOps engineer.

Built from

Intro

Small businesses deploying AI agents often see unpredictable monthly bills because every customer interaction triggers expensive model calls. This tutorial shows you how to build a spend-control system for Cohere’s API using the @reaatech/* package family. You’ll create per-tenant daily budgets, automatic model downgrade from command-a-03-2025 to command-r-03-2025 when budgets get tight, and real-time cost dashboards — all served through a Next.js API or a standalone Express CLI daemon.

Prerequisites

Node.js 22+ and pnpm 10 installed
A Cohere API key (free trial available at dashboard.cohere.com)
(Optional) Langfuse and Portkey accounts for observability export
Basic familiarity with TypeScript, Next.js App Router, and Express

Step 1: Scaffold the project and install dependencies

Start from a fresh directory created by the Next.js scaffold. Your package.json should include all the packages you’ll need — the @reaatech/* family for telemetry, routing, and budget enforcement, plus Cohere’s SDK, Express, Langfuse, Portkey, and dev tooling.

Example artifact

A complete, working implementation of this recipe — downloadable as a zip or browsable file by file. Generated by our build pipeline; tested with full coverage before publishing.

Download example (zip)Browse files

171 kB·130 tests·97.1% coverage·vitest passing

SHA-2564d9192ca65b7ba0b4924888ad2b3c0e150ae8e7a32281871a6e7d7cf1e472ca7

Book a conversation All solutions

Comments

Loading comments…

import { type CostSpan } from "@reaatech/llm-cost-telemetry"; import { CostCollector, CostAggregator, type AggregationDimension } from "@reaatech/llm-cost-telemetry-aggregation"; import type { DashboardSummary } from "../lib/types.js"; export class CostTelemetryService { private collector: CostCollector; private aggregator: CostAggregator; constructor() { this.aggregator = new CostAggregator({ dimensions: ["tenant", "feature", "provider", "model"] as never, timeWindows: ["hour", "day", "month"] as never, }); this.collector = new CostCollector({ maxBufferSize: 1000, flushIntervalMs: 60000, onFlush: (spans: CostSpan[]) => { for (const span of spans) { this.aggregator.add(span); } }, }); } ingestSpan(span: CostSpan): void { this.collector.add(span); } getTenantCosts(tenant: string): { totalUsd: number; byProvider: Record<string, number> } { const records = this.aggregator.getByTenant(tenant); const totalUsd = records.reduce((sum, r) => sum + (r.totalUsd ?? 0), 0); const byProvider: Record<string, number> = {}; for (const r of records) { const providerName = r.key?.provider ?? "unknown"; byProvider[providerName] = (byProvider[providerName] ?? 0) + (r.totalUsd ?? 0); } return { totalUsd, byProvider }; } getModelCosts(modelId?: string, period?: "day" | "month"): { totalUsd: number; callCount: number } { const options: { period?: "day" | "month"; groupBy?: AggregationDimension[] } = {}; if (period) options.period = period; if (modelId) options.groupBy = ["model"]; const summary = this.aggregator.getSummary(options); return { totalUsd: summary.totalUsd ?? 0, callCount: summary.totalCalls ?? 0 }; } getDailyTrend(): Array<{ date: string; totalUsd: number }> { const records = this.aggregator.getAll(); const byDate: Record<string, number> = {}; for (const r of records) { const ws = r.key?.windowStart ?? r.windowStart; if (!ws) continue; const date = typeof ws === "string" ? ws.slice(0, 10) : ws.toISOString().slice(0, 10); byDate[date] = (byDate[date] ?? 0) + (r.totalUsd ?? 0); } return Object.entries(byDate) .sort(([a], [b]) => a.localeCompare(b)) .map(([date, totalUsd]) => ({ date, totalUsd })); } getDashboardSummary(): DashboardSummary { const summary = this.aggregator.getSummary({}); const records = this.aggregator.getAll(); const byTenant: Record<string, number> = {}; const byModel: Record<string, number> = {}; for (const r of records) { const t = r.key?.tenant ?? "unknown"; const m = r.key?.model ?? "unknown"; byTenant[t] = (byTenant[t] ?? 0) + (r.totalUsd ?? 0); byModel[m] = (byModel[m] ?? 0) + (r.totalUsd ?? 0); } return { totalSpend: summary.totalUsd ?? 0, byTenant, byModel, budgetStatuses: [], }; } close(): void { void this.collector.close(); } }

import { BudgetController } from "@reaatech/agent-budget-engine"; import { SpendStore } from "@reaatech/agent-budget-spend-tracker"; import { BudgetScope } from "@reaatech/agent-budget-types"; import pino from "pino"; const logger = pino({ name: "budget-controller" }); export class BudgetEnforcementService { private controller: BudgetController; private onThresholdBreach = (event: { threshold: number }) => { logger.warn({ event, pct: Number(event.threshold) * 100 }, "budget threshold breach"); }; private onHardStop = (event: unknown) => { logger.error({ event }, "budget exhausted"); }; private onStateChange = (event: unknown) => { logger.info({ event }, "Budget state changed"); }; private spendStore: SpendStore; constructor() { this.spendStore = new SpendStore(); this.controller = new BudgetController({ spendTracker: this.spendStore }); this.controller.on("threshold-breach", this.onThresholdBreach); this.controller.on("hard-stop", this.onHardStop); this.controller.on("state-change", this.onStateChange); } defineTenantBudget(options: { scopeType: BudgetScope; scopeKey: string; limit: number; policy: { softCap: number; hardCap: number; autoDowngrade: Array<{ from: string[]; to: string }>; disableTools: string[]; }; }): void { this.controller.defineBudget(options); logger.info({ scopeKey: options.scopeKey, limit: options.limit }, "Tenant budget defined"); } checkCall(options: { scopeType: BudgetScope; scopeKey: string; estimatedCost: number; modelId: string; tools: string[]; }): { allowed: boolean; suggestedModel?: string; disabledTools?: string[] } { const result = this.controller.check(options); return { allowed: result.allowed, suggestedModel: result.suggestedModel, disabledTools: result.disabledTools, }; } recordSpend(entry: { requestId: string; scopeType: BudgetScope; scopeKey: string; cost: number; inputTokens: number; outputTokens: number; modelId: string; provider: string; timestamp: Date; }): void { this.controller.record(entry); } getTenantState(scopeType: BudgetScope, scopeKey: string): { state: string; spent: number; remaining: number } | null { const state = this.controller.getState(scopeType, scopeKey); if (!state) return null; return { state: state.state, spent: state.spent, remaining: state.remaining, }; } resetBudget(scopeType: BudgetScope, scopeKey: string): void { this.controller.reset(scopeType, scopeKey); logger.info({ scopeKey }, "Budget reset"); } getDisabledTools(scopeType: BudgetScope, scopeKey: string): string[] { return this.controller.getDisabledTools(scopeType, scopeKey); } close(): void { logger.info("Budget enforcement service closed"); } }

import Langfuse from "langfuse"; import Portkey from "portkey-ai"; import type { CostSpan } from "@reaatech/llm-cost-telemetry"; import pino from "pino"; const logger = pino({ name: "observability" }); export const langfuseClient: Langfuse | null = process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY ? new Langfuse({ publicKey: process.env.LANGFUSE_PUBLIC_KEY, secretKey: process.env.LANGFUSE_SECRET_KEY, }) : null; export function traceCohereCall(span: CostSpan): void { if (!langfuseClient) return; langfuseClient.trace({ name: "cohere-chat", metadata: { provider: span.provider, model: span.model, tenant: span.tenant, feature: span.feature, costUsd: span.costUsd, inputTokens: span.inputTokens, outputTokens: span.outputTokens, timestamp: span.timestamp, }, }); } export function logBudgetTransition(event: { tenant: string; fromState: string; toState: string; dailyPct: number; }): void { if (!langfuseClient) return; langfuseClient.trace({ name: "budget-state-change", metadata: { tenant: event.tenant, fromState: event.fromState, toState: event.toState, dailyPct: event.dailyPct, }, }); } export const portkeyClient: Portkey | null = process.env.PORTKEY_API_KEY || process.env.PORTKEY_VIRTUAL_KEY ? new Portkey({ apiKey: process.env.PORTKEY_API_KEY ?? undefined, virtualKey: process.env.PORTKEY_VIRTUAL_KEY ?? undefined, }) : null; export async function reportCostToPortkey(client: Portkey, span: CostSpan): Promise<void> { await client.chat.completions.create({ messages: [{ role: "user", content: "cost report" }], model: span.model, }); logger.info({ costUsd: span.costUsd, model: span.model }, "Portkey cost report sent"); } export function getPortkeyClient(): Portkey | null { return portkeyClient; } export async function shutdown(): Promise<void> { const tasks: Promise<unknown>[] = []; if (langfuseClient) { tasks.push(langfuseClient.shutdownAsync()); } if (portkeyClient) { logger.info("Portkey client cleanup skipped — no shutdown method available"); } await Promise.allSettled(tasks); }

import { type NextRequest, NextResponse } from "next/server"; import { getCostTelemetry, getBudgetEnforcement, getCohereClient } from "../../../src/index.js"; import { BudgetScope } from "@reaatech/agent-budget-types"; export function GET(): NextResponse { return NextResponse.json(getCostTelemetry().getDashboardSummary()); } export async function POST(req: NextRequest): Promise<NextResponse> { const body = (await req.json()) as { tenant?: string; model?: string; prompt?: string; }; const tenant = body.tenant; const model = body.model; const prompt = body.prompt; if (!tenant) { return NextResponse.json({ error: "Missing tenant" }, { status: 400 }); } const check = getBudgetEnforcement().checkCall({ scopeType: BudgetScope.User, scopeKey: tenant, estimatedCost: 0, modelId: model ?? "command-a-03-2025", tools: [], }); if (!check.allowed) { return NextResponse.json({ error: "Budget limit reached" }, { status: 403 }); } let result; try { result = await getCohereClient().chat({ model, messages: [{ role: "user", content: prompt ?? "" }], }); } catch { return NextResponse.json({ error: "Cohere API error" }, { status: 502 }); } getBudgetEnforcement().recordSpend({ requestId: result.costSpan.id ?? result.costSpan.spanId ?? "", scopeType: BudgetScope.User, scopeKey: tenant, cost: result.costSpan.costUsd, inputTokens: result.costSpan.inputTokens, outputTokens: result.costSpan.outputTokens, modelId: result.costSpan.model, provider: "cohere", timestamp: result.costSpan.timestamp ?? new Date(), }); return NextResponse.json({ content: result.content, costUsd: result.costSpan.costUsd, model: result.costSpan.model, }); } export async function PUT(req: NextRequest): Promise<NextResponse> { const body = (await req.json()) as { tenant?: string; limit?: number; }; const tenant = body.tenant; const limit = body.limit; if (!tenant) { return NextResponse.json({ error: "Missing tenant" }, { status: 400 }); } getBudgetEnforcement().defineTenantBudget({ scopeType: BudgetScope.User, scopeKey: tenant, limit: limit ?? 100, policy: { softCap: 0.8, hardCap: 1.0, autoDowngrade: [{ from: ["command-a-03-2025"], to: "command-r-03-2025" }], disableTools: [], }, }); return NextResponse.json({ success: true, tenant }); } export async function DELETE(req: NextRequest): Promise<NextResponse> { const body = (await req.json()) as { tenant?: string }; const tenant = body.tenant; if (!tenant) { return NextResponse.json({ error: "Missing tenant" }, { status: 400 }); } getBudgetEnforcement().resetBudget(BudgetScope.User, tenant); return NextResponse.json({ success: true, tenant }); }

import { CohereClientWrapper } from "./services/cohere-client.js"; import { CostTelemetryService } from "./services/cost-telemetry.js"; import { BudgetEnforcementService } from "./services/budget-controller.js"; import { createCohereRouter } from "./services/llm-router.js"; import { shutdown as shutdownObservability } from "./adapters/observability.js"; import type { LLMRouter } from "@reaatech/llm-router-engine"; let _costTelemetry: CostTelemetryService | undefined; let _budgetEnforcement: BudgetEnforcementService | undefined; let _cohereClient: CohereClientWrapper | undefined; let _router: LLMRouter | undefined; export function getCostTelemetry(): CostTelemetryService { _costTelemetry ??= new CostTelemetryService(); return _costTelemetry; } export function getBudgetEnforcement(): BudgetEnforcementService { _budgetEnforcement ??= new BudgetEnforcementService(); return _budgetEnforcement; } export function getCohereClient(): CohereClientWrapper { if (!_cohereClient) { _cohereClient = new CohereClientWrapper({ onCostSpan: (span) => { getCostTelemetry().ingestSpan(span); }, }); } return _cohereClient; } export function getRouter(): LLMRouter { if (!_router) { _router = createCohereRouter({ executeModel: async (model, request) => { const result = await getCohereClient().chat({ model: model.id, messages: [{ role: "user", content: request.prompt }], }); return { content: result.content, inputTokens: result.costSpan.inputTokens, outputTokens: result.costSpan.outputTokens, }; }, }); } return _router; } export async function init(options?: { cohereApiKey?: string }): Promise<void> { if (options?.cohereApiKey) { process.env.COHERE_API_KEY = options.cohereApiKey; } getCostTelemetry(); getBudgetEnforcement(); getCohereClient(); getRouter(); await Promise.resolve(); } export async function shutdown(): Promise<void> { if (_costTelemetry) _costTelemetry.close(); if (_budgetEnforcement) _budgetEnforcement.close(); await shutdownObservability(); }

Cohere AI Spend Control for Budget-Conscious SMBs

The problem

Built from

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Example artifact

Comments

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Step 2: Configure environment variables

Step 3: Define core types

Step 4: Add Cohere pricing

Step 5: Build the Cohere client wrapper

Step 6: Build the cost telemetry service

Step 7: Build the budget enforcement service

Step 8: Build the LLM router service

Step 9: Wire up observability adapters

Step 10: Create the Next.js API route

Step 11: Wire up singletons in the main module

Step 12: Create the CLI daemon

Step 13: Run the tests

Next steps