libretto 0.4.4 → 0.5.0

package/src/shared/llm/client.ts

@@ -0,0 +1,217 @@
+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",
+] as const;
+
+const VERTEX_PROJECT_ENV_VARS = [
+	"GOOGLE_CLOUD_PROJECT",
+	"GCLOUD_PROJECT",
+] as const;
+
+const SUPPORTED_PROVIDER_ALIASES = {
+	google: "google",
+	gemini: "google",
+	vertex: "vertex",
+	anthropic: "anthropic",
+	codex: "openai",
+	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;
+}
+
+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").`,
+		);
+	}
+	const providerInput = model.slice(0, slashIndex).toLowerCase();
+	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.`,
+		);
+	}
+
+	return { provider, modelId };
+}
+
+export function hasProviderCredentials(
+	provider: Provider,
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	switch (provider) {
+		case "google":
+			return readFirstEnvValue(env, GEMINI_API_KEY_ENV_VARS) !== null;
+		case "vertex":
+			return readFirstEnvValue(env, VERTEX_PROJECT_ENV_VARS) !== null;
+		case "anthropic":
+			return Boolean(env.ANTHROPIC_API_KEY?.trim());
+		case "openai":
+			return Boolean(env.OPENAI_API_KEY?.trim());
+	}
+}
+
+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.";
+		case "vertex":
+			return "Vertex AI project is missing. Set GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and ensure application default credentials are configured.";
+		case "anthropic": {
+			return "Anthropic API key is missing. Set ANTHROPIC_API_KEY.";
+		}
+		case "openai": {
+			return "OpenAI API key is missing. Set OPENAI_API_KEY.";
+		}
+	}
+}
+
+async function getProviderModel(
+	provider: Provider,
+	modelId: string,
+): Promise<LanguageModel> {
+	switch (provider) {
+		case "google": {
+			const apiKey = readFirstEnvValue(process.env, GEMINI_API_KEY_ENV_VARS);
+			if (!apiKey) {
+				throw new Error(missingProviderCredentialsMessage(provider));
+			}
+			const { createGoogleGenerativeAI } = await import("@ai-sdk/google");
+			const google = createGoogleGenerativeAI({ apiKey });
+			return google(modelId);
+		}
+		case "vertex": {
+			const project = readFirstEnvValue(process.env, VERTEX_PROJECT_ENV_VARS);
+			if (!project) {
+				throw new Error(missingProviderCredentialsMessage(provider));
+			}
+			const { createVertex } = await import("@ai-sdk/google-vertex");
+			const vertex = createVertex({
+				project,
+				location: process.env.GOOGLE_CLOUD_LOCATION || "global",
+			});
+			return vertex(modelId);
+		}
+		case "anthropic": {
+			const apiKey = process.env.ANTHROPIC_API_KEY?.trim();
+			if (!apiKey) {
+				throw new Error(missingProviderCredentialsMessage(provider));
+			}
+			const { createAnthropic } = await import("@ai-sdk/anthropic");
+			const anthropic = createAnthropic({ apiKey });
+			return anthropic(modelId);
+		}
+		case "openai": {
+			const apiKey = process.env.OPENAI_API_KEY?.trim();
+			if (!apiKey) {
+				throw new Error(missingProviderCredentialsMessage(provider));
+			}
+			const { createOpenAI } = await import("@ai-sdk/openai");
+			const openai = createOpenAI({ apiKey });
+			return openai(modelId);
+		}
+	}
+}
+
+function convertUserContentParts(parts: MessageContentPart[]) {
+	return parts.map((part) => {
+		if (part.type === "text") {
+			return { type: "text" as const, text: part.text };
+		}
+		return {
+			type: "image" as const,
+			image: part.image,
+			...(part.mediaType ? { mediaType: part.mediaType } : {}),
+		};
+	});
+}
+
+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: 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),
+			};
+		}
+		if (typeof msg.content === "string") {
+			return { role: "assistant", content: msg.content };
+		}
+		return {
+			role: "assistant",
+			content: convertAssistantContentParts(msg.content),
+		};
+	});
+}
+
+export function createLLMClient(model: string): LLMClient {
+	const { provider, modelId } = parseModel(model);
+	let modelPromise: Promise<LanguageModel> | null = null;
+
+	const getModel = () => {
+		modelPromise ??= getProviderModel(provider, modelId);
+		return modelPromise;
+	};
+
+	return {
+		async generateObject<T extends ZodType>(opts: {
+			prompt: string;
+			schema: T;
+			temperature?: number;
+		}): Promise<ZodOutput<T>> {
+			const aiModel = await getModel();
+			const result = await generateObject({
+				model: aiModel,
+				prompt: opts.prompt,
+				schema: opts.schema,
+				temperature: opts.temperature ?? 0,
+			});
+			return result.object as ZodOutput<T>;
+		},
+
+		async generateObjectFromMessages<T extends ZodType>(opts: {
+			messages: Message[];
+			schema: T;
+			temperature?: number;
+		}): Promise<ZodOutput<T>> {
+			const aiModel = await getModel();
+			const result = await generateObject({
+				model: aiModel,
+				messages: convertMessages(opts.messages),
+				schema: opts.schema,
+				temperature: opts.temperature ?? 0,
+			});
+			return result.object as ZodOutput<T>;
+		},
+	};
+}

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,6 @@
+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,352 @@
+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);
+		}
+	}
+}