docseek

Goal-driven document discovery. Give it a website and a goal in plain language, in any language:

"Find the English datasheet of every battery charger" · "Töltsd le a 2026-os havi alap jelentéseket" · "Finde alle Sitzungsunterlagen vom März"

and it crawls the site with a real browser and returns the documents the goal asks for, each with a relevance verdict (accepted, unsure, rejected) and facets such as the period and year it covers.

It is built for sites where the documents are not one link away: behind year filters and tabs, in "load more" listings, in single-page apps that load them from a JSON API, one or two clicks below a listing, or spread over hundreds of pages of look-alike documents.

How it decides

The crawl is driven by a relevance judge that answers four questions, and code does everything else:

1. Is this link a document the goal asks for? Every candidate gets a relevance score and a verdict.
2. What kind of page does this link lead to? Pages are visited in order of how likely they list documents.
3. Does this page still hide documents? If so, the page is escalated to a browsing agent that clicks, fills in and scrolls until it finds them.
4. Which filter value shows the documents? Code finds the page's filters, the judge picks the value, code sets it.

Two judges are built in:

The judge's wording comes from a domain profile (profile): generic works for any goal; fund-reports is an example of a profile tuned for one domain (periodic fund documents). A profile is a small JSON file - see docseek/profiles/ - so you can write one for your own domain.

The browsing agent (escalations, and the agent decision layer that crawls with the agent alone) runs on the same LLM configuration.

Quick start

pip install docseek
playwright install chromium

or from source:

git clone https://github.com/mohojojo/docseek && cd docseek
uv venv && source .venv/bin/activate      # or python -m venv .venv
uv pip install -e ".[dev]"
playwright install chromium

Then start the API:

export ANTHROPIC_API_KEY=...              # or configure any other model, see below
uvicorn docseek.server:app --port 8010

curl -s localhost:8010/v1/discover -H 'Content-Type: application/json' -d '{
  "url": "https://www.example.com/",
  "goal": "Find the 2025 annual reports (PDF)",
  "profile": "generic",
  "max_pages": 30
}'

Or with Docker: docker compose up --build.

Or from the command line (the same crawl, printed as JSON):

docseek https://www.example.com/ "Find the 2025 annual reports (PDF)" --max-pages 30

Any model

# OpenAI
export LLM_PROVIDER=openai-compatible LLM_MODEL=gpt-4.1-mini LLM_API_KEY=sk-...

# a local model through Ollama
export LLM_PROVIDER=openai-compatible LLM_BASE_URL=http://localhost:11434/v1 LLM_MODEL=llama3.1

# Anthropic (the default when ANTHROPIC_API_KEY is set)
export LLM_PROVIDER=anthropic LLM_MODEL=claude-haiku-4-5

The client adapts to what a server accepts (for example OpenAI's reasoning models, which take max_completion_tokens and no temperature). The browsing agent needs a model with tool calling; screenshots need a vision-capable model.

Generated programs

For a site you query again and again, docseek can write a discovery program: a coding agent explores the site once - raw HTML, rendered pages, the JSON calls a page makes - and writes a small Python function that finds the documents the goal asks for. Later requests run the program with no model at all, in seconds, and the relevance judge scores what it returns exactly as it scores a crawl.

export PROGRAMS_DIR=./programs CODEGEN_MODEL=claude-sonnet-5
docseek generate https://www.example.com/ "Find the 2025 annual reports (PDF)"   # a few minutes, once
docseek https://www.example.com/ "Find the 2025 annual reports (PDF)" --programs  # seconds, no model
docseek check                                                                      # has any site changed?

With "programs": true, /v1/discover answers from the site's program when it is healthy, and crawls otherwise: when the program errors, returns nothing where it used to find documents, or keeps fewer than half of what it kept last time, it is marked stale, the crawl answers, and a new program is written in the background. docseek check (or POST /v1/programs/check) replays every program against a snapshot of what it returned before - no model, no judge - and reports ok, grew, shrank or broken.

What a program can do is fenced in: it runs in a separate process with an empty environment, CPU and memory limits, an allowlist of standard-library modules, and no network except the parent's fetcher - the site and its subdomains, the data hosts and POST endpoints the site's own pages used while the program was written, robots.txt, and the same public-address rule as the crawl. This is a boundary, not a hardened jail: the code was written by a model that read untrusted page text, so the feature is off unless PROGRAMS_DIR is set, and a docseek that strangers can reach belongs in a container.

Health cannot tell when a program confidently returns the wrong slice of a site; a crawl or a person can.

Configuration

HTTP API

Main request fields for /v1/discover:

The result lists the documents with relevance, verdict, source (page, sitemap, api, agent), period and year, plus stop_reason, token counts and which model decided.

Crawling responsibly

• robots.txt is honoured for every host the crawl touches.
• SSRF protection: only http(s) URLs whose host resolves exclusively to public addresses are fetched or returned - a hostname pointing at 127.0.0.1 or a cloud metadata address is refused. The same rule applies to URLs a page or a model hands the crawler.
• Pages are visited one at a time by default (max_concurrent); set max_pages and max_seconds to what the site can take.
• Page text reaches the models as data. Instruction-like text in a page is flagged and never acted on.
• Crawl only what you are allowed to, and respect each site's terms.

Evaluating

eval/ measures recall and precision against hand-checked ground truth: see eval/ground_truth/README.md for the format and the scripts (run_jev.py for the judge-driven crawl, run_baseline.py for the agent path, run_codegen.py for generated programs, judge_compare.py for scoring a judge offline on a frozen, labelled candidate set).

Development

uv pip install -e ".[dev]"
playwright install chromium
pytest

The tests run offline: DNS resolution and robots.txt are faked (tests/conftest.py) and every model call is mocked. Browser tests use a local Chromium and are skipped when it is missing.

Licence

Apache-2.0 - see LICENSE. TypeSafe Jev is a third-party service with its own terms; its API client is included, its model is not.