Merge remote-tracking branch 'origin/master' into v2

Author: JCHAVEROT

.github/workflows/pyright.yml

@@ -32,3 +32,15 @@ jobs:
         run: |
           source .venv/bin/activate
           pyright
+
+      - name: Install dependencies - colvision
+        run: |
+          uv venv .venv-colvision
+          source .venv-colvision/bin/activate
+          uv pip install -e ".[colvision,cpu,dev]"
+
+      - name: Run Pyright - colvision
+        continue-on-error: true
+        run: |
+          source .venv-colvision/bin/activate
+          pyright src/mmore/colvision

.github/workflows/tests.yml

@@ -11,25 +11,27 @@ jobs:
     runs-on: ubuntu-latest
 
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.11", "3.12"]
 
+    name: test (py${{ matrix.python-version }})
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
 
-      - name: Install uv and create venv
-        run: |
-          pipx install uv
-          uv venv .venv
+      - name: Install uv
+        run: pipx install uv
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies (using uv)
+      - name: Install dependencies - process (using uv)
         run: |
+          uv venv .venv
           source .venv/bin/activate
           uv pip install -e ".[process,index,rag,api,cpu,dev,websearch]"
 
@@ -39,7 +41,18 @@ jobs:
           uv pip show cohere || echo "Cohere not installed"
           uv pip show langchain-cohere || echo "Langchain-cohere not installed"
 
-      - name: Run tests
+      - name: Run tests - process
         run: |
           source .venv/bin/activate
-          pytest
+          pytest --ignore=tests/test_colvision.py
+
+      - name: Install dependencies - colvision
+        run: |
+          uv venv .venv-colvision
+          source .venv-colvision/bin/activate
+          uv pip install -e ".[colvision,cpu,dev]"
+
+      - name: Run tests - colvision
+        run: |
+          source .venv-colvision/bin/activate
+          pytest tests/test_colvision.py

docs/source/core_features/colpali.md docs/source/core_features/colvision.mddocs/source/core_features/colpali.md renamed to docs/source/core_features/colvision.md

@@ -1,10 +1,49 @@
-# 🖼️ ColPali Integration
+# 🖼️ ColVision Integration
 
-## Overview
+PDF retrieval pipeline using ColVision embeddings, stored in Milvus.
 
-This module provides a complete pipeline for processing PDF documents with ColPali embeddings, storing them in a Milvus vector database, and performing semantic search.
+## Installation
 
-It is designed for efficient document retrieval and RAG applications.
+The `[colvision]` extra is mutually exclusive with `[process]` — use a dedicated venv.
+
+```bash
+uv sync --extra colvision
+```
+
+## Supported Models
+
+| Model | `model_name` |
+|---|---|
+| ColPali v1.3 | `vidore/colpali-v1.3` |
+| ColQwen2 v1.0 | `vidore/colqwen2-v1.0` |
+| ColQwen2.5 v0.2 | `vidore/colqwen2.5-v0.2` |
+| ColGemma3 | `Cognitive-Lab/ColNetraEmbed` |
+| ColSmol 256M | `vidore/colSmol-256M` |
+| ColSmol 500M | `vidore/colSmol-500M` |
+
+All models are installed with the single `[colvision]` extra.
+
+The model/processor class is auto-detected from `model_name`, and the embedding dimension is inferred at every stage (from the loaded model at `process` / `retrieve` time, from the parquet contents at `index` time).
+
+## Choosing a Model
+
+Set `model_name` in the YAML config, or override it via the `-m` / `--model` CLI flag on the `process` and `retrieve` commands.
+
+The pipeline runs in three steps — `process`, then `index`, then `retrieve` — and the
+`-m` / `--model` flag must be passed to both `process` and `retrieve`:
+
+```bash
+# 1. Process PDFs into embeddings
+python3 -m mmore colvision process --config-file examples/colvision/config_process.yml -m vidore/colqwen2.5-v0.2
+
+# 2. Index the embeddings into Milvus (no model needed here)
+python3 -m mmore colvision index --config-file examples/colvision/config_index.yml
+
+# 3. Retrieve with the same model used at processing time
+python3 -m mmore colvision retrieve --config-file examples/colvision/config_retrieval.yml -m vidore/colqwen2.5-v0.2
+```
+
+> **Important:** the same model must be used across `process` and `retrieve` — mixing produces incorrect results.
 
 ## 🧭 Architecture
 
@@ -17,28 +56,32 @@ The system consists of three main components:
 ## 📁 File Structure
 
 ```
-src/mmore/colpali/
-├── milvuscolpali.py      # Milvus database management
+src/mmore/colvision/
+├── model_utils.py        # Model/processor class resolution
+├── milvuscolvision.py      # Milvus database management
 ├── run_index.py          # Indexing pipeline
-├── run_process.py        # PDF processing pipeline  
+├── run_process.py        # PDF processing pipeline
 ├── run_retriever.py      # Search and retrieval API
-└── retriever.py          # ColPaliRetriever class for RAG integration
+└── retriever.py          # ColVisionRetriever class for RAG integration
 ```
 
 ## 🚀 Quick Start
 
 ### 1. Process PDFs into embeddings
 
 ```bash
-python3 -m mmore colpali process --config-file examples/colpali/config_process.yml
+python3 -m mmore colvision process --config-file examples/colvision/config_process.yml
+
+# Or override the model from the command line
+python3 -m mmore colvision process --config-file examples/colvision/config_process.yml --model vidore/colqwen2.5-v0.2
 ```
 
 **Example config (`config_process.yml`):**
 ```yaml
 data_path:
   - 'examples/sample_data/pdf'
 output_path: "./output"
-model_name: "vidore/colpali-v1.3"
+model_name: "vidore/colqwen2.5-v0.2"
 skip_already_processed: true
 num_workers: 5
 batch_size: 8
@@ -47,7 +90,7 @@ batch_size: 8
 ### 2. Index embeddings into Milvus
 
 ```bash
-python3 -m mmore colpali index --config-file examples/colpali/config_index.yml
+python3 -m mmore colvision index --config-file examples/colvision/config_index.yml
 ```
 
 **Example config (`config_index.yml`):**
@@ -57,7 +100,6 @@ milvus:
     db_path: ./output/milvus_data.db
     collection_name: pdf_pages
     create_collection: true
-    dim: 128
     metric_type: IP
 ```
 
@@ -66,47 +108,31 @@ milvus:
 #### Retrieval Server Mode
 ```bash
 # Start the retrieval API server
-python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieval.yml
+python3 -m mmore colvision retrieve --config-file examples/colvision/config_retrieval.yml
 ```
 
 Or with a custom host and port:
 ```bash
-python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieval.yml --host 0.0.0.0 --port 8001
+python3 -m mmore colvision retrieve --config-file examples/colvision/config_retrieval.yml --host 0.0.0.0 --port 8001
 ```
 
 **Example config (`config_retrieval.yml`):**
 ```yaml
-db_path: "./milvus_data"
+db_path: "./output/milvus_data.db"
 collection_name: "pdf_pages"
-model_name: "vidore/colpali-v1.3"
+model_name: "vidore/colqwen2.5-v0.2"
 top_k: 3
-dim: 128
-max_workers: 16
 metric_type: "IP"
+max_workers: 16
 text_parquet_path: "./output/pdf_page_text.parquet"
 ```
 
-#### Single Query Mode
-```bash
-# Run retrieval for a single query defined in the config file
-python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieval_single.yml
-```
-
-**Example config (`config_retrieval_single.yml`):**
-```yaml
-mode: "single"
-db_path: "./milvus_data"
-collection_name: "pdf_pages"
-model_name: "vidore/colpali-v1.3"
-query: "What may lead to dysbiosis and inflammation?"
-top_k: 5
-```
 Host and port are specified via CLI flags (`--host` and `--port`), not in the config file.
 
 #### Batch Mode
 ```bash
 # Process queries from file
-python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieval.yml --input-file queries.jsonl --output-file results.json
+python3 -m mmore colvision retrieve --config-file examples/colvision/config_retrieval.yml --input-file queries.jsonl --output-file results.json
 ```
 
 **Example queries file (`queries.jsonl`):**
@@ -119,20 +145,9 @@ Each line should be a JSON-encoded string (one query per line):
 
 Each line must be a valid JSON string, including quotes, since the file is parsed line by line with `json.loads()`.
 
-**Example config (`config_retrieval.yml`):**
-```yaml
-db_path: "./milvus_data"
-collection_name: "pdf_pages"
-model_name: "vidore/colpali-v1.3"
-top_k: 5
-dim: 128
-max_workers: 16
-text_parquet_path: "./output/pdf_page_text.parquet"
-```
-
 ## 🔧 Core Components
 
-### MilvusColpaliManager
+### MilvusColvisionManager
 - manages local Milvus database operations
 - handles collection creation and indexing
 - provides efficient batch insertion
@@ -146,14 +161,14 @@ text_parquet_path: "./output/pdf_page_text.parquet"
 
 ### PDF Processor
 - converts PDF pages to images
-- generates ColPali embeddings
+- generates ColVision embeddings
 - handles parallel processing
 - supports stop-and-resume workflows for large datasets
 
 **Processing Flow:**
 1. Crawl PDF files from specified directories
 2. Convert each page to high-resolution PNG
-3. Generate embeddings using ColPali model
+3. Generate embeddings using the configured model
 4. Store results in Parquet format
 
 ### Retriever
@@ -193,28 +208,25 @@ curl -X POST "http://localhost:8001/v1/retrieve" \
 
 ### RAG Pipeline Integration
 ```python
-from mmore.colpali.retriever import ColPaliRetriever, ColPaliRetrieverConfig
-from mmore.rag.pipeline import RAGPipeline, RAGConfig
+from mmore.colvision.retriever import ColVisionRetriever, ColVisionRetrieverConfig
 
-# Create ColPali retriever with text support
-colpali_config = ColPaliRetrieverConfig(
+config = ColVisionRetrieverConfig(
     db_path="./output/milvus_data.db",
     collection_name="pdf_pages",
-    model_name="vidore/colpali-v1.3",
+    model_name="vidore/colqwen2.5-v0.2",
     text_parquet_path="./output/pdf_page_text.parquet",
     top_k=3,
-    dim=128,
     max_workers=16,
     metric_type="IP",
 )
-colpali_retriever = ColPaliRetriever.from_config(colpali_config)
+retriever = ColVisionRetriever.from_config(config)
 
 # Use with RAG pipeline (requires LLM config)
-# rag_config = RAGConfig(retriever=colpali_retriever, ...)
+# rag_config = RAGConfig(retriever=retriever, ...)
 # rag_pipeline = RAGPipeline.from_config(rag_config)
 ```
 
-The `ColPaliRetriever` is a LangChain-compatible `BaseRetriever` that returns `Document` objects with:
+The `ColVisionRetriever` is a LangChain-compatible `BaseRetriever` that returns `Document` objects with:
 - `page_content`: the text content from the PDF page, if `text_parquet_path` is provided
 - `metadata`: contains `pdf_name`, `pdf_path`, `page_number`, `rank`, and `similarity` score
 
@@ -282,13 +294,13 @@ The `ColPaliRetriever` is a LangChain-compatible `BaseRetriever` that returns `D
 ### Complete Workflow
 ```bash
 # 1. Process all PDFs in a directory
-python3 -m mmore colpali process --config-file examples/colpali/config_process.yml
+python3 -m mmore colvision process --config-file examples/colvision/config_process.yml
 
 # 2. Index the embeddings
-python3 -m mmore colpali index --config-file examples/colpali/config_index.yml
+python3 -m mmore colvision index --config-file examples/colvision/config_index.yml
 
 # 3. Start the API server
-python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieval.yml
+python3 -m mmore colvision retrieve --config-file examples/colvision/config_retrieval.yml
 
 # 4. Query the system
 curl -X POST "http://localhost:8001/v1/retrieve" \
@@ -299,13 +311,13 @@ curl -X POST "http://localhost:8001/v1/retrieve" \
 ### Alternative: Batch processing
 ```bash
 # 1. Process PDFs (same as above)
-python3 -m mmore colpali process --config-file examples/colpali/config_process.yml
+python3 -m mmore colvision process --config-file examples/colvision/config_process.yml
 
 # 2. Index embeddings (same as above)
-python3 -m mmore colpali index --config-file examples/colpali/config_index.yml
+python3 -m mmore colvision index --config-file examples/colvision/config_index.yml
 
 # 3. Run batch retrieval
-python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieval.yml \
+python3 -m mmore colvision retrieve --config-file examples/colvision/config_retrieval.yml \
                        --input-file queries.jsonl \
                        --output-file results.json
 ```
@@ -319,7 +331,7 @@ python3 -m mmore colpali retrieve --config-file examples/colpali/config_retrieva
 ### For better accuracy
 - use higher DPI in PDF conversion, default is 200
 - increase `top_k` in retrieval to inspect more candidate pages
-- consider using larger ColPali models if available
+- consider using more recent ColVision models (ColQwen2.5, ColGemma3)
 
 ### For production
 - run Milvus in distributed mode for larger datasets

docs/source/getting_started/architecture.md

@@ -16,7 +16,7 @@ MMORE is designed as a multimodal ingestion and retrieval framework for heteroge
 MMORE is organized around three main executable stages:
 
 - `run_process`, which handles ingestion, crawling, dispatching, and document processing
-- `run_indexer`, which builds the searchable index and can integrate multimodal retrieval components such as ColPali
+- `run_indexer`, which builds the searchable index and can integrate multimodal retrieval components such as ColVision models
 - `run_rag`, which serves retrieval and RAG workflows through interfaces such as the API and CLI
 
 These stages interact with intermediate outputs, the vector database, and optional external components such as hosted LLM endpoints, WebRAG, or Live RAG.
@@ -104,9 +104,9 @@ That means the framework may work with:
 - plain text documents
 - structured metadata
 - images or layout-aware representations
-- multimodal retrieval models such as ColPali-related components
+- multimodal retrieval models such as ColVision-related components
 
-See [ColPali](../core_features/colpali.md) for the multimodal retrieval side.
+See [ColVision](../core_features/colvision.md) for the multimodal retrieval side.
 
 ### 6. Distributed execution
 

docs/source/getting_started/installation.md

@@ -102,8 +102,14 @@ cd mmore
 
 ### Step 4: Install the project and dependencies
 
+Pick the pipeline you intend to use. The standard pipeline (`[process]`, with text/document extraction) and the ColVision pipeline (`[colvision]`, with vision-based RAG) are **mutually exclusive** — set up a separate venv if you need both.
+
 ```bash
-uv sync
+# Standard pipeline (document processing + text RAG)
+uv sync --extra process --extra rag
+
+# OR ColVision pipeline (vision-based RAG: ColPali, ColQwen2/2.5, ColGemma3, ColSmol)
+uv sync --extra colvision
 ```
 
 For a CPU-only installation, use: