libretto 0.4.4 → 0.5.1

package/{dist/shared/llm/client.cjs → src/shared/llm/client.ts}

@@ -1,81 +1,69 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var client_exports = {};
-__export(client_exports, {
-  createLLMClient: () => createLLMClient,
-  hasProviderCredentials: () => hasProviderCredentials,
-  missingProviderCredentialsMessage: () => missingProviderCredentialsMessage,
-  parseModel: () => parseModel
-});
-module.exports = __toCommonJS(client_exports);
-var import_ai = require("ai");
+import { generateObject, type LanguageModel, type ModelMessage } from "ai";
+import type { ZodType, output as ZodOutput } from "zod";
+import type { LLMClient, Message, MessageContentPart } from "./types.js";
+
+export type Provider = "google" | "vertex" | "anthropic" | "openai";
+
 const GEMINI_API_KEY_ENV_VARS = [
   "GEMINI_API_KEY",
-  "GOOGLE_GENERATIVE_AI_API_KEY"
-];
+  "GOOGLE_GENERATIVE_AI_API_KEY",
+] as const;
+
 const VERTEX_PROJECT_ENV_VARS = [
   "GOOGLE_CLOUD_PROJECT",
-  "GCLOUD_PROJECT"
-];
+  "GCLOUD_PROJECT",
+] as const;
+
 const SUPPORTED_PROVIDER_ALIASES = {
   google: "google",
   gemini: "google",
   vertex: "vertex",
   anthropic: "anthropic",
   codex: "openai",
-  openai: "openai"
-};
-function readFirstEnvValue(env, names) {
+  openai: "openai",
+} as const satisfies Record<string, Provider>;
+
+function readFirstEnvValue(
+  env: NodeJS.ProcessEnv,
+  names: readonly string[],
+): string | null {
   for (const name of names) {
     const value = env[name]?.trim();
     if (value) return value;
   }
   return null;
 }
-function parseModel(model) {
+
+export function parseModel(model: string): {
+  provider: Provider;
+  modelId: string;
+} {
   const slashIndex = model.indexOf("/");
   if (slashIndex === -1) {
     throw new Error(
-      `Invalid model string "${model}". Expected format: "provider/model-id" (for example "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-3-flash-preview", or "vertex/gemini-2.5-pro").`
+      `Invalid model string "${model}". Expected format: "provider/model-id" (for example "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-3-flash-preview", or "vertex/gemini-2.5-pro").`,
     );
   }
   const providerInput = model.slice(0, slashIndex).toLowerCase();
-  const provider = SUPPORTED_PROVIDER_ALIASES[providerInput];
+  const provider =
+    SUPPORTED_PROVIDER_ALIASES[
+      providerInput as keyof typeof SUPPORTED_PROVIDER_ALIASES
+    ];
   const modelId = model.slice(slashIndex + 1);
+
   if (!provider) {
     throw new Error(
-      `Unsupported provider "${providerInput}". Supported providers: openai/codex, anthropic, google (Gemini API), and vertex.`
+      `Unsupported provider "${providerInput}". Supported providers: openai/codex, anthropic, google (Gemini API), and vertex.`,
     );
   }
+
   return { provider, modelId };
 }
-function hasProviderCredentials(provider, env = process.env) {
+
+export function hasProviderCredentials(
+  provider: Provider,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
   switch (provider) {
     case "google":
       return readFirstEnvValue(env, GEMINI_API_KEY_ENV_VARS) !== null;
@@ -87,7 +75,8 @@ function hasProviderCredentials(provider, env = process.env) {
       return Boolean(env.OPENAI_API_KEY?.trim());
   }
 }
-function missingProviderCredentialsMessage(provider) {
+
+export function missingProviderCredentialsMessage(provider: Provider): string {
   switch (provider) {
     case "google":
       return "Gemini API key is missing. Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.";
@@ -101,7 +90,11 @@ function missingProviderCredentialsMessage(provider) {
     }
   }
 }
-async function getProviderModel(provider, modelId) {
+
+async function getProviderModel(
+  provider: Provider,
+  modelId: string,
+): Promise<LanguageModel> {
   switch (provider) {
     case "google": {
       const apiKey = readFirstEnvValue(process.env, GEMINI_API_KEY_ENV_VARS);
@@ -120,7 +113,7 @@ async function getProviderModel(provider, modelId) {
       const { createVertex } = await import("@ai-sdk/google-vertex");
       const vertex = createVertex({
         project,
-        location: process.env.GOOGLE_CLOUD_LOCATION || "global"
+        location: process.env.GOOGLE_CLOUD_LOCATION || "global",
       });
       return vertex(modelId);
     }
@@ -144,30 +137,38 @@ async function getProviderModel(provider, modelId) {
     }
   }
 }
-function convertUserContentParts(parts) {
+
+function convertUserContentParts(parts: MessageContentPart[]) {
   return parts.map((part) => {
     if (part.type === "text") {
-      return { type: "text", text: part.text };
+      return { type: "text" as const, text: part.text };
     }
     return {
-      type: "image",
+      type: "image" as const,
       image: part.image,
-      ...part.mediaType ? { mediaType: part.mediaType } : {}
+      ...(part.mediaType ? { mediaType: part.mediaType } : {}),
     };
   });
 }
-function convertAssistantContentParts(parts) {
-  return parts.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }));
+
+function convertAssistantContentParts(parts: MessageContentPart[]) {
+  return parts
+    .filter(
+      (part): part is MessageContentPart & { type: "text" } =>
+        part.type === "text",
+    )
+    .map((part) => ({ type: "text" as const, text: part.text }));
 }
-function convertMessages(messages) {
-  return messages.map((msg) => {
+
+function convertMessages(messages: Message[]): ModelMessage[] {
+  return messages.map((msg): ModelMessage => {
     if (msg.role === "user") {
       if (typeof msg.content === "string") {
         return { role: "user", content: msg.content };
       }
       return {
         role: "user",
-        content: convertUserContentParts(msg.content)
+        content: convertUserContentParts(msg.content),
       };
     }
     if (typeof msg.content === "string") {
@@ -175,44 +176,49 @@ function convertMessages(messages) {
     }
     return {
       role: "assistant",
-      content: convertAssistantContentParts(msg.content)
+      content: convertAssistantContentParts(msg.content),
     };
   });
 }
-function createLLMClient(model) {
+
+export function createLLMClient(model: string): LLMClient {
   const { provider, modelId } = parseModel(model);
-  let modelPromise = null;
+  let modelPromise: Promise<LanguageModel> | null = null;
+
   const getModel = () => {
     modelPromise ??= getProviderModel(provider, modelId);
     return modelPromise;
   };
+
   return {
-    async generateObject(opts) {
+    async generateObject<T extends ZodType>(opts: {
+      prompt: string;
+      schema: T;
+      temperature?: number;
+    }): Promise<ZodOutput<T>> {
       const aiModel = await getModel();
-      const result = await (0, import_ai.generateObject)({
+      const result = await generateObject({
         model: aiModel,
         prompt: opts.prompt,
         schema: opts.schema,
-        temperature: opts.temperature ?? 0
+        temperature: opts.temperature ?? 0,
       });
-      return result.object;
+      return result.object as ZodOutput<T>;
     },
-    async generateObjectFromMessages(opts) {
+
+    async generateObjectFromMessages<T extends ZodType>(opts: {
+      messages: Message[];
+      schema: T;
+      temperature?: number;
+    }): Promise<ZodOutput<T>> {
       const aiModel = await getModel();
-      const result = await (0, import_ai.generateObject)({
+      const result = await generateObject({
         model: aiModel,
         messages: convertMessages(opts.messages),
         schema: opts.schema,
-        temperature: opts.temperature ?? 0
+        temperature: opts.temperature ?? 0,
       });
-      return result.object;
-    }
+      return result.object as ZodOutput<T>;
+    },
   };
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createLLMClient,
-  hasProviderCredentials,
-  missingProviderCredentialsMessage,
-  parseModel
-});

package/src/shared/llm/index.ts

@@ -0,0 +1,3 @@
+export type { LLMClient, Message, MessageContentPart } from "./types.js";
+export { createLLMClient } from "./client.js";
+export { createLLMClientFromModel } from "./ai-sdk-adapter.js";

package/src/shared/llm/types.ts

@@ -0,0 +1,63 @@
+import type z from "zod";
+
+export type MessageContentPart =
+  | { type: "text"; text: string }
+  | { type: "image"; image: string | Uint8Array; mediaType?: string };
+
+export type Message = {
+  role: "user" | "assistant";
+  content: string | MessageContentPart[];
+};
+
+/**
+ * Pluggable LLM client interface.
+ *
+ * Users provide their own implementation backed by any LLM provider
+ * (OpenAI, Anthropic, etc.). Libretto uses this interface for AI extraction,
+ * recovery agents, and error detection.
+ *
+ * **Error handling:** implementations should throw on failure rather than
+ * returning sentinel values (e.g. `null` or `undefined`). Libretto relies
+ * on exceptions to trigger retry/recovery logic.
+ *
+ * A ready-made adapter for the Vercel AI SDK is available via
+ * {@link createLLMClientFromModel} in `libretto/llm`.
+ */
+export interface LLMClient {
+  /**
+   * Generate a structured object from a single text prompt.
+   *
+   * The underlying model **must** support structured / JSON output so that
+   * the response can be parsed and validated against the provided Zod schema.
+   *
+   * @param opts.prompt - The text prompt sent to the model.
+   * @param opts.schema - A Zod schema describing the expected response shape.
+   * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
+   * @returns The parsed object matching the schema.
+   * @throws On LLM or parsing failure.
+   */
+  generateObject<T extends z.ZodType>(opts: {
+    prompt: string;
+    schema: T;
+    temperature?: number;
+  }): Promise<z.output<T>>;
+
+  /**
+   * Generate a structured object from a conversation-style message array.
+   *
+   * Messages may contain **image content** (base64 data URIs via
+   * {@link MessageContentPart}), so the backing model must support
+   * vision / multimodal input when images are present.
+   *
+   * @param opts.messages - Ordered list of user/assistant messages, potentially multimodal.
+   * @param opts.schema - A Zod schema describing the expected response shape.
+   * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
+   * @returns The parsed object matching the schema.
+   * @throws On LLM or parsing failure.
+   */
+  generateObjectFromMessages<T extends z.ZodType>(opts: {
+    messages: Message[];
+    schema: T;
+    temperature?: number;
+  }): Promise<z.output<T>>;
+}

package/src/shared/logger/index.ts

@@ -0,0 +1,13 @@
+export {
+  Logger,
+  defaultLogger,
+  type LoggerApi,
+  type MinimalLogger,
+  type LoggerSink,
+  type LogOptions,
+} from "./logger.js";
+export {
+  createFileLogSink,
+  prettyConsoleSink,
+  jsonlConsoleSink,
+} from "./sinks.js";

package/src/shared/logger/logger.ts

@@ -0,0 +1,358 @@
+function generateId(): string {
+  return Math.random().toString(36).substring(2, 15);
+}
+
+export type LogOptions = {
+  timestamp?: Date;
+};
+
+/**
+ * Minimal logger interface accepted by public-facing runtime functions.
+ * Any logger with info/warn/error methods satisfies this — no need to
+ * implement withScope, withContext, flush, etc.
+ */
+export type MinimalLogger = {
+  info: (event: string, data?: any) => void;
+  warn: (event: string, data?: any) => void;
+  error: (event: string, data?: any) => any;
+};
+
+/** Default console logger used when callers omit the logger option. */
+export const defaultLogger: MinimalLogger = {
+  info(event, data) {
+    console.log(`[INFO] ${event}`, data ?? "");
+  },
+  warn(event, data) {
+    console.warn(`[WARN] ${event}`, data ?? "");
+  },
+  error(event, data) {
+    console.error(`[ERROR] ${event}`, data ?? "");
+  },
+};
+
+export type LoggerApi = {
+  log: (
+    event: string,
+    data?: Record<string, any>,
+    options?: LogOptions,
+  ) => void;
+  /**
+   * Logs an error and returns an Error object that can be thrown
+   *
+   * either pass in an Error directly as data or as { error: Error, ...other_data }
+   */
+  error: (
+    event: string,
+    data?: Error | ({ error: Error } & Record<string, any>) | unknown,
+    options?: LogOptions,
+  ) => Error;
+  warn: (
+    event: string,
+    data?: Error | ({ error: Error } & Record<string, any>) | unknown,
+    options?: LogOptions,
+  ) => void;
+  info: (
+    event: string,
+    data?: Error | ({ error: Error } & Record<string, any>) | unknown,
+    options?: LogOptions,
+  ) => void;
+
+  /**
+   * Context passed in will be attached to all entries in this scope.
+   */
+  withScope: (scope: string, context?: Record<string, any>) => LoggerApi;
+
+  /**
+   * Context passed in will be attached to all entries.
+   */
+  withContext: (context: Record<string, any>) => LoggerApi;
+
+  /**
+   * Flushes all sinks in reverse order (most recently added first).
+   */
+  flush: () => Promise<void>;
+};
+
+export type LoggerSink = {
+  write: (args: {
+    id: string;
+    scope: string;
+    level: "log" | "error" | "warn" | "info";
+    event: string;
+    data: Record<string, any>;
+    options?: LogOptions;
+  }) => void;
+  flush?: () => Promise<void>;
+  close?: () => Promise<void>;
+};
+
+type SinkLifecycleState = {
+  closed: boolean;
+  closing?: Promise<void>;
+};
+
+const sinkLifecycleState = new WeakMap<LoggerSink, SinkLifecycleState>();
+
+function getSinkLifecycleState(sink: LoggerSink): SinkLifecycleState {
+  const existingState = sinkLifecycleState.get(sink);
+  if (existingState) {
+    return existingState;
+  }
+
+  const initialState: SinkLifecycleState = { closed: false };
+  sinkLifecycleState.set(sink, initialState);
+  return initialState;
+}
+
+function isSinkClosedOrClosing(sink: LoggerSink): boolean {
+  const state = sinkLifecycleState.get(sink);
+  return Boolean(state?.closed || state?.closing);
+}
+
+async function closeSinkOnce(sink: LoggerSink): Promise<void> {
+  if (!sink.close) {
+    return;
+  }
+
+  const state = getSinkLifecycleState(sink);
+  if (state.closed) {
+    return;
+  }
+
+  if (state.closing) {
+    return state.closing;
+  }
+
+  state.closing = (async () => {
+    try {
+      await sink.close?.();
+    } catch {
+      // Ignore close errors - we're likely shutting down
+    } finally {
+      state.closed = true;
+      state.closing = undefined;
+    }
+  })();
+
+  return state.closing;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function removeUndefined(data: any): any {
+  if (typeof data === "object" && data !== null) {
+    return Object.fromEntries(
+      Object.entries(data).filter(([_, value]) => value !== undefined),
+    );
+  }
+  return data;
+}
+
+export class Logger implements LoggerApi {
+  private readonly prefix: string;
+
+  constructor(
+    private readonly scopes: string[] = [],
+    private readonly sinks: LoggerSink[] = [],
+    private readonly scopeData: Record<string, any> = {},
+  ) {
+    this.prefix = scopes.join(".");
+  }
+
+  entry(entry: {
+    level: "log" | "error" | "warn" | "info";
+    event: string;
+    data?: Record<string, any>;
+    options?: LogOptions;
+  }) {
+    this.sinks.forEach((sink) => {
+      if (isSinkClosedOrClosing(sink)) {
+        return;
+      }
+
+      sink.write({
+        id: generateId(),
+        scope: this.prefix,
+        level: entry.level,
+        event: entry.event,
+        data: removeUndefined({ ...this.scopeData, ...entry.data }),
+        options: entry.options,
+      });
+    });
+  }
+
+  log(event: string, data?: Record<string, any>, options?: LogOptions) {
+    this.entry({ level: "log", event, data, options });
+  }
+
+  error(
+    event: string,
+    dataOrError?: Error | ({ error: Error } & Record<string, any>) | unknown,
+    options?: LogOptions,
+  ) {
+    const data =
+      dataOrError instanceof Error
+        ? {
+            error: {
+              type: dataOrError.constructor.name,
+              message: dataOrError.message,
+              stack: dataOrError.stack || null,
+            },
+          }
+        : isObject(dataOrError) && dataOrError.error instanceof Error
+          ? {
+              ...dataOrError,
+              error: {
+                type: dataOrError.error.constructor.name,
+                message: dataOrError.error.message,
+                stack: dataOrError.error.stack || null,
+              },
+            }
+          : isObject(dataOrError)
+            ? dataOrError
+            : dataOrError !== undefined
+              ? { error: dataOrError }
+              : undefined;
+
+    this.entry({
+      level: "error",
+      event,
+      data: data as Error | Record<string, any>,
+      options,
+    });
+
+    if (dataOrError instanceof Error) {
+      return dataOrError;
+    }
+
+    if (isObject(dataOrError) && dataOrError.error instanceof Error) {
+      return dataOrError.error;
+    }
+
+    let message = event;
+    if (data !== undefined) {
+      try {
+        message += "\n" + JSON.stringify(data, undefined, 2);
+      } catch {
+        message += "\n[Unserializable error data]";
+      }
+    }
+    return new Error(message);
+  }
+
+  warn(
+    event: string,
+    dataOrError?: Error | ({ error: Error } & Record<string, any>) | unknown,
+    options?: LogOptions,
+  ) {
+    const data =
+      dataOrError instanceof Error
+        ? {
+            error: {
+              type: dataOrError.constructor.name,
+              message: dataOrError.message,
+              stack: dataOrError.stack || null,
+            },
+          }
+        : isObject(dataOrError) && dataOrError.error instanceof Error
+          ? {
+              ...dataOrError,
+              error: {
+                type: dataOrError.error.constructor.name,
+                message: dataOrError.error.message,
+                stack: dataOrError.error.stack || null,
+              },
+            }
+          : isObject(dataOrError)
+            ? dataOrError
+            : dataOrError !== undefined
+              ? { error: dataOrError }
+              : undefined;
+
+    this.entry({
+      level: "warn",
+      event,
+      data: data as Record<string, any>,
+      options,
+    });
+  }
+
+  info(
+    event: string,
+    dataOrError?: Error | ({ error: Error } & Record<string, any>) | unknown,
+    options?: LogOptions,
+  ) {
+    const data =
+      dataOrError instanceof Error
+        ? {
+            error: {
+              type: dataOrError.constructor.name,
+              message: dataOrError.message,
+              stack: dataOrError.stack || null,
+            },
+          }
+        : isObject(dataOrError) && dataOrError.error instanceof Error
+          ? {
+              ...dataOrError,
+              error: {
+                type: dataOrError.error.constructor.name,
+                message: dataOrError.error.message,
+                stack: dataOrError.error.stack || null,
+              },
+            }
+          : isObject(dataOrError)
+            ? dataOrError
+            : dataOrError !== undefined
+              ? { error: dataOrError }
+              : undefined;
+
+    this.entry({
+      level: "info",
+      event,
+      data: data as Record<string, any>,
+      options,
+    });
+  }
+
+  withScope(scope: string, context: Record<string, any> = {}): LoggerApi {
+    return new Logger([...this.scopes, scope], this.sinks, {
+      ...this.scopeData,
+      ...context,
+    });
+  }
+
+  withContext(context: Record<string, any>): LoggerApi {
+    return new Logger(this.scopes, this.sinks, {
+      ...this.scopeData,
+      ...context,
+    });
+  }
+
+  withSink(sink: LoggerSink): Logger {
+    return new Logger(this.scopes, [...this.sinks, sink]);
+  }
+
+  async flush(): Promise<void> {
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      if (isSinkClosedOrClosing(sink)) continue;
+      try {
+        await sink.flush?.();
+      } catch {
+        // Ignore flush errors - we're likely shutting down
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.flush();
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      await closeSinkOnce(sink);
+    }
+  }
+}