risicare 0.1.5 → 0.2.1

package/dist/index.d.cts

@@ -1,3 +1,8 @@
+export { RisicareCallbackHandler } from './frameworks/langchain.cjs';
+export { instrumentLangGraph } from './frameworks/langgraph.cjs';
+export { patchInstructor } from './frameworks/instructor.cjs';
+export { RisicareLlamaIndexHandler } from './frameworks/llamaindex.cjs';
+
 /**
  * SDK configuration with environment variable loading.
  *
@@ -83,18 +88,38 @@ declare enum SemanticPhase {
 declare enum AgentRole {
     ORCHESTRATOR = "orchestrator",
     WORKER = "worker",
-    REVIEWER = "reviewer",
+    SUPERVISOR = "supervisor",
+    SPECIALIST = "specialist",
+    ROUTER = "router",
+    AGGREGATOR = "aggregator",
+    BROADCASTER = "broadcaster",
+    CRITIC = "critic",
     PLANNER = "planner",
     EXECUTOR = "executor",
-    CRITIC = "critic",
+    RETRIEVER = "retriever",
+    VALIDATOR = "validator",
+    REVIEWER = "reviewer",
     CUSTOM = "custom"
 }
 declare enum MessageType {
-    REQUEST = "request",
+    TASK = "task",
+    RESULT = "result",
+    STATUS = "status",
+    ERROR = "error",
+    QUERY = "query",
     RESPONSE = "response",
+    BROADCAST = "broadcast",
+    DIRECT = "direct",
+    PROPOSAL = "proposal",
+    VOTE = "vote",
+    CONSENSUS = "consensus",
+    CONFLICT = "conflict",
+    HEARTBEAT = "heartbeat",
+    SHUTDOWN = "shutdown",
+    HANDOFF = "handoff",
+    REQUEST = "request",
     DELEGATE = "delegate",
-    COORDINATE = "coordinate",
-    BROADCAST = "broadcast"
+    COORDINATE = "coordinate"
 }
 interface SpanEvent {
     name: string;
@@ -477,14 +502,34 @@ declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: Se
  *   return await llm.invoke(`Decide action: ${analysis}`);
  * });
  */
-/** Wrap a function in a THINK phase context with auto-span. */
-declare function traceThink<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-/** Wrap a function in a DECIDE phase context with auto-span. */
-declare function traceDecide<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-/** Wrap a function in an ACT phase context with auto-span. */
-declare function traceAct<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-/** Wrap a function in an OBSERVE phase context with auto-span. */
-declare function traceObserve<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in a THINK phase context with auto-span.
+ *
+ * @example traceThink(async () => { ... })
+ * @example traceThink("analyze-data", async () => { ... })
+ */
+declare function traceThink<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in a DECIDE phase context with auto-span.
+ *
+ * @example traceDecide(async () => { ... })
+ * @example traceDecide("choose-action", async () => { ... })
+ */
+declare function traceDecide<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in an ACT phase context with auto-span.
+ *
+ * @example traceAct(async () => { ... })
+ * @example traceAct("execute-tool", async () => { ... })
+ */
+declare function traceAct<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in an OBSERVE phase context with auto-span.
+ *
+ * @example traceObserve(async () => { ... })
+ * @example traceObserve("check-result", async () => { ... })
+ */
+declare function traceObserve<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
 /**
  * Phase context — cognitive phase tracking (THINK/DECIDE/ACT/OBSERVE).
@@ -618,4 +663,69 @@ declare function registerSpan(span: Span, ttlMs?: number): void;
 declare function getSpanById(spanId: string): Span | undefined;
 declare function unregisterSpan(spanId: string): void;
 
-export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, reportError, score, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };
+/**
+ * tracedStream — Wrap an async iterable in a trace span.
+ *
+ * Creates a span that starts when iteration begins and ends when
+ * iteration completes (or errors). Chunks pass through UNCHANGED.
+ *
+ * This is the user-level streaming utility. For provider-level streaming
+ * enrichment (token counts, cost), see individual provider instrumentors.
+ *
+ * Usage:
+ *   const stream = await openai.chat.completions.create({ stream: true, ... });
+ *   for await (const chunk of tracedStream(stream, { name: 'llm-stream' })) {
+ *     process(chunk);
+ *   }
+ */
+
+interface TracedStreamOptions {
+    /** Span name */
+    name: string;
+    /** Span kind (default: INTERNAL) */
+    kind?: SpanKind;
+    /** Additional span attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Wrap an async iterable in a trace span.
+ *
+ * - Span starts on first iteration
+ * - chunk_count attribute set when iteration ends
+ * - On error: span records exception, error re-thrown to caller
+ * - On early break: span ended cleanly via finally
+ * - If SDK not initialized: chunks pass through without wrapping
+ */
+declare function tracedStream<T>(source: AsyncIterable<T>, options: TracedStreamOptions | string): AsyncGenerator<T, void, undefined>;
+
+/**
+ * Double-tracing prevention for framework integrations.
+ *
+ * When a framework integration (e.g., LlamaIndex handler) creates its own
+ * LLM span, the underlying provider proxy (e.g., patchOpenAI) would also
+ * create a duplicate span. This module provides suppression:
+ *
+ * - Framework integrations SET suppression via suppressProviderInstrumentation()
+ * - Provider proxies CHECK via isProviderInstrumentationSuppressed() and skip
+ *
+ * Scoped to AsyncLocalStorage — concurrent calls are independent.
+ */
+/**
+ * Run a callback with provider instrumentation suppressed.
+ *
+ * During this callback, all provider instrumentors (patchOpenAI, etc.) will
+ * skip span creation. The framework is responsible for creating the span.
+ *
+ * @param fn - The function to run with suppression active
+ * @returns The function's return value
+ */
+declare function suppressProviderInstrumentation<T>(fn: () => T): T;
+/**
+ * Check if provider instrumentation should be suppressed.
+ *
+ * Called by provider instrumentors as an early-exit guard. When true,
+ * the provider calls the original method directly without creating a span.
+ */
+declare function isProviderInstrumentationSuppressed(): boolean;
+
+export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, withAgent, withPhase, withSession };

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+export { RisicareCallbackHandler } from './frameworks/langchain.js';
+export { instrumentLangGraph } from './frameworks/langgraph.js';
+export { patchInstructor } from './frameworks/instructor.js';
+export { RisicareLlamaIndexHandler } from './frameworks/llamaindex.js';
+
 /**
  * SDK configuration with environment variable loading.
  *
@@ -83,18 +88,38 @@ declare enum SemanticPhase {
 declare enum AgentRole {
     ORCHESTRATOR = "orchestrator",
     WORKER = "worker",
-    REVIEWER = "reviewer",
+    SUPERVISOR = "supervisor",
+    SPECIALIST = "specialist",
+    ROUTER = "router",
+    AGGREGATOR = "aggregator",
+    BROADCASTER = "broadcaster",
+    CRITIC = "critic",
     PLANNER = "planner",
     EXECUTOR = "executor",
-    CRITIC = "critic",
+    RETRIEVER = "retriever",
+    VALIDATOR = "validator",
+    REVIEWER = "reviewer",
     CUSTOM = "custom"
 }
 declare enum MessageType {
-    REQUEST = "request",
+    TASK = "task",
+    RESULT = "result",
+    STATUS = "status",
+    ERROR = "error",
+    QUERY = "query",
     RESPONSE = "response",
+    BROADCAST = "broadcast",
+    DIRECT = "direct",
+    PROPOSAL = "proposal",
+    VOTE = "vote",
+    CONSENSUS = "consensus",
+    CONFLICT = "conflict",
+    HEARTBEAT = "heartbeat",
+    SHUTDOWN = "shutdown",
+    HANDOFF = "handoff",
+    REQUEST = "request",
     DELEGATE = "delegate",
-    COORDINATE = "coordinate",
-    BROADCAST = "broadcast"
+    COORDINATE = "coordinate"
 }
 interface SpanEvent {
     name: string;
@@ -477,14 +502,34 @@ declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: Se
  *   return await llm.invoke(`Decide action: ${analysis}`);
  * });
  */
-/** Wrap a function in a THINK phase context with auto-span. */
-declare function traceThink<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-/** Wrap a function in a DECIDE phase context with auto-span. */
-declare function traceDecide<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-/** Wrap a function in an ACT phase context with auto-span. */
-declare function traceAct<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-/** Wrap a function in an OBSERVE phase context with auto-span. */
-declare function traceObserve<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in a THINK phase context with auto-span.
+ *
+ * @example traceThink(async () => { ... })
+ * @example traceThink("analyze-data", async () => { ... })
+ */
+declare function traceThink<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in a DECIDE phase context with auto-span.
+ *
+ * @example traceDecide(async () => { ... })
+ * @example traceDecide("choose-action", async () => { ... })
+ */
+declare function traceDecide<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in an ACT phase context with auto-span.
+ *
+ * @example traceAct(async () => { ... })
+ * @example traceAct("execute-tool", async () => { ... })
+ */
+declare function traceAct<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function in an OBSERVE phase context with auto-span.
+ *
+ * @example traceObserve(async () => { ... })
+ * @example traceObserve("check-result", async () => { ... })
+ */
+declare function traceObserve<TArgs extends unknown[], TReturn>(fnOrName: ((...args: TArgs) => TReturn) | string, maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
 /**
  * Phase context — cognitive phase tracking (THINK/DECIDE/ACT/OBSERVE).
@@ -618,4 +663,69 @@ declare function registerSpan(span: Span, ttlMs?: number): void;
 declare function getSpanById(spanId: string): Span | undefined;
 declare function unregisterSpan(spanId: string): void;
 
-export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, reportError, score, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };
+/**
+ * tracedStream — Wrap an async iterable in a trace span.
+ *
+ * Creates a span that starts when iteration begins and ends when
+ * iteration completes (or errors). Chunks pass through UNCHANGED.
+ *
+ * This is the user-level streaming utility. For provider-level streaming
+ * enrichment (token counts, cost), see individual provider instrumentors.
+ *
+ * Usage:
+ *   const stream = await openai.chat.completions.create({ stream: true, ... });
+ *   for await (const chunk of tracedStream(stream, { name: 'llm-stream' })) {
+ *     process(chunk);
+ *   }
+ */
+
+interface TracedStreamOptions {
+    /** Span name */
+    name: string;
+    /** Span kind (default: INTERNAL) */
+    kind?: SpanKind;
+    /** Additional span attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Wrap an async iterable in a trace span.
+ *
+ * - Span starts on first iteration
+ * - chunk_count attribute set when iteration ends
+ * - On error: span records exception, error re-thrown to caller
+ * - On early break: span ended cleanly via finally
+ * - If SDK not initialized: chunks pass through without wrapping
+ */
+declare function tracedStream<T>(source: AsyncIterable<T>, options: TracedStreamOptions | string): AsyncGenerator<T, void, undefined>;
+
+/**
+ * Double-tracing prevention for framework integrations.
+ *
+ * When a framework integration (e.g., LlamaIndex handler) creates its own
+ * LLM span, the underlying provider proxy (e.g., patchOpenAI) would also
+ * create a duplicate span. This module provides suppression:
+ *
+ * - Framework integrations SET suppression via suppressProviderInstrumentation()
+ * - Provider proxies CHECK via isProviderInstrumentationSuppressed() and skip
+ *
+ * Scoped to AsyncLocalStorage — concurrent calls are independent.
+ */
+/**
+ * Run a callback with provider instrumentation suppressed.
+ *
+ * During this callback, all provider instrumentors (patchOpenAI, etc.) will
+ * skip span creation. The framework is responsible for creating the span.
+ *
+ * @param fn - The function to run with suppression active
+ * @returns The function's return value
+ */
+declare function suppressProviderInstrumentation<T>(fn: () => T): T;
+/**
+ * Check if provider instrumentation should be suppressed.
+ *
+ * Called by provider instrumentors as an early-exit guard. When true,
+ * the provider calls the original method directly without creating a span.
+ */
+declare function isProviderInstrumentationSuppressed(): boolean;
+
+export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, withAgent, withPhase, withSession };