analog-sdk 0.16.0

Python SDK for Analog — Analog lets any AI understand websites as code. Webpages in, structured records out: deterministic, local-first, honest.

analog-sdk

Python SDK and command-line app for Analog. Analog lets any AI understand websites as code — webpages in, structured records out: deterministic, zero-shot, local-first. The extraction pipeline contains no LLMs. Given the same page URL and HTML, the same engine produces the same records. A live page's HTML can change between fetches.

Install

macOS, Linux, or WSL:

curl -LsSf https://getanalog.io/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://getanalog.io/install.ps1 | iex"

The installer puts the analog command on your PATH as an isolated uv tool. If uv is already installed, use uv tool install analog-sdk. Homebrew users can instead run brew install getanalog/tap/analog; pipx install analog-sdk and pip install analog-sdk in a managed virtual environment also work with Python 3.10+.

Analog's browser downloads automatically on first use. To install it ahead of time, run analog browser install. The complete installation options and CI guidance live in the installation guide.

Create an account and connect this terminal with analog signup (an invite code is required during the private alpha). Use analog login for an existing account or another machine. The credential is stored locally and picked up automatically by the SDK, CLI, and MCP server; see authentication for its storage, scope, and revocation model.

Extract a page

From the shell:

analog get https://quotes.toscrape.com/js/

Analog renders the page, returns its structured records, saves the result locally, and prints a handle such as 20260719-k7m2p9. Use that handle with analog open, describe, find, distinct, export, or diff without fetching the page again. Run analog --help for the complete command surface.

The same call in Python:

from analog import analog

result = analog("https://quotes.toscrape.com/js/")
print(result.preview())

for section in result.structured_content:
    print(section.label, section.records)

analog() uses the built-in browser by default. Its main controls are reveal_all, load_all, expand_all, and pages; the Fetching guide explains when to use each. Pass fetcher=HttpFetcher() for a plain HTTP request, supply your own Fetcher, or use html= when you already have the page content. For a local markdown conversion with no extraction or account, set mode="local".

Result shape

An AnalogResponse is an orientation view plus the page's data:

• structured_content is the ordered list of extracted Section objects.
• Each section carries records, field metadata, and its own markdown.
• collections provides high-confidence unions over compatible physical sections, with one identity-deduplicated local records view and pointers back to every placement.
• outline reports the significant page areas and what happened to them.
• navigation preserves the page's labeled link trees.
• warnings, pagination details, and browse actions disclose partial or uncertain coverage.
• handle identifies the local saved result.

Read result.preview() first. Then use result.section(label), sections_by_kind(kind), or find(...) to narrow the data before pulling whole record sets. Export helpers include to_json(), to_yaml(), to_csv(), and the optional pandas-backed to_dataframe().

A page can contain several unrelated sections: for example, a catalog, a reviews area, and a comparison table. Analog preserves those boundaries instead of silently pooling unlike records. When several physical sections are confidently parts of the same dataset, result.collections[0].records offers the combined view while collection.sections preserves every authored placement. Work with one section, one Collection, all sections of a shared kind, or project common fields explicitly. Field names are a best-effort starting point when the page supplies no useful label; field values preserve what the page rendered. Coverage notes call out withheld content, unusual rows, page-owned truncation, pagination, and interactive controls that were available but not used.

Results are saved by default as structured records and page markdown, never raw HTML. Reopen them with analog.open(handle), latest(), and history(); pass save=False to skip persistence. The Results guide covers querying, field statistics, filters, numeric values, exports, renaming, several sections on one page, retention, and CLI exit codes. Exact Python names, parameters, and return types are in the compact Python API reference.

Data flow and privacy

Pages are fetched on your machine. The SDK uses a local headless browser, which visits as an unauthenticated user by default. Analog receives the URL and rendered page content for extraction. The structured result comes back and, unless disabled, is saved in your local cache alongside the page's markdown. Raw HTML is used for the request and local markdown conversion, then dropped rather than written to the result store.

Authenticated content is sent only when you explicitly provide it through html= or a custom fetcher. Point Analog at content that is acceptable to send, or use mode="local" to keep the page entirely on your machine. Local and private-network addresses are declined by default; reaching a development server or intranet host requires the explicit allow_private=True opt-in.

Library failures derive from AnalogError, with narrower types for authentication, connectivity, rate limits, version skew, fetch refusals, robots.txt decisions, incompatible sections, and saved-result problems. Catch the narrow type when your application has a specific recovery path; otherwise catch AnalogError at the integration boundary. The API reference lists the complete exception inventory.

Extraction URLs are never logged. A quality report includes the URL you explicitly submit; it never includes page content. Read Privacy & security for the complete data, credential, fetching-identity, and network-boundary contracts.

Where to go next

• Quickstart — the shortest path from installation to a useful saved result.
• Fit check — decide whether a page belongs in a structured extraction workflow before spending one.
• Fetching and Results — control page capture, then query and export what came back.
• MCP server — expose the same workflow as tools to an MCP client.
• Limitations and Troubleshooting — known boundaries and fixes for common failures.

The docs site is the durable owner for task guidance; this README stays a short landing page. analog docs prints its URL when you need to hand the documentation to another process, and the core docs are also included in the site's /llms.txt and /llms-full.txt views.

Use analog feedback to report a poor extraction or request a feature. Use analog contact or email [e-mail] for support.

License

MIT — see LICENSE.