risicare 0.1.4 → 0.2.0

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;
@@ -345,6 +370,34 @@ declare function getMetrics(): {
     queueCapacity: number;
     queueUtilization: number;
 };
+/**
+ * Report a caught exception to the self-healing pipeline.
+ *
+ * Creates an error span that triggers diagnosis and fix generation.
+ * This function never throws and is non-blocking.
+ *
+ * @param error - The caught exception (Error object or string)
+ * @param options - Optional attributes and context overrides
+ */
+declare function reportError(error: unknown, options?: {
+    name?: string;
+    attributes?: Record<string, unknown>;
+}): void;
+/**
+ * Record a custom evaluation score on a trace.
+ *
+ * Sends the score to the server in a fire-and-forget fashion.
+ * This function never throws and is non-blocking.
+ *
+ * @param traceId - The trace to score
+ * @param name - Score name (e.g., "accuracy", "user_satisfaction")
+ * @param value - Score value between 0.0 and 1.0 inclusive
+ * @param options - Optional span_id and comment
+ */
+declare function score(traceId: string, name: string, value: number, options?: {
+    spanId?: string;
+    comment?: string;
+}): void;
 
 /**
  * Agent context — identifies which agent is executing.
@@ -590,4 +643,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, 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;
@@ -345,6 +370,34 @@ declare function getMetrics(): {
     queueCapacity: number;
     queueUtilization: number;
 };
+/**
+ * Report a caught exception to the self-healing pipeline.
+ *
+ * Creates an error span that triggers diagnosis and fix generation.
+ * This function never throws and is non-blocking.
+ *
+ * @param error - The caught exception (Error object or string)
+ * @param options - Optional attributes and context overrides
+ */
+declare function reportError(error: unknown, options?: {
+    name?: string;
+    attributes?: Record<string, unknown>;
+}): void;
+/**
+ * Record a custom evaluation score on a trace.
+ *
+ * Sends the score to the server in a fire-and-forget fashion.
+ * This function never throws and is non-blocking.
+ *
+ * @param traceId - The trace to score
+ * @param name - Score name (e.g., "accuracy", "user_satisfaction")
+ * @param value - Score value between 0.0 and 1.0 inclusive
+ * @param options - Optional span_id and comment
+ */
+declare function score(traceId: string, name: string, value: number, options?: {
+    spanId?: string;
+    comment?: string;
+}): void;
 
 /**
  * Agent context — identifies which agent is executing.
@@ -590,4 +643,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, 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 };