libretto 0.1.5 → 0.2.1

package/dist/shared/llm/client.js

@@ -0,0 +1,115 @@
+import { createVertex } from "@ai-sdk/google-vertex";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateObject } from "ai";
+function parseModel(model) {
+  const slashIndex = model.indexOf("/");
+  if (slashIndex === -1) {
+    throw new Error(
+      `Invalid model string "${model}". Expected format: "provider/model-id" (e.g. "google/gemini-3-flash-preview").`
+    );
+  }
+  const provider = model.slice(0, slashIndex);
+  const modelId = model.slice(slashIndex + 1);
+  if (!["google", "anthropic", "openai"].includes(provider)) {
+    throw new Error(
+      `Unsupported provider "${provider}". Supported providers: google, anthropic, openai.`
+    );
+  }
+  return { provider, modelId };
+}
+function getProviderModel(provider, modelId) {
+  switch (provider) {
+    case "google": {
+      const project = process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT;
+      if (!project) {
+        throw new Error(
+          "Missing GCP project for Vertex AI. Set GOOGLE_CLOUD_PROJECT environment variable and ensure application default credentials are configured (gcloud auth application-default login)."
+        );
+      }
+      const vertex = createVertex({
+        project,
+        location: process.env.GOOGLE_CLOUD_LOCATION || "global"
+      });
+      return vertex(modelId);
+    }
+    case "anthropic": {
+      const apiKey = process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        throw new Error(
+          "Missing API key for Anthropic. Set ANTHROPIC_API_KEY environment variable."
+        );
+      }
+      const anthropic = createAnthropic({ apiKey });
+      return anthropic(modelId);
+    }
+    case "openai": {
+      const apiKey = process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        throw new Error(
+          "Missing API key for OpenAI. Set OPENAI_API_KEY environment variable."
+        );
+      }
+      const openai = createOpenAI({ apiKey });
+      return openai(modelId);
+    }
+  }
+}
+function convertUserContentParts(parts) {
+  return parts.map((part) => {
+    if (part.type === "text") {
+      return { type: "text", text: part.text };
+    }
+    return { type: "image", image: part.image };
+  });
+}
+function convertAssistantContentParts(parts) {
+  return parts.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }));
+}
+function convertMessages(messages) {
+  return messages.map((msg) => {
+    if (msg.role === "user") {
+      if (typeof msg.content === "string") {
+        return { role: "user", content: msg.content };
+      }
+      return {
+        role: "user",
+        content: convertUserContentParts(msg.content)
+      };
+    }
+    if (typeof msg.content === "string") {
+      return { role: "assistant", content: msg.content };
+    }
+    return {
+      role: "assistant",
+      content: convertAssistantContentParts(msg.content)
+    };
+  });
+}
+function createLLMClient(model) {
+  const { provider, modelId } = parseModel(model);
+  const aiModel = getProviderModel(provider, modelId);
+  return {
+    async generateObject(opts) {
+      const result = await generateObject({
+        model: aiModel,
+        prompt: opts.prompt,
+        schema: opts.schema,
+        temperature: opts.temperature ?? 0
+      });
+      return result.object;
+    },
+    async generateObjectFromMessages(opts) {
+      const result = await generateObject({
+        model: aiModel,
+        messages: convertMessages(opts.messages),
+        schema: opts.schema,
+        temperature: opts.temperature ?? 0
+      });
+      return result.object;
+    }
+  };
+}
+export {
+  createLLMClient
+};

package/dist/shared/llm/index.cjs

@@ -0,0 +1,28 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var llm_exports = {};
+__export(llm_exports, {
+  createLLMClient: () => import_client.createLLMClient
+});
+module.exports = __toCommonJS(llm_exports);
+var import_client = require("./client.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createLLMClient
+});

package/dist/shared/llm/index.d.cts

@@ -0,0 +1,3 @@
+export { LLMClient, Message, MessageContentPart } from './types.cjs';
+export { createLLMClient } from './client.cjs';
+import 'zod';

package/dist/shared/llm/index.d.ts

@@ -0,0 +1,3 @@
+export { LLMClient, Message, MessageContentPart } from './types.js';
+export { createLLMClient } from './client.js';
+import 'zod';

package/dist/shared/llm/index.js

@@ -0,0 +1,4 @@
+import { createLLMClient } from "./client.js";
+export {
+  createLLMClient
+};

package/dist/shared/llm/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/shared/llm/types.d.cts

@@ -0,0 +1,34 @@
+import z from 'zod';
+
+type MessageContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    image: string;
+};
+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.
+ */
+interface LLMClient {
+    generateObject<T extends z.ZodType>(opts: {
+        prompt: string;
+        schema: T;
+        temperature?: number;
+    }): Promise<z.infer<T>>;
+    generateObjectFromMessages<T extends z.ZodType>(opts: {
+        messages: Message[];
+        schema: T;
+        temperature?: number;
+    }): Promise<z.infer<T>>;
+}
+
+export type { LLMClient, Message, MessageContentPart };

package/dist/shared/llm/types.d.ts

@@ -0,0 +1,34 @@
+import z from 'zod';
+
+type MessageContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    image: string;
+};
+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.
+ */
+interface LLMClient {
+    generateObject<T extends z.ZodType>(opts: {
+        prompt: string;
+        schema: T;
+        temperature?: number;
+    }): Promise<z.infer<T>>;
+    generateObjectFromMessages<T extends z.ZodType>(opts: {
+        messages: Message[];
+        schema: T;
+        temperature?: number;
+    }): Promise<z.infer<T>>;
+}
+
+export type { LLMClient, Message, MessageContentPart };

package/dist/shared/logger/index.cjs

@@ -0,0 +1,37 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var logger_exports = {};
+__export(logger_exports, {
+  Logger: () => import_logger.Logger,
+  createFileLogSink: () => import_sinks.createFileLogSink,
+  defaultLogger: () => import_logger.defaultLogger,
+  jsonlConsoleSink: () => import_sinks.jsonlConsoleSink,
+  prettyConsoleSink: () => import_sinks.prettyConsoleSink
+});
+module.exports = __toCommonJS(logger_exports);
+var import_logger = require("./logger.js");
+var import_sinks = require("./sinks.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Logger,
+  createFileLogSink,
+  defaultLogger,
+  jsonlConsoleSink,
+  prettyConsoleSink
+});

package/dist/shared/logger/index.d.cts

@@ -0,0 +1,2 @@
+export { LogOptions, Logger, LoggerApi, LoggerSink, MinimalLogger, defaultLogger } from './logger.cjs';
+export { createFileLogSink, jsonlConsoleSink, prettyConsoleSink } from './sinks.cjs';

package/dist/shared/logger/index.d.ts

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

package/dist/shared/logger/index.js

@@ -0,0 +1,13 @@
+import { Logger, defaultLogger } from "./logger.js";
+import {
+  createFileLogSink,
+  prettyConsoleSink,
+  jsonlConsoleSink
+} from "./sinks.js";
+export {
+  Logger,
+  createFileLogSink,
+  defaultLogger,
+  jsonlConsoleSink,
+  prettyConsoleSink
+};

package/dist/shared/logger/logger.cjs

@@ -0,0 +1,213 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var logger_exports = {};
+__export(logger_exports, {
+  Logger: () => Logger,
+  defaultLogger: () => defaultLogger
+});
+module.exports = __toCommonJS(logger_exports);
+function generateId() {
+  return Math.random().toString(36).substring(2, 15);
+}
+const defaultLogger = {
+  info(event, data) {
+    console.log(`[INFO] ${event}`, data ?? "");
+  },
+  warn(event, data) {
+    console.warn(`[WARN] ${event}`, data ?? "");
+  },
+  error(event, data) {
+    console.error(`[ERROR] ${event}`, data ?? "");
+  }
+};
+const sinkLifecycleState = /* @__PURE__ */ new WeakMap();
+function getSinkLifecycleState(sink) {
+  const existingState = sinkLifecycleState.get(sink);
+  if (existingState) {
+    return existingState;
+  }
+  const initialState = { closed: false };
+  sinkLifecycleState.set(sink, initialState);
+  return initialState;
+}
+function isSinkClosedOrClosing(sink) {
+  const state = sinkLifecycleState.get(sink);
+  return Boolean(state?.closed || state?.closing);
+}
+async function closeSinkOnce(sink) {
+  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 {
+    } finally {
+      state.closed = true;
+      state.closing = void 0;
+    }
+  })();
+  return state.closing;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function removeUndefined(data) {
+  if (typeof data === "object" && data !== null) {
+    return Object.fromEntries(
+      Object.entries(data).filter(([_, value]) => value !== void 0)
+    );
+  }
+  return data;
+}
+class Logger {
+  constructor(scopes = [], sinks = [], scopeData = {}) {
+    this.scopes = scopes;
+    this.sinks = sinks;
+    this.scopeData = scopeData;
+    this.prefix = scopes.join(".");
+  }
+  prefix;
+  entry(entry) {
+    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, data, options) {
+    this.entry({ level: "log", event, data, options });
+  }
+  error(event, dataOrError, options) {
+    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 !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "error",
+      event,
+      data,
+      options
+    });
+    if (dataOrError instanceof Error) {
+      return dataOrError;
+    }
+    if (isObject(dataOrError) && dataOrError.error instanceof Error) {
+      return dataOrError.error;
+    }
+    let message = event;
+    if (data !== void 0) {
+      try {
+        message += "\n" + JSON.stringify(data, void 0, 2);
+      } catch {
+        message += "\n[Unserializable error data]";
+      }
+    }
+    return new Error(message);
+  }
+  warn(event, dataOrError, options) {
+    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 !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "warn",
+      event,
+      data,
+      options
+    });
+  }
+  info(event, data, options) {
+    this.entry({ level: "info", event, data, options });
+  }
+  withScope(scope, context = {}) {
+    return new Logger([...this.scopes, scope], this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withContext(context) {
+    return new Logger(this.scopes, this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withSink(sink) {
+    return new Logger(this.scopes, [...this.sinks, sink]);
+  }
+  async flush() {
+    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 {
+      }
+    }
+  }
+  async close() {
+    await this.flush();
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      await closeSinkOnce(sink);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Logger,
+  defaultLogger
+});

package/dist/shared/logger/logger.d.cts

@@ -0,0 +1,82 @@
+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.
+ */
+type MinimalLogger = {
+    info: (event: string, data?: Record<string, any>) => void;
+    warn: (event: string, data?: any) => void;
+    error: (event: string, data?: any) => any;
+};
+/** Default console logger used when callers omit the logger option. */
+declare const defaultLogger: MinimalLogger;
+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?: Record<string, any>, 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>;
+};
+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>;
+};
+declare class Logger implements LoggerApi {
+    private readonly scopes;
+    private readonly sinks;
+    private readonly scopeData;
+    private readonly prefix;
+    constructor(scopes?: string[], sinks?: LoggerSink[], scopeData?: Record<string, any>);
+    entry(entry: {
+        level: "log" | "error" | "warn" | "info";
+        event: string;
+        data?: Record<string, any>;
+        options?: LogOptions;
+    }): void;
+    log(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    error(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): Error;
+    warn(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
+    info(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    withScope(scope: string, context?: Record<string, any>): LoggerApi;
+    withContext(context: Record<string, any>): LoggerApi;
+    withSink(sink: LoggerSink): Logger;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export { type LogOptions, Logger, type LoggerApi, type LoggerSink, type MinimalLogger, defaultLogger };

package/dist/shared/logger/logger.d.ts

@@ -0,0 +1,82 @@
+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.
+ */
+type MinimalLogger = {
+    info: (event: string, data?: Record<string, any>) => void;
+    warn: (event: string, data?: any) => void;
+    error: (event: string, data?: any) => any;
+};
+/** Default console logger used when callers omit the logger option. */
+declare const defaultLogger: MinimalLogger;
+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?: Record<string, any>, 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>;
+};
+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>;
+};
+declare class Logger implements LoggerApi {
+    private readonly scopes;
+    private readonly sinks;
+    private readonly scopeData;
+    private readonly prefix;
+    constructor(scopes?: string[], sinks?: LoggerSink[], scopeData?: Record<string, any>);
+    entry(entry: {
+        level: "log" | "error" | "warn" | "info";
+        event: string;
+        data?: Record<string, any>;
+        options?: LogOptions;
+    }): void;
+    log(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    error(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): Error;
+    warn(event: string, dataOrError?: Error | ({
+        error: Error;
+    } & Record<string, any>) | unknown, options?: LogOptions): void;
+    info(event: string, data?: Record<string, any>, options?: LogOptions): void;
+    withScope(scope: string, context?: Record<string, any>): LoggerApi;
+    withContext(context: Record<string, any>): LoggerApi;
+    withSink(sink: LoggerSink): Logger;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+export { type LogOptions, Logger, type LoggerApi, type LoggerSink, type MinimalLogger, defaultLogger };