Skip to main content

Documentation Index

Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

Extract structured data from pages using AI-powered analysis.
extractFromPage() combines a screenshot with DOM content and sends both to an LLM to extract structured data matching a Zod schema. Because the visual analysis happens in a separate LLM call, it keeps your coding agent’s context window free of raw HTML.
For production workflows, start with the most deterministic source of data:
  • Use captured network requests when the site already returns the data you need as JSON or another structured response.
  • Use Playwright locators and selectors when the content is visible in stable DOM elements.
  • Use regular code or regex to normalize the extracted text when the formatting rules are straightforward.
  • Use a structured LLM call only for formatting or interpretation that is hard to express deterministically.
Use extractFromPage() as the fallback when the page is easier to interpret visually or structurally than it is to parse through network responses or selectors. This path is not fully deterministic.

​
extractFromPage()

async function extractFromPage<T extends z.ZodType>(
  options: ExtractOptions<T>,
): Promise<z.infer<T>>;

​
How it works

  • With selector: waits for the element to be visible, takes a screenshot of just that element, and reads its innerHTML (truncated at 30 000 characters).
  • Without selector: takes a full-page screenshot via CDP and reads the full page HTML (truncated at 50 000 characters).
Both the screenshot and the DOM snippet are sent to the LLM together with your instruction. The response is parsed and validated against your Zod schema before being returned.

​
ExtractOptions<T>

​
page
Page
required
The Playwright Page to extract from.
​
instruction
string
required
A natural-language description of what to extract. For example: "Extract the first 5 search results".
​
schema
T extends z.ZodType
required
A Zod schema that describes the shape of the data you want back. The return type of extractFromPage is z.infer<T>.
​
model
LanguageModel
required
A Vercel AI SDK LanguageModel instance. Pass the result of calling a provider factory such as openai("gpt-4o") from @ai-sdk/openai. The backing model must support vision (multimodal) input because extractFromPage always sends a screenshot.
​
logger
MinimalLogger
Optional logger. Defaults to a simple console-based logger when omitted.
​
selector
string
Optional CSS selector. When provided, the screenshot and DOM capture are scoped to the matching element instead of the full page. Useful for large pages where you only care about one section.

​
Example

import { extractFromPage } from "libretto";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const SearchResult = z.object({
  title: z.string(),
  url: z.string(),
  snippet: z.string(),
});

const results = await extractFromPage({
  page,
  instruction: "Extract the first 5 search results",
  schema: z.array(SearchResult),
  model: openai("gpt-4o"),
  // Optional: scope to a specific element
  selector: ".search-results",
});
// results is typed as Array<{ title: string; url: string; snippet: string }>
Use selector to narrow extraction to a single widget or table when the full page HTML is large. Scoped extraction is faster and uses fewer tokens.

​
Supported providers

Any provider that implements the Vercel AI SDK LanguageModel interface works with extractFromPage and the other LLM-powered functions. The most common ones:
PackageExample
@ai-sdk/openaiopenai("gpt-4o")
@ai-sdk/anthropicanthropic("claude-3-5-sonnet-20241022")
@ai-sdk/googlegoogle("gemini-1.5-pro")
@ai-sdk/google-vertexvertex("gemini-1.5-pro")