# katherlab/llmaixlib architecture

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

- Interactive diagram: https://gitdiagram.com/katherlab/llmaixlib
- Repository: https://github.com/katherlab/llmaixlib

## Overview

##### Project type and purpose
- LLMAIx is an open-source Python library (not a full-stack “app”) that provides:
- Preprocessing of documents (PDF/DOCX/TXT), with optional OCR backends.
- A wrapper for information extraction via OpenAI-API compatible LLMs, returning structured JSON.

##### File structure
- Top-level:
- src/llmaix – core package
– cli.py: command-line interface entrypoint
– preprocess.py & extract.py: main modules
– utils.py: shared helpers
- tests/: unit tests and test PDF samples
- pyproject.toml: build config
- GitHub workflows: CI for tests and publishing

##### Key components
A. User Interfaces
– CLI (llmaix command)
– Python API (import llmaix.preprocess_file, llmaix.extract_info)
B. Core Library
– Preprocess module
- PDF/Text loader
- OCR orchestrator (calls external OCR backends)
- Backend selector (pymupdf4llm, markitdown, docling)
– Extract module
- Prompt builder
- API client to OpenAI-compatible endpoints
- Pydantic model validation
– Utils module (common functions, e.g. file I/O)
C. External Dependencies
– OCR backends: Tesseract (via ocrmypdf), Surya-OCR, Docling-VLM
– PDF parsing libs: pymupdf4llm, markitdown, docling
– Cloud LLM endpoints: OpenAI API or custom base URL
– Environment variables (.env for API key, model name, base URL)
D. CI/CD & Packaging
– GitHub Actions (tests, publish)
– PyPI packaging via pyproject.toml
– Dependency groups (docling, surya)

##### Relationships & data flows
- User invokes CLI or Python API →
Preprocess module reads file →
If use_ocr=True: dispatch to selected OCR backend → raw text
Else: use selected PDF/Text backend → raw text
→ Hand off text to Extract module →
Build prompt + pydantic schema → call OpenAI API →
Receive LLM response → validate against schema → JSON output → return to user

##### Architectural patterns & principles
- Modular layering: separate CLI, preprocessing, extraction, utils
- Strategy pattern: pluggable OCR and PDF backends chosen at runtime
- Adapter/Wrapping: unify different backends under common interface
- Configuration via environment variables and dependency-group extras

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces Layer
    subgraph "Interfaces" 
        direction TB
        CLI["CLI"]:::interface
        PyAPI["Python API"]:::interface
    end

    %% Core Library Layer
    subgraph "Core Library" 
        direction TB
        subgraph "Preprocess Module" 
            direction TB
            Loader["PDF/Text Loader"]:::core
            Orchestrator["OCR Orchestrator"]:::core
            Selector["Backend Selector"]:::core
        end
        subgraph "Extract Module"
            direction TB
            PromptBuilder["Prompt Builder"]:::core
            APIClient["API Client"]:::core
            Validator["Pydantic Validator"]:::core
        end
        Utils["Utils Module"]:::core
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        OCRBackends["OCR Backends\n(Tesseract, Surya-OCR, Docling-VLM)"]:::external
        PDFBackends["PDF Parsing Libs\n(pymupdf4llm, markitdown, docling)"]:::external
        LLMAPI["LLM Endpoint\n(OpenAI or custom)"]:::external
        EnvVars["Environment Variables\n(.env for API key, model, base URL)"]:::external
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        TestsWorkflow[".github/workflows/tests.yml"]:::ci
        PublishWorkflow[".github/workflows/python-publish.yml"]:::ci
        PyProject["pyproject.toml"]:::ci
        TestsSuite["tests/"]:::ci
    end

    %% Data Flows
    CLI -->|"invoke"| Loader
    PyAPI -->|"call llmaix.preprocess_file"| Loader
    Loader -->|"extract raw text"| Selector
    Selector -->|"select PDF/Text backend"| PDFBackends
    Loader -->|"if use_ocr=True"| Orchestrator
    Orchestrator -->|"dispatch OCR job"| OCRBackends
    Selector --> Loader
    Loader -->|"output raw text"| PromptBuilder
    PromptBuilder -->|"build prompt"| APIClient
    APIClient -->|"call LLM"| LLMAPI
    LLMAPI -->|"response JSON"| Validator
    Validator -->|"validated JSON"| PyAPI
    Validator -->|"validated JSON"| CLI

    %% Utils usage
    Utils -.-> Loader
    Utils -.-> Orchestrator
    Utils -.-> PromptBuilder
    Utils -.-> Validator

    %% CI/CD flows (dotted)
    TestsWorkflow -.-> TestsSuite
    PublishWorkflow -.-> PyProject

    %% Click Events
    click CLI "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/cli.py"
    click PyAPI "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/__init__.py"
    click Loader "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/preprocess.py"
    click Orchestrator "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/preprocess.py"
    click Selector "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/preprocess.py"
    click PromptBuilder "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/extract.py"
    click APIClient "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/extract.py"
    click Validator "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/extract.py"
    click Utils "https://github.com/katherlab/llmaixlib/blob/main/src/llmaix/utils.py"
    click TestsSuite "https://github.com/katherlab/llmaixlib/tree/main/tests/"
    click TestsWorkflow "https://github.com/katherlab/llmaixlib/blob/main/.github/workflows/tests.yml"
    click PublishWorkflow "https://github.com/katherlab/llmaixlib/blob/main/.github/workflows/python-publish.yml"
    click PyProject "https://github.com/katherlab/llmaixlib/blob/main/pyproject.toml"

    %% Styles
    classDef interface fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef core fill:#99ccff,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef ci fill:#dddddd,stroke:#333,stroke-width:1px
```
