# s-emanuilov/litepali architecture

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

- Interactive diagram: https://gitdiagram.com/s-emanuilov/litepali
- Repository: https://github.com/s-emanuilov/litepali

## Overview

##### Project Type and Purpose
- LitePali is an open-source Python library (packaged via pyproject.toml) for lightweight, image-based document retrieval using Vision-Language Models (specifically the ColPali engine). It is optimized for cloud deployment and batch processing of images, rather than PDF parsing.

##### File Structure Analysis
- Top-level files:
- README.md, LICENSE, pyproject.toml, .gitignore, .pre-commit-config.yaml – standard packaging, CI, and documentation.
- _config.yml, CNAME – GitHub Pages / docs site configuration.
- examples/: Jupyter notebooks showing usage patterns (e.g., converting PDFs to images externally, RAG example).
- src/litepali/: the core library code. model.py contains the LitePali class and ImageFile data structure.

##### README Insights
- Lists core features: direct image processing, batch and deterministic processing, minimal dependencies, optimized for cloud.
- Describes the underlying model: late interaction mechanism, multi‐vector representations, visual & textual understanding, efficient indexing.
- Usage section outlines the library’s public API: add images, process, search, save/load index.

##### Main Components
a. Client Application / User Code
- The Python script or notebook that instantiates LitePali, adds ImageFile objects, invokes process() and search().
b. API Layer (LitePali Class)
- Methods: add(ImageFile), process(), search(query), save_index(path), load_index(path).
c. Image Preprocessing Module
- Loads and optionally normalizes images, attaches metadata (document_id, page_id).
d. Feature Extraction (VLM Engine)
- Integration with colpali-engine (vision‐language model) using PyTorch to compute multi‐vector embeddings for each image and textual query.
e. Indexing Engine
- Builds and stores a vector index (in-memory or file‐based) for fast similarity search.
f. Retrieval Module
- Executes k-NN search on the index, returns top-k results with scores and metadata.
g. Persistence / Storage
- Serializes the index (and optionally image metadata) to disk via save_index/load_index.
h. External Dependencies
- PyTorch (for model), colpali-engine, any serialization libraries (e.g., pickle, JSON), cloud storage if used.

##### Relationships & Data Flow
- User code → (calls) LitePali API → (passes) ImageFile → Preprocessing → Feature Extraction → Indexing → Stored Index
- User search query → (calls) LitePali.search() → Query embedding (Feature Extraction) → Retrieval from Index → Results back to User
- save_index/load_index interact with Persistence block.

##### Architectural Patterns & Principles
- Modular design: clear separation between API, preprocessing, embedding, indexing, and retrieval.
- Plug-and-play model engine: the colpali-engine interface can be swapped/updated.
- Stateless processing steps, except for the in-memory index.
- Batch processing support for throughput and deterministic ordering.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Application / User Code" 
        direction TB
        Convert["convert_pdf_to_images.ipynb"]:::external
        RAG["rag_example.ipynb"]:::external
    end
    click Convert "https://github.com/s-emanuilov/litepali/blob/main/examples/convert_pdf_to_images.ipynb"
    click RAG "https://github.com/s-emanuilov/litepali/blob/main/examples/rag_example.ipynb"

    %% API Layer
    subgraph "LitePali API Layer" 
        direction TB
        API["LitePali Class"]:::core
        Pre["Image Preprocessing Module"]:::core
        Emb["Feature Extraction\n(VLM Engine)"]:::core
        Index["Indexing Engine"]:::core
        Ret["Retrieval Module"]:::core
        API -->|"add(ImageFile)"| Pre
        Pre -->|"images with metadata"| Emb
        Emb -->|"embeddings"| Index
        Index -->|"index data"| Ret
        Ret -->|"search results"| API
    end
    click API "https://github.com/s-emanuilov/litepali/blob/main/src/litepali/model.py"
    click Pre "https://github.com/s-emanuilov/litepali/blob/main/src/litepali/model.py"
    click Emb "https://github.com/s-emanuilov/litepali/blob/main/src/litepali/model.py"
    click Index "https://github.com/s-emanuilov/litepali/blob/main/src/litepali/model.py"
    click Ret "https://github.com/s-emanuilov/litepali/blob/main/src/litepali/model.py"

    %% Persistence / Storage
    Persist["Persistence / Storage\n(save/load index)"]:::storage
    API -->|"save_index/load_index"| Persist
    click Persist "https://github.com/s-emanuilov/litepali/blob/main/src/litepali/model.py"

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Torch["PyTorch"]:::external
        Col["colpali-engine"]:::external
        PDFConv["PDF-to-Image Converter"]:::external
    end
    Emb -->|"model inferencing"| Torch
    Emb -->|"uses"| Col
    Pre -->|"external conversion"| PDFConv

    %% Packaging, Docs, CI
    subgraph "Project Configuration & Documentation"
        direction TB
        Pack["pyproject.toml"]:::infra
        Docs["assets/ , README.md"]:::infra
        Pages["_config.yml , CNAME"]:::infra
        CI[".pre-commit-config.yaml , .gitignore"]:::infra
    end
    click Pack "https://github.com/s-emanuilov/litepali/blob/main/pyproject.toml"
    click Docs "https://github.com/s-emanuilov/litepali/tree/main/assets/"
    click Docs "https://github.com/s-emanuilov/litepali/blob/main/README.md"
    click Pages "https://github.com/s-emanuilov/litepali/blob/main/_config.yml"
    click Pages "https://github.com/s-emanuilov/litepali/tree/main/CNAME"
    click CI "https://github.com/s-emanuilov/litepali/blob/main/.pre-commit-config.yaml"
    click CI "https://github.com/s-emanuilov/litepali/blob/main/.gitignore"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#000;
    classDef external fill:#d4edda,stroke:#155724,color:#000;
    classDef storage fill:#fff3cd,stroke:#856404,color:#000;
    classDef infra fill:#f8d7da,stroke:#721c24,color:#000;
```
