sprawll 0.0.2

Evidence-gated scrape-to-artifact harness: artifacts you can defend

sprawll

Research artifacts you can defend.

Every AI research tool can write you a report.
sprawll is the one that refuses to publish a claim it can't pin to an archived source.

---

Highlights

• 🧾 Evidence-gated output — only claims that survive span-level verification against archived sources ship; everything else is withheld, never silently included
• 📦 Byte-for-byte archives — every source captured as WARC, with canonical snapshots every claim offset points into
• 🔢 Deterministic numeric guard — every figure in a claim must literally exist in a cited source
• 🔒 Local-first — prefers a local Ollama model; sources and drafts never leave your machine
• 💸 Hard budget cap — API fallback is checked against a dollar ceiling before every call
• 🔁 Replayable — re-verify any run from its archive with zero network access

Quick start

$ pip install sprawll
$ sprawll research-pack "solar e-bike charging on university campuses" \
      -u https://example.edu/solar-project \
      -u https://example.org/cycling-economy

What you get back:

Artifact	What it is
report.md	Only claims that survived verification, each cited; single-source claims flagged
diagnostics.md	Every claim that failed, with the exact unsupported span named
corpus.warc.gz	The sources as they existed when fetched, byte-for-byte
snapshots/	The canonical extracted text every claim offset points into

[!NOTE] The promise is precise: defensible against this archived corpus, retrieved on these dates. Not "true". Nobody can honestly sell you "true"; we can sell you "checkable".

How it verifies

Source-first pipeline:

fetch → archive (WARC) → extract → harvest facts → draft (only from harvested facts) → ground → render

The grounding gate has two layers:

1. Span model (LettuceDetect, MIT) — checks every claim against source text, chunked with tracked offsets
2. Numeric guard (deterministic) — every figure in a claim must literally exist in a cited source. Catches the hedged wrong numbers models gloss over

Publication is binary: supported claims ship, everything else goes to diagnostics. Claims one source supports and another contradicts publish as supported but contested. If the span model is unavailable, the LLM-judge fallback brands the whole report DEGRADED.

Local-first

sprawll prefers a local LLM. If Ollama is running, your sources and drafts never leave your machine:

$ ollama pull qwen3:14b   # ~9 GB, fits a 12 GB GPU

API keys (ANTHROPIC_API_KEY / OPENAI_API_KEY) are the fallback, capped by a hard dollar ceiling (SPRAWLL_BUDGET_USD, default $2 — checked before every call). Pin explicitly:

$ export SPRAWLL_LLM=ollama/qwen3:14b
$ export SPRAWLL_LLM=litellm/anthropic/claude-sonnet-5

No LLM at all? sprawll refuses to draft undefended text — sprawll audit still grounds claims you wrote yourself.

Replay and audit

$ sprawll research-pack --from-archive runs/<run-dir>   # re-verify, no network
$ sprawll audit claims.json snapshots/                  # just the grounding gate

Failed sources are taxonomized (fetch_failed, robots_blocked, paywalled, timeout, extract_empty) and shown in the report's source table — a source that couldn't be archived is a fact about the corpus, not a rounding error.

Install notes

[!TIP] Core is pure-Python pip. Fetching uses crawl4ai (real browser) when installed — pip install sprawll[crawl] then playwright install chromium — and falls back to plain HTTP (marked DEGRADED in fetch notes) when not.

• First grounding run downloads the LettuceDetect weights (~1.5 GB).

License

MIT

---

_{Defensible beats plausible.}