@struct-ai/sdk 0.3.0 → 0.4.2

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

@@ -0,0 +1,360 @@
+import { EVENT_NAMES } from "../semconv.js";
+import { serializeToolDefinitions, truncateAndSerialize } from "../truncation.js";
+/** Read `key` from a Responses item that may be a plain object or SDK object. */
+function get(item, key, dflt) {
+    if (item == null || typeof item !== "object")
+        return dflt;
+    const v = item[key];
+    return v === undefined ? dflt : v;
+}
+/** Map a Responses `input_image.image_url` to a spec image part (never embeds full base64). */
+function parseImageUrl(imageUrl) {
+    if (typeof imageUrl === "string" && imageUrl.startsWith("data:")) {
+        try {
+            const idx = imageUrl.indexOf(",");
+            const header = idx >= 0 ? imageUrl.slice(0, idx) : imageUrl; // "data:<mime>;base64"
+            const data = idx >= 0 ? imageUrl.slice(idx + 1) : "";
+            const mime = header.slice("data:".length).split(";")[0] || undefined;
+            return {
+                type: "blob",
+                modality: "image",
+                content: data.slice(0, 256) + "...",
+                mime_type: mime,
+            };
+        }
+        catch {
+            /* malformed data URL falls through to uri */
+        }
+    }
+    return { type: "uri", modality: "image", uri: imageUrl || "" };
+}
+/** Map ONE entry inside a Responses `message.content` list to a spec part. */
+function contentEntryToPart(entry) {
+    if (typeof entry === "string")
+        return { type: "text", content: entry };
+    const entryType = get(entry, "type");
+    if (entryType === "input_text" || entryType === "output_text") {
+        return { type: "text", content: get(entry, "text", "") || "" };
+    }
+    if (entryType === "refusal") {
+        return { type: "text", content: get(entry, "refusal", "") || "" };
+    }
+    if (entryType === "input_image" || entryType === "output_image") {
+        // A Responses image can reference an uploaded file by `file_id` instead of
+        // an `image_url`. Preserve that identity as a file part (never embed file
+        // contents — we don't have them) rather than dropping it to an empty uri.
+        const fileId = get(entry, "file_id");
+        if (typeof fileId === "string" && fileId) {
+            return { type: "file", modality: "image", file_id: fileId };
+        }
+        const url = get(entry, "image_url", "") || "";
+        if (entryType === "input_image")
+            return parseImageUrl(url);
+        return url ? parseImageUrl(url) : { type: "output_image" };
+    }
+    if (entryType === "input_file") {
+        // Preserve safe identity fields; NEVER embed the base64 `file_data`.
+        const part = { type: "file" };
+        const fileId = get(entry, "file_id");
+        const filename = get(entry, "filename");
+        const fileUrl = get(entry, "file_url");
+        if (typeof fileId === "string" && fileId)
+            part.file_id = fileId;
+        if (typeof filename === "string" && filename)
+            part.filename = filename;
+        if (typeof fileUrl === "string" && fileUrl)
+            part.uri = fileUrl;
+        return part;
+    }
+    if (entryType === "input_audio") {
+        // Preserve only the audio format; NEVER embed the base64 `data`.
+        const part = { type: "audio", modality: "audio" };
+        const audio = get(entry, "input_audio");
+        const format = get(audio, "format") ?? get(entry, "format");
+        if (typeof format === "string" && format)
+            part.format = format;
+        return part;
+    }
+    return { type: entryType || "unknown" };
+}
+/** Map a Responses `message.content` (string or list) to spec parts. */
+export function messageContentToParts(content) {
+    if (content == null)
+        return [];
+    if (typeof content === "string")
+        return [{ type: "text", content }];
+    if (!Array.isArray(content))
+        return [];
+    return content.map(contentEntryToPart);
+}
+/** Map a top-level `function_call` item to a single `tool_call` part. */
+function functionCallParts(item) {
+    const part = { type: "tool_call", name: get(item, "name", "") || "" };
+    const callId = get(item, "call_id");
+    if (callId)
+        part.id = callId;
+    const rawArgs = get(item, "arguments");
+    if (rawArgs !== undefined && rawArgs !== null) {
+        if (typeof rawArgs === "string") {
+            // JSON string on the wire; parse to a dict when we can, else keep raw.
+            try {
+                part.arguments = rawArgs ? JSON.parse(rawArgs) : {};
+            }
+            catch {
+                part.arguments = rawArgs;
+            }
+        }
+        else {
+            part.arguments = rawArgs;
+        }
+    }
+    return [part];
+}
+/**
+ * Map a function_call_output / custom_tool_call_output item to a single
+ * tool_call_response part. `output` may be a string OR an array of
+ * input-content items — arrays route through the safe content mapper so inline
+ * base64 (`file_data`, audio `data`) is never copied verbatim.
+ */
+function toolResponseParts(item) {
+    const part = { type: "tool_call_response" };
+    const callId = get(item, "call_id");
+    if (callId)
+        part.id = callId;
+    const output = get(item, "output", "");
+    part.response = Array.isArray(output) ? messageContentToParts(output) : output;
+    return [part];
+}
+/** Map a `custom_tool_call` item to a tool_call part with its RAW string input. */
+function customToolCallParts(item) {
+    const part = { type: "tool_call", name: get(item, "name", "") || "" };
+    const callId = get(item, "call_id");
+    if (callId)
+        part.id = callId;
+    const input = get(item, "input");
+    if (typeof input === "string")
+        part.arguments = input; // freeform — keep raw
+    return [part];
+}
+const EVENT_NAME_MAP = {
+    user: EVENT_NAMES.USER_MESSAGE,
+    assistant: EVENT_NAMES.ASSISTANT_MESSAGE,
+    system: EVENT_NAMES.SYSTEM_MESSAGE,
+    // OpenAI's `developer` role is system-level instruction; Struct renders only
+    // the known user/assistant/system/tool event names, so map it to the system
+    // event (the payload keeps `role: "developer"` for fidelity).
+    developer: EVENT_NAMES.SYSTEM_MESSAGE,
+};
+/**
+ * True for a Responses `input` item that is a chat message. Covers the explicit
+ * ``{"type": "message", ...}`` form AND OpenAI's ``EasyInputMessage`` shorthand,
+ * where ``type`` is OPTIONAL (``type?: "message"``) — e.g.
+ * ``{"role": "user", "content": "hi"}``. A typeless item counts only when it
+ * carries a string ``role`` (so we never treat function_call / reasoning / other
+ * typeless objects as messages).
+ */
+function isMessageItem(item) {
+    const itemType = get(item, "type");
+    if (itemType === "message")
+        return true;
+    return ((itemType === undefined || itemType === null) &&
+        typeof get(item, "role") === "string");
+}
+/** Map ONE Responses `input` item to `[eventName, role, parts]`, or null. */
+export function inputItemToEvent(item) {
+    if (isMessageItem(item)) {
+        const role = get(item, "role", "user") || "user";
+        const parts = messageContentToParts(get(item, "content"));
+        const eventName = EVENT_NAME_MAP[role] ?? `gen_ai.${role}.message`;
+        return [eventName, role, parts];
+    }
+    const itemType = get(item, "type");
+    if (itemType === "function_call") {
+        return [EVENT_NAMES.ASSISTANT_MESSAGE, "assistant", functionCallParts(item)];
+    }
+    if (itemType === "custom_tool_call") {
+        // OpenAI custom tools: same semantics as function_call but `input` is a
+        // FREEFORM string — never JSON.parse it.
+        return [EVENT_NAMES.ASSISTANT_MESSAGE, "assistant", customToolCallParts(item)];
+    }
+    if (itemType === "function_call_output" || itemType === "custom_tool_call_output") {
+        return [EVENT_NAMES.TOOL_MESSAGE, "tool", toolResponseParts(item)];
+    }
+    // Deliberately NO message event for everything else:
+    // - reasoning / compaction / compaction_trigger (encrypted_content NEVER read)
+    // - builtin/agentic tool machinery — computer_call(+output), web_search_call,
+    //   file_search_call, image_generation_call, code_interpreter_call,
+    //   local_shell_call(+output), and the v6-era shell_call(+output),
+    //   apply_patch_call(+output), tool_search_call/tool_search_output,
+    //   additional_tools, program(+output), mcp_* —
+    //   these are not chat messages, and their payloads (shell commands, patches,
+    //   program code) are exactly the sensitive fields we must not serialize.
+    // - unknown future items.
+    // The shape-sweep test pins every documented member of this policy.
+    return null;
+}
+/** Map ONE `response.output` item to the assistant's choice parts. */
+export function outputItemToChoiceParts(item) {
+    const itemType = get(item, "type");
+    if (itemType === "message")
+        return messageContentToParts(get(item, "content"));
+    if (itemType === "function_call")
+        return functionCallParts(item);
+    if (itemType === "custom_tool_call")
+        return customToolCallParts(item);
+    // v6 ResponseOutputItem also carries tool RESULTS — capture them (with the
+    // same array base64-stripping as the input path). Other agentic *_output
+    // items (computer/shell/apply_patch/…) stay privacy-skipped below.
+    if (itemType === "function_call_output" || itemType === "custom_tool_call_output") {
+        return toolResponseParts(item);
+    }
+    return [];
+}
+/** Normalize the `input` kwarg to a list of items (bare string → one user message). */
+export function normalizeInput(input) {
+    if (typeof input === "string") {
+        return [
+            { type: "message", role: "user", content: [{ type: "input_text", text: input }] },
+        ];
+    }
+    if (Array.isArray(input))
+        return input;
+    return [];
+}
+/** Spec parts of the LAST `user` message in `input` (for parent propagation). */
+export function lastUserParts(input) {
+    const items = normalizeInput(input);
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (isMessageItem(item) && get(item, "role") === "user") {
+            return messageContentToParts(get(item, "content"));
+        }
+    }
+    return undefined;
+}
+/** Every function_call `(name, call_id)` from a response.output (for tool linkage). */
+export function iterFunctionCalls(output) {
+    const pairs = [];
+    if (!Array.isArray(output))
+        return pairs;
+    for (const item of output) {
+        const itemType = get(item, "type");
+        // custom_tool_call is a tool invocation too — its call_id is what a
+        // custom_tool_call_output echoes, so @struct.tool() linkage needs it.
+        if (itemType !== "function_call" && itemType !== "custom_tool_call")
+            continue;
+        const name = get(item, "name", "") || "";
+        const callId = get(item, "call_id", "") || "";
+        if (name && callId)
+            pairs.push([name, callId]);
+    }
+    return pairs;
+}
+/** Derive a raw finish-reason string from a Responses response. */
+export function deriveFinishReason(response) {
+    const incomplete = get(response, "incomplete_details");
+    if (incomplete != null) {
+        const reason = get(incomplete, "reason", "") || "";
+        return reason ? `incomplete:${reason}` : "incomplete";
+    }
+    return get(response, "status") || undefined;
+}
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "incomplete",
+    "failed",
+    "cancelled",
+]);
+/**
+ * True when a Responses response is in a terminal state (generation finished).
+ * A `background: true` request can return non-terminal (`"queued"` /
+ * `"in_progress"`) with no assistant message yet — we must NOT emit a terminal
+ * `gen_ai.choice` / finish reason for those. A response with no status is
+ * treated as terminal so we never silently drop telemetry for the common
+ * synchronous call (or minimal mocks).
+ */
+export function isTerminalResponse(response) {
+    if (get(response, "incomplete_details") != null)
+        return true;
+    const status = get(response, "status");
+    if (status == null)
+        return true;
+    return TERMINAL_STATUSES.has(status);
+}
+// Only terminal statuses map to a spec choice finish reason; non-terminal
+// (queued/in_progress) responses never reach here — the caller skips the choice
+// event entirely (see isTerminalResponse).
+const FINISH_REASON_MAP = {
+    completed: "stop",
+    // "incomplete" is handled reason-aware in mapChoiceFinishReason (length vs
+    // content_filter), not here.
+    failed: "error",
+    cancelled: "stop",
+};
+/** Map a raw Responses status/derived reason to a spec choice finish reason. */
+export function mapChoiceFinishReason(raw) {
+    if (!raw)
+        return "stop";
+    const [base, detail] = raw.split(":"); // e.g. "incomplete:max_output_tokens"
+    if (base === "incomplete") {
+        // Documented incomplete reasons: max_output_tokens → length,
+        // content_filter → content_filter (its own spec value). Unknown future
+        // reasons fall back to length (the generic "cut short" semantics).
+        if (detail === "content_filter")
+            return "content_filter";
+        return "length";
+    }
+    return FINISH_REASON_MAP[base] ?? "stop";
+}
+/** Serialize `input` → spec `gen_ai.input.messages` JSON string. */
+export function toInputMessages(input) {
+    try {
+        const result = [];
+        for (const item of normalizeInput(input)) {
+            const mapped = inputItemToEvent(item);
+            if (!mapped)
+                continue;
+            const [, role, parts] = mapped;
+            result.push({ role, parts });
+        }
+        return truncateAndSerialize(result);
+    }
+    catch {
+        return "[]";
+    }
+}
+/** Serialize Responses `instructions` → spec `system_instructions` JSON string. */
+export function toSystemInstructions(instructions) {
+    try {
+        if (typeof instructions === "string") {
+            return truncateAndSerialize([{ type: "text", content: instructions }]);
+        }
+        if (instructions) {
+            return truncateAndSerialize([{ type: "text", content: String(instructions) }]);
+        }
+        return "[]";
+    }
+    catch {
+        return "[]";
+    }
+}
+/** Serialize `response.output` → spec `gen_ai.output.messages` JSON string. */
+export function toOutputMessages(output, finishReason) {
+    try {
+        const parts = [];
+        for (const item of Array.isArray(output) ? output : []) {
+            parts.push(...outputItemToChoiceParts(item));
+        }
+        const msg = { role: "assistant", parts };
+        if (finishReason)
+            msg.finish_reason = mapChoiceFinishReason(finishReason);
+        return truncateAndSerialize([msg]);
+    }
+    catch {
+        return "[]";
+    }
+}
+export function safeJsonForTool(obj) {
+    return serializeToolDefinitions(obj);
+}
+//# sourceMappingURL=openai-content.js.map

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

@@ -0,0 +1,39 @@
+import { type Span, 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_output_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    input?: unknown;
+    instructions?: 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;
+declare function detectProvider(resource: unknown): string;
+/** @internal */
+export declare const _detectProviderForTest: typeof detectProvider;
+export declare function wrapCreate(original: CreateMethod): CreateMethod;
+declare function setChatRequestAttrs(span: Span, params: CreateParams | undefined, sdk: StructSDK, logger: Logger | undefined, provider?: string): void;
+/** @internal */
+export type _PatchContextForTest = PatchContext;
+/** @internal */
+export declare function _wrapCreateForTest(original: CreateMethod): CreateMethod;
+/** @internal */
+export declare const _setChatRequestAttrsForTest: typeof setChatRequestAttrs;
+export declare function _setActivePatchCtxForTest(ctx: PatchContext | undefined): void;
+/** @internal — version-compat tests assert the patch surface across openai releases. */
+export declare function _collectResponsesClassesForTest(mod: Record<string, unknown>): Array<{
+    prototype: Record<string, unknown>;
+}>;
+export {};
+//# sourceMappingURL=openai.d.ts.map