orbitron 0.1.0a1
A lightweight async package for building Multi-Modal RAG applications
License: MIT
Requires Python: >=3.11

# Orbitron 

**A lightweight, async Python package for building Multi-Modal Retrieval-Augmented Generation (RAG) applications.**

![Orbitron](orbitron.png)
Orbitron simplifies the process of indexing visual content (images, pages from PDFs) and retrieving the most relevant items based on text queries. It integrates with Cohere's multimodal embeddings and Qdrant vector stores out-of-the-box.

**Key Features:**

*   **Multi-Modal Indexing:** Supports indexing individual image files (`.png`, `.jpg`, `.jpeg`, `.bmp`) and extracting/indexing images from PDF pages.
*   **Cohere Integration:** Uses Cohere's powerful `embed-v4.0` model for generating multimodal embeddings.
*   **Vectorstore Integration:** Provides a ready-to-use vector store implementation (currently supports Qdrant).
*   **Simple API:** Easy-to-use interface for indexing and retrieval.

## Table of Contents

- [Orbitron](#orbitron)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
    - [Dependencies](#dependencies)
      - [Poppler (External System Dependency)](#poppler-external-system-dependency)
      - [Python Dependencies](#python-dependencies)
  - [Quickstart](#quickstart)
    - [Output Directory](#output-directory)
  - [Contributing](#contributing)
  - [License](#license)

## Installation

You can install `orbitron` using pip:

```bash
pip install orbitron
```

**Requirements:**

*   Python 3.11+

### Dependencies

#### Poppler (External System Dependency)

Orbitron uses the `pdf2image` library to extract images from PDF files. `pdf2image` relies on the **Poppler** PDF rendering library utilities being installed on your system and available in your PATH.

**Installation Instructions:**

*   **Debian/Ubuntu:**
    ```bash
    sudo apt-get update && sudo apt-get install poppler-utils
    ```
*   **macOS (using Homebrew):**
    ```bash
    brew install poppler
    ```
*   **Windows:**
    *   Download the latest Poppler binaries (e.g., from [here](https://github.com/oschwartz10612/poppler-windows/releases/)).
    *   Extract the archive.
    *   Add the `bin/` directory from the extracted archive to your system's PATH environment variable.


You can check if Poppler is likely installed and accessible using:
```python
from orbitron.utils import check_poppler_installed

if check_poppler_installed():
    print("Poppler utilities seem to be installed and accessible.")
else:
    print("Warning: Poppler utilities (needed for PDF indexing) not found in PATH.")
```

#### Python Dependencies

Orbitron's core Python dependencies (like `cohere`, `qdrant-client`, `pdf2image`, `Pillow`, `numpy`) are listed in `pyproject.toml` and will be installed automatically by pip.


## Quickstart

This example demonstrates indexing a PDF and retrieving relevant pages based on a text query using an in-memory Qdrant database.

```python
import asyncio
import os
from pathlib import Path

from dotenv import load_dotenv
from qdrant_client import AsyncQdrantClient

from orbitron import MultiModalRAG, QdrantVectorStore


async def main():
    # Load environment variables
    load_dotenv()

    # Configuration
    pdf_path = "YOUR_FILE.pdf"

    cohere_api_key = os.getenv("COHERE_API_KEY")

    try:
        # Initialize vector store
        qdrant_client = AsyncQdrantClient(":memory:")
        vector_store = QdrantVectorStore(qdrant_client, collection_name="my_docs")

        # Initialize RAG client
        rag = MultiModalRAG(vector_store, cohere_api_key, verbose=True)

        # Index PDF
        summary = await rag.index(pdf_path)
        print(f"Indexing summary: {summary}")

        query = "" # Replace with your query

        # Retrieve results
        results = await rag.retrieve(query, top_k=3)

        # Display results
        for i, result in enumerate(results, 1):
            print(f"\nResult {i}:")
            print(f"  Source: {result.source_file}")
            print(f"  Page: {result.page_number}")
            print(f"  Score: {result.score:.4f}")
            print(f"  Image Path: {result.image_path}")

    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(main())
```


### Output Directory

The `output_dir` parameter in `MultiModalRAG` specifies where supporting files are stored, primarily the images extracted from PDFs.

*   **Default:** If `output_dir` is not provided, it defaults to `./.orbitron/data` (a directory named `.orbitron` containing `data`) **relative to the current working directory** where your Python script is executed.
*   **Specified Path:** If you provide a path (e.g., `output_dir="my_data"` or `output_dir="/abs/path/data"`), Orbitron will resolve it:
    *   Relative paths are interpreted relative to the current working directory.
    *   Absolute paths are used directly.


## Contributing

Contributions are welcome! Please follow these guidelines:

1.  **Reporting Issues:** Use the GitHub issue tracker to report bugs, suggest features, or ask questions. Provide clear steps to reproduce bugs.
2.  **Pull Requests:**
    *   Fork the repository.
    *   Create a new branch for your feature or bug fix.
    *   Install development dependencies: `pip install -e .[dev]`
    *   Make your changes.
    *   Ensure code is formatted (`black .`), sorted (`isort .`), and passes type checks (`mypy src`). Add tests if applicable.
    *   Commit your changes with clear messages.
    *   Push your branch and open a pull request against the main branch.

## License

This project is licensed under the **MIT License**. See the `LICENSE` file for details.

---