# nahuelpanigo/document_extraction_llm architecture

> Architecture diagram of the GitHub repository nahuelpanigo/document_extraction_llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nahuelpanigo/document_extraction_llm
- Repository: https://github.com/nahuelpanigo/document_extraction_llm

## Overview

##### Project type and purpose
- This is a document‐extraction and metadata‐extraction system built in Python. It consists of:
- A data‐preparation pipeline to download, clean, normalize, and structure PDF documents into JSON (download_prepare_clean_normalize_sedici_dataset).
- A fine‐tuning pipeline that generates training tokens, fine‐tunes LLMs on the prepared dataset, and validates the results (fine_tunning + validation).
- A microservice‐based runtime inference API that ingests documents, extracts text, calls an LLM to extract metadata, and orchestrates the results (api/app with extractor_service, llm_service, orchestrator).

##### File structure
- **download_prepare_clean_normalize_sedici_dataset/**: data ingestion, CSV filtering, PDF download, OCR/text extraction, JSON generation.
- **fine_tunning/** + **validation/**: token generation, model management, Hugging Face integration, training orchestration, result validation scripts.
- **api/app/**: three FastAPI microservices, each in its own subfolder (extractor_service, llm_service, orchestrator), plus Dockerfiles and docker-compose.yml.
- **utils/** and **constants.py**: shared utilities for normalization, OCR, terminal coloring.
- Root scripts: run_all_services, run_extractor_temp, etc., for local launches.

##### Key insights from the README
- The README describes three high‐level flows: GENERATING TRAIN DATA → FINE TUNING → VALIDATION → RUNNING API.
- The API exposes an `/upload` endpoint for inference.
- It suggests Docker + FastAPI for deployment, plus environment‐based configs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Deployment Manager
    DockerCompose["Docker Compose"]:::deployment
    click DockerCompose "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/docker-compose.yml"

    subgraph "Data Preparation Pipeline"
        direction TB
        CSV_Filter["CSV Filter & Normalizer"]:::dataPrep
        click CSV_Filter "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/download_prepare_clean_normalize_sedici_dataset/extract_data_from_csv_sedici.py"
        PDF_Downloader["PDF Downloader"]:::dataPrep
        click PDF_Downloader "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/download_prepare_clean_normalize_sedici_dataset/download_data.py"
        Text_Extractor["Text Extractor (OCR + PDF Reader) & JSON Generator"]:::dataPrep
        click Text_Extractor "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/download_prepare_clean_normalize_sedici_dataset/extract_text_make_dataset.py"
        click Text_Extractor "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/utils/text_extraction/pdf_extraction_with_OCR.py"
        click Text_Extractor "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/utils/text_extraction/pdf_reader.py"
    end

    subgraph "Fine-Tuning Pipeline"
        direction TB
        HF_Fetcher["HF Data Fetcher"]:::training
        click HF_Fetcher "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/fine_tunning/hugging_face_connection.py"
        Token_Generator["Token Generator"]:::training
        click Token_Generator "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/fine_tunning/generate_tokens.py"
        Trainer["Trainer & PEFT Configuration"]:::training
        click Trainer "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/fine_tunning/main.py"
        click Trainer "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/fine_tunning/trainer.py"
        click Trainer "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/fine_tunning/peft_configuration.py"
        click Trainer "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/fine_tunning/model_managment.py"
    end

    subgraph "Validation Module"
        direction TB
        Test_JSON["Test JSON Generation & Cleanup"]:::validation
        click Test_JSON "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/validation/make_json_test.py"
        click Test_JSON "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/validation/remove_unused_fields.py"
        click Test_JSON "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/validation/result/LEDEN/extract_json_type.py"
    end

    subgraph "Inference Microservices"
        direction TB
        Client["Client"]:::external
        ORCHESTRATOR["Orchestrator Service"]:::micro
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/app/main.py"
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/service/orchestrator.py"
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/service/indentifier.py"
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/service/strategies/type_strategy.py"
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/models/modelo_tipo_documento.pkl"
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/models/vectorizador_tfidf.pkl"
        click ORCHESTRATOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/orchestrator/routers/router.py"
        EXTRACTOR["Extractor Service"]:::micro
        click EXTRACTOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/extractor_service/app/main.py"
        click EXTRACTOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/extractor_service/routers/router.py"
        click EXTRACTOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/extractor_service/service/reader_strategy.py"
        click EXTRACTOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/extractor_service/service/strategies/pdf_reader_strategy.py"
        click EXTRACTOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/extractor_service/service/strategies/word_reader_strategy.py"
        click EXTRACTOR "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/extractor_service/service/utils/normalization_and_parse.py"
        LLM["LLM Service"]:::micro
        click LLM "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/llm_service/app/main.py"
        click LLM "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/llm_service/services/llms_extraction.py"
        click LLM "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/llm_service/services/model_managment.py"
        click LLM "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/api/app/llm_service/routers/router.py"
    end

    subgraph "Shared Components"
        direction TB
        Utils["Common Libraries"]:::shared
        click Utils "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/utils/normalization/normalice_data.py"
        click Utils "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/utils/colors/colors_terminal.py"
        Constants["Constants"]:::shared
        click Constants "https://github.com/nahuelpanigo/document_extraction_llm/blob/main/constants.py"
    end

    subgraph "External Services"
        direction TB
        HF_Hub["Hugging Face Hub"]:::external
        Gemini["Gemini LLM"]:::external
    end

    %% Data Preparation to Training
    CSV_Filter -->|"filtered CSV"| PDF_Downloader
    PDF_Downloader -->|"PDFs"| Text_Extractor
    Text_Extractor -->|"JSON dataset"| HF_Fetcher

    %% Training to Validation
    HF_Fetcher -->|"raw data"| Token_Generator
    Token_Generator -->|"tokens"| Trainer
    Trainer -->|"fine-tuned model"| Test_JSON

    %% Inference Flow
    Client -->|"POST /upload"| ORCHESTRATOR
    ORCHESTRATOR -->|"extract text HTTP"| EXTRACTOR
    EXTRACTOR -->|"text payload"| ORCHESTRATOR
    ORCHESTRATOR -->|"metadata request HTTP"| LLM
    LLM -->|"metadata response"| ORCHESTRATOR
    ORCHESTRATOR -->|"JSON result"| Client

    %% Shared & External usage
    Text_Extractor -->|uses| Utils
    PDF_Downloader -->|uses| Utils
    HF_Fetcher -->|calls| HF_Hub
    Trainer -->|saves model to| Gemini
    ORCHESTRATOR -->|uses| Constants

    %% Styles
    classDef dataPrep fill:#D6E9F8,stroke:#1F618D,color:#1B2631
    classDef training fill:#D5F5E3,stroke:#196F3D,color:#1B2631
    classDef validation fill:#FDEBD0,stroke:#B9770E,color:#1B2631
    classDef micro fill:#FAD7A0,stroke:#D35400,color:#1B2631
    classDef shared fill:#E8DAEF,stroke:#6C3483,color:#1B2631
    classDef external fill:#D5D8DC,stroke:#566573,color:#1B2631
    classDef deployment fill:#AED6F1,stroke:#2874A6,color:#1B2631
    classDef storage fill:#ABEBC6,stroke:#1D8348,color:#1B2631
```
