@struct-ai/sdk 0.1.0

package/dist/esm/integrations/anthropic-content.js

@@ -0,0 +1,168 @@
+import { safeJsonStringify, truncateAndSerialize, truncateField, } from "../truncation.js";
+import { ANTHROPIC_FINISH_REASON_MAP } from "../semconv.js";
+/**
+ * Walk Anthropic response content blocks, return (name, id) pairs for tool_use blocks.
+ * Port of _iter_tool_uses from anthropic.py.
+ */
+export function iterToolUses(blocks) {
+    const out = [];
+    if (!Array.isArray(blocks))
+        return out;
+    for (const block of blocks) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type !== "tool_use")
+            continue;
+        const name = typeof b.name === "string" ? b.name : "";
+        const id = typeof b.id === "string" ? b.id : "";
+        if (name && id)
+            out.push([name, id]);
+    }
+    return out;
+}
+/**
+ * Convert arbitrary content (string | block[] | unknown) → GenAI parts.
+ * Port of _content_to_parts from anthropic.py.
+ */
+export function contentToParts(content) {
+    if (content == null)
+        return [];
+    if (typeof content === "string") {
+        return [{ type: "text", content }];
+    }
+    if (!Array.isArray(content)) {
+        return [{ type: "text", content: String(content) }];
+    }
+    const parts = [];
+    for (const item of content) {
+        if (item == null)
+            continue;
+        if (typeof item === "string") {
+            parts.push({ type: "text", content: item });
+            continue;
+        }
+        if (typeof item !== "object")
+            continue;
+        const block = item;
+        const blockType = typeof block.type === "string" ? block.type : undefined;
+        if (blockType === "text") {
+            const text = typeof block.text === "string" ? block.text : "";
+            parts.push({ type: "text", content: text });
+        }
+        else if (blockType === "tool_use") {
+            const name = typeof block.name === "string" ? block.name : "";
+            const part = { type: "tool_call", name };
+            if (block.id)
+                part.id = block.id;
+            if (block.input !== undefined)
+                part.arguments = block.input;
+            parts.push(part);
+        }
+        else if (blockType === "tool_result") {
+            const part = { type: "tool_call_response" };
+            if (block.tool_use_id)
+                part.id = block.tool_use_id;
+            part.response = block.content ?? "";
+            parts.push(part);
+        }
+        else if (blockType === "thinking") {
+            const thinking = typeof block.thinking === "string" ? block.thinking : "";
+            parts.push({ type: "reasoning", content: thinking });
+        }
+        else if (blockType === "image") {
+            const source = block.source ?? {};
+            if (source.type === "base64" && typeof source.data === "string") {
+                parts.push({
+                    type: "blob",
+                    modality: "image",
+                    content: source.data.slice(0, 256) + "...",
+                    mime_type: source.media_type,
+                });
+            }
+            else if (source.type === "url" && typeof source.url === "string") {
+                parts.push({
+                    type: "uri",
+                    modality: "image",
+                    uri: source.url,
+                });
+            }
+            else {
+                parts.push({ type: "image" });
+            }
+        }
+        else {
+            parts.push({ type: blockType || "unknown" });
+        }
+    }
+    return parts;
+}
+/** Convert Anthropic message list → GenAI input-messages JSON string. */
+export function toInputMessages(messages) {
+    if (!Array.isArray(messages))
+        return "[]";
+    try {
+        const result = messages.map((msg) => {
+            const m = (msg ?? {});
+            const role = typeof m.role === "string" ? m.role : "user";
+            const parts = contentToParts(m.content);
+            return { role, parts };
+        });
+        return truncateAndSerialize(result);
+    }
+    catch {
+        return "[]";
+    }
+}
+/** Convert response content blocks → GenAI output-messages JSON string. */
+export function toOutputMessages(contentBlocks, stopReason) {
+    try {
+        const parts = contentToParts(contentBlocks);
+        const msg = { role: "assistant", parts };
+        if (stopReason) {
+            msg.finish_reason = ANTHROPIC_FINISH_REASON_MAP[stopReason] ?? stopReason;
+        }
+        return truncateAndSerialize([msg]);
+    }
+    catch {
+        return "[]";
+    }
+}
+/** Convert system prompt (string | block[]) → GenAI system_instructions JSON string. */
+export function toSystemInstructions(system) {
+    try {
+        if (typeof system === "string") {
+            return truncateAndSerialize([{ type: "text", content: system }]);
+        }
+        if (Array.isArray(system)) {
+            const parts = contentToParts(system);
+            return truncateAndSerialize(parts);
+        }
+        return "[]";
+    }
+    catch {
+        return "[]";
+    }
+}
+export function safeJsonForTool(obj) {
+    try {
+        return truncateAndSerialize(obj);
+    }
+    catch {
+        return safeJsonStringify(obj);
+    }
+}
+/** Extract the last user message's parts for parent-span propagation. */
+export function lastUserMessageParts(messages) {
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg && msg.role === "user") {
+            return contentToParts(msg.content);
+        }
+    }
+    return undefined;
+}
+export { truncateField };
+//# sourceMappingURL=anthropic-content.js.map

package/dist/esm/integrations/anthropic.d.ts

@@ -0,0 +1,34 @@
+import { type Tracer } from "@opentelemetry/api";
+import type { Logger } from "@opentelemetry/api-logs";
+import { type StructSDK } from "../core.js";
+interface PatchContext {
+    tracer: Tracer;
+    sdk: StructSDK;
+    logger: Logger | undefined;
+}
+interface CreateParams {
+    model?: string;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    stop_sequences?: string[];
+    messages?: unknown[];
+    system?: unknown;
+    tools?: unknown[];
+    stream?: boolean;
+}
+export declare function patch(sdk: StructSDK): Promise<void>;
+export declare function unpatch(): Promise<void>;
+type CreateMethod = (this: unknown, params: CreateParams, opts?: unknown) => unknown;
+type StreamMethod = (this: unknown, params: CreateParams, opts?: unknown) => unknown;
+/** @internal */
+export type _PatchContextForTest = PatchContext;
+/** @internal */
+export declare function _wrapCreateForTest(original: CreateMethod): CreateMethod;
+/** @internal */
+export declare function _wrapStreamForTest(original: StreamMethod): StreamMethod;
+/** @internal */
+export declare function _setActivePatchCtxForTest(ctx: PatchContext | undefined): void;
+export {};
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/esm/integrations/anthropic.js

@@ -0,0 +1,370 @@
+import { SpanKind, SpanStatusCode, context as otelContext, trace, } from "@opentelemetry/api";
+import { ensurePendingToolCallsSlot, getAgentSpan, getSessionId, pushPendingToolCalls, runWithStore, snapshotStore, } from "../context.js";
+function childParentContext() {
+    const agentSpan = getAgentSpan();
+    return agentSpan
+        ? trace.setSpan(otelContext.active(), agentSpan)
+        : otelContext.active();
+}
+import { safe } from "../core.js";
+import { emitAnthropicChoiceEvent, emitAnthropicMessageEvents, } from "../events.js";
+import { ERROR_TYPE, GEN_AI, STRUCT, } from "../semconv.js";
+import { truncateAndSerialize } from "../truncation.js";
+import { iterToolUses, lastUserMessageParts, safeJsonForTool, toInputMessages, toOutputMessages, toSystemInstructions, } from "./anthropic-content.js";
+const STRUCT_WRAPPED = Symbol.for("struct.wrapped");
+const STRUCT_ORIGINAL = Symbol.for("struct.original");
+/**
+ * Mutable reference updated on each patch() call. Wrappers dereference this
+ * at call time, so the most recently initialized SDK always wins — matches
+ * the fact that `struct` is a singleton in production, and keeps tests with
+ * multiple StructSDK instances working correctly.
+ */
+const activePatchCtx = { value: undefined };
+export async function patch(sdk) {
+    const anthropicMod = (await import("@anthropic-ai/sdk"));
+    activePatchCtx.value = {
+        tracer: sdk.getTracer("struct-sdk-anthropic"),
+        sdk,
+        logger: sdk.emitEvents ? sdk.getLogger("struct-sdk-anthropic") : undefined,
+    };
+    const classes = collectMessagesClasses(anthropicMod);
+    for (const cls of classes) {
+        wrapMethod(cls.prototype, "create", false);
+        wrapMethod(cls.prototype, "stream", true);
+    }
+    // Best-effort: also patch bedrock + vertex packages if installed.
+    await tryPatchCompanion("@anthropic-ai/bedrock-sdk");
+    await tryPatchCompanion("@anthropic-ai/vertex-sdk");
+}
+export async function unpatch() {
+    activePatchCtx.value = undefined;
+    try {
+        const anthropicMod = (await import("@anthropic-ai/sdk"));
+        const classes = collectMessagesClasses(anthropicMod);
+        for (const cls of classes) {
+            restoreMethod(cls.prototype, "create");
+            restoreMethod(cls.prototype, "stream");
+        }
+    }
+    catch {
+        /* not installed */
+    }
+}
+function collectMessagesClasses(mod) {
+    const classes = [];
+    const Anthropic = mod.default ?? mod.Anthropic;
+    if (typeof Anthropic === "function") {
+        const ctor = Anthropic;
+        if (typeof ctor.Messages === "function") {
+            classes.push(ctor.Messages);
+        }
+        if (ctor.Beta && typeof ctor.Beta.Messages === "function") {
+            classes.push(ctor.Beta.Messages);
+        }
+    }
+    return classes;
+}
+async function tryPatchCompanion(moduleName) {
+    try {
+        const mod = (await import(moduleName));
+        const classes = collectMessagesClasses(mod);
+        for (const cls of classes) {
+            wrapMethod(cls.prototype, "create", false);
+            wrapMethod(cls.prototype, "stream", true);
+        }
+    }
+    catch {
+        /* not installed */
+    }
+}
+function wrapMethod(proto, methodName, isStream) {
+    const original = proto[methodName];
+    if (typeof original !== "function")
+        return;
+    const existing = original;
+    if (existing[STRUCT_WRAPPED])
+        return;
+    const wrapper = isStream
+        ? wrapStream(original)
+        : wrapCreate(original);
+    wrapper[STRUCT_WRAPPED] = true;
+    wrapper[STRUCT_ORIGINAL] = original;
+    proto[methodName] = wrapper;
+}
+function restoreMethod(proto, methodName) {
+    const current = proto[methodName];
+    if (current && current[STRUCT_WRAPPED] && current[STRUCT_ORIGINAL]) {
+        proto[methodName] = current[STRUCT_ORIGINAL];
+    }
+}
+function wrapCreate(original) {
+    return function wrappedCreate(params, opts) {
+        const patchCtx = activePatchCtx.value;
+        if (!patchCtx) {
+            return original.call(this, params, opts);
+        }
+        // If params.stream is true, Messages.create delegates to the streaming path.
+        // We still need to instrument the returned stream like we do in messages.stream.
+        if (params && params.stream === true) {
+            return wrapStream(original).call(this, params, opts);
+        }
+        const { tracer, sdk, logger } = patchCtx;
+        const internalLogger = sdk.getInternalLogger();
+        const model = params?.model ?? "unknown";
+        // Span creation itself can fail (custom tracer, broken context). If it
+        // does, fall through to calling `original` directly so the user's API
+        // call always runs. Mirrors the Python `_wrap_create` fall-through.
+        let span;
+        let ctx;
+        safe(() => {
+            const parentCtx = childParentContext();
+            span = tracer.startSpan(`chat ${model}`, { kind: SpanKind.CLIENT }, parentCtx);
+            ctx = trace.setSpan(parentCtx, span);
+        }, "anthropic.create.start_span", internalLogger);
+        if (!span || !ctx) {
+            return original.call(this, params, opts);
+        }
+        const liveSpan = span;
+        const liveCtx = ctx;
+        // Enter the span's context BEFORE emitting request-side log records so
+        // `logger.emit({ context: otelContext.active() })` picks up the chat
+        // span as the log's TraceId / SpanId. Without this the UI can't link
+        // user/system message logs back to the chat span.
+        return otelContext.with(liveCtx, () => {
+            safe(() => setChatRequestAttrs(liveSpan, params, sdk, logger), "anthropic.create.set_request_attrs", internalLogger);
+            const promise = Promise.resolve(original.call(this, params, opts));
+            return promise.then((result) => {
+                safe(() => setChatResponseAttrs(liveSpan, sdk, result, logger), "anthropic.create.set_response_attrs", internalLogger);
+                safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.create.set_ok_status", internalLogger);
+                safe(() => liveSpan.end(), "anthropic.create.span_end", internalLogger);
+                return result;
+            }, (err) => {
+                safe(() => recordErrorOnSpan(liveSpan, err), "anthropic.create.record_error", internalLogger);
+                safe(() => liveSpan.end(), "anthropic.create.span_end_on_error", internalLogger);
+                // User's API exception always propagates unchanged.
+                throw err;
+            });
+        });
+    };
+}
+function wrapStream(original) {
+    return function wrappedStream(params, opts) {
+        const patchCtx = activePatchCtx.value;
+        if (!patchCtx) {
+            return original.call(this, params, opts);
+        }
+        const { tracer, sdk, logger } = patchCtx;
+        const internalLogger = sdk.getInternalLogger();
+        const model = params?.model ?? "unknown";
+        // Span creation itself can fail. If it does, fall through to calling
+        // `original` directly so the user's stream call always runs. Mirrors
+        // the Python `_wrap_stream` fall-through pattern.
+        let span;
+        let ctx;
+        safe(() => {
+            const parentCtx = childParentContext();
+            span = tracer.startSpan(`chat ${model}`, { kind: SpanKind.CLIENT }, parentCtx);
+            ctx = trace.setSpan(parentCtx, span);
+        }, "anthropic.stream.start_span", internalLogger);
+        if (!span || !ctx) {
+            return original.call(this, params, opts);
+        }
+        const liveSpan = span;
+        const liveCtx = ctx;
+        const storeSnapshot = snapshotStore();
+        // Enter the span's context BEFORE request-side log emission so logs
+        // link back to the chat span via TraceId. Same rationale as wrapCreate.
+        // @anthropic-ai/sdk's `stream()` returns a MessageStream synchronously.
+        const stream = otelContext.with(liveCtx, () => {
+            safe(() => setChatRequestAttrs(liveSpan, params, sdk, logger), "anthropic.stream.set_request_attrs", internalLogger);
+            return original.call(this, params, opts);
+        });
+        let finalized = false;
+        const finalize = (result, err) => {
+            if (finalized)
+                return;
+            finalized = true;
+            runWithStore(storeSnapshot, () => {
+                if (err) {
+                    safe(() => recordErrorOnSpan(liveSpan, err), "anthropic.stream.record_error", internalLogger);
+                }
+                else if (result) {
+                    safe(() => otelContext.with(liveCtx, () => setChatResponseAttrs(liveSpan, sdk, result, logger)), "anthropic.stream.set_response_attrs", internalLogger);
+                    safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.stream.set_ok_status", internalLogger);
+                }
+                else {
+                    safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.stream.set_ok_status", internalLogger);
+                }
+                safe(() => liveSpan.end(), "anthropic.stream.span_end", internalLogger);
+            });
+        };
+        const ee = stream;
+        if (ee && typeof ee.on === "function") {
+            ee.on("finalMessage", (msg) => {
+                finalize(msg, undefined);
+            });
+            ee.on("error", (err) => {
+                finalize(undefined, err);
+            });
+            // If the stream is created and never iterated / finalized, at least
+            // don't hang on test exit — "end" fires after iteration completes.
+            ee.on("end", () => {
+                // Only fires if no finalMessage / error fired first (rare path).
+                finalize(undefined, undefined);
+            });
+        }
+        // Wrap the async iterator so each .next() runs inside the captured ALS store.
+        if (ee && typeof ee[Symbol.asyncIterator] === "function") {
+            const originalIter = ee[Symbol.asyncIterator].bind(ee);
+            ee[Symbol.asyncIterator] = () => {
+                const inner = originalIter();
+                const wrapped = {
+                    next() {
+                        return runWithStore(storeSnapshot, () => inner.next());
+                    },
+                    return(value) {
+                        return runWithStore(storeSnapshot, () => inner.return ? inner.return(value) : Promise.resolve({ value, done: true }));
+                    },
+                    throw(err) {
+                        return runWithStore(storeSnapshot, () => inner.throw
+                            ? inner.throw(err)
+                            : Promise.reject(err));
+                    },
+                };
+                return wrapped;
+            };
+        }
+        return stream;
+    };
+}
+function setChatRequestAttrs(span, params, sdk, logger) {
+    span.setAttribute(GEN_AI.OPERATION_NAME, "chat");
+    span.setAttribute(GEN_AI.PROVIDER_NAME, "anthropic");
+    const model = params?.model ?? "unknown";
+    span.setAttribute(GEN_AI.REQUEST_MODEL, model);
+    const sessionId = getSessionId();
+    if (sessionId) {
+        span.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+    }
+    if (params?.max_tokens !== undefined) {
+        span.setAttribute(GEN_AI.REQUEST_MAX_TOKENS, params.max_tokens);
+    }
+    if (params?.temperature !== undefined) {
+        span.setAttribute(GEN_AI.REQUEST_TEMPERATURE, params.temperature);
+    }
+    if (params?.top_p !== undefined) {
+        span.setAttribute(GEN_AI.REQUEST_TOP_P, params.top_p);
+    }
+    if (params?.top_k !== undefined) {
+        span.setAttribute(GEN_AI.REQUEST_TOP_K, params.top_k);
+    }
+    if (params?.stop_sequences && params.stop_sequences.length > 0) {
+        span.setAttribute(GEN_AI.REQUEST_STOP_SEQUENCES, params.stop_sequences);
+    }
+    if (Array.isArray(params?.messages)) {
+        span.setAttribute(STRUCT.INPUT_MESSAGE_COUNT, params.messages.length);
+        propagateUserPromptToParent(params.messages);
+    }
+    if (sdk.emitEvents && logger && Array.isArray(params?.messages)) {
+        emitAnthropicMessageEvents(logger, params.messages, params.system);
+    }
+    if (sdk.emitSpanContent) {
+        if (Array.isArray(params?.messages)) {
+            span.setAttribute(GEN_AI.INPUT_MESSAGES, toInputMessages(params.messages));
+        }
+        if (params?.system) {
+            span.setAttribute(GEN_AI.SYSTEM_INSTRUCTIONS, toSystemInstructions(params.system));
+        }
+        if (params?.tools && Array.isArray(params.tools)) {
+            span.setAttribute(GEN_AI.TOOL_DEFINITIONS, safeJsonForTool(params.tools));
+        }
+    }
+}
+function setChatResponseAttrs(span, sdk, response, logger) {
+    const usage = response.usage;
+    if (usage) {
+        const inputTokens = usage.input_tokens ?? 0;
+        const outputTokens = usage.output_tokens ?? 0;
+        const cacheRead = usage.cache_read_input_tokens ?? 0;
+        const cacheCreation = usage.cache_creation_input_tokens ?? 0;
+        // Anthropic's input_tokens excludes cached tokens — add them back for the true total.
+        span.setAttribute(GEN_AI.USAGE_INPUT_TOKENS, inputTokens + cacheRead + cacheCreation);
+        span.setAttribute(GEN_AI.USAGE_OUTPUT_TOKENS, outputTokens);
+        if (cacheRead) {
+            span.setAttribute(GEN_AI.USAGE_CACHE_READ_INPUT_TOKENS, cacheRead);
+        }
+        if (cacheCreation) {
+            span.setAttribute(GEN_AI.USAGE_CACHE_CREATION_INPUT_TOKENS, cacheCreation);
+        }
+    }
+    if (response.model) {
+        span.setAttribute(GEN_AI.RESPONSE_MODEL, response.model);
+    }
+    if (response.stop_reason) {
+        span.setAttribute(GEN_AI.RESPONSE_FINISH_REASONS, [response.stop_reason]);
+    }
+    if (response.id) {
+        span.setAttribute(GEN_AI.RESPONSE_ID, response.id);
+    }
+    if (response.content) {
+        // Always runs — populates pending queue regardless of content-capture mode.
+        recordPendingToolCalls(response.content);
+        if (sdk.emitEvents && logger) {
+            emitAnthropicChoiceEvent(logger, response.content, response.stop_reason);
+        }
+        if (sdk.emitSpanContent) {
+            span.setAttribute(GEN_AI.OUTPUT_MESSAGES, toOutputMessages(response.content, response.stop_reason));
+        }
+    }
+}
+function recordPendingToolCalls(contentBlocks) {
+    const pairs = iterToolUses(contentBlocks);
+    if (pairs.length === 0)
+        return;
+    // Ensure the current store has a slot — initializes a transient dict if we're
+    // not inside a struct.agent() scope (matches Python behavior).
+    ensurePendingToolCallsSlot();
+    pushPendingToolCalls(pairs);
+}
+function propagateUserPromptToParent(messages) {
+    try {
+        const agentSpan = getAgentSpan();
+        if (!agentSpan)
+            return;
+        // The SDK span type doesn't expose `attributes` — we use a brand check on
+        // the SDK's ReadableSpan-like shape.
+        const agentAttrs = agentSpan
+            .attributes;
+        if (agentAttrs && agentAttrs[GEN_AI.INPUT_MESSAGES])
+            return;
+        const parts = lastUserMessageParts(messages);
+        if (!parts)
+            return;
+        agentSpan.setAttribute(GEN_AI.INPUT_MESSAGES, truncateAndSerialize([{ role: "user", parts }]));
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
+function recordErrorOnSpan(span, err) {
+    const errorType = err instanceof Error ? err.constructor.name : typeof err;
+    const message = err instanceof Error ? err.message : String(err);
+    span.setAttribute(ERROR_TYPE, errorType);
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    if (err instanceof Error) {
+        span.recordException(err);
+    }
+}
+/** @internal */
+export function _wrapCreateForTest(original) {
+    return wrapCreate(original);
+}
+/** @internal */
+export function _wrapStreamForTest(original) {
+    return wrapStream(original);
+}
+/** @internal */
+export function _setActivePatchCtxForTest(ctx) {
+    activePatchCtx.value = ctx;
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/esm/integrations/index.d.ts

@@ -0,0 +1,5 @@
+import type { StructSDK } from "../core.js";
+export declare const patchedIntegrations: Set<string>;
+export declare function resetPatchedIntegrations(): void;
+export declare function autoInstrument(sdk: StructSDK): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/integrations/index.js

@@ -0,0 +1,42 @@
+export const patchedIntegrations = new Set();
+export function resetPatchedIntegrations() {
+    patchedIntegrations.clear();
+}
+const INTEGRATIONS = [
+    {
+        name: "anthropic",
+        probe: () => import("@anthropic-ai/sdk"),
+        apply: async (sdk) => {
+            const mod = await import("./anthropic.js");
+            await mod.patch(sdk);
+        },
+    },
+    {
+        name: "langchain",
+        probe: () => import("@langchain/core/language_models/chat_models"),
+        apply: async (sdk) => {
+            const mod = await import("./langchain.js");
+            await mod.patch(sdk);
+        },
+    },
+];
+export async function autoInstrument(sdk) {
+    for (const integration of INTEGRATIONS) {
+        if (patchedIntegrations.has(integration.name))
+            continue;
+        try {
+            await integration.probe();
+        }
+        catch {
+            continue;
+        }
+        try {
+            await integration.apply(sdk);
+            patchedIntegrations.add(integration.name);
+        }
+        catch (err) {
+            sdk.getInternalLogger().debug(`Failed to instrument ${integration.name}`, err);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map