SDKs

TypeScript SDK

buzo-sdk is the official Node-only client for the Buzo retrieval and generation ingest endpoints. Zero added latency on your agent's request path.

Install

npm install buzo-sdk
# Optional peer dependency for the LangChain callback integration:
npm install @langchain/core

Client

Construct one Buzo client per process, at module load. It is safe to share across requests.

lib/buzo.ts

import { Buzo } from 'buzo-sdk'

export const buzo = new Buzo({
  apiKey: process.env.BUZO_API_KEY!,
})

Configuration

Option	Type	Default	Purpose
`apiKey`	`string`	required	API key starting with `ak_live_`, `sdk` scope.
`endpoint`	`string`	`https://api.buzo.ai`	Override for self-hosted Buzo deployments.
`queryCapture`	`'plaintext' \| 'hash' \| 'redact'`	`'plaintext'`	See Capture modes.
`redactPatterns`	`{ pattern, replacement }[]`	`[]`	Regex replacements applied when `queryCapture === 'redact'`.
`outputCapture`	`'off' \| 'redacted' \| 'plaintext'`	`'off'`	v0.2+. Opt-in LLM output capture for CITED_FLAGGED attribution.
`outputRedactPatterns`	`{ pattern, replacement }[]`	`[]`	Applied when `outputCapture === 'redacted'`.
`resultsCapture`	`'ids-only' \| 'plaintext' \| 'redacted'`	`'ids-only'`	v0.4+. Opt-in capture of retrieved-vector content for full-corpus citation matching. See Capture modes.
`resultsRedactPatterns`	`{ pattern, replacement }[]`	`[]`	Applied when `resultsCapture === 'redacted'`.
`sampleRate`	`number`	`1.0`	Uniform random sampling. `0.1` ships 10% of events.
`batchSize`	`number`	`25`	Events buffered before a flush fires.
`flushIntervalMs`	`number`	`5000`	Maximum age of a buffered event before the timer fires a flush.
`maxBufferSize`	`number`	`1000`	Ring buffer capacity. Drops oldest when full.
`logger`	`(level, msg, ctx) => void`	no-op	Hook for SDK-internal telemetry (circuit open, 4xx, buffer overflow, etc.).
`disabled`	`boolean`	`false`	Kill switch — disables all network I/O. Useful for tests.

recordRetrieval

The direct API for retrieval events. Fire-and-forget — never throws, never blocks.

buzo.recordRetrieval({
  collectionId: 'prod-support-kb',
  agentId: 'support-v3',
  query: { text: 'how do I reset my password?' },
  results: [
    // `content` is optional (v0.4+). Pass it raw — the SDK strips or redacts
    // based on the `resultsCapture` config. With the default `ids-only`
    // mode, content is dropped before egress even if supplied here.
    { id: 'vec_abc', score: 0.87, content: doc1.pageContent },
    { id: 'vec_def', score: 0.81, content: doc2.pageContent },
  ],
  latencyMs: 47,
  // Optional — stamp when the retriever is part of a larger chain, so the
  // server can correlate it with the matching recordGeneration call.
  parentQueryId: 'chain-run-root',
  metadata: { sessionId: 'sess_123' },
})

recordGeneration v0.2+

Ship an LLM generation event for CITED_FLAGGED attribution. No-op when outputCapture === 'off'.

buzo.recordGeneration({
  // Correlation — either runId or parentRunId must match the parentQueryId
  // you stamped on recordRetrieval for the retrievals in the same chain.
  runId: 'chain-run-llm',
  parentRunId: 'chain-run-root',
  collectionId: 'prod-support-kb',
  agentId: 'support-v3',
  output: { text: finalAnswer },
  model: 'gpt-4o',
  promptTokens: tokens.prompt,
  completionTokens: tokens.completion,
  latencyMs: elapsed,
})

flush

Force-flushes the buffer. Use in edge runtimes and short-lived environments so events ship before the process is recycled.

Vercel Edge

export const runtime = 'edge'

export async function POST(req: Request) {
  const answer = await chain.invoke(question, { callbacks: [handler] })
  // Ship buffered traces before the isolate is evicted.
  // ctx.waitUntil(buzo.flush())
  return new Response(answer)
}

Failure semantics

Scenario	Behavior
Buzo returns 5xx	Retry. Repeated failures open a short-lived circuit breaker.
Buzo returns 4xx	Batch dropped, no retry, logged via `logger`.
Network error / DNS failure	Same as 5xx.
Customer process crashes	Buffered traces lost. Telemetry is not a transactional log.
Customer retriever throws	Trace recorded with `error` field, original error re-thrown.