How ahmedelzaria/lab-result-extraction works
Project type and purpose
• This is a backend microservice (FastAPI) for extracting structured data from lab-result PDFs.
• It validates incoming files, extracts raw text (via PDF libraries or OCR), parses and cleans it (Llama Parse), then runs a small LLM (GPT-4o-mini) to output JSON.
File structure
• Top level
• Dockerfile/.dockerignore: containerization
• README.md: architecture overview, tech stack
• requirements.txt: Python dependencies
• app/: main package
• app/main.py: FastAPI entrypoint
• app/models: AI-model interfaces (openai_models.py)
• app/processors: file-type handlers (pdf_processor.py inherits base_processor.py)
• app/validators: file checks (size, extension, MIME), composite_validator
• app/prompts: static prompt templates for Llama and OpenAI
• tests/: unit tests for validators and processors
Key insights from README
• Two-stage pipeline:
1. Validation & Extraction
2. Parsing & Field Extraction
• Modular, SOLID architecture: validators, processors, model handlers
• External services: Llama Parse API, OpenAI API
• Tech stack: Python, FastAPI, pdfplumber, PyPDF2, Docker, Pytest
Components
• Client / Consumer (e.g., curl, frontend)
• FastAPI App (app/main.py)
• CompositeValidator
• ExtensionValidator
• SizeValidator
• MimeValidator
• PDFProcessor (uses pdfplumber / PyPDF2 / OCR)
• TextParser (Llama Parse Service)
• FieldExtractor (OpenAI GPT-4o-mini Model Handler)
• JSON Formatter / Response
b. External services & libraries:
• Llama Parse API
• OpenAI API
• pdfplumber, PyPDF2 (local)
c. Data stores: none (stateless service)
d. Tests: separate test harness (not on the critical path)
1. Client → FastAPI endpoint (POST /extract)
2. FastAPI → CompositeValidator → each validator → return OK or error
3. Validated file → PDFProcessor → raw text (or OCR‐converted text)
4. Raw text → TextParser (Llama Parse) → structured Markdown/text
5. Parsed text → FieldExtractor (OpenAI API) → JSON fields
6. JSON → FastAPI → Client response
Architectural patterns & principles
• Modular pipeline: each step isolated in its own class
• SOLID:
• Single Responsibility: validators only validate, processors only extract, models only handle API calls
• Open/Closed: new file types or models added via subclassing
• Dependency Injection: FastAPI injects dependencies (e.g., validator, processor) into endpoints
• Stateless microservice: no persistent storage, scales horizontally
Don’t omit these essential details
• CompositeValidator orchestrating individual validators
• PDFProcessor’s fallback to OCR for scanned docs
• Two distinct AI steps: Llama Parse for text structuring + GPT-4o-mini for field extraction
• Docker boundary indicating environment variables (.env) and container ports