risicare 0.1.4 → 0.2.0

package/dist/index.cjs

@@ -32,6 +32,8 @@ var src_exports = {};
 __export(src_exports, {
   AgentRole: () => AgentRole,
   MessageType: () => MessageType,
+  RisicareCallbackHandler: () => RisicareCallbackHandler,
+  RisicareLlamaIndexHandler: () => RisicareLlamaIndexHandler,
   SemanticPhase: () => SemanticPhase,
   SpanKind: () => SpanKind,
   SpanStatus: () => SpanStatus,
@@ -56,10 +58,16 @@ __export(src_exports, {
   getTracer: () => getTracer2,
   init: () => init,
   injectTraceContext: () => injectTraceContext,
+  instrumentLangGraph: () => instrumentLangGraph,
   isEnabled: () => isEnabled,
+  isProviderInstrumentationSuppressed: () => isProviderInstrumentationSuppressed,
+  patchInstructor: () => patchInstructor,
   registerSpan: () => registerSpan,
+  reportError: () => reportError,
+  score: () => score,
   session: () => session,
   shutdown: () => shutdown,
+  suppressProviderInstrumentation: () => suppressProviderInstrumentation,
   traceAct: () => traceAct,
   traceCoordinate: () => traceCoordinate,
   traceDecide: () => traceDecide,
@@ -67,6 +75,7 @@ __export(src_exports, {
   traceMessage: () => traceMessage,
   traceObserve: () => traceObserve,
   traceThink: () => traceThink,
+  tracedStream: () => tracedStream,
   unregisterSpan: () => unregisterSpan,
   withAgent: () => withAgent,
   withPhase: () => withPhase,
@@ -189,19 +198,39 @@ var SemanticPhase = /* @__PURE__ */ ((SemanticPhase2) => {
 var AgentRole = /* @__PURE__ */ ((AgentRole2) => {
   AgentRole2["ORCHESTRATOR"] = "orchestrator";
   AgentRole2["WORKER"] = "worker";
-  AgentRole2["REVIEWER"] = "reviewer";
+  AgentRole2["SUPERVISOR"] = "supervisor";
+  AgentRole2["SPECIALIST"] = "specialist";
+  AgentRole2["ROUTER"] = "router";
+  AgentRole2["AGGREGATOR"] = "aggregator";
+  AgentRole2["BROADCASTER"] = "broadcaster";
+  AgentRole2["CRITIC"] = "critic";
   AgentRole2["PLANNER"] = "planner";
   AgentRole2["EXECUTOR"] = "executor";
-  AgentRole2["CRITIC"] = "critic";
+  AgentRole2["RETRIEVER"] = "retriever";
+  AgentRole2["VALIDATOR"] = "validator";
+  AgentRole2["REVIEWER"] = "reviewer";
   AgentRole2["CUSTOM"] = "custom";
   return AgentRole2;
 })(AgentRole || {});
 var MessageType = /* @__PURE__ */ ((MessageType2) => {
-  MessageType2["REQUEST"] = "request";
+  MessageType2["TASK"] = "task";
+  MessageType2["RESULT"] = "result";
+  MessageType2["STATUS"] = "status";
+  MessageType2["ERROR"] = "error";
+  MessageType2["QUERY"] = "query";
   MessageType2["RESPONSE"] = "response";
+  MessageType2["BROADCAST"] = "broadcast";
+  MessageType2["DIRECT"] = "direct";
+  MessageType2["PROPOSAL"] = "proposal";
+  MessageType2["VOTE"] = "vote";
+  MessageType2["CONSENSUS"] = "consensus";
+  MessageType2["CONFLICT"] = "conflict";
+  MessageType2["HEARTBEAT"] = "heartbeat";
+  MessageType2["SHUTDOWN"] = "shutdown";
+  MessageType2["HANDOFF"] = "handoff";
+  MessageType2["REQUEST"] = "request";
   MessageType2["DELEGATE"] = "delegate";
   MessageType2["COORDINATE"] = "coordinate";
-  MessageType2["BROADCAST"] = "broadcast";
   return MessageType2;
 })(MessageType || {});
 
@@ -1119,10 +1148,66 @@ function getMetrics() {
     queueUtilization: 0
   };
 }
+function reportError(error, options) {
+  try {
+    const tracer = getTracer2();
+    if (!tracer) return;
+    const err = error instanceof Error ? error : new Error(String(error));
+    const spanName = options?.name ?? `error:${err.constructor.name}`;
+    tracer.startSpan({ name: spanName, kind: "internal" /* INTERNAL */ }, (span) => {
+      span.setStatus("error" /* ERROR */, err.message);
+      span.setAttribute("error", true);
+      span.setAttribute("error.type", err.constructor.name);
+      span.setAttribute("error.message", err.message.slice(0, 2e3));
+      if (err.stack) span.setAttribute("error.stack", err.stack.slice(0, 4e3));
+      span.setAttribute("risicare.reported_error", true);
+      if (options?.attributes) {
+        for (const [k, v] of Object.entries(options.attributes)) {
+          span.setAttribute(k, v);
+        }
+      }
+    });
+  } catch {
+    debug("reportError failed");
+  }
+}
+function score(traceId, name, value, options) {
+  try {
+    if (typeof value !== "number" || value < 0 || value > 1) {
+      debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);
+      return;
+    }
+    if (!traceId || !name) {
+      debug("score: traceId and name are required");
+      return;
+    }
+    const client = getClient();
+    if (!client?.enabled || !client.config.apiKey) return;
+    const endpoint = client.config.endpoint.replace(/\/$/, "");
+    const url = `${endpoint}/api/v1/scores`;
+    const body = JSON.stringify({
+      trace_id: traceId,
+      name,
+      score: value,
+      source: "sdk",
+      ...options?.spanId && { span_id: options.spanId },
+      ...options?.comment && { comment: options.comment }
+    });
+    fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${client.config.apiKey}`
+      },
+      body
+    }).catch((err) => debug(`score: send failed: ${err}`));
+  } catch {
+    debug("score failed");
+  }
+}
 
 // src/context/agent.ts
 function withAgent(options, fn) {
-  if (!isEnabled()) return fn();
   const parent = getCurrentAgent();
   const agentName = options.name ?? "agent";
   const agent2 = {
@@ -1155,7 +1240,6 @@ function agent(options, fn) {
 
 // src/context/session.ts
 function withSession(options, fn) {
-  if (!isEnabled()) return fn();
   const session2 = {
     sessionId: options.sessionId,
     userId: options.userId,
@@ -1176,7 +1260,6 @@ function session(optionsOrResolver, fn) {
 
 // src/context/phase.ts
 function withPhase(phase, fn) {
-  if (!isEnabled()) return fn();
   return runWithContext({ phase }, fn);
 }
 
@@ -1383,10 +1466,381 @@ function maybeCleanup() {
     }
   }
 }
+
+// src/streaming.ts
+async function* tracedStream(source, options) {
+  const opts = typeof options === "string" ? { name: options } : options;
+  const tracer = getTracer2();
+  if (!tracer || !tracer.enabled) {
+    yield* source;
+    return;
+  }
+  const span = tracer.createSpan({
+    name: opts.name,
+    kind: opts.kind ?? "internal" /* INTERNAL */,
+    attributes: opts.attributes
+  });
+  let chunkCount = 0;
+  try {
+    for await (const chunk of source) {
+      chunkCount++;
+      yield chunk;
+    }
+    span.setAttribute("stream.chunk_count", chunkCount);
+    span.setAttribute("stream.completed", true);
+  } catch (error) {
+    span.setAttribute("stream.chunk_count", chunkCount);
+    span.setAttribute("stream.completed", false);
+    span.recordException(error instanceof Error ? error : String(error));
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+
+// src/frameworks/langchain.ts
+var RisicareCallbackHandler = class {
+  name = "RisicareCallbackHandler";
+  _spans = /* @__PURE__ */ new Map();
+  // ── Chain lifecycle ────────────────────────────────────────────────────────
+  handleChainStart(chain, _inputs, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: chain.name || chain._type || "chain",
+      kind: "internal" /* INTERNAL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId,
+        ...parentRunId ? { "langchain.parent_run_id": parentRunId } : {},
+        ...chain._type ? { "langchain.chain_type": chain._type } : {}
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleChainEnd(_outputs, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  handleChainError(error, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.recordException(error);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  // ── LLM lifecycle ─────────────────────────────────────────────────────────
+  handleLLMStart(llm, _prompts, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: llm.name || llm._type || "llm",
+      kind: "llm_call" /* LLM_CALL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId,
+        "gen_ai.system": "langchain",
+        "gen_ai.prompt.count": _prompts.length
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleLLMEnd(output, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    const usage = output.llmOutput?.tokenUsage;
+    if (usage) {
+      entry.span.setLlmFields({
+        promptTokens: usage.promptTokens ?? usage.prompt_tokens,
+        completionTokens: usage.completionTokens ?? usage.completion_tokens,
+        totalTokens: usage.totalTokens ?? usage.total_tokens
+      });
+    }
+    const model = output.llmOutput?.model ?? output.llmOutput?.modelName;
+    if (model) {
+      entry.span.setLlmFields({ model });
+    }
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  handleLLMError(error, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.recordException(error);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  // ── Tool lifecycle ────────────────────────────────────────────────────────
+  handleToolStart(tool, input, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: tool.name || "tool",
+      kind: "tool_call" /* TOOL_CALL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId,
+        "tool.name": tool.name || "unknown",
+        "tool.input_length": input?.length ?? 0
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleToolEnd(output, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.setAttribute("tool.output_length", output?.length ?? 0);
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  handleToolError(error, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.recordException(error);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  // ── Retriever lifecycle ───────────────────────────────────────────────────
+  handleRetrieverStart(retriever, _query, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: retriever.name || "retriever",
+      kind: "retrieval" /* RETRIEVAL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleRetrieverEnd(documents, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.setAttribute(
+      "retriever.document_count",
+      documents?.length ?? 0
+    );
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+};
+
+// src/frameworks/langgraph.ts
+function instrumentLangGraph(graph) {
+  return new Proxy(graph, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if ((prop === "invoke" || prop === "stream") && typeof value === "function") {
+        return function patchedMethod(...args) {
+          const tracer = getTracer2();
+          if (!tracer?.enabled) return value.apply(this, args);
+          return tracer.startSpan(
+            {
+              name: `langgraph.${String(prop)}`,
+              kind: "agent" /* AGENT */,
+              attributes: { framework: "langgraph" }
+            },
+            (_span) => {
+              const config = args[1] ?? {};
+              const callbacks = config.callbacks ?? [];
+              callbacks.push(new RisicareCallbackHandler());
+              args[1] = { ...config, callbacks };
+              const result = value.apply(this, args);
+              if (result && typeof result.then === "function") {
+                return result.then((r) => r);
+              }
+              return result;
+            }
+          );
+        };
+      }
+      return value;
+    }
+  });
+}
+
+// src/frameworks/instructor.ts
+function patchInstructor(client) {
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (prop === "create" && typeof value === "function") {
+        return function patchedCreate(...args) {
+          const tracer = getTracer2();
+          if (!tracer?.enabled) {
+            debug(
+              "Tracer not initialized \u2014 call init() before using patchInstructor()"
+            );
+            return value.apply(this, args);
+          }
+          const params = args[0] ?? {};
+          const responseModel = params.response_model ?? params.responseModel;
+          let modelName = "unknown";
+          if (responseModel && typeof responseModel === "function") {
+            modelName = responseModel.name || "unknown";
+          } else if (responseModel && typeof responseModel === "object") {
+            modelName = responseModel.name ?? responseModel.description ?? "schema";
+          } else if (typeof responseModel === "string") {
+            modelName = responseModel;
+          }
+          return tracer.startSpan(
+            {
+              name: "instructor.create",
+              kind: "llm_call" /* LLM_CALL */,
+              attributes: {
+                framework: "instructor",
+                "framework.span_kind": "extraction",
+                "instructor.response_model": modelName,
+                ...params.max_retries != null ? { "instructor.max_retries": params.max_retries } : {},
+                ...params.model != null ? { "gen_ai.request.model": params.model } : {}
+              }
+            },
+            (_span) => {
+              const result = value.apply(this, args);
+              if (result && typeof result.then === "function") {
+                return result.then((r) => r);
+              }
+              return result;
+            }
+          );
+        };
+      }
+      return value;
+    }
+  });
+}
+
+// src/context/dedup.ts
+function suppressProviderInstrumentation(fn) {
+  return runWithContext({ _suppressProviderInstrumentation: true }, fn);
+}
+function isProviderInstrumentationSuppressed() {
+  return getContext()._suppressProviderInstrumentation === true;
+}
+
+// src/frameworks/llamaindex.ts
+var RisicareLlamaIndexHandler = class {
+  _spans = /* @__PURE__ */ new Map();
+  /**
+   * Handle a LlamaIndex lifecycle event.
+   *
+   * Events follow the convention:
+   *   - `*.start` / `*.begin` -- component starts
+   *   - `*.end` / `*.complete` -- component finishes
+   *   - `*.error` -- component failed
+   */
+  onEvent(event) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    if (event.type.endsWith(".start") || event.type.endsWith(".begin")) {
+      this._handleStart(event);
+    } else if (event.type.endsWith(".end") || event.type.endsWith(".complete")) {
+      this._handleEnd(event);
+    } else if (event.type.endsWith(".error")) {
+      this._handleError(event);
+    }
+  }
+  /**
+   * Run a function with provider instrumentation suppressed.
+   *
+   * LlamaIndex handler creates its own LLM spans, so provider spans
+   * (patchOpenAI, patchAnthropic, etc.) should be suppressed to avoid
+   * double-tracing.
+   */
+  withSuppression(fn) {
+    return suppressProviderInstrumentation(fn);
+  }
+  // ── Internal event handlers ───────────────────────────────────────────────
+  _handleStart(event) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const componentKind = this._classifyComponent(event.type);
+    const parentEntry = event.parentId ? this._spans.get(event.parentId) : void 0;
+    const spanKind = componentKind === "llm" ? "llm_call" /* LLM_CALL */ : componentKind === "retrieval" ? "retrieval" /* RETRIEVAL */ : componentKind === "embedding" ? "llm_call" /* LLM_CALL */ : "internal" /* INTERNAL */;
+    const span = tracer.createSpan({
+      name: event.type.replace(/\.(start|begin)$/, ""),
+      kind: spanKind,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        framework: "llamaindex",
+        "framework.span_kind": componentKind,
+        ...event.data?.model ? { "gen_ai.request.model": event.data.model } : {}
+      }
+    });
+    this._spans.set(event.id, { span, startTime: Date.now(), componentKind });
+  }
+  _handleEnd(event) {
+    const entry = this._spans.get(event.id);
+    if (!entry) return;
+    entry.span.setAttribute(
+      "gen_ai.latency_ms",
+      Date.now() - entry.startTime
+    );
+    const usage = event.data?.usage;
+    if (usage) {
+      entry.span.setLlmFields({
+        promptTokens: usage.promptTokens ?? usage.prompt_tokens,
+        completionTokens: usage.completionTokens ?? usage.completion_tokens
+      });
+    }
+    if (event.data?.documentCount != null) {
+      entry.span.setAttribute(
+        "retriever.document_count",
+        event.data.documentCount
+      );
+    }
+    entry.span.end();
+    this._spans.delete(event.id);
+  }
+  _handleError(event) {
+    const entry = this._spans.get(event.id);
+    if (!entry) return;
+    const error = event.data?.error;
+    entry.span.recordException(
+      error instanceof Error ? error : String(error ?? "Unknown error")
+    );
+    entry.span.end();
+    this._spans.delete(event.id);
+  }
+  /**
+   * Classify a LlamaIndex event type into a component kind.
+   */
+  _classifyComponent(eventType) {
+    const lower = eventType.toLowerCase();
+    if (lower.includes("llm") || lower.includes("chat")) return "llm";
+    if (lower.includes("embed")) return "embedding";
+    if (lower.includes("retriev") || lower.includes("vector")) return "retrieval";
+    if (lower.includes("synth") || lower.includes("response")) return "synthesis";
+    if (lower.includes("query")) return "query";
+    return "component";
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentRole,
   MessageType,
+  RisicareCallbackHandler,
+  RisicareLlamaIndexHandler,
   SemanticPhase,
   SpanKind,
   SpanStatus,
@@ -1411,10 +1865,16 @@ function maybeCleanup() {
   getTracer,
   init,
   injectTraceContext,
+  instrumentLangGraph,
   isEnabled,
+  isProviderInstrumentationSuppressed,
+  patchInstructor,
   registerSpan,
+  reportError,
+  score,
   session,
   shutdown,
+  suppressProviderInstrumentation,
   traceAct,
   traceCoordinate,
   traceDecide,
@@ -1422,6 +1882,7 @@ function maybeCleanup() {
   traceMessage,
   traceObserve,
   traceThink,
+  tracedStream,
   unregisterSpan,
   withAgent,
   withPhase,