risicare 0.1.5 → 0.2.1

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,12 +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,
@@ -69,6 +75,7 @@ __export(src_exports, {
   traceMessage: () => traceMessage,
   traceObserve: () => traceObserve,
   traceThink: () => traceThink,
+  tracedStream: () => tracedStream,
   unregisterSpan: () => unregisterSpan,
   withAgent: () => withAgent,
   withPhase: () => withPhase,
@@ -191,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 || {});
 
@@ -1237,28 +1264,36 @@ function withPhase(phase, fn) {
 }
 
 // src/decorators/phase.ts
-function phaseWrapper(phase, kind, fn) {
+function phaseWrapper(phase, kind, name, fn) {
   return (...args) => {
     const tracer = getTracer2();
     if (!tracer) {
       return fn(...args);
     }
     return withPhase(phase, () => {
-      return tracer.startSpan({ name: `phase:${phase}`, kind }, () => fn(...args));
+      return tracer.startSpan({ name, kind }, () => fn(...args));
     });
   };
 }
-function traceThink(fn) {
-  return phaseWrapper("think" /* THINK */, "think" /* THINK */, fn);
+function traceThink(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:think`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("think" /* THINK */, "think" /* THINK */, name, fn);
 }
-function traceDecide(fn) {
-  return phaseWrapper("decide" /* DECIDE */, "decide" /* DECIDE */, fn);
+function traceDecide(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:decide`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("decide" /* DECIDE */, "decide" /* DECIDE */, name, fn);
 }
-function traceAct(fn) {
-  return phaseWrapper("act" /* ACT */, "tool_call" /* TOOL_CALL */, fn);
+function traceAct(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:act`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("act" /* ACT */, "tool_call" /* TOOL_CALL */, name, fn);
 }
-function traceObserve(fn) {
-  return phaseWrapper("observe" /* OBSERVE */, "observe" /* OBSERVE */, fn);
+function traceObserve(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:observe`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("observe" /* OBSERVE */, "observe" /* OBSERVE */, name, fn);
 }
 
 // src/decorators/multi-agent.ts
@@ -1439,10 +1474,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,
@@ -1467,12 +1873,16 @@ function maybeCleanup() {
   getTracer,
   init,
   injectTraceContext,
+  instrumentLangGraph,
   isEnabled,
+  isProviderInstrumentationSuppressed,
+  patchInstructor,
   registerSpan,
   reportError,
   score,
   session,
   shutdown,
+  suppressProviderInstrumentation,
   traceAct,
   traceCoordinate,
   traceDecide,
@@ -1480,6 +1890,7 @@ function maybeCleanup() {
   traceMessage,
   traceObserve,
   traceThink,
+  tracedStream,
   unregisterSpan,
   withAgent,
   withPhase,