docagent

An agent that reads raw documents (PDF, DOCX, TXT, Excel) and turns them into structured data — CSV to start, Excel/databases to follow.

Status: Phase 1a

• read_documents — reads a file or a directory of files into normalized {source, page, text, metadata} records. Supports PDF (text-based), DOCX, TXT, and Excel. Scanned/OCR PDFs are not yet supported (needs a local-vs-API evaluation, tracked for a later slice).
• write_to_csv — writes a list of flat records to a CSV file, with optional explicit column ordering.
• A single extractor agent (LangChain create_agent, backed by Claude) that calls read_documents, proposes a flat schema, and drafts records as a structured ExtractionResult — no evaluator agent yet (that's Phase 1b).
• A CLI that runs the extractor, shows you the proposed schema, and only writes the CSV once you confirm it.

Setup

cp .env.example .env   # then fill in ANTHROPIC_API_KEY
uv sync

Usage

uv run docagent path/to/documents output.csv --instructions "map to vendor, amount, date"

This prints the proposed schema and a sample of the drafted records, then prompts for confirmation before writing output.csv.

Development

uv run pytest --cov=docagent --cov-report=term-missing
uv run ruff check .

Tests cover read_documents, write_to_csv, config, cli, and that agent.py builds correctly (using a fake API key — no network call). The live extractor run against a real document set has not been exercised end-to-end here; that needs a real ANTHROPIC_API_KEY and should be smoke-tested manually before relying on it.

Roadmap

• 1b — evaluator agent that checks the extractor's records against the source text, with a bounded retry loop back to the extractor.
• OCR support for scanned/image PDFs (local unstructured/tesseract vs. a 3rd-party API — needs a quality comparison first).
• write_to_excel, write_to_db tools.
• Web wrapper: email verification, file upload, human-in-the-loop schema review in-browser, delivery by email. See the architecture diagram from planning for the full multi-agent shape this is heading toward.