Blood Test Parser

A Python application that extracts blood test data from PDF documents using Google's Gemini AI and optionally updates Google Spreadsheets with the results.

This app was developed to support healthcare professionals within the Servicio Canario de Salud who assist migrant children arriving in the Canary Islands. The tool streamlines the recording of historical blood test results, providing an invaluable data source for both clinical follow-up and future medical research.

The app is live in https://blood-test-parser.vercel.app/.

Features

• PDF Text Extraction: Extract blood test data from PDF documents
• AI-Powered Parsing: Uses Google Gemini AI to interpret and structure blood test results
• Batch Processing: Process single files or entire directories
• Data Validation: Validate extracted data against expected results
• Google Sheets Integration: Automatically update Google Spreadsheets with extracted data
• Patient Matching: Smart patient matching using name combinations
• Error Handling: Comprehensive error handling and logging
• Copy-Paste Support: Generate tab-separated values for manual data entry

Installation

1. Clone the repository:

   git clone <repository-url>
   cd blood_test_parser

2. Install dependencies:

   uv sync

3. Set up environment variables:

   export GOOGLE_API_KEY="your_gemini_api_key"

Basic Usage

Extract data from a single PDF:

python main.py path/to/blood_test.pdf

Process multiple PDFs in a directory:

python main.py path/to/blood_tests_directory/

Extract and validate results:

python main.py path/to/file.pdf --validate --validation-threshold 85.0

Google Sheets Integration

Quick Start

1. Follow the Google Sheets Setup Guide
2. Place your credentials.json file in the project directory
3. Run with spreadsheet integration:

python main.py path/to/blood_test.pdf --spreadsheet "YOUR_SPREADSHEET_ID"

How It Works

The system:

1. Extracts blood test data from PDFs using AI
2. Searches for patients across ALL sheets/tabs in your spreadsheet using the "FILIACION" column
3. Matches patients by NOMBRE + APELLIDOS (with fallback to APELLIDOS + NOMBRE)
4. Automatically detects which sheet the patient is in
5. Updates the matching row in the correct sheet with blood test results
6. Provides copy-paste values for unmatched patients

Command Line Options

python main.py [INPUT_PATH] [OPTIONS]

Arguments:
  INPUT_PATH                Path to PDF file or directory

Options:
  --api-key KEY            Google API key (or set GOOGLE_API_KEY env var)
  --output, -o FILE        Output JSON file path
  --spreadsheet, -s ID     Google Spreadsheet ID or name to update
  --credentials FILE       Path to Google credentials file (default: credentials.json)
  --validate               Enable validation against expected results
  --validation-threshold N Accuracy threshold for validation (default: 80.0)
  --validation-report FILE Path to save detailed validation report
  --verbose, -v            Enable verbose logging
  --help, -h               Show help message

Examples

Basic extraction:

python main.py blood_test.pdf --api-key "your_api_key"

Extract and update spreadsheet:

python main.py blood_tests/ \
  --spreadsheet "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" \
  --credentials "my_credentials.json"

Full validation workflow:

python main.py blood_tests/ \
  --validate \
  --validation-threshold 90.0 \
  --validation-report "validation_results.json" \
  --verbose

Data Structure

The extracted data follows this schema:

{
  "NOMBRE": "JUAN",
  "APELLIDOS": "GARCIA RODRIGUEZ",
  "HOSPITAL": "NEGRIN",
  "NRO_HISTORIA_CLINICA": "12345678",
  "NRO_MUESTRA": "ABC123456",
  "HEMOGLOBINA": 14.2,
  "HEMATOCRITO": 42.5,
  "VCM": 87.3,
  "ADE": 13.2,
  "PLAQUETAS": 298,
  "LEUCOCITOS": 6.8,
  "EOSINOFILOS_TOTALES": 0.12,
  "EOSINOFILOS_PORCENTAJE": 1.8,
  "GLUCOSA": 98,
  "CREATININA": 0.9,
  "ALT": 22,
  "AST": 18,
  "GGT": 28,
  "COLESTEROL": 187,
  "FERRITINA": 125,
  "VIH": 0,
  "VHA": null,
  "VHC": 0,
  "LUES": 1,
  "STRONGYLOIDES": null,
  "SARAMPION": null,
  "SCHISTOSOMA": null
}

Files Generated

• Extraction Results: extraction_results/extraction_results_TIMESTAMP.json
• Validation Reports: validation_reports/validation_report_TIMESTAMP.json
• Log Files: blood_test_parser.log

Configuration

Environment Variables

• GOOGLE_API_KEY: Your Google Gemini API key

Google Sheets Setup

See GOOGLE_SHEETS_SETUP.md for detailed instructions on:

• Creating a Google Cloud project
• Enabling APIs
• Setting up service account credentials
• Preparing your spreadsheet

Patient Matching Logic

1. Multi-Sheet Search: Searches across ALL sheets/tabs in the spreadsheet
2. Primary Match: NOMBRE + APELLIDOS → Search in FILIACION column of each sheet
3. Fallback Match: APELLIDOS + NOMBRE → Search in FILIACION column of each sheet
4. Case Insensitive: All matching is case-insensitive
5. Space Tolerant: Extra spaces are ignored
6. Sheet Detection: Automatically identifies which sheet contains the patient
7. Duplicate Handling: Multiple matches (across all sheets) are flagged for manual review
8. Missing Patient: Unmatched patients generate copy-paste values

Error Handling

The system handles various error scenarios:

• Missing credentials: Clear setup instructions provided
• Spreadsheet access: Permission and sharing guidance
• Patient not found: Copy-paste values for manual entry
• Duplicate patients: Warning with row numbers
• API errors: Detailed error logging
• Network issues: Graceful degradation with manual fallbacks

Troubleshooting

Common Issues

1. Authentication Errors:

   • Verify credentials.json exists and is valid
   • Check spreadsheet sharing with service account email

2. Patient Not Found:

   • Verify NOMBRE Y APELLIDO column exists in spreadsheet
   • Check patient name formatting (spaces, accents, etc.)
   • Use --verbose flag for detailed matching logs

3. API Rate Limits:

   • The system handles rate limiting automatically
   • Large batches may take longer to process

4. Column Mapping Issues:

   • Ensure spreadsheet headers match expected column names
   • Check for typos in column headers
   • Use case-insensitive matching

Debug Mode

Enable verbose logging for troubleshooting:

python main.py file.pdf --spreadsheet "ID" --verbose

Architecture

Originally built as a small-scale experiment, this project loads htmx via a local minified file. This bypasses CDN restrictions present in the Servicio Canario de Salud's environment (Microsoft Edge). While migrating to a bundler like Vite or Webpack is planned, the local file remains for now as htmx is our only—and very lightweight—dependency.

---

⚠️ Disclaimer

As this was originally built as a small-scale experiment, the code in this repo was heavily vibe-coded to prioritise speed and exploration. This means it does not follow coding best practices and should not be used as an example of such.