@coalex-ai/sdk

TypeScript SDK for Coalex — AI governance observability for enterprises in regulated markets.

Built on OpenTelemetry. Ships as pure ESM.

Install

npm install @coalex-ai/sdk
# or
pnpm add @coalex-ai/sdk

Quick Start

import { register, autoInstrumentAsync, coalexContext, evaluate } from "@coalex-ai/sdk";

// 1. Initialize the SDK
register({
  apiKey: process.env.COALEX_API_KEY,
  serviceName: "my-agent",
});

// 2. Auto-instrument AI libraries (OpenAI, LangChain, Anthropic)
await autoInstrumentAsync();

// 3. Wrap agent invocations for tracing
const result = await coalexContext({ agentId: "support-agent" }, async () => {
  // Your AI agent logic here
  return await chain.invoke({ question: "..." });
});

API

register(options?)

Initialize the SDK. Must be called before any other function.

register({
  endpoint: "https://collect.coalex.ai", // default
  apiKey: "your-api-key",
  serviceName: "my-agent",
  filterNonAiSpans: false,    // filter out non-AI spans
  suppressExportErrors: true, // suppress OTLP export errors (default)
});

autoInstrumentAsync(options?)

Instrument AI libraries using dynamic import(). Use this in ESM projects.

const results = await autoInstrumentAsync();
// { openai: "success", langchain: "not_installed", anthropic: "success" }

autoInstrument(options?)

Synchronous variant using require(). Use this in CommonJS projects.

const results = autoInstrument();

Both accept an options object:

autoInstrumentAsync({
  includeLibraries: ["openai", "anthropic"], // only these
  excludeLibraries: ["langchain"],           // skip these
  tracerProvider: customProvider,             // custom OTel provider
  suppressErrors: true,                      // swallow errors (default)
});

instrumentOpenAI() / instrumentLangChain() / instrumentAnthropic()

Convenience functions to instrument a single library.

instrumentOpenAI();  // returns boolean

coalexContext(options, fn) / coalexContextSync(options, fn)

Wrap a function in a traced Coalex invocation span.

const result = await coalexContext(
  { agentId: "my-agent", requestId: "req-123", version: "1.0" },
  async () => {
    // traced code
  },
);

evaluate(options)

Submit an AI output for evaluation. Returns the governance decision.

const decision = await evaluate({
  traceId: "abc-123",
  input: { question: "What is the policy?" },
  output: { answer: "The policy states..." },
  metrics: { answer: ["f1", "semantic_similarity"] },
});
// { status: "auto_approved" | "escalated" | "rejected", riskScore: 0.12, escalationId?: "..." }

Available metrics: f1, word_overlap, bleu, rouge_l, semantic_similarity, exact_match, levenshtein, contains.

resolve(options)

Resolve an escalated evaluation.

const result = await resolve({
  escalationId: "esc-456",
  decision: "approved", // "approved" | "rejected" | "corrected"
  reviewer: "[email protected]",
  reason: "Output is accurate",
});

Extension Spans

Import from @coalex-ai/sdk/ext for fine-grained tracing of RAG pipelines:

import { toolSpan, embeddingSpan, retrievalSpan, rerankerSpan, guardrailSpan } from "@coalex-ai/sdk/ext";

• toolSpan — Trace tool/function calls
• embeddingSpan — Trace embedding generation
• retrievalSpan — Trace document retrieval
• rerankerSpan — Trace reranking steps
• guardrailSpan — Trace guardrail checks

Requirements

• Node.js 18+
• TypeScript 5.0+ (for type-checking)

License

Apache-2.0