libretto 0.2.3 → 0.2.4

package/README.md

@@ -1,231 +1,125 @@
 # Libretto
 
-A TypeScript library for browser automation with AI-powered recovery and data extraction. Built on Playwright.
-
-## Features
-
-- **AI-powered recovery** — Vision-based agent that automatically detects and dismisses popups or obstacles using an LLM
-- **Structured data extraction** — Extract typed data from web pages using AI vision + Zod schemas
-- **Error detection** — Classify form/submission errors against known patterns
-- **In-browser network requests** — Execute authenticated fetch calls inside the page context with optional Zod validation
-- **File downloads** — Trigger and intercept file downloads via click, with optional save-to-disk
-- **Dry-run mode** — Skip mutations in development without side effects
-- **Pluggable LLM** — Bring your own LLM provider (Claude, GPT, etc.) via a simple interface
-- **Pluggable logging** — All runtime functions accept an optional logger; defaults to console output
+AI-powered browser automation library and CLI built on Playwright.
 
 ## Installation
 
 ```bash
 pnpm add libretto playwright zod
+npx libretto init
 ```
 
-`playwright` and `zod` are peer dependencies.
+> **pnpm users:** add `onlyBuiltDependencies` to your `package.json` to allow
+> Playwright's postinstall script to run:
+>
+> ```jsonc
+> // package.json
+> {
+>   "pnpm": {
+>     "onlyBuiltDependencies": ["playwright"]
+>   }
+> }
+> ```
 
 ## Quick Start
 
-```typescript
-import { chromium } from "playwright";
-import { extractFromPage, attemptWithRecovery } from "libretto";
-
-const browser = await chromium.launch();
-const page = await browser.newPage();
-
-await page.goto("https://example.com/login");
-await page.fill("#email", "user@example.com");
-await page.fill("#password", "secret");
-
-// Automatically retry with AI popup recovery on failure
-await attemptWithRecovery(page, () => page.click('button[type="submit"]'));
-
-await browser.close();
-```
-
-## Runtime Functions
+### 1. Configure your LLM
 
-### Recovery
-
-#### `attemptWithRecovery(page, fn, logger?, llmClient?)`
-
-Executes a function and, if it fails, uses AI vision to detect and dismiss popups before retrying once.
+The easiest way is to use the built-in Vercel AI SDK adapter with any compatible provider:
 
 ```typescript
-import { attemptWithRecovery } from "libretto";
+import { createLLMClientFromModel } from "libretto/llm";
+import { openai } from "@ai-sdk/openai";
 
-await attemptWithRecovery(page, async () => {
-  await page.click('button[type="submit"]');
-}, undefined, llmClient);
+const llmClient = createLLMClientFromModel(openai("gpt-4o"));
 ```
 
-#### `executeRecoveryAgent(page, instruction, logger?, llmClient?)`
-
-Runs a multi-step vision-based recovery agent that takes screenshots and executes browser actions (click, type, scroll, etc.) to resolve obstacles.
+Or use any other provider:
 
 ```typescript
-import { executeRecoveryAgent } from "libretto";
-
-await executeRecoveryAgent(
-  page,
-  "Close the cookie consent banner",
-  undefined,
-  llmClient,
-);
-```
+import { createLLMClientFromModel } from "libretto";
+import { anthropic } from "@ai-sdk/anthropic";
 
-#### `detectSubmissionError(page, error, logContext, llmClient, knownErrors?, logger?)`
-
-Uses a screenshot + LLM vision to detect if an error occurred during a form submission. Matches against provided known error patterns.
-
-```typescript
-import { detectSubmissionError } from "libretto";
-
-try {
-  await page.click("#submit");
-} catch (error) {
-  const result = await detectSubmissionError(page, error, "checkout", llmClient, [
-    { id: "duplicate", errorPatterns: ["already exists"], userMessage: "Duplicate entry" },
-  ]);
-  console.log(result.errorId, result.message);
-}
+const llmClient = createLLMClientFromModel(anthropic("claude-sonnet-4-20250514"));
 ```
 
-### Data Extraction
-
-#### `extractFromPage(options)`
-
-Extract structured data from a page using AI vision + a Zod schema.
-
-```typescript
-import { extractFromPage } from "libretto";
-import { z } from "zod";
-
-const result = await extractFromPage({
-  page,
-  llmClient,
-  instruction: "Extract the product name and price",
-  schema: z.object({
-    name: z.string(),
-    price: z.number(),
-  }),
-  selector: ".product-card", // optional — scopes to a specific element
-});
-// result is typed as { name: string; price: number }
-```
-
-### Network
-
-#### `pageRequest(page, config, options?)`
-
-Executes a fetch call inside the browser context via `page.evaluate()`, inheriting the page's cookies and auth state. Supports optional Zod validation.
-
-```typescript
-import { pageRequest } from "libretto";
-import { z } from "zod";
-
-const data = await pageRequest(
-  page,
-  {
-    url: "https://example.com/api/profile",
-    method: "GET",
-    responseType: "json",
-  },
-  {
-    schema: z.object({ name: z.string(), email: z.string() }),
-  },
-);
-```
-
-### Downloads
-
-#### `downloadViaClick(page, selector, options?)`
-
-Triggers a file download by clicking a DOM element and intercepts the result.
-
-```typescript
-import { downloadViaClick } from "libretto";
-
-const { buffer, filename } = await downloadViaClick(page, "#download-btn");
-```
-
-#### `downloadAndSave(page, selector, options?)`
-
-Same as `downloadViaClick` but also writes the file to disk.
-
-```typescript
-import { downloadAndSave } from "libretto";
-
-const { savedTo } = await downloadAndSave(page, "#export-csv", {
-  savePath: "./exports/report.csv",
-});
-```
-
-## LLM Client Interface
-
-Provide your own implementation backed by any LLM provider:
+You can also implement the `LLMClient` interface directly for full control:
 
 ```typescript
 import type { LLMClient } from "libretto";
 
-const myLLMClient: LLMClient = {
+const llmClient: LLMClient = {
   async generateObject({ prompt, schema, temperature }) {
     // Call your LLM, return parsed + validated result
   },
   async generateObjectFromMessages({ messages, schema, temperature }) {
-    // Call your LLM with message history, return parsed + validated result
+    // Call your LLM with message history (may include images)
   },
 };
 ```
 
-## Logging
-
-All runtime functions accept an optional `logger` parameter. When omitted, output goes to `console.log` with `[INFO]`, `[WARN]`, `[ERROR]` prefixes.
-
-For structured logging, use the built-in `Logger` class:
+### 2. Write a workflow
 
 ```typescript
-import { Logger, createFileLogSink, prettyConsoleSink } from "libretto";
+import { workflow } from "libretto";
+import { z } from "zod";
 
-const logger = new Logger()
-  .withSink(createFileLogSink({ filePath: "./app.log" }))
-  .withSink(prettyConsoleSink);
+export default workflow({
+  name: "extract-product",
+  schema: z.object({ url: z.string() }),
+  handler: async (ctx) => {
+    const page = ctx.page;
+    await page.goto(ctx.params.url);
 
-const scoped = logger.withScope("auth");
-scoped.info("login attempt", { user: "alice" });
-scoped.error("login failed", { reason: "bad password" });
-```
+    const data = await ctx.extract({
+      instruction: "Extract the product name and price",
+      schema: z.object({ name: z.string(), price: z.number() }),
+    });
 
-## Module Exports
+    return data;
+  },
+});
+```
 
-Libretto provides granular imports:
+### 3. Run it
 
-| Import                   | Contents                                                  |
-| ------------------------ | --------------------------------------------------------- |
-| `libretto`               | Everything                                                |
-| `libretto/logger`        | `Logger`, `defaultLogger`, sinks                          |
-| `libretto/recovery`      | `attemptWithRecovery`, `executeRecoveryAgent`, `detectSubmissionError` |
-| `libretto/extract`       | `extractFromPage`                                         |
-| `libretto/network`       | `pageRequest`                                             |
-| `libretto/download`      | `downloadViaClick`, `downloadAndSave`                     |
-| `libretto/debug`         | `debugPause`                                              |
-| `libretto/config`        | `isDryRun`, `isDebugMode`, `shouldPauseBeforeMutation`    |
-| `libretto/instrumentation` | `instrumentPage`, `installInstrumentation`              |
-| `libretto/visualization` | Ghost cursor and highlight helpers                        |
-| `libretto/run`           | `launchBrowser`                                           |
-| `libretto/state`         | Session state serialization and parsing                   |
-| `libretto/llm`           | `LLMClient` type                                          |
+```bash
+npx libretto run ./workflows/extract-product.ts extractProduct \
+  --params '{"url": "https://example.com/product"}'
+```
 
-## Configuration
+## CLI Commands
 
-Runtime flags via environment variables:
+```
+npx libretto init                  # Copy skills, install Playwright Chromium
+npx libretto open <url>            # Launch browser and open URL
+npx libretto run <file> <export>   # Run a workflow
+npx libretto ai configure <preset> # Configure AI runtime (codex, claude, gemini)
+npx libretto snapshot              # Capture page screenshot + HTML
+npx libretto exec <code>           # Execute Playwright code
+```
 
-| Env Variable          | Effect                                              |
-| --------------------- | --------------------------------------------------- |
-| `LIBRETTO_DEBUG`      | Enable debug mode                                   |
-| `LIBRETTO_DRY_RUN`   | Enable dry-run mode (defaults to `true` in development) |
+Run `npx libretto help` for the full list.
 
-## Development
+## Module Exports
 
-```bash
-pnpm install
-pnpm build         # compile to dist/
-pnpm type-check    # typecheck without emitting
-```
+| Import                     | Contents                                                      |
+| -------------------------- | ------------------------------------------------------------- |
+| `libretto`                 | Everything                                                    |
+| `libretto/llm`             | `LLMClient` type, `createLLMClient`, `createLLMClientFromModel` |
+| `libretto/recovery`        | `attemptWithRecovery`, `executeRecoveryAgent`, `detectSubmissionError` |
+| `libretto/extract`         | `extractFromPage`                                             |
+| `libretto/network`         | `pageRequest`                                                 |
+| `libretto/download`        | `downloadViaClick`, `downloadAndSave`                         |
+| `libretto/logger`          | `Logger`, `defaultLogger`, sinks                              |
+| `libretto/debug`           | `debugPause`                                                  |
+| `libretto/config`          | `isDryRun`, `isDebugMode`, `shouldPauseBeforeMutation`        |
+| `libretto/instrumentation` | `instrumentPage`, `installInstrumentation`                    |
+| `libretto/visualization`   | Ghost cursor and highlight helpers                            |
+| `libretto/run`             | `launchBrowser`                                               |
+| `libretto/state`           | Session state serialization and parsing                       |
+
+## Links
+
+- [GitHub](https://github.com/saffron-health/libretto)
+- [Issues](https://github.com/saffron-health/libretto/issues)

package/dist/cli/cli.js

@@ -4,6 +4,7 @@ import { registerAICommands } from "./commands/ai.js";
 import { registerBrowserCommands } from "./commands/browser.js";
 import { registerExecutionCommands } from "./commands/execution.js";
 import { registerLogCommands } from "./commands/logs.js";
+import { registerInitCommand } from "./commands/init.js";
 import { registerSnapshotCommands } from "./commands/snapshot.js";
 import {
   closeLogger,
@@ -26,6 +27,7 @@ const CLI_COMMANDS = /* @__PURE__ */ new Set([
   "pages",
   "resume",
   "close",
+  "init",
   "--help",
   "-h",
   "help"
@@ -34,6 +36,7 @@ function printUsage() {
   console.log(`Usage: libretto-cli <command> [--session <name>]
 
 Commands:
+  init [--skip-browsers] Initialize libretto (copy skills, install browsers)
   open <url> [--headless] Launch browser and open URL (headed by default)
                           Automatically loads saved profile if available
   run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--headed|--headless] [--debug]  Run an exported Libretto workflow from a file; pass --debug to enable pause-on-failure debugging (or --no-debug to disable)
@@ -160,6 +163,7 @@ function createParser(logger) {
   parser = registerLogCommands(parser);
   parser = registerAICommands(parser);
   parser = registerSnapshotCommands(parser, logger);
+  parser = registerInitCommand(parser);
   parser = parser.command("help", "Show usage", () => {
   }, () => {
     printUsage();

package/dist/cli/commands/init.js

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, cpSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { REPO_ROOT } from "../core/context.js";
+function getSkillSourceDir() {
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = join(thisDir, "..", "..", "..");
+  const skillDir = join(pkgRoot, "skill");
+  if (existsSync(skillDir)) return skillDir;
+  const skillsDir = join(pkgRoot, "skills");
+  if (existsSync(skillsDir)) return skillsDir;
+  throw new Error(
+    "Could not find skill/ or skills/ directory in the libretto package."
+  );
+}
+function copySkills() {
+  const src = getSkillSourceDir();
+  const files = readdirSync(src);
+  if (files.length === 0) {
+    console.log("  No skill files found to copy.");
+    return;
+  }
+  const targets = [
+    join(REPO_ROOT, ".agents", "skills", "libretto"),
+    join(REPO_ROOT, ".claude", "skills", "libretto")
+  ];
+  for (const target of targets) {
+    mkdirSync(target, { recursive: true });
+    cpSync(src, target, { recursive: true });
+    console.log(`  \u2713 Copied skill files to ${target}`);
+  }
+}
+function installBrowsers() {
+  console.log("\nInstalling Playwright Chromium...");
+  const result = spawnSync("npx", ["playwright", "install", "chromium"], {
+    stdio: "inherit",
+    shell: true
+  });
+  if (result.status === 0) {
+    console.log("  \u2713 Playwright Chromium installed");
+  } else {
+    console.error(
+      "  \u2717 Failed to install Playwright Chromium. Run manually: npx playwright install chromium"
+    );
+  }
+}
+function checkSnapshotLLM() {
+  const hasAnyCreds = process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
+  console.log("\nSnapshot LLM configuration:");
+  if (hasAnyCreds) {
+    console.log("  \u2713 LLM credentials detected");
+  } else {
+    console.log("  \u2717 No LLM credentials found.");
+    console.log("    Set one of the following environment variables:");
+    console.log("      GOOGLE_CLOUD_PROJECT  (for Vertex AI / Gemini)");
+    console.log("      ANTHROPIC_API_KEY     (for Claude)");
+    console.log("      OPENAI_API_KEY        (for GPT)");
+    console.log(
+      "    Then configure via: npx libretto ai configure <preset>"
+    );
+  }
+}
+function registerInitCommand(yargs) {
+  return yargs.command(
+    "init",
+    "Initialize libretto in the current project",
+    (cmd) => cmd.option("skip-browsers", {
+      type: "boolean",
+      default: false,
+      describe: "Skip Playwright Chromium installation"
+    }),
+    (argv) => {
+      console.log("Initializing libretto...\n");
+      console.log("Copying skill files...");
+      try {
+        copySkills();
+      } catch (err) {
+        console.error(
+          `  \u2717 ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      if (!argv["skip-browsers"]) {
+        installBrowsers();
+      } else {
+        console.log("\nSkipping browser installation (--skip-browsers)");
+      }
+      checkSnapshotLLM();
+      console.log("\n\u2713 libretto init complete");
+    }
+  );
+}
+export {
+  registerInitCommand
+};

package/dist/cli/core/context.js

@@ -53,6 +53,11 @@ function ensureLibrettoSetup() {
   if (!existsSync(LIBRETTO_GITIGNORE_PATH)) {
     writeFileSync(LIBRETTO_GITIGNORE_PATH, LIBRETTO_GITIGNORE_CONTENT, "utf-8");
   }
+  const agentsSkillsDir = join(REPO_ROOT, ".agents", "skills", "libretto");
+  const claudeSkillsDir = join(REPO_ROOT, ".claude", "skills", "libretto");
+  if (!existsSync(agentsSkillsDir) && !existsSync(claudeSkillsDir)) {
+    console.log("[libretto] Skills not installed. Run 'npx libretto init' to complete setup.");
+  }
 }
 function createLoggerForSession(session) {
   validateSessionName(session);

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   attemptWithRecovery: () => import_recovery.attemptWithRecovery,
   clearHighlights: () => import_highlight.clearHighlights,
   createFileLogSink: () => import_sinks.createFileLogSink,
+  createLLMClientFromModel: () => import_ai_sdk_adapter.createLLMClientFromModel,
   debugPause: () => import_pause.debugPause,
   defaultLogger: () => import_logger.defaultLogger,
   detectSubmissionError: () => import_errors.detectSubmissionError,
@@ -63,6 +64,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_logger = require("./shared/logger/logger.js");
 var import_sinks = require("./shared/logger/sinks.js");
+var import_ai_sdk_adapter = require("./shared/llm/ai-sdk-adapter.js");
 var import_state = require("./shared/state/index.js");
 var import_agent = require("./runtime/recovery/agent.js");
 var import_recovery = require("./runtime/recovery/recovery.js");
@@ -90,6 +92,7 @@ var import_workflow = require("./shared/workflow/workflow.js");
   attemptWithRecovery,
   clearHighlights,
   createFileLogSink,
+  createLLMClientFromModel,
   debugPause,
   defaultLogger,
   detectSubmissionError,

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 export { LogOptions, Logger, LoggerApi, LoggerSink, MinimalLogger, defaultLogger } from './shared/logger/logger.cjs';
 export { createFileLogSink, jsonlConsoleSink, prettyConsoleSink } from './shared/logger/sinks.cjs';
 export { LLMClient, Message, MessageContentPart } from './shared/llm/types.cjs';
+export { createLLMClientFromModel } from './shared/llm/ai-sdk-adapter.cjs';
 export { SESSION_STATE_VERSION, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './shared/state/session-state.cjs';
 export { executeRecoveryAgent } from './runtime/recovery/agent.cjs';
 export { attemptWithRecovery } from './runtime/recovery/recovery.cjs';
@@ -16,4 +17,5 @@ export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.cjs';
 export { LIBRETTO_WORKFLOW_BRAND, LibrettoAuthProfile, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowMetadata, workflow } from './shared/workflow/workflow.cjs';
 import 'zod';
+import 'ai';
 import 'playwright';

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { LogOptions, Logger, LoggerApi, LoggerSink, MinimalLogger, defaultLogger } from './shared/logger/logger.js';
 export { createFileLogSink, jsonlConsoleSink, prettyConsoleSink } from './shared/logger/sinks.js';
 export { LLMClient, Message, MessageContentPart } from './shared/llm/types.js';
+export { createLLMClientFromModel } from './shared/llm/ai-sdk-adapter.js';
 export { SESSION_STATE_VERSION, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './shared/state/session-state.js';
 export { executeRecoveryAgent } from './runtime/recovery/agent.js';
 export { attemptWithRecovery } from './runtime/recovery/recovery.js';
@@ -16,4 +17,5 @@ export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.js';
 export { LIBRETTO_WORKFLOW_BRAND, LibrettoAuthProfile, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowMetadata, workflow } from './shared/workflow/workflow.js';
 import 'zod';
+import 'ai';
 import 'playwright';

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   prettyConsoleSink,
   jsonlConsoleSink
 } from "./shared/logger/sinks.js";
+import { createLLMClientFromModel } from "./shared/llm/ai-sdk-adapter.js";
 import {
   SESSION_STATE_VERSION,
   SessionStatusSchema,
@@ -74,6 +75,7 @@ export {
   attemptWithRecovery,
   clearHighlights,
   createFileLogSink,
+  createLLMClientFromModel,
   debugPause,
   defaultLogger,
   detectSubmissionError,

package/dist/shared/llm/ai-sdk-adapter.cjs

@@ -0,0 +1,61 @@
+"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 ai_sdk_adapter_exports = {};
+__export(ai_sdk_adapter_exports, {
+  createLLMClientFromModel: () => createLLMClientFromModel
+});
+module.exports = __toCommonJS(ai_sdk_adapter_exports);
+var import_ai = require("ai");
+function createLLMClientFromModel(model) {
+  return {
+    async generateObject(opts) {
+      const { object } = await (0, import_ai.generateObject)({
+        model,
+        schema: opts.schema,
+        prompt: opts.prompt,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    },
+    async generateObjectFromMessages(opts) {
+      const messages = opts.messages.map((msg) => {
+        if (typeof msg.content === "string") {
+          return { role: msg.role, content: msg.content };
+        }
+        return {
+          role: msg.role,
+          content: msg.content.map(
+            (part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", image: part.image }
+          )
+        };
+      });
+      const { object } = await (0, import_ai.generateObject)({
+        model,
+        schema: opts.schema,
+        messages,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createLLMClientFromModel
+});

package/dist/shared/llm/ai-sdk-adapter.d.cts

@@ -0,0 +1,22 @@
+import { LanguageModel } from 'ai';
+import { LLMClient } from './types.cjs';
+import 'zod';
+
+/**
+ * Creates a libretto LLMClient from a Vercel AI SDK LanguageModel.
+ *
+ * This eliminates the need for consumers to write their own adapter
+ * when using @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google-vertex,
+ * or any other Vercel AI SDK-compatible provider.
+ *
+ * @example
+ * ```typescript
+ * import { createLLMClientFromModel } from "libretto/llm";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const llmClient = createLLMClientFromModel(openai("gpt-4o"));
+ * ```
+ */
+declare function createLLMClientFromModel(model: LanguageModel): LLMClient;
+
+export { createLLMClientFromModel };

package/dist/shared/llm/ai-sdk-adapter.d.ts

@@ -0,0 +1,22 @@
+import { LanguageModel } from 'ai';
+import { LLMClient } from './types.js';
+import 'zod';
+
+/**
+ * Creates a libretto LLMClient from a Vercel AI SDK LanguageModel.
+ *
+ * This eliminates the need for consumers to write their own adapter
+ * when using @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google-vertex,
+ * or any other Vercel AI SDK-compatible provider.
+ *
+ * @example
+ * ```typescript
+ * import { createLLMClientFromModel } from "libretto/llm";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const llmClient = createLLMClientFromModel(openai("gpt-4o"));
+ * ```
+ */
+declare function createLLMClientFromModel(model: LanguageModel): LLMClient;
+
+export { createLLMClientFromModel };

package/dist/shared/llm/ai-sdk-adapter.js

@@ -0,0 +1,37 @@
+import { generateObject } from "ai";
+function createLLMClientFromModel(model) {
+  return {
+    async generateObject(opts) {
+      const { object } = await generateObject({
+        model,
+        schema: opts.schema,
+        prompt: opts.prompt,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    },
+    async generateObjectFromMessages(opts) {
+      const messages = opts.messages.map((msg) => {
+        if (typeof msg.content === "string") {
+          return { role: msg.role, content: msg.content };
+        }
+        return {
+          role: msg.role,
+          content: msg.content.map(
+            (part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", image: part.image }
+          )
+        };
+      });
+      const { object } = await generateObject({
+        model,
+        schema: opts.schema,
+        messages,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    }
+  };
+}
+export {
+  createLLMClientFromModel
+};

package/dist/shared/llm/index.cjs

@@ -18,11 +18,14 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var llm_exports = {};
 __export(llm_exports, {
-  createLLMClient: () => import_client.createLLMClient
+  createLLMClient: () => import_client.createLLMClient,
+  createLLMClientFromModel: () => import_ai_sdk_adapter.createLLMClientFromModel
 });
 module.exports = __toCommonJS(llm_exports);
 var import_client = require("./client.js");
+var import_ai_sdk_adapter = require("./ai-sdk-adapter.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createLLMClient
+  createLLMClient,
+  createLLMClientFromModel
 });

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

@@ -1,3 +1,5 @@
 export { LLMClient, Message, MessageContentPart } from './types.cjs';
 export { createLLMClient } from './client.cjs';
+export { createLLMClientFromModel } from './ai-sdk-adapter.cjs';
 import 'zod';
+import 'ai';

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

@@ -1,3 +1,5 @@
 export { LLMClient, Message, MessageContentPart } from './types.js';
 export { createLLMClient } from './client.js';
+export { createLLMClientFromModel } from './ai-sdk-adapter.js';
 import 'zod';
+import 'ai';

package/dist/shared/llm/index.js

@@ -1,4 +1,6 @@
 import { createLLMClient } from "./client.js";
+import { createLLMClientFromModel } from "./ai-sdk-adapter.js";
 export {
-  createLLMClient
+  createLLMClient,
+  createLLMClientFromModel
 };

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

@@ -17,13 +17,45 @@ type Message = {
  * 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`.
  */
 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.infer<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;

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

@@ -17,13 +17,45 @@ type Message = {
  * 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`.
  */
 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.infer<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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -105,15 +105,9 @@
     "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "@ai-sdk/anthropic": {
-      "optional": true
-    },
-    "@ai-sdk/google-vertex": {
-      "optional": true
-    },
-    "@ai-sdk/openai": {
-      "optional": true
-    }
+    "@ai-sdk/anthropic": { "optional": true },
+    "@ai-sdk/google-vertex": { "optional": true },
+    "@ai-sdk/openai": { "optional": true }
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.53",