Harvey

Build a local document Q&A tool for my own contracts and PDFs. Python 3.11, single project, no web framework, no accounts, no telemetry.

Stack, no alternatives:
- CLI with Typer
- pypdf for text extraction, page numbers preserved
- SQLite with the sqlite-vec extension for vector storage
- OpenAI API for embeddings and answers, key from .env via python-dotenv, plus an --ollama flag that swaps to a local model at http://localhost:11434

Commands:
- ingest PATH: walk a folder, extract text per page, chunk to roughly 800 tokens with 100 overlap, store chunk text plus doc name plus page number, embed and index. Skip files already ingested unless --force.
- ask "QUESTION": retrieve top 12 chunks, then answer with an LLM that is instructed to answer only from the provided chunks and to say "not in these documents" when the answer is absent. Every claim must carry an inline citation like [contract.pdf p.4].
- sources "QUESTION": print the retrieved chunks verbatim with file and page, no LLM, so I can read the raw text.
- docs: list ingested files, page counts, chunk counts.

In scope: local-only storage in ./index.db, deterministic chunking, a --model flag, plain text output.
Out of scope: web UI, multi-user, cloud sync, any bundled case law or statute data, any attempt to cite external legal sources.

Print a one-line disclaimer after every answer: this is a reading aid over my own files, not legal advice, verify each citation.
Include a README with setup, .env.example, and a short section explaining that answers are only as good as the documents I ingested.

# AGENTS.md — Build guide for Harvey

## Project scope
Indexes a folder of your own contracts and PDFs locally, then answers questions about them with quotes and page citations so you can check every claim yourself.

Catalogue verdict: no. You can absolutely build a local RAG assistant over your own PDFs in an afternoon, and for reading your lease or a vendor contract that is genuinely enough. Harvey is not sold on that loop. It is sold on trained-and-evaluated legal workflows, curated case law and regulatory sources under license, deployment that survives a law firm's security review, and the ability to put a name behind an output that a partner will bill against. The thing you cannot one-shot is the confidence to rely on the answer, which in legal work is the entire product. A personal replacement is fine for personal stakes and dangerous the moment money or a filing depends on it.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- An LLM API key, or a local model via Ollama if you would rather nothing leaves the machine
- Your own documents: no licensed case law, no statute databases, no primary sources
- Python 3.11 and a willingness to read the cited passage rather than trust the summary

## Stack and architecture
- Build a local document Q&A tool for my own contracts and PDFs. Python 3.11, single project, no web framework, no accounts, no telemetry.
- Model source documents, editable pages, links or annotations, and exported versions; store source IDs and timestamps for each.
- Interface for this AI for law firms and in-house legal teams workflow: a focused AI for law firms and in-house legal teams input, review, and export interface.

## Security and data integrity
- If An LLM API key, or a local model via Ollama if you would rather nothing leaves the machine is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: Licensed primary law: case law, statutes, filings and regulatory corpora you cannot legally scrape together.

## Agent implementation rules
- Project rule, data: Model source documents, editable pages, links or annotations, and exported versions; store source IDs and timestamps for each.
- Project rule, behavior: ingest PATH: walk a folder, extract text per page, chunk to roughly 800 tokens with 100 overlap, store chunk text plus doc name plus page number, embed and index. Skip files already ingested unless --force.
- Project rule, recovery: If An LLM API key, or a local model via Ollama if you would rather nothing leaves the machine is unavailable, keep the source record and show a recoverable error instead of a fabricated result.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this AI for law firms and in-house legal teams operation with sample or user-owned data: ingest PATH: walk a folder, extract text per page, chunk to roughly 800 tokens with 100 overlap, store chunk text plus doc name plus page number, embed and index. Skip files already ingested unless --force.
- Show a concrete result or export: Print a one-line disclaimer after every answer: this is a reading aid over my own files, not legal advice, verify each citation.
- State the practical limit: Licensed primary law: case law, statutes, filings and regulatory corpora you cannot legally scrape together.

## Engineering roadmap
1. Phase 1, architecture and data: Build a local document Q&A tool for my own contracts and PDFs. Python 3.11, single project, no web framework, no accounts, no telemetry. Model source documents, editable pages, links or annotations, and exported versions; store source IDs and timestamps for each.
2. Phase 2, implement: ingest PATH: walk a folder, extract text per page, chunk to roughly 800 tokens with 100 overlap, store chunk text plus doc name plus page number, embed and index. Skip files already ingested unless --force.
3. Phase 3, implement: docs: list ingested files, page counts, chunk counts.
4. Phase 4, review and output: In scope: local-only storage in ./index.db, deterministic chunking, a --model flag, plain text output. Print a one-line disclaimer after every answer: this is a reading aid over my own files, not legal advice, verify each citation.
5. Phase 5, recovery and acceptance: If An LLM API key, or a local model via Ollama if you would rather nothing leaves the machine is unavailable, keep the source record and show a recoverable error instead of a fabricated result. Verify this invariant with a saved fixture: An invalid input or interrupted operation must retain the source and show a recoverable state; exported records must reload with the same IDs. State the practical limit: Licensed primary law: case law, statutes, filings and regulatory corpora you cannot legally scrape together.

## Paid-product capabilities outside this build
- Licensed primary law: case law, statutes, filings and regulatory corpora you cannot legally scrape together
- Workflow products that have been evaluated by actual lawyers: diligence checklists, redline review, deposition prep
- Firm-grade deployment: SSO, data residency, retention controls, audit logs, security questionnaires answered
- Anyone to blame. Your hallucination is your malpractice exposure
- Integration into the systems legal work actually lives in: DMS, iManage, Word, the review platform

## Implementation prompt
Build a local document Q&A tool for my own contracts and PDFs. Python 3.11, single project, no web framework, no accounts, no telemetry.

Stack, no alternatives:
- CLI with Typer
- pypdf for text extraction, page numbers preserved
- SQLite with the sqlite-vec extension for vector storage
- OpenAI API for embeddings and answers, key from .env via python-dotenv, plus an --ollama flag that swaps to a local model at http://localhost:11434

Commands:
- ingest PATH: walk a folder, extract text per page, chunk to roughly 800 tokens with 100 overlap, store chunk text plus doc name plus page number, embed and index. Skip files already ingested unless --force.
- ask "QUESTION": retrieve top 12 chunks, then answer with an LLM that is instructed to answer only from the provided chunks and to say "not in these documents" when the answer is absent. Every claim must carry an inline citation like [contract.pdf p.4].
- sources "QUESTION": print the retrieved chunks verbatim with file and page, no LLM, so I can read the raw text.
- docs: list ingested files, page counts, chunk counts.

In scope: local-only storage in ./index.db, deterministic chunking, a --model flag, plain text output.
Out of scope: web UI, multi-user, cloud sync, any bundled case law or statute data, any attempt to cite external legal sources.

Print a one-line disclaimer after every answer: this is a reading aid over my own files, not legal advice, verify each citation.
Include a README with setup, .env.example, and a short section explaining that answers are only as good as the documents I ingested.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.