Ask Cooter

Ask Cooter

Turn any PDF — even a scanned, text-free one — into a private, cited knowledgeexpert. Ask Cooter ingests a PDF, extracts clean text, tables, and figuredescriptions from every page with a vision model, embeds it into a vector store,and answers questions about it with citations back to the exact source page —through a CLI, a local chat UI, or an MCP server.

Because extraction is vision-based, it works on scanned documents with noselectable text (the hard case), not just digital PDFs.

Initial use case

The proof-of-concept corpus is a Harley-Davidson Softail (1984–1999) servicemanual — 651 scanned pages, zero embedded text — turned into a mechanic'sassistant ("Ask Cooter") that answers repair questions and cites the page to openfor the original diagram or torque spec. The defaults in .env.example point atthat manual; nothing in the pipeline is motorcycle-specific: set PDF_PATH to anyPDF and re-run the ingest.

See DESIGN.md for the architecture and rationale.

How it works

Any PDF (scanned images or digital text)
  → render each page to PNG            (PyMuPDF)
  → vision extraction (Claude)         → clean markdown + tables + figure text + specs
  → chunk + Voyage embeddings          → stored in Postgres/pgvector
Question → embed → pgvector similarity search → cited passages → answer (CLI / chat UI / MCP)

Stack (as built)

Prerequisites

• Python 3.11+
• PostgreSQL 18 (installed at C:\Program Files\PostgreSQL\18, port 5433)with the pgvector extension. pgvector ships no Windows binaries, so it'scompiled from source (step 1) and installed with a script. The compiled .dllis not committed; build it locally. No Docker.
• API keys: ANTHROPIC_API_KEY (vision extraction) and VOYAGE_API_KEY(embeddings). Anthropic doesn't do embeddings, so Voyage is a separate signup.

Setup (native, no Docker)

python -m venv .venv
. .venv/Scripts/activate            # PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env                 # then fill in the two API keys

1. Build pgvector for PostgreSQL 18 (the compiled .dll isn't committed).From an x64 Native Tools Command Prompt for VS:

git clone --branch v0.8.6 https://github.com/pgvector/pgvector.git
cd pgvector
set PGROOT=C:\Program Files\PostgreSQL\18
nmake /f Makefile.win

Copy the outputs into pgvector-build\ (where the install script looks):

Copy-Item pgvector\vector.dll, pgvector\vector.control, pgvector\sql\vector--*.sql pgvector-build\

On PG18 the standard build links cleanly. (On PG17, EDB's build did not exportfloat_to_shortest_decimal_*; a small shim defining those functions, added toOBJS in Makefile.win, is required. PG18 exports them, so no shim is needed.)

2. Install pgvector into PostgreSQL 18 (copies the files into Program Files —needs admin; the script self-elevates via UAC):

powershell -ExecutionPolicy Bypass -File scripts\install-pgvector.ps1

3. Create the database + role + extension (prompts for the postgressuperuser password; PG18 is on port 5433):

& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U postgres -p 5433 -f scripts\bootstrap-db.sql

4. Create the Ask Cooter tables:

python -m askcooter.cli init-db

Ingest a PDF (one-time, costs API money)

This renders every page of the configured PDF (PDF_PATH), runs each through thevision model, embeds the text, and stores everything. It is resumable — re-runthe same command to retry any pages that failed, and it auto-retries the outputcontent-filter false positives with a model fallback.

Recommended: prototype on a small page range first to eyeball quality and cost:

python -m askcooter.cli ingest --start 88 --end 92      # example pages
python -m askcooter.cli query "primary chaincase oil"

Then run the whole document:

python -m askcooter.cli ingest

Point it at a different PDF: set PDF_PATH in .env. One PDF per database —to switch corpora, use a fresh DATABASE_URL (or truncate pages/chunks andre-init-db), since results are ranked across whatever is in the DB.

Cost note: extraction is one vision call per page (651 for the Softail manual).EXTRACT_MODEL defaults to claude-opus-5 (highest fidelity); setEXTRACT_MODEL=claude-sonnet-5 in .env for a much cheaper run — usually fine forOCR-style extraction. Embeddings (Voyage) are cents.

Ask a question (direct, cited answer)

ask retrieves the relevant passages, hands them to Claude, and returns a directanswer with source-page citations:

python -m askcooter.cli ask "how much oil does the primary chaincase hold?"

query is the raw retrieval view (top matching passages, no synthesis) — usefulfor debugging what the vector search finds:

python -m askcooter.cli query "how do I test the starter solenoid?"
python -m askcooter.cli sections

Chat UI

A local single-page chat with streaming answers, rendered markdown, multi-turncontext, and clickable source citations that open the original page — extractedtext plus the scanned image, with zoom and page-flip:

python -m askcooter.cli web            # http://127.0.0.1:8000

A bike profile (year + model, default 1986 Softail Custom) tailors answers toyour machine. Questions and their answers are saved to Postgres (theuser_history table, keyed by an opaque per-browser token); the history sidebarloads from the DB, and clicking a past question replays its saved answer withsources — no API call. Self-contained (no external assets), light/dark aware. UsesANSWER_MODEL and the keys from .env. Bind elsewhere with --host / --port.

Accessing the database

The data lives in PostgreSQL 18 (askcooter DB, role cooter, port 5433).

• psql shell: powershell -ExecutionPolicy Bypass -File scripts\db-shell.ps1(or & "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U cooter -p 5433 -d askcooter)
• pgAdmin 4 (installed by the EDB Postgres installer): add a server →host localhost, port 5433, database askcooter, user cooter.
• Any GUI (DBeaver, TablePlus): connect to localhost:5433 / askcooter / cooter.

Handy queries: SELECT count(*) FROM pages; · SELECT pdf_page, printed_page, section FROM pages ORDER BY pdf_page; · SELECT count(*) FROM chunks; · SELECT question, created_at FROM user_history ORDER BY id DESC;

Use as an MCP server

Run over stdio:

python -m askcooter.cli serve

Register with Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ask-cooter": {
      "command": "python",
      "args": ["-m", "askcooter.cli", "serve"],
      "cwd": "C:/app/AskCooter",
      "env": {
        "DATABASE_URL": "postgresql://cooter:cooter@localhost:5433/askcooter",
        "VOYAGE_API_KEY": "pa-..."
      }
    }
  }
}

(The server needs VOYAGE_API_KEY to embed incoming queries and DATABASE_URLto reach Postgres. It also needs ANTHROPIC_API_KEY if the ask tool is used —add it to the env block above. search_manual alone does not require it, sincethe MCP host does the synthesis.)

MCP tools

Project layout

askcooter/
  config.py            env-based settings
  db.py                pgvector connection + schema init
  schema.sql           DDL (pages, chunks, user_history)
  ingest/
    render.py          PDF page → PNG
    extract.py         Claude vision → structured JSON
    chunk.py           structure-aware chunking
    embed.py           Voyage embeddings
    pipeline.py        resumable orchestration
  retrieval.py         query embed + pgvector search + spec/section lookups
  answer.py            retrieval + Claude synthesis (the `ask` layer)
  history.py           user_history persistence (record / list / clear)
  mcp_server.py        FastMCP server (5 tools)
  cli.py               init-db / ingest / ask / query / sections / web / serve
  web/
    app.py             FastAPI backend: /api/ask, /api/page, /api/meta, /api/history
    index.html         single-page chat UI
scripts/
  install-pgvector.ps1 copy the built extension into PG18 (admin)
  bootstrap-db.sql     create role/db/extension
  db-shell.ps1         open a psql shell to the DB

Notes & limits

• Page numbers: pdf_page is 0-based internally; the CLI and tools print the1-based PDF page plus the manual's own printed label so you can always find theoriginal.
• Copyright: your source PDF may be copyrighted (the Softail manual is).Keeping Ask Cooter private/personal is the intended use — see DESIGN.md §6 beforeconsidering any public deployment.
• User history: the chat UI writes each Q&A to the user_history table, keyedby an opaque client token (no auth). Past questions reload from the DB and replaytheir saved answers. GET/DELETE /api/history back the sidebar.

License

PolyForm Noncommercial License 1.0.0 — see LICENSE. Copyright 2026SmallAxeIT. Free to use, modify, and share for noncommercial purposes only;commercial use is not granted.

The Harley-Davidson Softail service manual is not part of this repository andis not covered by this license; it is copyrighted by its publisher and excludedfrom version control (see .gitignore).

Known limitations & tech debt

• Embedding dimension is hardcoded in schema.sql (VECTOR(1024)). It mustmatch EMBED_DIM and the Voyage model's native dimension. Changing VOYAGE_MODELto a different-dimension model requires editing the DDL and a full re-embed; thereis no migration path.
• Ingest is sequential. ~1–2s per page (≈15–25 min for 651 pages). A thread poolover pages would parallelize it. Retry is re-running the command (per-page commit +skip); the Anthropic SDK retries 429/5xx transient failures.
• Citation fidelity is prompt-enforced, not guaranteed. ask / answer.pysynthesize a cited answer server-side; search_manual returns raw passages for anMCP host to synthesize. In both paths the model is instructed to cite; there is nopost-check that every claim maps to a retrieved page.
• Chunking uses a char≈token approximation (len//4). The value is stored asmetadata only; chunk boundaries are character-bounded, not token-based.
• Windows/EDB-specific build. The pgvector build and install scripts hardcodeC:\Program Files\PostgreSQL\18 and the MSVC toolchain. Not portable as-is.
• No automated tests. Verification is manual (compile, render, live query).
• Follow-up retrieval uses the current question only. The chat UI passes priorturns to the answer model, but retrieval embeds just the latest question, soelliptical follow-ups ("what about the front one?") can retrieve poorly. Queryrewriting would address it.
• History accumulates duplicate rows. Every ask inserts a user_history row,so re-asking a question stores it again; the sidebar dedups for display, but thetable grows unbounded. Dedup-on-insert or periodic pruning would bound it.
• History token travels in the query string. GET/DELETE /api/history?user_token=…can land in server/access logs. Harmless locally; move to a header or POST bodybefore any networked deployment.
• printed_page is model-read per page. OCR misreads of the printed label arepossible; pdf_page is authoritative for jumping.