ragit 0.0.1__py3-none-any.whl

ragit/providers/base.py

@@ -0,0 +1,146 @@
+#
+# Copyright RODMENA LIMITED 2025
+# SPDX-License-Identifier: Apache-2.0
+#
+"""
+Base provider interfaces for LLM and Embedding providers.
+
+These abstract classes define the interface that all providers must implement,
+making it easy to add new providers (Gemini, Claude, OpenAI, etc.)
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class LLMResponse:
+    """Response from an LLM call."""
+    text: str
+    model: str
+    provider: str
+    usage: Optional[dict] = None
+
+
+@dataclass
+class EmbeddingResponse:
+    """Response from an embedding call."""
+    embedding: list[float]
+    model: str
+    provider: str
+    dimensions: int
+
+
+class BaseLLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+
+    Implement this to add support for new LLM providers like Gemini, Claude, etc.
+    """
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the provider name (e.g., 'ollama', 'gemini', 'claude')."""
+        pass
+
+    @abstractmethod
+    def generate(
+        self,
+        prompt: str,
+        model: str,
+        system_prompt: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> LLMResponse:
+        """
+        Generate text from the LLM.
+
+        Parameters
+        ----------
+        prompt : str
+            The user prompt/query.
+        model : str
+            Model identifier (e.g., 'llama3', 'qwen3-vl:235b-instruct-cloud').
+        system_prompt : str, optional
+            System prompt for context/instructions.
+        temperature : float
+            Sampling temperature (0.0 to 1.0).
+        max_tokens : int, optional
+            Maximum tokens to generate.
+
+        Returns
+        -------
+        LLMResponse
+            The generated response.
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the provider is available and configured."""
+        pass
+
+
+class BaseEmbeddingProvider(ABC):
+    """
+    Abstract base class for embedding providers.
+
+    Implement this to add support for new embedding providers.
+    """
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the provider name."""
+        pass
+
+    @property
+    @abstractmethod
+    def dimensions(self) -> int:
+        """Return the embedding dimensions for the current model."""
+        pass
+
+    @abstractmethod
+    def embed(self, text: str, model: str) -> EmbeddingResponse:
+        """
+        Generate embedding for text.
+
+        Parameters
+        ----------
+        text : str
+            Text to embed.
+        model : str
+            Model identifier (e.g., 'nomic-embed-text').
+
+        Returns
+        -------
+        EmbeddingResponse
+            The embedding response.
+        """
+        pass
+
+    @abstractmethod
+    def embed_batch(self, texts: list[str], model: str) -> list[EmbeddingResponse]:
+        """
+        Generate embeddings for multiple texts.
+
+        Parameters
+        ----------
+        texts : list[str]
+            Texts to embed.
+        model : str
+            Model identifier.
+
+        Returns
+        -------
+        list[EmbeddingResponse]
+            List of embedding responses.
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the provider is available and configured."""
+        pass

ragit/providers/ollama.py

@@ -0,0 +1,250 @@
+#
+# Copyright RODMENA LIMITED 2025
+# SPDX-License-Identifier: Apache-2.0
+#
+"""
+Ollama provider for LLM and Embedding operations.
+
+This provider connects to a local or remote Ollama server.
+"""
+
+import requests
+from typing import Optional
+
+from ragit.providers.base import (
+    BaseLLMProvider,
+    BaseEmbeddingProvider,
+    LLMResponse,
+    EmbeddingResponse,
+)
+
+
+class OllamaProvider(BaseLLMProvider, BaseEmbeddingProvider):
+    """
+    Ollama provider for both LLM and Embedding operations.
+
+    Parameters
+    ----------
+    base_url : str
+        Ollama server URL (default: http://localhost:11434)
+    timeout : int
+        Request timeout in seconds (default: 120)
+
+    Examples
+    --------
+    >>> provider = OllamaProvider()
+    >>> response = provider.generate("What is RAG?", model="llama3")
+    >>> print(response.text)
+
+    >>> embedding = provider.embed("Hello world", model="nomic-embed-text")
+    >>> print(len(embedding.embedding))
+    """
+
+    # Known embedding model dimensions
+    EMBEDDING_DIMENSIONS = {
+        "nomic-embed-text": 768,
+        "nomic-embed-text:latest": 768,
+        "mxbai-embed-large": 1024,
+        "all-minilm": 384,
+        "snowflake-arctic-embed": 1024,
+    }
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:11434",
+        timeout: int = 120,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._current_embed_model: Optional[str] = None
+        self._current_dimensions: int = 768  # default
+
+    @property
+    def provider_name(self) -> str:
+        return "ollama"
+
+    @property
+    def dimensions(self) -> int:
+        return self._current_dimensions
+
+    def is_available(self) -> bool:
+        """Check if Ollama server is reachable."""
+        try:
+            response = requests.get(f"{self.base_url}/api/tags", timeout=5)
+            return response.status_code == 200
+        except requests.RequestException:
+            return False
+
+    def list_models(self) -> list[dict]:
+        """List available models on the Ollama server."""
+        try:
+            response = requests.get(f"{self.base_url}/api/tags", timeout=10)
+            response.raise_for_status()
+            return response.json().get("models", [])
+        except requests.RequestException as e:
+            raise ConnectionError(f"Failed to list Ollama models: {e}") from e
+
+    def generate(
+        self,
+        prompt: str,
+        model: str,
+        system_prompt: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> LLMResponse:
+        """Generate text using Ollama."""
+        payload = {
+            "model": model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {
+                "temperature": temperature,
+            },
+        }
+
+        if system_prompt:
+            payload["system"] = system_prompt
+
+        if max_tokens:
+            payload["options"]["num_predict"] = max_tokens
+
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/generate",
+                json=payload,
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            return LLMResponse(
+                text=data.get("response", ""),
+                model=model,
+                provider=self.provider_name,
+                usage={
+                    "prompt_tokens": data.get("prompt_eval_count"),
+                    "completion_tokens": data.get("eval_count"),
+                    "total_duration": data.get("total_duration"),
+                },
+            )
+        except requests.RequestException as e:
+            raise ConnectionError(f"Ollama generate failed: {e}") from e
+
+    def embed(self, text: str, model: str) -> EmbeddingResponse:
+        """Generate embedding using Ollama."""
+        self._current_embed_model = model
+        self._current_dimensions = self.EMBEDDING_DIMENSIONS.get(model, 768)
+
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/embed",
+                json={"model": model, "input": text},
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            embedding = data.get("embeddings", [[]])[0]
+            if not embedding:
+                raise ValueError("Empty embedding returned from Ollama")
+
+            # Update dimensions from actual response
+            self._current_dimensions = len(embedding)
+
+            return EmbeddingResponse(
+                embedding=embedding,
+                model=model,
+                provider=self.provider_name,
+                dimensions=len(embedding),
+            )
+        except requests.RequestException as e:
+            raise ConnectionError(f"Ollama embed failed: {e}") from e
+
+    def embed_batch(self, texts: list[str], model: str) -> list[EmbeddingResponse]:
+        """Generate embeddings for multiple texts."""
+        self._current_embed_model = model
+        self._current_dimensions = self.EMBEDDING_DIMENSIONS.get(model, 768)
+
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/embed",
+                json={"model": model, "input": texts},
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            embeddings = data.get("embeddings", [])
+            if embeddings:
+                self._current_dimensions = len(embeddings[0])
+
+            return [
+                EmbeddingResponse(
+                    embedding=emb,
+                    model=model,
+                    provider=self.provider_name,
+                    dimensions=len(emb),
+                )
+                for emb in embeddings
+            ]
+        except requests.RequestException as e:
+            raise ConnectionError(f"Ollama batch embed failed: {e}") from e
+
+    def chat(
+        self,
+        messages: list[dict],
+        model: str,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> LLMResponse:
+        """
+        Chat completion using Ollama.
+
+        Parameters
+        ----------
+        messages : list[dict]
+            List of messages with 'role' and 'content' keys.
+        model : str
+            Model identifier.
+        temperature : float
+            Sampling temperature.
+        max_tokens : int, optional
+            Maximum tokens to generate.
+
+        Returns
+        -------
+        LLMResponse
+            The generated response.
+        """
+        payload = {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+            "options": {
+                "temperature": temperature,
+            },
+        }
+
+        if max_tokens:
+            payload["options"]["num_predict"] = max_tokens
+
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/chat",
+                json=payload,
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            return LLMResponse(
+                text=data.get("message", {}).get("content", ""),
+                model=model,
+                provider=self.provider_name,
+                usage={
+                    "prompt_tokens": data.get("prompt_eval_count"),
+                    "completion_tokens": data.get("eval_count"),
+                },
+            )
+        except requests.RequestException as e:
+            raise ConnectionError(f"Ollama chat failed: {e}") from e

ragit/utils/__init__.py

@@ -0,0 +1,105 @@
+#
+# Copyright RODMENA LIMITED 2025
+# SPDX-License-Identifier: Apache-2.0
+#
+"""
+Ragit utilities module.
+"""
+
+from collections import deque
+from collections.abc import Hashable
+from datetime import datetime
+from math import floor
+from typing import Sequence
+
+import pandas as pd
+
+
+def get_hashable_repr(dct: dict):
+    """
+    Returns a hashable representation of the provided dictionary.
+    """
+    queue = deque((k, v, 0, None) for k, v in dct.items())
+    dict_unpacked = []
+    while queue:
+        key, val, lvl, p_ref = queue.pop()
+        if hasattr(val, "items"):  # we have a nested dict
+            dict_unpacked.append((key, "+", lvl, p_ref))
+            if hash(key) != p_ref:
+                lvl += 1
+            queue.extendleft((k, v, lvl, hash(key)) for k, v in val.items())
+        elif isinstance(val, Hashable):
+            dict_unpacked.append((key, val, lvl, p_ref))
+        elif isinstance(val, Sequence):
+            dict_unpacked.append((key, "+", lvl, p_ref))
+            queue.extendleft((key, vv, floor(lvl) + ind * 0.01, hash(key)) for ind, vv in enumerate(val, 1))
+        else:
+            raise ValueError(f"Unsupported type in dict: {type(val)}")
+
+    return tuple(sorted(dict_unpacked, key=lambda it: (it[2], it[0])))
+
+
+def remove_duplicates(items: list[dict]) -> list[dict]:
+    """
+    Deduplicates list of provided dictionary items.
+
+    Parameters
+    ----------
+    items : list[dict]
+        List of items to deduplicate.
+
+    Returns
+    -------
+    list[dict]
+        A deduplicated list of input items.
+    """
+    duplicate_tracker = set()
+    deduplicated_items = []
+    for ind, elem in enumerate(map(get_hashable_repr, items)):
+        if elem not in duplicate_tracker:
+            duplicate_tracker.add(elem)
+            deduplicated_items.append(items[ind])
+    return deduplicated_items
+
+
+def handle_missing_values_in_combinations(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Handle missing values in experiment data combinations.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Experiment data with combinations being explored.
+
+    Returns
+    -------
+    pd.DataFrame
+        Data with NaN values properly replaced.
+    """
+    if "chunk_overlap" in df.columns:
+        df["chunk_overlap"] = df["chunk_overlap"].map(lambda el: 0 if pd.isna(el) else el)
+
+    return df
+
+
+def datetime_str_to_epoch_time(timestamp: str | int) -> str | int:
+    """
+    Convert datetime string to epoch time.
+
+    Parameters
+    ----------
+    timestamp : str | int
+        Either a datetime string or a unix timestamp.
+
+    Returns
+    -------
+    int
+        Unix timestamp or -1 if parsing fails.
+    """
+    if not isinstance(timestamp, str):
+        return timestamp
+    try:
+        iso_parseable = datetime.fromisoformat(timestamp)
+    except ValueError:
+        return -1
+    return int(iso_parseable.timestamp())

ragit/version.py

@@ -0,0 +1,5 @@
+#
+# Copyright RODMENA LIMITED 2025
+# SPDX-License-Identifier: Apache-2.0
+#
+__version__ = "0.0.1"

ragit-0.0.1.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ragit
+Version: 0.0.1
+Summary: Automatic RAG Pattern Optimization Engine
+Author: RODMENA LIMITED
+Maintainer-email: RODMENA LIMITED <info@rodmena.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/rodmena-limited/ragit
+Project-URL: Repository, https://github.com/rodmena-limited/ragit
+Project-URL: Issues, https://github.com/rodmena-limited/ragit/issues
+Keywords: AI,RAG,LLM,GenAI,Optimization,Ollama
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: dev
+Requires-Dist: ragit[test]; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Dynamic: license-file
+
+# ragit
+
+Automatic RAG (Retrieval-Augmented Generation) hyperparameter optimization engine.
+
+## What it does
+
+ragit finds the best configuration for your RAG pipeline by testing different combinations of:
+- Chunk sizes and overlaps
+- Number of retrieved chunks
+- Embedding models
+- LLM models
+
+You provide documents and benchmark questions, ragit evaluates different configurations and returns the best one.
+
+## Install
+
+```bash
+pip install ragit
+```
+
+## Usage
+
+```python
+from ragit import RagitExperiment, Document, BenchmarkQuestion
+
+documents = [
+    Document(id="doc1", content="Your document text here..."),
+]
+
+benchmark = [
+    BenchmarkQuestion(
+        question="A question about your documents?",
+        ground_truth="The expected answer."
+    ),
+]
+
+experiment = RagitExperiment(documents, benchmark)
+results = experiment.run()
+
+print(results[0])  # Best configuration
+```
+
+## License
+
+Apache-2.0 - RODMENA LIMITED

ragit-0.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+ragit/__init__.py,sha256=kAHylscZh8-O8YdyO_5x0Wry3yTMBu0aUAPNV6z9tng,1539
+ragit/version.py,sha256=0QBeKFCe0Qwtua_u4nCcHvzZyfARcJVV-zvY4l2wYwA,97
+ragit/core/__init__.py,sha256=j53PFfoSMXwSbK1rRHpMbo8mX2i4R1LJ5kvTxBd7-0w,100
+ragit/core/experiment/__init__.py,sha256=_olxvo2Mf6fcBNhUf5YA-v2KIMb5W3UQA2hl30HLgRw,452
+ragit/core/experiment/experiment.py,sha256=ykbLqmFMsQ7gqcHqzJ8KAEKe-BQFur6aVw5imZlKJ80,14769
+ragit/core/experiment/results.py,sha256=UzPSVlJTfOgu6SQhVIVT8IzN4Eo7tQQ9oNGUVANCTTU,3453
+ragit/providers/__init__.py,sha256=znyg13wFgcNKVT7YYimRRwu3nvdrrQsVA251fY8LOX4,435
+ragit/providers/base.py,sha256=F64KxlQh9Mq1bv842y9yUcAiWdjhPxiYVQoVXqk7ULs,3428
+ragit/providers/ollama.py,sha256=AM4_DeWv7lS78KlIEh3k8XbXOf8mMazpfjKZYIN6t4k,7637
+ragit/utils/__init__.py,sha256=ZTlohzMF_3hMLZDaDZ94BGvP6SdqnTjJ40AVk4S1Cl0,2867
+ragit-0.0.1.dist-info/licenses/LICENSE,sha256=tAkwu8-AdEyGxGoSvJ2gVmQdcicWw3j1ZZueVV74M-E,11357
+ragit-0.0.1.dist-info/METADATA,sha256=TXd4diiW82nJaYDvixdkGLXPRi451l_LVQMjI1uIr-0,2329
+ragit-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ragit-0.0.1.dist-info/top_level.txt,sha256=pkPbG7yrw61wt9_y_xcLE2vq2a55fzockASD0yq0g4s,6
+ragit-0.0.1.dist-info/RECORD,,

ragit-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+