@struktur/sdk 2.1.1 → 2.2.0

package/src/llm/LLMClient.test.ts

@@ -1,394 +0,0 @@
-import { test, expect, mock } from "bun:test";
-import type { ModelMessage } from "ai";
-
-type GenerateTextParams = {
-  model: unknown;
-  output: unknown;
-  system: string;
-  messages: ModelMessage[];
-  providerOptions?: unknown;
-};
-
-let generateTextImpl: (params: GenerateTextParams) => Promise<{
-  output: unknown;
-  usage?: Record<string, unknown>;
-}>;
-
-const calls: GenerateTextParams[] = [];
-
-mock.module("ai", () => ({
-  generateText: (params: GenerateTextParams) => {
-    calls.push(params);
-    return generateTextImpl(params);
-  },
-  Output: {
-    object: (config: unknown) => config,
-  },
-  jsonSchema: (schema: unknown) => ({ wrapped: schema }),
-}));
-
-const { generateStructured } = await import("./LLMClient");
-
-test("generateStructured maps prompt/completion token usage", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: { promptTokens: 2, completionTokens: 3, totalTokens: 9 },
-  });
-
-  const result = await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(result.usage).toEqual({ inputTokens: 2, outputTokens: 3, totalTokens: 9 });
-  expect(calls[0]?.output).toEqual({ schema: { wrapped: { type: "object" } }, name: "extract" });
-  expect(calls[0]?.messages[0]).toEqual({ role: "user", content: "prompt" });
-});
-
-test("generateStructured uses explicit messages and totals usage", async () => {
-  calls.length = 0;
-  const messages: ModelMessage[] = [{ role: "user", content: "custom" }];
-  generateTextImpl = async (params) => ({
-    output: { title: "ok" },
-    usage: { inputTokens: 4, outputTokens: 6 },
-  });
-
-  const result = await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    system: "sys",
-    user: "fallback",
-    messages,
-  });
-
-  expect(calls[0]?.messages).toBe(messages);
-  expect(result.usage).toEqual({ inputTokens: 4, outputTokens: 6, totalTokens: 10 });
-});
-
-test("generateStructured passes OpenRouter provider preference", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: { inputTokens: 1, outputTokens: 1 },
-  });
-
-  const model = { __openrouter_provider: "cerebras" };
-  await generateStructured({
-    model,
-    schema: { type: "object" },
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(calls[0]?.providerOptions).toEqual({
-    openrouter: {
-      provider: {
-        order: ["cerebras"],
-      },
-    },
-  });
-});
-
-test("generateStructured does not add openrouter providerOptions without preference", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: { inputTokens: 1, outputTokens: 1 },
-  });
-
-  await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(calls[0]?.providerOptions).not.toHaveProperty("openrouter");
-});
-
-test("generateStructured uses inputTokens/outputTokens when promptTokens missing", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: { inputTokens: 5, outputTokens: 7 },
-  });
-
-  const result = await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(result.usage).toEqual({ inputTokens: 5, outputTokens: 7, totalTokens: 12 });
-});
-
-test("generateStructured uses totalTokens from response when present", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: { inputTokens: 3, outputTokens: 4, totalTokens: 100 },
-  });
-
-  const result = await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(result.usage.totalTokens).toBe(100);
-});
-
-test("generateStructured handles missing usage", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-  });
-
-  const result = await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(result.usage).toEqual({ inputTokens: 0, outputTokens: 0, totalTokens: 0 });
-});
-
-test("generateStructured uses custom schema name", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: {},
-  });
-
-  await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    schemaName: "custom_schema",
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(calls[0]?.output).toHaveProperty("name", "custom_schema");
-});
-
-test("generateStructured uses custom schema description", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => ({
-    output: { title: "ok" },
-    usage: {},
-  });
-
-  await generateStructured({
-    model: {},
-    schema: { type: "object" },
-    schemaDescription: "Extract data",
-    system: "sys",
-    user: "prompt",
-  });
-
-  expect(calls[0]?.output).toHaveProperty("description", "Extract data");
-});
-
-test("generateStructured shows friendly error when model doesn't support images", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      responseBody: '{"error":{"message":"No endpoints found that support image input","code":404}}',
-      statusCode: 404,
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "meta-llama/llama-3.1-8b-instruct" },
-        schema: { type: "object" },
-        system: "sys",
-        user: [{ type: "text", text: "prompt" }, { type: "image", image: "base64data" }],
-      }),
-  ).toThrow(
-    'Model "meta-llama/llama-3.1-8b-instruct" does not support image input. Please use a model that supports images (e.g., gpt-4o, claude-3-5-sonnet, gemini-1.5-pro) or remove the --images and --screenshots flags.',
-  );
-});
-
-test("generateStructured rethrows other API errors", async () => {
-  calls.length = 0;
-  const originalError = new Error("Some other error");
-  generateTextImpl = async () => {
-    throw originalError;
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: {},
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow("Some other error");
-});
-
-test("generateStructured shows friendly error for internal server error", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      statusCode: 200,
-      responseBody: undefined,
-      data: {
-        code: 500,
-        message: "Internal Server Error",
-        type: null,
-        param: null,
-      },
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "openai/gpt-5-mini" },
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow(
-    'Provider error for model "openai/gpt-5-mini": Internal server error. The model or provider may be experiencing issues. Please try again or use a different model.',
-  );
-});
-
-test("generateStructured shows friendly error for authentication failure", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      statusCode: 401,
-      responseBody: '{"error":{"message":"Invalid API key"}}',
-      data: {
-        code: 401,
-        message: "Invalid API key",
-      },
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "gpt-4o" },
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow(
-    'Authentication failed for model "gpt-4o". Please check your API key is valid and has the necessary permissions.',
-  );
-});
-
-test("generateStructured shows friendly error for rate limit", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      statusCode: 429,
-      responseBody: '{"error":{"message":"Rate limit exceeded"}}',
-      data: {
-        code: 429,
-        message: "Rate limit exceeded",
-      },
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "claude-3-5-sonnet" },
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow(
-    'Rate limit exceeded for model "claude-3-5-sonnet". Please wait a moment and try again, or use a different model.',
-  );
-});
-
-test("generateStructured shows friendly error for model not found", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      statusCode: 404,
-      responseBody: '{"error":{"message":"Model not found"}}',
-      data: {
-        code: 404,
-        message: "Model not found",
-      },
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "nonexistent-model" },
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow(
-    'Model "nonexistent-model" not found or unavailable. Model not found Please check the model name or try a different model.',
-  );
-});
-
-test("generateStructured shows friendly error for access denied", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      statusCode: 403,
-      responseBody: '{"error":{"message":"Access denied"}}',
-      data: {
-        code: 403,
-        message: "Access denied",
-      },
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "gpt-4-turbo" },
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow(
-    'Access denied for model "gpt-4-turbo". Your API key may not have access to this model. Please check your subscription or try a different model.',
-  );
-});
-
-test("generateStructured shows generic provider error message", async () => {
-  calls.length = 0;
-  generateTextImpl = async () => {
-    throw {
-      statusCode: 400,
-      responseBody: '{"error":{"message":"Context length exceeded"}}',
-      data: {
-        code: 400,
-        message: "Context length exceeded",
-      },
-    };
-  };
-
-  expect(
-    async () =>
-      await generateStructured({
-        model: { modelId: "gpt-3.5-turbo" },
-        schema: { type: "object" },
-        system: "sys",
-        user: "prompt",
-      }),
-  ).toThrow(
-    'Provider error for model "gpt-3.5-turbo": Context length exceeded',
-  );
-});

package/src/llm/LLMClient.ts

@@ -1,264 +0,0 @@
-import { generateText, Output, jsonSchema, type ModelMessage } from "ai";
-import type { AnyJSONSchema, Usage, TelemetryAdapter } from "../types";
-import type { UserContent } from "./message";
-
-type GenerateTextParams = Parameters<typeof generateText>[0];
-type ModelType = GenerateTextParams extends { model: infer M } ? M : unknown;
-type MessageType = Array<ModelMessage>;
-
-export type StructuredRequest<T> = {
-  model: ModelType | unknown;
-  system: string;
-  user: UserContent;
-  messages?: MessageType;
-  schema: unknown;
-  schemaName?: string;
-  schemaDescription?: string;
-  strict?: boolean;
-  /**
-   * Telemetry adapter for tracing LLM calls
-   */
-  telemetry?: TelemetryAdapter;
-  /**
-   * Parent span for creating hierarchical traces
-   */
-  parentSpan?: { id: string; traceId: string; name: string; kind: string; startTime: number; parentId?: string };
-};
-
-export type StructuredResponse<T> = {
-  data: T;
-  usage: Usage;
-};
-
-const isZodSchema = (
-  schema: unknown,
-): schema is { safeParse: (data: unknown) => unknown } => {
-  return (
-    typeof schema === "object" &&
-    schema !== null &&
-    "safeParse" in schema &&
-    typeof (schema as { safeParse?: unknown }).safeParse === "function"
-  );
-};
-
-export const generateStructured = async <T>(
-  request: StructuredRequest<T>,
-): Promise<StructuredResponse<T>> => {
-  const { telemetry, parentSpan } = request;
-  
-  // Start LLM span if telemetry is enabled
-  const llmSpan = telemetry?.startSpan({
-    name: "llm.generateStructured",
-    kind: "LLM",
-    parentSpan,
-    attributes: {
-      "llm.schema_name": request.schemaName ?? "extract",
-      "llm.strict": request.strict ?? false,
-    },
-  });
-
-  const startTime = Date.now();
-
-  const schema = isZodSchema(request.schema)
-    ? request.schema
-    : jsonSchema(request.schema as AnyJSONSchema);
-
-  // Check for OpenRouter provider preference attached to the model
-  const preferredProvider = (
-    request.model as { __openrouter_provider?: string }
-  )?.__openrouter_provider;
-
-  if (preferredProvider && process.env.DEBUG) {
-    console.error(
-      `[DEBUG] Routing to OpenRouter provider: ${preferredProvider}`,
-    );
-  }
-
-  const providerOptions = preferredProvider
-    ? {
-        openrouter: {
-          provider: {
-            order: [preferredProvider],
-          },
-        },
-      }
-    : undefined;
-
-  let result;
-  try {
-    result = await generateText({
-      model: request.model as ModelType,
-      output: Output.object({
-        schema: schema as GenerateTextParams extends { schema: infer S }
-          ? S
-          : never,
-        name: request.schemaName ?? "extract",
-        description: request.schemaDescription,
-      }),
-      providerOptions: {
-        openai: {
-          strictJsonSchema: request.strict ?? false,
-        },
-      },
-      system: request.system,
-      messages: (request.messages ?? [
-        { role: "user", content: request.user },
-      ]) as MessageType,
-      ...(providerOptions ? { providerOptions } : {}),
-    });
-  } catch (error) {
-    // Determine model ID for error messages
-    const modelId =
-      typeof request.model === "object" && request.model !== null
-        ? (request.model as { modelId?: string }).modelId ??
-          JSON.stringify(request.model)
-        : String(request.model);
-
-    if (
-      error &&
-      typeof error === "object" &&
-      "responseBody" in error &&
-      "statusCode" in error
-    ) {
-      const apiError = error as {
-        responseBody: unknown;
-        statusCode: number;
-        data?: {
-          code?: number;
-          message?: string;
-          type?: string | null;
-          param?: string | null;
-        };
-      };
-
-      const responseBody = apiError.responseBody;
-      const errorData = apiError.data;
-
-      if (
-        typeof responseBody === "string" &&
-        responseBody.includes("No endpoints found that support image input")
-      ) {
-        throw new Error(
-          `Model "${modelId}" does not support image input. Please use a model that supports images (e.g., gpt-4o, claude-3-5-sonnet, gemini-1.5-pro) or remove the --images and --screenshots flags.`,
-        );
-      }
-
-      if (errorData?.code === 500 || errorData?.message?.includes("Internal Server Error")) {
-        throw new Error(
-          `Provider error for model "${modelId}": Internal server error. The model or provider may be experiencing issues. Please try again or use a different model.`,
-        );
-      }
-
-      if (apiError.statusCode === 401 || errorData?.code === 401) {
-        throw new Error(
-          `Authentication failed for model "${modelId}". Please check your API key is valid and has the necessary permissions.`,
-        );
-      }
-
-      if (apiError.statusCode === 403 || errorData?.code === 403) {
-        throw new Error(
-          `Access denied for model "${modelId}". Your API key may not have access to this model. Please check your subscription or try a different model.`,
-        );
-      }
-
-      if (apiError.statusCode === 429 || errorData?.code === 429) {
-        throw new Error(
-          `Rate limit exceeded for model "${modelId}". Please wait a moment and try again, or use a different model.`,
-        );
-      }
-
-      if (apiError.statusCode === 404 || errorData?.code === 404) {
-        const errorMsg = errorData?.message || "Model not found";
-        throw new Error(
-          `Model "${modelId}" not found or unavailable. ${errorMsg} Please check the model name or try a different model.`,
-        );
-      }
-
-      if (errorData?.message) {
-        throw new Error(
-          `Provider error for model "${modelId}": ${errorData.message}`,
-        );
-      }
-    }
-    
-    // Record error in telemetry
-    if (llmSpan && telemetry) {
-      const latencyMs = Date.now() - startTime;
-      telemetry.recordEvent(llmSpan, {
-        type: "llm_call",
-        model: modelId,
-        provider: "unknown", // Will be determined by the model
-        input: {
-          messages: request.messages ?? [{ role: "user", content: typeof request.user === "string" ? request.user : "" }],
-          temperature: undefined,
-          maxTokens: undefined,
-          schema: request.schema,
-        },
-        error: error instanceof Error ? error : new Error(String(error)),
-        latencyMs,
-      });
-      telemetry.endSpan(llmSpan, {
-        status: "error",
-        error: error instanceof Error ? error : new Error(String(error)),
-        latencyMs,
-      });
-    }
-    
-    throw error;
-  }
-
-  const usageRaw = result.usage ?? {};
-  const inputTokens =
-    "promptTokens" in usageRaw
-      ? (usageRaw.promptTokens as number)
-      : ((usageRaw as { inputTokens?: number }).inputTokens ?? 0);
-  const outputTokens =
-    "completionTokens" in usageRaw
-      ? (usageRaw.completionTokens as number)
-      : ((usageRaw as { outputTokens?: number }).outputTokens ?? 0);
-  const totalTokens =
-    "totalTokens" in usageRaw
-      ? (usageRaw.totalTokens as number)
-      : inputTokens + outputTokens;
-
-  const usage: Usage = {
-    inputTokens,
-    outputTokens,
-    totalTokens,
-  };
-
-  // Record successful LLM call in telemetry
-  if (llmSpan && telemetry) {
-    const latencyMs = Date.now() - startTime;
-    telemetry.recordEvent(llmSpan, {
-      type: "llm_call",
-      model: typeof request.model === "object" && request.model !== null
-        ? (request.model as { modelId?: string }).modelId ?? "unknown"
-        : String(request.model),
-      provider: preferredProvider ?? "unknown",
-      input: {
-        messages: request.messages ?? [{ role: "user", content: typeof request.user === "string" ? request.user : "" }],
-        temperature: undefined,
-        maxTokens: undefined,
-        schema: request.schema,
-      },
-      output: {
-        content: JSON.stringify(result.output),
-        structured: true,
-        usage: {
-          input: inputTokens,
-          output: outputTokens,
-          total: totalTokens,
-        },
-      },
-      latencyMs,
-    });
-    telemetry.endSpan(llmSpan, {
-      status: "ok",
-      output: result.output,
-      latencyMs,
-    });
-  }
-
-  return { data: result.output as T, usage };
-};