Document AI Assistant

Document AI Assistant is a phase-based Flask API for document-grounded Q&A using retrieval-augmented generation.

It accepts PDF uploads, chunks content, stores embeddings in Pinecone, retrieves relevant chunks with Vertex AI embeddings, and answers with evidence-backed responses through LangGraph orchestration.

Features

• Upload and validate PDFs
• Page-aware chunking with deterministic metadata
• Embedding generation with Vertex AI abstraction
• Pinecone vector store for indexing and retrieval
• LangGraph orchestration for validation/retrieval/generation control flow
• Grounded responses with citations (document_id, filename, page)
• Rejection when evidence is insufficient
• Structured errors and request-id propagation
• CI/lint/test pipeline and Docker image
• RAG evaluation runner with persisted results

Diagram

flowchart TD
    A[POST /api/v1/documents] --> B[PDF validation]
    B --> C[Text extraction]
    C --> D[Chunking]
    D --> E[Vertex AI Embeddings]
    E --> F[Pinecone upsert]

    Q[POST /api/v1/questions] --> R[LangGraph validate]
    R --> S[Retriever]
    S --> P[Pinecone query]
    P --> G[Answer generator]
    G --> H[Structured response]

    M[GET /health] --> I[Health JSON]

Loading

Tech stack

• Python 3.11+
• Flask
• LangGraph
• Google Vertex AI (Gemini embeddings + generation)
• Pinecone
• Pytest + Ruff + Black

Project structure

document-ai-assistant/
├── src/
│   ├── api/
│   ├── agent/
│   ├── config.py
│   ├── evaluation/
│   ├── generation/
│   ├── ingestion/
│   ├── logging_config.py
│   ├── retrieval/
│   └── services/
├── tests/
├── docs/
├── evaluation/
├── .github/workflows/
├── Dockerfile
├── requirements.txt
└── requirements-dev.txt

Setup

python -m venv .venv
. .venv/Scripts/activate
make install

Environment

Copy .env.example to .env and fill required values:

• GOOGLE_CLOUD_PROJECT
• GOOGLE_CLOUD_LOCATION
• VERTEX_CHAT_MODEL
• VERTEX_EMBEDDING_MODEL
• PINECONE_API_KEY
• PINECONE_INDEX_NAME
• RATE_LIMIT_ENABLED
• RATE_LIMIT_REQUESTS_PER_WINDOW
• RATE_LIMIT_WINDOW_SECONDS

Run

make run

API

• GET /health
• POST /api/v1/documents
• GET /api/v1/documents
• DELETE /api/v1/documents/{document_id}
• POST /api/v1/questions

Example usage

curl -X POST http://localhost:8080/api/v1/documents \
  -F "file=@./sample.pdf"

curl -X POST http://localhost:8080/api/v1/questions \
  -H "Content-Type: application/json" \
  -d '{"question": "How many vacation days are provided?", "document_ids": []}'

Testing

make test
make lint
make typecheck
make coverage

Evaluation

make evaluate

The report is written under evaluation/results/ as timestamped JSON.

Docker

make docker-build
make docker-run

Deployment

A Cloud Run deployment workflow is available in .github/workflows/deploy.yml.

See:

• docs/deployment.md
• docs/architecture.md
• docs/decisions.md
• docs/security.md
• docs/api.md

Limitations

• In development, auth is optional; in production, APP_ENV=production requires API_KEY and authenticated requests via X-API-Key.
• Pinecone namespace and index must be created in advance.
• application/x-pdf may vary by browser/clients.

License

MIT.