Gravitas

Internal workflow for messy legal-style documents: extract text (native PDF, Tesseract OCR, or MarkItDown), optional Groq OCR refine before chunking, hybrid RAG (Chroma + BM25), grounded drafting with inspectable [E#] evidence tags, and an operator edit memory loop.

Resource	Description
plan.md	Assessment-aligned scope and build plan
DIRECTORY_STRUCTURE.md	Folder map
docs/ARCHITECTURE.md	Components, data flow, and RAG pipeline

---

Quick start

Prerequisites

• Conda (Miniconda or Miniforge)
• Node.js 18+
• Groq API key
• Tesseract and Poppler for OCR and PDF rasterization (see system dependencies)

Run the backend and frontend in separate terminals. When both are up, open http://localhost:5173.

1. Backend (Conda)

Use environment gravitas with Python 3.11 (environment.yml).

macOS / Linux — from the repository root:

conda env create -f environment.yml
# Existing env with dependency changes:
# conda env update -f environment.yml --prune

conda activate gravitas
cd backend
cp .env.example .env
# Set GROQ_API_KEY in .env; tune non-secrets in config.yaml

pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Windows — from the repository root (Anaconda Prompt, PowerShell, or cmd):

conda env create -f environment.yml
REM Existing env: conda env update -f environment.yml --prune

conda activate gravitas
cd backend
copy .env.example .env
REM Set GROQ_API_KEY in .env; tune non-secrets in config.yaml

pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

PowerShell alternative for .env: Copy-Item .env.example .env

Tests (from backend/, any platform):

pytest

System dependencies (OCR / PDF rasterization)

Platform	Command / notes
macOS	brew install tesseract poppler
Linux (Debian/Ubuntu)	sudo apt-get install -y tesseract-ocr poppler-utils
Windows	Install Tesseract and Poppler; add both to PATH. Examples (elevated terminal if required): • Chocolatey: choco install tesseract poppler -y • Scoop: scoop install tesseract poppler • winget: winget install UB-Mannheim.TesseractOCR Poppler: poppler-windows releases — add the bin folder to PATH. Restart the terminal after installing.

2. Frontend

From the repository root:

cd frontend
cp .env.example .env   # optional; see frontend/.env.example
npm install
npm run dev

In development, Vite proxies /api and /health to http://127.0.0.1:8000. Set VITE_API_URL in frontend/.env only when not using the proxy.

---

Web app

Features

Area	Capabilities
Documents	Upload, processing status, open, delete (in-app confirmation modal)
Workspace	Chunk table, saved drafts, hybrid retrieval, drafting with optional Use memory, editable draft, evidence panel, Save operator version
Delete	Removes SQLite rows (chunks and drafts cascade), Chroma vectors, and backend/data/files/<id>/

Screenshots

Documents — upload zone and document list.

Document workspace — chunks, drafting controls, and evidence panel.

Saved drafts — list with Open and Reload.

Drafting — generated output with [E#] tags and retrieved sources.

---

Configuration

File	Purpose
backend/.env	Secrets: GROQ_API_KEY; optional GROQ_MODEL, DATA_DIR
backend/config.yaml	Tunables: models, chunking, ocr_refine, retrieval k, CORS, prompt paths
backend/prompts/drafting.yaml	Drafting prompts (Jinja2)
backend/prompts/ocr_refine.yaml	Post-OCR cleanup prompts (Jinja2)
environment.yml	Conda env gravitas (Python 3.11) and pip requirements

---

API

Method	Path	Description
POST	/api/documents	Multipart upload; background processing
GET	/api/documents	List documents
GET	/api/documents/{id}	Document metadata
GET	/api/documents/{id}/chunks	Chunk list
DELETE	/api/documents/{id}	Purge document, files, and Chroma vectors (204)
POST	/api/documents/{id}/draft	Body: { "query": "...", "use_memory": true } — create draft
GET	/api/documents/{id}/drafts	List drafts (query, created_at, has_operator_version)
GET	/api/drafts/{draft_id}	Load draft (operator text preferred when present)
POST	/api/drafts/{draft_id}/operator	Body: { "text": "..." } — save operator version and mine edits

Interactive docs: http://127.0.0.1:8000/docs (with the backend running).

---

Documentation

Document	Contents
docs/ARCHITECTURE.md	System design and RAG pipeline
docs/ASSUMPTIONS.md	Scope, tradeoffs, and limitations
docs/EVALUATION.md	Evaluation approach