Spaces:

khagu
/

setu

Running

App Files Files Community

setu / docs /pdf_processing_architecture.md

khagu

chore: finally untrack large database files

3998131 23 days ago

preview code

raw

history blame contribute delete

25.1 kB

PDF Processing System Architecture

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js)                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  PDF Upload Component                                     │   │
│  │  • File input                                             │   │
│  │  • Drag & drop                                            │   │
│  │  • Progress indicator                                     │   │
│  └──────────────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                      HTTP/FormData
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      FastAPI Backend                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  POST /api/v1/process-pdf                                        │
│  └─► Extract sentences only                                      │
│                                                                   │
│  POST /api/v1/process-pdf-to-bias                                │
│  └─► Extract + Analyze bias (complete pipeline)                 │
│                                                                   │
│  GET /api/v1/pdf-health                                          │
│  └─► Service status check                                        │
│                                                                   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
         ┌─────────────────┴─────────────────┐
         │                                   │
         ▼                                   ▼
    ┌────────────┐                   ┌─────────────────┐
    │ PDF Bytes  │                   │ PDFProcessor    │
    │            │                   │ (utility/)      │
    └────────────┘                   └─────────────────┘
         │                                   │
         └───────────┬───────────────────────┘
                     │
                     ▼
         ┌─────────────────────────────┐
         │  Step 1: Extract Text       │
         │  PyMuPDF (fitz)             │
         │  • Read PDF pages           │
         │  • Extract raw text         │
         │  • Handle multi-page        │
         └────────────┬────────────────┘
                      │
                      ▼
         ┌─────────────────────────────┐
         │  Step 2: Clean Text         │
         │  Regex Processing           │
         │  • Remove extra whitespace  │
         │  • Normalize formatting     │
         └────────────┬────────────────┘
                      │
                      ▼
         ┌─────────────────────────────┐
         │  Step 3: Segment Sentences  │
         │  Nepali-aware Regex         │
         │  • Split on दण्ड (।)         │
         │  • Handle punctuation       │
         │  • Filter short fragments   │
         └────────────┬────────────────┘
                      │
                      ▼
         ┌─────────────────────────────┐
         │  Step 4: Refine (Optional)  │
         │  Mistral LLM API            │
         │  • Correct segmentation     │
         │  • Remove duplicates        │
         │  • JSON formatting          │
         └────────────┬────────────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
         ▼                         ▼
    ┌──────────────┐        ┌─────────────────┐
    │   Sentences  │        │  Return JSON    │
    │   List       │        │  Array          │
    └──────┬───────┘        └────────┬────────┘
           │                         │
           │            ┌────────────┴─────────────┐
           │            │                          │
           │            ▼                          ▼
           │      ┌─────────────────┐      ┌──────────────────┐
           │      │ Option A:       │      │ Option B:        │
           │      │ Return to       │      │ Pass to Bias     │
           │      │ User            │      │ Detection        │
           │      └─────────────────┘      └────────┬─────────┘
           │                                        │
           │                                        ▼
           │                              ┌──────────────────────┐
           │                              │  Bias Detection Model│
           │                              │  DistilBERT Nepali   │
           │                              │  (module_b)          │
           │                              ├──────────────────────┤
           │                              │ • Classify sentence  │
           │                              │ • 11 categories:     │
           │                              │  - neutral           │
           │                              │  - gender            │
           │                              │  - caste             │
           │                              │  - religion          │
           │                              │  - political         │
           │                              │  - age               │
           │                              │  - disability        │
           │                              │  - appearance        │
           │                              │  - social status     │
           │                              │  - religiosity       │
           │                              │  - ambiguity         │
           │                              └────────┬─────────────┘
           │                                       │
           └───────────┬───────────────────────────┘
                       │
                       ▼
        ┌──────────────────────────────────────┐
        │       Response to User                │
        ├──────────────────────────────────────┤
        │ • Extracted sentences                │
        │ • Bias classification results        │
        │ • Confidence scores                  │
        │ • Biased/neutral counts              │
        │ • Processing metadata                │
        └──────────────────────────────────────┘
                       │
                       ▼
            ┌──────────────────────┐
            │  Frontend Display    │
            │  • Show results      │
            │  • Highlight biases  │
            │  • Display stats     │
            └──────────────────────┘

Data Flow Diagram

INPUT: PDF File
   │
   ├─ Metadata
   │  ├─ Filename
   │  ├─ File size
   │  └─ Upload timestamp
   │
   └─ Binary content
      │
      ▼
   PDFProcessor.process_pdf_from_bytes()
      │
      ├─ extract_text_from_pdf()
      │  │ Uses: PyMuPDF.fitz.open()
      │  │ Output: Raw text string + page count
      │  └─ ~200-500ms
      │
      ├─ clean_text()
      │  │ Uses: Regex replacements
      │  │ Output: Normalized text string
      │  └─ ~50ms
      │
      ├─ split_into_sentences()
      │  │ Uses: Nepali-aware regex patterns
      │  │ Output: List[sentences]
      │  └─ ~50-150ms
      │
      └─ refine_sentences_with_llm() [OPTIONAL]
         │ Uses: Mistral API
         │ Input: JSON-formatted sentences
         │ Output: Refined List[sentences]
         └─ ~2-5s (includes API latency)
         
   ▼
OUTPUT 1 (Extract Only):
   {
       "success": true,
       "sentences": ["वाक्य १", "वाक्य २", ...],
       "total_sentences": 15,
       "raw_text": "फुल text...",
       "filename": "doc.pdf"
   }

OUTPUT 2 (Extract + Bias):
   {
       "success": true,
       "total_sentences": 15,
       "biased_count": 2,
       "neutral_count": 13,
       "results": [
           {
               "sentence": "वाक्य १",
               "category": "neutral",
               "confidence": 0.95,
               "is_biased": false
           },
           ...
       ],
       "filename": "doc.pdf"
   }

Component Architecture

┌─────────────────────────────────────────────────────────────┐
│                    utility/ module                           │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  PDFProcessor Class                                          │
│  ├─ __init__(mistral_api_key)                               │
│  │  └─ Initialize MistralClient                             │
│  │                                                            │
│  ├─ extract_text_from_pdf(pdf_path)                          │
│  │  ├─ fitz.open(pdf_path)                                   │
│  │  ├─ Iterate pages                                         │
│  │  ├─ get_text("text")                                      │
│  │  └─ Return: raw text                                      │
│  │                                                            │
│  ├─ clean_text(text)                                         │
│  │  ├─ Remove newlines                                       │
│  │  ├─ Normalize spaces                                      │
│  │  └─ Return: cleaned text                                  │
│  │                                                            │
│  ├─ split_into_sentences(text)                               │
│  │  ├─ Apply Nepali regex patterns                           │
│  │  ├─ Filter short fragments                               │
│  │  └─ Return: sentence list                                │
│  │                                                            │
│  ├─ refine_sentences_with_llm(sentences)                     │
│  │  ├─ Format as JSON                                        │
│  │  ├─ Send to Mistral API                                   │
│  │  ├─ Parse JSON response                                   │
│  │  └─ Return: refined sentences                             │
│  │                                                            │
│  ├─ process_pdf(pdf_path, refine_with_llm)                   │
│  │  └─ Complete pipeline (file path)                         │
│  │                                                            │
│  └─ process_pdf_from_bytes(pdf_bytes, refine_with_llm)       │
│     └─ Complete pipeline (bytes)                             │
│                                                               │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    api/routes/ module                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  pdf_processing.py (FastAPI Routes)                          │
│  ├─ POST /api/v1/process-pdf                                │
│  │  ├─ Receive: file (UploadFile), refine_with_llm          │
│  │  ├─ Call: PDFProcessor.process_pdf_from_bytes()          │
│  │  └─ Return: PDFProcessingResponse                         │
│  │                                                            │
│  ├─ POST /api/v1/process-pdf-to-bias                         │
│  │  ├─ Receive: file, refine_with_llm, confidence_threshold  │
│  │  ├─ Call: PDFProcessor.process_pdf_from_bytes()          │
│  │  ├─ Call: run_bias_detection()                           │
│  │  └─ Return: PDFToBiasDetectionResponse                    │
│  │                                                            │
│  └─ GET /api/v1/pdf-health                                  │
│     ├─ Check: PDFProcessor availability                     │
│     ├─ Check: Mistral client status                         │
│     └─ Return: health status                                │
│                                                               │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                  api/schemas.py (Pydantic Models)            │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  PDFProcessingRequest / Response                             │
│  PDFToBiasDetectionRequest / Response                        │
│  BiasResult (reused from bias_detection)                     │
│                                                               │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│               External Dependencies                          │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  PyMuPDF (fitz)                                              │
│  └─ PDF text extraction                                      │
│                                                               │
│  Mistral API Client                                          │
│  └─ LLM-based sentence refinement                            │
│                                                               │
│  FastAPI                                                      │
│  └─ API framework (from module_a)                            │
│                                                               │
│  Pydantic                                                     │
│  └─ Data validation                                          │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Processing Timeline

Timeline for Single PDF (~10 KB):

Time  Component                Duration    Cumulative
────────────────────────────────────────────────────
0ms   ├─ API receives upload  ~5ms        5ms
      │
5ms   ├─ Read bytes           ~10ms       15ms
      │
15ms  ├─ PyMuPDF extraction   ~200ms      215ms
      │
215ms ├─ Text cleaning        ~30ms       245ms
      │
245ms ├─ Sentence split       ~100ms      345ms
      │
345ms ├─ LLM refinement       ~3500ms     3845ms
      │   (if enabled)
      │
3845ms├─ Bias detection       ~500ms      4345ms
      │   (if enabled)
      │
4345ms└─ Return response      ~5ms        4350ms
       
Total Time:
├─ With LLM + Bias:  ~4.3 seconds
├─ With LLM only:    ~3.8 seconds
├─ Without LLM:      ~0.35 seconds
└─ Bias only:        ~0.5 seconds (sentence extraction)

Error Handling Flow

API Request
   │
   ├─ Validate file
   │  ├─ Is PDF? → No → 400 Bad Request
   │  ├─ Is empty? → Yes → 400 Bad Request
   │  └─ Is valid? → Continue
   │
   └─ Process PDF
      ├─ Extract text
      │  ├─ File not found? → FileNotFoundError → 500
      │  ├─ Permission denied? → Exception → 500
      │  └─ Success? → Continue
      │
      ├─ Split sentences
      │  ├─ No sentences? → Warning in response → 200 (empty results)
      │  └─ Success? → Continue
      │
      └─ Refine with LLM (if enabled)
         ├─ API key missing? → Warning, use regex → 200 (fallback)
         ├─ Network error? → Warning, use regex → 200 (fallback)
         ├─ Invalid JSON? → Warning, use regex → 200 (fallback)
         └─ Success? → Return refined sentences → 200

State Diagram

             ┌──────────────┐
             │   Idle       │
             └──────┬───────┘
                    │
        User uploads PDF
                    │
                    ▼
         ┌──────────────────┐
         │   Validating     │
         └──────┬───────────┘
                │
         ┌──────┴──────┐
         │             │
    Invalid         Valid
         │             │
         ▼             ▼
    ┌─────────┐  ┌──────────────────┐
    │  Error  │  │  Extracting      │
    └─────────┘  └──────┬───────────┘
                        │
                 ┌──────┴──────┐
                 │             │
             Success      No Text
                 │             │
                 ▼             ▼
            ┌──────────┐  ┌──────────┐
            │Splitting │  │  Error   │
            └──────┬───┘  └──────────┘
                   │
            ┌──────┴──────┐
            │             │
        Success      No Sentences
            │             │
            ▼             ▼
      ┌────────────┐  ┌──────────┐
      │Refining    │  │  Error   │
      │(Optional)  │  └──────────┘
      └──────┬─────┘
             │
      ┌──────┴──────┐
      │             │
   Success       Failed
      │             │
      ├─────┬───────┤
      │     │       │
      ▼     ▼       ▼
   ┌──────────────┐ ┌────────┐
   │ Formatting   │ │Fallback│
   │Response      │ │(Regex) │
   └──────┬───────┘ └───┬────┘
          │             │
          └──────┬──────┘
                 │
                 ▼
        ┌─────────────────┐
        │ Bias Detection  │
        │ (if enabled)    │
        └────────┬────────┘
                 │
          ┌──────┴──────┐
          │             │
      Success        Error
          │             │
          ▼             ▼
    ┌────────────┐  ┌────────┐
    │Format      │  │Return  │
    │Response    │  │Error   │
    └────────┬───┘  └───┬────┘
             │          │
             └────┬─────┘
                  │
                  ▼
        ┌──────────────────┐
        │Send Response     │
        │to Client         │
        └──────────────────┘

Integration Points

Frontend (Next.js)
       │
       ├─► /api/v1/process-pdf
       │   └─ Use for: Sentence extraction only
       │
       ├─► /api/v1/process-pdf-to-bias
       │   └─ Use for: Full analysis (PDF → Bias)
       │
       └─► /api/v1/pdf-health
           └─ Use for: Service status check

Internal Integration
       │
       ├─► PDFProcessor class
       │   └─ Use in: Custom workflows
       │
       └─► run_bias_detection() function
           └─ Use in: Direct bias analysis

This architecture provides: ✅ Scalable processing pipeline ✅ Clear separation of concerns ✅ Reusable components ✅ Error resilience ✅ Performance optimization options ✅ Easy integration points