@llmops/sdk 0.5.4 → 0.6.0

package/dist/agents-exporter-BorGCb93.mjs

@@ -0,0 +1,207 @@
+//#region src/telemetry/agents-exporter.ts
+function normalizeTraceId(id) {
+	return id.startsWith("trace_") ? id.slice(6) : id;
+}
+function normalizeSpanId(id) {
+	return id.startsWith("span_") ? id.slice(5) : id;
+}
+function isoToNano(iso) {
+	if (!iso) return "0";
+	const ms = new Date(iso).getTime();
+	if (isNaN(ms)) return "0";
+	return (BigInt(ms) * BigInt(1e6)).toString();
+}
+function toOtlpValue(value) {
+	if (typeof value === "string") return { stringValue: value };
+	if (typeof value === "number") return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+	if (typeof value === "boolean") return { boolValue: value };
+	if (Array.isArray(value)) return { arrayValue: { values: value.map((v) => toOtlpValue(v)) } };
+	if (typeof value === "object" && value !== null) try {
+		return { stringValue: JSON.stringify(value) };
+	} catch {
+		return { stringValue: String(value) };
+	}
+	return { stringValue: String(value) };
+}
+function kv(key, value) {
+	return {
+		key,
+		value: toOtlpValue(value)
+	};
+}
+/**
+* Derive a human-readable span name from the span data type.
+*/
+function deriveSpanName(data) {
+	switch (data.type) {
+		case "agent": return `Agent: ${data.name}`;
+		case "function": return `Tool: ${data.name}`;
+		case "generation": return data.model ? `Generation: ${data.model}` : "Generation";
+		case "response": return "Response";
+		case "handoff": return `Handoff: ${data.from_agent ?? "?"} → ${data.to_agent ?? "?"}`;
+		case "guardrail": return `Guardrail: ${data.name}`;
+		case "custom": return `Custom: ${data.name}`;
+		case "transcription": return data.model ? `Transcription: ${data.model}` : "Transcription";
+		case "speech": return data.model ? `Speech: ${data.model}` : "Speech";
+		case "speech_group": return "Speech Group";
+		case "mcp_tools": return `MCP Tools: ${data.server ?? "unknown"}`;
+		default: return "Unknown Span";
+	}
+}
+/**
+* Convert span data fields to OTLP attributes that our UI's getSpanType() recognizes.
+*/
+function convertSpanDataToAttributes(data, error) {
+	const attrs = [kv("openai.agents.span_type", data.type)];
+	switch (data.type) {
+		case "generation":
+			attrs.push(kv("gen_ai.operation.name", "chat"));
+			if (data.model) {
+				attrs.push(kv("gen_ai.request.model", data.model));
+				attrs.push(kv("gen_ai.system", "openai"));
+			}
+			if (data.usage?.input_tokens != null) attrs.push(kv("gen_ai.usage.input_tokens", data.usage.input_tokens));
+			if (data.usage?.output_tokens != null) attrs.push(kv("gen_ai.usage.output_tokens", data.usage.output_tokens));
+			if (data.input) attrs.push(kv("ai.prompt.messages", JSON.stringify(data.input)));
+			if (data.output) attrs.push(kv("gen_ai.completion", JSON.stringify(data.output)));
+			if (data.model_config) attrs.push(kv("gen_ai.request.model_config", JSON.stringify(data.model_config)));
+			break;
+		case "agent":
+			attrs.push(kv("openai.agents.agent.name", data.name));
+			if (data.tools?.length) attrs.push(kv("openai.agents.agent.tools", JSON.stringify(data.tools)));
+			if (data.handoffs?.length) attrs.push(kv("openai.agents.agent.handoffs", JSON.stringify(data.handoffs)));
+			if (data.output_type) attrs.push(kv("openai.agents.agent.output_type", data.output_type));
+			break;
+		case "function":
+			attrs.push(kv("gen_ai.tool.name", data.name));
+			if (data.input) attrs.push(kv("ai.prompt.messages", data.input));
+			if (data.output) attrs.push(kv("ai.response.text", data.output));
+			if (data.mcp_data) attrs.push(kv("openai.agents.function.mcp_data", data.mcp_data));
+			break;
+		case "handoff":
+			if (data.from_agent) attrs.push(kv("openai.agents.handoff.from_agent", data.from_agent));
+			if (data.to_agent) attrs.push(kv("openai.agents.handoff.to_agent", data.to_agent));
+			break;
+		case "guardrail":
+			attrs.push(kv("llmops.guardrail.action", data.triggered ? "triggered" : "passed"));
+			attrs.push(kv("openai.agents.guardrail.name", data.name));
+			break;
+		case "response":
+			attrs.push(kv("gen_ai.operation.name", "chat"));
+			if (data.response_id) attrs.push(kv("openai.agents.response.id", data.response_id));
+			break;
+		case "custom":
+			attrs.push(kv("openai.agents.custom.name", data.name));
+			attrs.push(kv("openai.agents.custom.data", JSON.stringify(data.data)));
+			break;
+		case "transcription":
+			attrs.push(kv("gen_ai.operation.name", "transcription"));
+			if (data.model) attrs.push(kv("gen_ai.request.model", data.model));
+			if (data.output) attrs.push(kv("ai.response.text", data.output));
+			break;
+		case "speech":
+			attrs.push(kv("gen_ai.operation.name", "speech"));
+			if (data.model) attrs.push(kv("gen_ai.request.model", data.model));
+			if (data.input) attrs.push(kv("ai.prompt.messages", data.input));
+			break;
+		case "speech_group":
+			if (data.input) attrs.push(kv("openai.agents.speech_group.input", data.input));
+			break;
+		case "mcp_tools":
+			attrs.push(kv("gen_ai.tool.name", `mcp:${data.server ?? "unknown"}`));
+			if (data.result) attrs.push(kv("openai.agents.mcp.tools", JSON.stringify(data.result)));
+			break;
+	}
+	if (error) {
+		attrs.push(kv("error.message", error.message));
+		if (error.data) attrs.push(kv("error.data", JSON.stringify(error.data)));
+	}
+	return attrs;
+}
+function buildResourceSpans(traceId, trace, spans) {
+	const resourceAttrs = [kv("service.name", "@openai/agents")];
+	if (trace) {
+		resourceAttrs.push(kv("openai.agents.trace.name", trace.name));
+		if (trace.groupId) resourceAttrs.push(kv("openai.agents.trace.group_id", trace.groupId));
+		if (trace.metadata && Object.keys(trace.metadata).length > 0) resourceAttrs.push(kv("openai.agents.trace.metadata", JSON.stringify(trace.metadata)));
+	}
+	const normalizedTraceId = normalizeTraceId(traceId);
+	return {
+		resource: { attributes: resourceAttrs },
+		scopeSpans: [{
+			scope: { name: "@llmops/agents-exporter" },
+			spans: spans.map((span) => {
+				const isError = !!span.error;
+				return {
+					traceId: normalizedTraceId,
+					spanId: normalizeSpanId(span.spanId),
+					parentSpanId: span.parentId ? normalizeSpanId(span.parentId) : void 0,
+					name: deriveSpanName(span.spanData),
+					kind: 1,
+					startTimeUnixNano: isoToNano(span.startedAt),
+					endTimeUnixNano: isoToNano(span.endedAt),
+					attributes: convertSpanDataToAttributes(span.spanData, span.error),
+					events: [],
+					status: isError ? {
+						code: 2,
+						message: span.error.message
+					} : { code: 1 }
+				};
+			})
+		}]
+	};
+}
+/**
+* Create a TracingExporter for @openai/agents that sends traces to LLMOps.
+*
+* Usage:
+* ```typescript
+* import { createLLMOpsAgentsExporter } from '@llmops/sdk';
+* import { setTraceProcessors, BatchTraceProcessor } from '@openai/agents';
+*
+* setTraceProcessors([
+*   new BatchTraceProcessor(createLLMOpsAgentsExporter({
+*     baseURL: 'http://localhost:5177',
+*     apiKey: process.env.LLMOPS_API_KEY!,
+*   }))
+* ]);
+* ```
+*/
+function createLLMOpsAgentsExporter(config) {
+	const url = `${config.baseURL.replace(/\/$/, "")}/api/otlp/v1/traces`;
+	const fetchFn = config.fetch ?? globalThis.fetch;
+	return { async export(items, signal) {
+		const traces = [];
+		const spans = [];
+		for (const item of items) if (item.type === "trace") traces.push(item);
+		else spans.push(item);
+		if (spans.length === 0) return;
+		const traceMap = /* @__PURE__ */ new Map();
+		for (const t of traces) traceMap.set(t.traceId, t);
+		const spansByTrace = /* @__PURE__ */ new Map();
+		for (const s of spans) {
+			const group = spansByTrace.get(s.traceId) ?? [];
+			group.push(s);
+			spansByTrace.set(s.traceId, group);
+		}
+		const resourceSpans = [];
+		for (const [traceId, traceSpans] of spansByTrace) {
+			const trace = traceMap.get(traceId);
+			resourceSpans.push(buildResourceSpans(traceId, trace, traceSpans));
+		}
+		if (resourceSpans.length === 0) return;
+		await fetchFn(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${config.apiKey}`,
+				...config.headers ?? {}
+			},
+			body: JSON.stringify({ resourceSpans }),
+			signal
+		});
+	} };
+}
+
+//#endregion
+export { createLLMOpsAgentsExporter as t };

package/dist/agents-exporter-Ct3l12qS.cjs

@@ -0,0 +1,213 @@
+
+//#region src/telemetry/agents-exporter.ts
+function normalizeTraceId(id) {
+	return id.startsWith("trace_") ? id.slice(6) : id;
+}
+function normalizeSpanId(id) {
+	return id.startsWith("span_") ? id.slice(5) : id;
+}
+function isoToNano(iso) {
+	if (!iso) return "0";
+	const ms = new Date(iso).getTime();
+	if (isNaN(ms)) return "0";
+	return (BigInt(ms) * BigInt(1e6)).toString();
+}
+function toOtlpValue(value) {
+	if (typeof value === "string") return { stringValue: value };
+	if (typeof value === "number") return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+	if (typeof value === "boolean") return { boolValue: value };
+	if (Array.isArray(value)) return { arrayValue: { values: value.map((v) => toOtlpValue(v)) } };
+	if (typeof value === "object" && value !== null) try {
+		return { stringValue: JSON.stringify(value) };
+	} catch {
+		return { stringValue: String(value) };
+	}
+	return { stringValue: String(value) };
+}
+function kv(key, value) {
+	return {
+		key,
+		value: toOtlpValue(value)
+	};
+}
+/**
+* Derive a human-readable span name from the span data type.
+*/
+function deriveSpanName(data) {
+	switch (data.type) {
+		case "agent": return `Agent: ${data.name}`;
+		case "function": return `Tool: ${data.name}`;
+		case "generation": return data.model ? `Generation: ${data.model}` : "Generation";
+		case "response": return "Response";
+		case "handoff": return `Handoff: ${data.from_agent ?? "?"} → ${data.to_agent ?? "?"}`;
+		case "guardrail": return `Guardrail: ${data.name}`;
+		case "custom": return `Custom: ${data.name}`;
+		case "transcription": return data.model ? `Transcription: ${data.model}` : "Transcription";
+		case "speech": return data.model ? `Speech: ${data.model}` : "Speech";
+		case "speech_group": return "Speech Group";
+		case "mcp_tools": return `MCP Tools: ${data.server ?? "unknown"}`;
+		default: return "Unknown Span";
+	}
+}
+/**
+* Convert span data fields to OTLP attributes that our UI's getSpanType() recognizes.
+*/
+function convertSpanDataToAttributes(data, error) {
+	const attrs = [kv("openai.agents.span_type", data.type)];
+	switch (data.type) {
+		case "generation":
+			attrs.push(kv("gen_ai.operation.name", "chat"));
+			if (data.model) {
+				attrs.push(kv("gen_ai.request.model", data.model));
+				attrs.push(kv("gen_ai.system", "openai"));
+			}
+			if (data.usage?.input_tokens != null) attrs.push(kv("gen_ai.usage.input_tokens", data.usage.input_tokens));
+			if (data.usage?.output_tokens != null) attrs.push(kv("gen_ai.usage.output_tokens", data.usage.output_tokens));
+			if (data.input) attrs.push(kv("ai.prompt.messages", JSON.stringify(data.input)));
+			if (data.output) attrs.push(kv("gen_ai.completion", JSON.stringify(data.output)));
+			if (data.model_config) attrs.push(kv("gen_ai.request.model_config", JSON.stringify(data.model_config)));
+			break;
+		case "agent":
+			attrs.push(kv("openai.agents.agent.name", data.name));
+			if (data.tools?.length) attrs.push(kv("openai.agents.agent.tools", JSON.stringify(data.tools)));
+			if (data.handoffs?.length) attrs.push(kv("openai.agents.agent.handoffs", JSON.stringify(data.handoffs)));
+			if (data.output_type) attrs.push(kv("openai.agents.agent.output_type", data.output_type));
+			break;
+		case "function":
+			attrs.push(kv("gen_ai.tool.name", data.name));
+			if (data.input) attrs.push(kv("ai.prompt.messages", data.input));
+			if (data.output) attrs.push(kv("ai.response.text", data.output));
+			if (data.mcp_data) attrs.push(kv("openai.agents.function.mcp_data", data.mcp_data));
+			break;
+		case "handoff":
+			if (data.from_agent) attrs.push(kv("openai.agents.handoff.from_agent", data.from_agent));
+			if (data.to_agent) attrs.push(kv("openai.agents.handoff.to_agent", data.to_agent));
+			break;
+		case "guardrail":
+			attrs.push(kv("llmops.guardrail.action", data.triggered ? "triggered" : "passed"));
+			attrs.push(kv("openai.agents.guardrail.name", data.name));
+			break;
+		case "response":
+			attrs.push(kv("gen_ai.operation.name", "chat"));
+			if (data.response_id) attrs.push(kv("openai.agents.response.id", data.response_id));
+			break;
+		case "custom":
+			attrs.push(kv("openai.agents.custom.name", data.name));
+			attrs.push(kv("openai.agents.custom.data", JSON.stringify(data.data)));
+			break;
+		case "transcription":
+			attrs.push(kv("gen_ai.operation.name", "transcription"));
+			if (data.model) attrs.push(kv("gen_ai.request.model", data.model));
+			if (data.output) attrs.push(kv("ai.response.text", data.output));
+			break;
+		case "speech":
+			attrs.push(kv("gen_ai.operation.name", "speech"));
+			if (data.model) attrs.push(kv("gen_ai.request.model", data.model));
+			if (data.input) attrs.push(kv("ai.prompt.messages", data.input));
+			break;
+		case "speech_group":
+			if (data.input) attrs.push(kv("openai.agents.speech_group.input", data.input));
+			break;
+		case "mcp_tools":
+			attrs.push(kv("gen_ai.tool.name", `mcp:${data.server ?? "unknown"}`));
+			if (data.result) attrs.push(kv("openai.agents.mcp.tools", JSON.stringify(data.result)));
+			break;
+	}
+	if (error) {
+		attrs.push(kv("error.message", error.message));
+		if (error.data) attrs.push(kv("error.data", JSON.stringify(error.data)));
+	}
+	return attrs;
+}
+function buildResourceSpans(traceId, trace, spans) {
+	const resourceAttrs = [kv("service.name", "@openai/agents")];
+	if (trace) {
+		resourceAttrs.push(kv("openai.agents.trace.name", trace.name));
+		if (trace.groupId) resourceAttrs.push(kv("openai.agents.trace.group_id", trace.groupId));
+		if (trace.metadata && Object.keys(trace.metadata).length > 0) resourceAttrs.push(kv("openai.agents.trace.metadata", JSON.stringify(trace.metadata)));
+	}
+	const normalizedTraceId = normalizeTraceId(traceId);
+	return {
+		resource: { attributes: resourceAttrs },
+		scopeSpans: [{
+			scope: { name: "@llmops/agents-exporter" },
+			spans: spans.map((span) => {
+				const isError = !!span.error;
+				return {
+					traceId: normalizedTraceId,
+					spanId: normalizeSpanId(span.spanId),
+					parentSpanId: span.parentId ? normalizeSpanId(span.parentId) : void 0,
+					name: deriveSpanName(span.spanData),
+					kind: 1,
+					startTimeUnixNano: isoToNano(span.startedAt),
+					endTimeUnixNano: isoToNano(span.endedAt),
+					attributes: convertSpanDataToAttributes(span.spanData, span.error),
+					events: [],
+					status: isError ? {
+						code: 2,
+						message: span.error.message
+					} : { code: 1 }
+				};
+			})
+		}]
+	};
+}
+/**
+* Create a TracingExporter for @openai/agents that sends traces to LLMOps.
+*
+* Usage:
+* ```typescript
+* import { createLLMOpsAgentsExporter } from '@llmops/sdk';
+* import { setTraceProcessors, BatchTraceProcessor } from '@openai/agents';
+*
+* setTraceProcessors([
+*   new BatchTraceProcessor(createLLMOpsAgentsExporter({
+*     baseURL: 'http://localhost:5177',
+*     apiKey: process.env.LLMOPS_API_KEY!,
+*   }))
+* ]);
+* ```
+*/
+function createLLMOpsAgentsExporter(config) {
+	const url = `${config.baseURL.replace(/\/$/, "")}/api/otlp/v1/traces`;
+	const fetchFn = config.fetch ?? globalThis.fetch;
+	return { async export(items, signal) {
+		const traces = [];
+		const spans = [];
+		for (const item of items) if (item.type === "trace") traces.push(item);
+		else spans.push(item);
+		if (spans.length === 0) return;
+		const traceMap = /* @__PURE__ */ new Map();
+		for (const t of traces) traceMap.set(t.traceId, t);
+		const spansByTrace = /* @__PURE__ */ new Map();
+		for (const s of spans) {
+			const group = spansByTrace.get(s.traceId) ?? [];
+			group.push(s);
+			spansByTrace.set(s.traceId, group);
+		}
+		const resourceSpans = [];
+		for (const [traceId, traceSpans] of spansByTrace) {
+			const trace = traceMap.get(traceId);
+			resourceSpans.push(buildResourceSpans(traceId, trace, traceSpans));
+		}
+		if (resourceSpans.length === 0) return;
+		await fetchFn(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${config.apiKey}`,
+				...config.headers ?? {}
+			},
+			body: JSON.stringify({ resourceSpans }),
+			signal
+		});
+	} };
+}
+
+//#endregion
+Object.defineProperty(exports, 'createLLMOpsAgentsExporter', {
+  enumerable: true,
+  get: function () {
+    return createLLMOpsAgentsExporter;
+  }
+});

package/dist/agents-exporter-DIoxRgjd.d.mts

@@ -0,0 +1,155 @@
+//#region src/telemetry/agents-exporter.d.ts
+/**
+ * LLMOps Tracing Exporter for @openai/agents
+ *
+ * Implements the TracingExporter interface from @openai/agents-core, converting
+ * the agents framework's Trace/Span format to OTLP JSON and sending it to
+ * the LLMOps OTLP ingestion endpoint.
+ *
+ * No dependency on @openai/agents — types are defined inline using structural
+ * compatibility (same pattern as the OTel exporter).
+ *
+ * @example
+ * ```typescript
+ * import { createLLMOpsAgentsExporter } from '@llmops/sdk';
+ * import { setTraceProcessors, BatchTraceProcessor } from '@openai/agents';
+ *
+ * const exporter = createLLMOpsAgentsExporter({
+ *   baseURL: 'http://localhost:5177',
+ *   apiKey: process.env.LLMOPS_API_KEY!,
+ * });
+ *
+ * setTraceProcessors([new BatchTraceProcessor(exporter)]);
+ *
+ * // All @openai/agents traces now flow to LLMOps automatically
+ * ```
+ */
+/** Matches TracingExporter from @openai/agents-core */
+interface AgentsTracingExporter {
+  export(items: (AgentsTrace | AgentsSpan)[], signal?: AbortSignal): Promise<void>;
+}
+/** Matches Trace from @openai/agents-core */
+interface AgentsTrace {
+  type: 'trace';
+  traceId: string;
+  name: string;
+  groupId?: string | null;
+  metadata?: Record<string, unknown>;
+}
+/** Matches SpanError from @openai/agents-core */
+interface AgentsSpanError {
+  message: string;
+  data?: Record<string, unknown>;
+}
+/** Matches Span from @openai/agents-core */
+interface AgentsSpan {
+  type: 'trace.span';
+  spanId: string;
+  traceId: string;
+  parentId?: string | null;
+  startedAt?: string | null;
+  endedAt?: string | null;
+  error?: AgentsSpanError | null;
+  spanData: AgentsSpanData;
+}
+type AgentSpanData = {
+  type: 'agent';
+  name: string;
+  handoffs?: string[];
+  tools?: string[];
+  output_type?: string;
+};
+type FunctionSpanData = {
+  type: 'function';
+  name: string;
+  input: string;
+  output: string;
+  mcp_data?: string;
+};
+type GenerationUsageData = {
+  input_tokens?: number;
+  output_tokens?: number;
+  details?: Record<string, unknown> | null;
+  [key: string]: unknown;
+};
+type GenerationSpanData = {
+  type: 'generation';
+  input?: Record<string, unknown>[];
+  output?: Record<string, unknown>[];
+  model?: string;
+  model_config?: Record<string, unknown>;
+  usage?: GenerationUsageData;
+};
+type ResponseSpanData = {
+  type: 'response';
+  response_id?: string;
+  [key: string]: unknown;
+};
+type HandoffSpanData = {
+  type: 'handoff';
+  from_agent?: string;
+  to_agent?: string;
+};
+type CustomSpanData = {
+  type: 'custom';
+  name: string;
+  data: Record<string, unknown>;
+};
+type GuardrailSpanData = {
+  type: 'guardrail';
+  name: string;
+  triggered: boolean;
+};
+type TranscriptionSpanData = {
+  type: 'transcription';
+  input: unknown;
+  output?: string;
+  model?: string;
+  model_config?: Record<string, unknown>;
+};
+type SpeechSpanData = {
+  type: 'speech';
+  input?: string;
+  output: unknown;
+  model?: string;
+  model_config?: Record<string, unknown>;
+};
+type SpeechGroupSpanData = {
+  type: 'speech_group';
+  input?: string;
+};
+type MCPListToolsSpanData = {
+  type: 'mcp_tools';
+  server?: string;
+  result?: string[];
+};
+type AgentsSpanData = AgentSpanData | FunctionSpanData | GenerationSpanData | ResponseSpanData | HandoffSpanData | CustomSpanData | GuardrailSpanData | TranscriptionSpanData | SpeechSpanData | SpeechGroupSpanData | MCPListToolsSpanData;
+interface LLMOpsAgentsExporterConfig {
+  /** LLMOps server base URL (e.g. http://localhost:5177) */
+  baseURL: string;
+  /** Environment secret or API key for authentication */
+  apiKey: string;
+  /** Custom headers to include in requests */
+  headers?: Record<string, string>;
+  /** Custom fetch implementation (used internally by client.agentsExporter()) */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * Create a TracingExporter for @openai/agents that sends traces to LLMOps.
+ *
+ * Usage:
+ * ```typescript
+ * import { createLLMOpsAgentsExporter } from '@llmops/sdk';
+ * import { setTraceProcessors, BatchTraceProcessor } from '@openai/agents';
+ *
+ * setTraceProcessors([
+ *   new BatchTraceProcessor(createLLMOpsAgentsExporter({
+ *     baseURL: 'http://localhost:5177',
+ *     apiKey: process.env.LLMOPS_API_KEY!,
+ *   }))
+ * ]);
+ * ```
+ */
+declare function createLLMOpsAgentsExporter(config: LLMOpsAgentsExporterConfig): AgentsTracingExporter;
+//#endregion
+export { AgentsTracingExporter as a, AgentsTrace as i, AgentsSpanData as n, LLMOpsAgentsExporterConfig as o, AgentsSpanError as r, createLLMOpsAgentsExporter as s, AgentsSpan as t };