Document-intelligence AI agent

Turn messy documents into schema-shaped JSON

One HTTP agent for invoices, contracts, ISO standards, and custom forms. Pass a JSON Schema per request — no separate parser for every layout.

Why DocuLens

Organizations drown in PDFs. Traditional parsers break when templates change. DocuLens combines deterministic extraction with LLM structuring so one deployment serves many document types.

Pain	Solution
Layouts drift; bespoke parsers multiply	Schema-driven API — swap `response_schema` per call
Mixed digital PDFs and scanned pages	PyMuPDF text layer + Tesseract or Google Vision OCR
Unstructured blobs hard to validate	OpenAI structured outputs match your JSON Schema
Need guardrails before LLM	Split pipeline: `/process/pdf` → your API → `/process/text`
Ops wants standard deploy + observability	Docker, Gunicorn, Cloud Run · `GET /health` · OpenAPI at `/docs`
Secrets must not live in git	`OPENAI_API_KEY` exported at runtime only — never in `.env`

How it works

Four steps from upload to structured JSON. Optional guardrail stage between extract and structure.

Upload

POST /process with PDF or .txt plus your response_schema.

Extract

PyMuPDF for text layers; OCR rasterizes scanned pages when needed.

Structure

LLM maps text to your schema via OpenAI structured outputs.

Respond

{"json": { ... }} ready for validation, ETL, or apps.

DocuLens sample schemas and document fixtures for invoices, contracts, and ISO standards

Deploy anywhere

Same agent image from laptop to Cloud Run. Pass API keys at run time, not bake time.

Target	Best for	Quick path
Local dev	Evaluation, schema tuning	`./scripts/setup.sh` → export key → `python -m app.main`
Gunicorn	VM or bare-metal	`gunicorn app.main:app --config gunicorn_config.py`
Docker	Portable CI/CD artifact	`docker build -t doculens .` · `-e OPENAI_API_KEY` at run
Cloud Run	Managed scale-to-zero on GCP	Cloud Build → Artifact Registry → `gcloud run deploy`

Prerequisites

Python 3.12+, OPENAI_API_KEY, Tesseract + Poppler (default OCR) or GCP creds for Vision.

Health check

GET /health returns service id, agent role, and semver for probes and scripts.

API docs

OpenAPI at /openapi.yaml · Swagger UI at /docs when the service is running.

Use cases

Working fixtures in samples/ — swap file and schema; agent behavior stays the same.

Accounts payable

Vendor, line items, totals from invoices. sample_invoice.txt + invoice_schema.json

Legal / procurement

Parties, term, commercial terms from contracts. sample_contract.txt + contract_schema.json

Quality / compliance

ISO 9001 clauses → structured SOP. sample_iso_standard.txt + sop_schema.json

Manufacturing QA

Inspection criteria and check steps. sample_iso_manufacturing.txt + quality_inspection_schema.json

Custom forms

Any PDF or text plus a JSON Schema you define. Resumes, recipes, medical forms, internal PDFs.

Downstream systems

JSON integrates with databases, CRMs, ATS, ETL. Convert to CSV in your reporting layer if needed.

Built for every stakeholder

Engineering gets a clean API; leadership gets one agent instead of many parsers.

Engineering REST + OpenAPI, pluggable OCR/LLM, samples/ for curl and integration tests.

Product / ops Change document behavior via schema updates — not code deploys per template.

Data / analytics Validatable JSON; guardrail-friendly two-stage pipeline before structuring.

Security / compliance Runtime secrets only; data stays on your infra; restrict access at gateway.

Leadership Faster time-to-value vs bespoke parsers; predictable Cloud Run or Docker ops.

Next steps

From first curl to production deploy in an afternoon.

Run ./scripts/setup.sh and POST samples/sample_invoice.txt with invoice_schema.json.
Review API details and common questions in the user guide and FAQ.
Tune with OPENAI_SCHEMA_STRICT and custom prompts in prompts/.
Deploy via Docker or Cloud Run; probe GET /health from your load balancer.
Extend OCR engine, model, or providers through env vars — no fork required.