JavaScript SDK

npm install risicare

import { init } from 'risicare';
 
init(config?: RisicareConfig): void

import { enable, disable, isEnabled } from 'risicare';
 
enable(): void
disable(): void
isEnabled(): boolean

import { flush, shutdown } from 'risicare';
 
flush(): Promise<void>
shutdown(): Promise<void>

import { getMetrics } from 'risicare';
 
getMetrics(): {
  exportedSpans: number;
  droppedSpans: number;
  failedExports: number;
  queueSize: number;
  queueCapacity: number;
  queueUtilization: number;
}

import { getTraceContent } from 'risicare';
 
getTraceContent(): boolean

import { reportError } from 'risicare';
 
try {
    const result = await llm.invoke(query);
} catch (error) {
    reportError(error);          // Triggers diagnosis → fix generation
    return fallbackResponse;
}

import { score } from 'risicare';
 
score('trace-abc123', 'factual_accuracy', 0.92, {
    comment: 'Verified against source documents',
});

import { patchOpenAI } from 'risicare/openai';
import { patchAnthropic } from 'risicare/anthropic';
import { patchGroq } from 'risicare/groq';
import OpenAI from 'openai';
 
const openai = patchOpenAI(new OpenAI());
// All chat.completions.create and embeddings.create calls are now traced

import { patchOpenAI } from 'risicare/openai';
import OpenAI from 'openai';
 
// DeepSeek via OpenAI-compatible API — auto-detected as "deepseek"
const deepseek = patchOpenAI(new OpenAI({
    baseURL: 'https://api.deepseek.com/v1',
    apiKey: process.env.DEEPSEEK_API_KEY,
}));

import { generateText, streamText, generateObject } from 'ai';
import { patchVercelAI } from 'risicare/vercel-ai';
 
const { tracedGenerateText, tracedStreamText, tracedGenerateObject } = patchVercelAI();
const generate = tracedGenerateText(generateText);
const stream = tracedStreamText(streamText);
const genObject = tracedGenerateObject(generateObject);

import { RisicareCallbackHandler } from 'risicare/langchain';
 
const handler = new RisicareCallbackHandler();
const result = await chain.invoke(input, { callbacks: [handler] });

import { instrumentLangGraph } from 'risicare/langgraph';
 
const tracedGraph = instrumentLangGraph(compiledGraph);
const result = await tracedGraph.invoke(input);

import { patchInstructor } from 'risicare/instructor';
 
const patchedClient = patchInstructor(instructorClient);
const result = await patchedClient.create({ /* ... */ });

import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
 
const handler = new RisicareLlamaIndexHandler();
// Register with LlamaIndex's event system

import { tracedStream } from 'risicare';
 
const stream = tracedStream(asyncIterable, { name: 'llm-stream' });
for await (const chunk of stream) {
    process(chunk);
}
// Span automatically records stream.chunk_count and stream.completed

import { suppressProviderInstrumentation, isProviderInstrumentationSuppressed } from 'risicare';
 
suppressProviderInstrumentation(() => {
    // Provider patches are suppressed inside this scope
    await client.chat.completions.create(/* ... */);
});

import { agent } from 'risicare';
 
agent<T extends (...args: any[]) => any>(
  options: {
    name?: string;
    role?: string;  // orchestrator, worker, supervisor, specialist, router, etc.
    agentType?: string;
    version?: number;
    metadata?: Record<string, unknown>;
  },
  fn: T
): T

import { session } from 'risicare';
 
session<T extends (...args: any[]) => any>(
  optionsOrResolver: SessionOptions | ((...args: any[]) => SessionOptions),
  fn: T
): T
 
interface SessionOptions {
  sessionId: string;
  userId?: string;
}

import { traceThink, traceDecide, traceAct, traceObserve } from 'risicare';
 
// Bare form — span named after the function
const analyze = traceThink(async () => { /* ... */ });
 
// Named form — explicit span name
const analyze = traceThink('analyze-query', async () => { /* ... */ });
 
// All four phases support both forms
traceDecide('choose-action', async () => { /* ... */ });
traceAct('execute-tool', async () => { /* ... */ });
traceObserve('check-result', async () => { /* ... */ });

import { traceMessage, traceDelegate, traceCoordinate } from 'risicare';
 
traceMessage<T extends (...args: any[]) => any>(
  options: { to: string },
  fn: T
): T
 
traceDelegate<T extends (...args: any[]) => any>(
  options: { to: string },
  fn: T
): T
 
traceCoordinate<T extends (...args: any[]) => any>(
  options: { participants: string[] },
  fn: T
): T

import { getCurrentContext } from 'risicare';
 
getCurrentContext(): ContextState | undefined
 
interface ContextState {
  session?: { sessionId: string; userId?: string };
  agent?: { name: string; role?: string; agentId?: string };
  span?: Span;
  phase?: SemanticPhase;
}

import {
  getCurrentTraceId,
  getCurrentSpanId,
  getCurrentAgentId,
  getCurrentSessionId,
} from 'risicare';
 
getCurrentTraceId(): string | undefined
getCurrentSpanId(): string | undefined
getCurrentAgentId(): string | undefined
getCurrentSessionId(): string | undefined

import { injectTraceContext, extractTraceContext } from 'risicare';
 
injectTraceContext(headers: Record<string, string>): void
extractTraceContext(headers: Record<string, string>): TraceContext | undefined

import {
  registerSpan,
  getSpanById,
  unregisterSpan,
} from 'risicare';
 
registerSpan(span: Span, ttlMs?: number): void
getSpanById(spanId: string): Span | undefined
unregisterSpan(spanId: string): void

interface RisicareConfig {
  apiKey?: string;
  projectId?: string;  // DEPRECATED — emits console.warn. Will be removed in v1.0.
  endpoint?: string;
  environment?: string;
  serviceName?: string;
  serviceVersion?: string;
  enabled?: boolean;
  traceContent?: boolean;
  compress?: boolean;
  sampleRate?: number;
  batchSize?: number;
  batchTimeoutMs?: number;
  maxQueueSize?: number;
  debug?: boolean;
  metadata?: Record<string, unknown>;
}

interface TraceContext {
  traceId: string;
  spanId: string;
  sessionId?: string;
  agentId?: string;
}

class Span {
  traceId: string;
  spanId: string;
  name: string;
  kind: SpanKind;
  startTime: number;
  endTime?: number;
  attributes: Record<string, unknown>;
  events: SpanEvent[];
  status: SpanStatus;
 
  setAttribute(key: string, value: unknown): this;
  addEvent(name: string, attributes?: Record<string, unknown>): this;
  setStatus(status: SpanStatus): this;
  end(): void;
}

enum SpanKind {
  INTERNAL = 'internal',
  SERVER = 'server',
  CLIENT = 'client',
  PRODUCER = 'producer',
  CONSUMER = 'consumer',
  AGENT = 'agent',
  LLM_CALL = 'llm_call',
  TOOL_CALL = 'tool_call',
  RETRIEVAL = 'retrieval',
  DECISION = 'decision',
  DELEGATION = 'delegation',
  COORDINATION = 'coordination',
  MESSAGE = 'message',
  THINK = 'think',
  DECIDE = 'decide',
  OBSERVE = 'observe',
  REFLECT = 'reflect',
}

enum SpanStatus {
  UNSET = 'unset',
  OK = 'ok',
  ERROR = 'error',
}