ragit 0.7.5__tar.gz → 0.8.1__tar.gz

ragit-0.8.1/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: ragit
+Version: 0.8.1
+Summary: Automatic RAG Pattern Optimization Engine
+Author: RODMENA LIMITED
+Maintainer-email: RODMENA LIMITED <info@rodmena.co.uk>
+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: Programming Language :: Python :: 3.14
+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: python-dotenv>=1.0.0
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: trio>=0.24.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: ragit[test]; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: issuedb[web]; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Provides-Extra: transformers
+Requires-Dist: sentence-transformers>=2.2.0; extra == "transformers"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Dynamic: license-file
+
+# ragit
+
+RAG toolkit for Python. Document loading, chunking, vector search, LLM integration.
+
+## Installation
+
+```bash
+pip install ragit
+
+# For offline embedding
+pip install ragit[transformers]
+```
+
+## Quick Start
+
+You must provide an embedding source: custom function, SentenceTransformers, or any provider.
+
+### Custom Embedding Function
+
+```python
+from ragit import RAGAssistant
+
+def my_embed(text: str) -> list[float]:
+    # Use any embedding API: OpenAI, Cohere, HuggingFace, etc.
+    return embedding_vector
+
+assistant = RAGAssistant("docs/", embed_fn=my_embed)
+results = assistant.retrieve("search query")
+```
+
+### With LLM for Q&A
+
+```python
+def my_embed(text: str) -> list[float]:
+    return embedding_vector
+
+def my_generate(prompt: str, system_prompt: str = "") -> str:
+    return llm_response
+
+assistant = RAGAssistant("docs/", embed_fn=my_embed, generate_fn=my_generate)
+answer = assistant.ask("How does authentication work?")
+```
+
+### Offline Embedding (SentenceTransformers)
+
+Models are downloaded automatically on first use (~90MB for default model).
+
+```python
+from ragit import RAGAssistant
+from ragit.providers import SentenceTransformersProvider
+
+# Uses all-MiniLM-L6-v2 by default
+assistant = RAGAssistant("docs/", provider=SentenceTransformersProvider())
+
+# Or specify a model
+assistant = RAGAssistant(
+    "docs/",
+    provider=SentenceTransformersProvider(model_name="all-mpnet-base-v2")
+)
+```
+
+Available models: `all-MiniLM-L6-v2` (384d), `all-mpnet-base-v2` (768d), `paraphrase-MiniLM-L6-v2` (384d)
+
+## Core API
+
+```python
+assistant = RAGAssistant(
+    documents,           # Path, list of Documents, or list of Chunks
+    embed_fn=...,        # Embedding function: (str) -> list[float]
+    generate_fn=...,     # LLM function: (prompt, system_prompt) -> str
+    provider=...,        # Or use a provider instead of functions
+    chunk_size=512,
+    chunk_overlap=50
+)
+
+results = assistant.retrieve(query, top_k=3)      # [(Chunk, score), ...]
+context = assistant.get_context(query, top_k=3)   # Formatted string
+answer = assistant.ask(question, top_k=3)         # Requires generate_fn/LLM
+code = assistant.generate_code(request)           # Requires generate_fn/LLM
+```
+
+## Document Loading
+
+```python
+from ragit import load_text, load_directory, chunk_text
+
+doc = load_text("file.md")
+docs = load_directory("docs/", "*.md")
+chunks = chunk_text(text, chunk_size=512, chunk_overlap=50, doc_id="id")
+```
+
+## Hyperparameter Optimization
+
+```python
+from ragit import RagitExperiment, Document, BenchmarkQuestion
+
+def my_embed(text: str) -> list[float]:
+    return embedding_vector
+
+def my_generate(prompt: str, system_prompt: str = "") -> str:
+    return llm_response
+
+docs = [Document(id="1", content="...")]
+benchmark = [BenchmarkQuestion(question="...", ground_truth="...")]
+
+experiment = RagitExperiment(
+    docs, benchmark,
+    embed_fn=my_embed,
+    generate_fn=my_generate
+)
+results = experiment.run(max_configs=20)
+print(results[0])  # Best config
+```
+
+## License
+
+Apache-2.0 - RODMENA LIMITED

ragit-0.8.1/README.md

@@ -0,0 +1,117 @@
+# ragit
+
+RAG toolkit for Python. Document loading, chunking, vector search, LLM integration.
+
+## Installation
+
+```bash
+pip install ragit
+
+# For offline embedding
+pip install ragit[transformers]
+```
+
+## Quick Start
+
+You must provide an embedding source: custom function, SentenceTransformers, or any provider.
+
+### Custom Embedding Function
+
+```python
+from ragit import RAGAssistant
+
+def my_embed(text: str) -> list[float]:
+    # Use any embedding API: OpenAI, Cohere, HuggingFace, etc.
+    return embedding_vector
+
+assistant = RAGAssistant("docs/", embed_fn=my_embed)
+results = assistant.retrieve("search query")
+```
+
+### With LLM for Q&A
+
+```python
+def my_embed(text: str) -> list[float]:
+    return embedding_vector
+
+def my_generate(prompt: str, system_prompt: str = "") -> str:
+    return llm_response
+
+assistant = RAGAssistant("docs/", embed_fn=my_embed, generate_fn=my_generate)
+answer = assistant.ask("How does authentication work?")
+```
+
+### Offline Embedding (SentenceTransformers)
+
+Models are downloaded automatically on first use (~90MB for default model).
+
+```python
+from ragit import RAGAssistant
+from ragit.providers import SentenceTransformersProvider
+
+# Uses all-MiniLM-L6-v2 by default
+assistant = RAGAssistant("docs/", provider=SentenceTransformersProvider())
+
+# Or specify a model
+assistant = RAGAssistant(
+    "docs/",
+    provider=SentenceTransformersProvider(model_name="all-mpnet-base-v2")
+)
+```
+
+Available models: `all-MiniLM-L6-v2` (384d), `all-mpnet-base-v2` (768d), `paraphrase-MiniLM-L6-v2` (384d)
+
+## Core API
+
+```python
+assistant = RAGAssistant(
+    documents,           # Path, list of Documents, or list of Chunks
+    embed_fn=...,        # Embedding function: (str) -> list[float]
+    generate_fn=...,     # LLM function: (prompt, system_prompt) -> str
+    provider=...,        # Or use a provider instead of functions
+    chunk_size=512,
+    chunk_overlap=50
+)
+
+results = assistant.retrieve(query, top_k=3)      # [(Chunk, score), ...]
+context = assistant.get_context(query, top_k=3)   # Formatted string
+answer = assistant.ask(question, top_k=3)         # Requires generate_fn/LLM
+code = assistant.generate_code(request)           # Requires generate_fn/LLM
+```
+
+## Document Loading
+
+```python
+from ragit import load_text, load_directory, chunk_text
+
+doc = load_text("file.md")
+docs = load_directory("docs/", "*.md")
+chunks = chunk_text(text, chunk_size=512, chunk_overlap=50, doc_id="id")
+```
+
+## Hyperparameter Optimization
+
+```python
+from ragit import RagitExperiment, Document, BenchmarkQuestion
+
+def my_embed(text: str) -> list[float]:
+    return embedding_vector
+
+def my_generate(prompt: str, system_prompt: str = "") -> str:
+    return llm_response
+
+docs = [Document(id="1", content="...")]
+benchmark = [BenchmarkQuestion(question="...", ground_truth="...")]
+
+experiment = RagitExperiment(
+    docs, benchmark,
+    embed_fn=my_embed,
+    generate_fn=my_generate
+)
+results = experiment.run(max_configs=20)
+print(results[0])  # Best config
+```
+
+## License
+
+Apache-2.0 - RODMENA LIMITED

{ragit-0.7.5 → ragit-0.8.1}/pyproject.toml

@@ -59,6 +59,8 @@ dev = [
 
 test = ["pytest", "pytest-cov", "pytest-mock"]
 
+transformers = ["sentence-transformers>=2.2.0"]
+
 docs = [
     "sphinx>=7.0",
     "sphinx-rtd-theme>=2.0",
@@ -79,7 +81,7 @@ python_classes = ["Test*"]
 python_functions = ["test_*"]
 log_cli = false
 log_level = "INFO"
-addopts = "-v --tb=short"
+addopts = "-v --tb=short -m 'not integration'"
 markers = [
     "integration: marks tests as integration tests (may require external services)",
 ]

{ragit-0.7.5 → ragit-0.8.1}/ragit/__init__.py

@@ -9,14 +9,21 @@ Quick Start
 -----------
 >>> from ragit import RAGAssistant
 >>>
->>> # Load docs and ask questions
->>> assistant = RAGAssistant("docs/")
->>> answer = assistant.ask("How do I create a REST API?")
->>> print(answer)
+>>> # With custom embedding function (retrieval-only)
+>>> def my_embed(text: str) -> list[float]:
+...     # Your embedding implementation
+...     pass
+>>> assistant = RAGAssistant("docs/", embed_fn=my_embed)
+>>> results = assistant.retrieve("How do I create a REST API?")
+>>>
+>>> # With SentenceTransformers (offline, requires ragit[transformers])
+>>> from ragit.providers import SentenceTransformersProvider
+>>> assistant = RAGAssistant("docs/", provider=SentenceTransformersProvider())
 >>>
->>> # Generate code
->>> code = assistant.generate_code("create a user authentication API")
->>> print(code)
+>>> # With Ollama (explicit)
+>>> from ragit.providers import OllamaProvider
+>>> assistant = RAGAssistant("docs/", provider=OllamaProvider())
+>>> answer = assistant.ask("How do I create a REST API?")
 
 Optimization
 ------------
@@ -25,7 +32,8 @@ Optimization
 >>> docs = [Document(id="doc1", content="...")]
 >>> benchmark = [BenchmarkQuestion(question="What is X?", ground_truth="...")]
 >>>
->>> experiment = RagitExperiment(docs, benchmark)
+>>> # With explicit provider
+>>> experiment = RagitExperiment(docs, benchmark, provider=OllamaProvider())
 >>> results = experiment.run()
 >>> print(results[0])  # Best configuration
 """
@@ -63,7 +71,12 @@ from ragit.loaders import (  # noqa: E402
     load_directory,
     load_text,
 )
-from ragit.providers import OllamaProvider  # noqa: E402
+from ragit.providers import (  # noqa: E402
+    BaseEmbeddingProvider,
+    BaseLLMProvider,
+    FunctionProvider,
+    OllamaProvider,
+)
 
 __all__ = [
     "__version__",
@@ -79,7 +92,11 @@ __all__ = [
     # Core classes
     "Document",
     "Chunk",
+    # Providers
     "OllamaProvider",
+    "FunctionProvider",
+    "BaseLLMProvider",
+    "BaseEmbeddingProvider",
     # Optimization
     "RagitExperiment",
     "BenchmarkQuestion",
@@ -87,3 +104,13 @@ __all__ = [
     "EvaluationResult",
     "ExperimentResults",
 ]
+
+# Conditionally add SentenceTransformersProvider if available
+try:
+    from ragit.providers import (  # noqa: E402
+        SentenceTransformersProvider as SentenceTransformersProvider,
+    )
+
+    __all__ += ["SentenceTransformersProvider"]
+except ImportError:
+    pass

{ragit-0.7.5 → ragit-0.8.1}/ragit/assistant.py

@@ -10,16 +10,17 @@ Provides a simple interface for RAG-based tasks.
 Note: This class is NOT thread-safe. Do not share instances across threads.
 """
 
+from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import numpy as np
 from numpy.typing import NDArray
 
-from ragit.config import config
 from ragit.core.experiment.experiment import Chunk, Document
 from ragit.loaders import chunk_document, chunk_rst_sections, load_directory, load_text
-from ragit.providers import OllamaProvider
+from ragit.providers.base import BaseEmbeddingProvider, BaseLLMProvider
+from ragit.providers.function_adapter import FunctionProvider
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
@@ -38,48 +39,100 @@ class RAGAssistant:
         - List of Document objects
         - Path to a single file
         - Path to a directory (will load all .txt, .md, .rst files)
-    provider : OllamaProvider, optional
-        LLM/embedding provider. Defaults to OllamaProvider().
+    embed_fn : Callable[[str], list[float]], optional
+        Function that takes text and returns an embedding vector.
+        If provided, creates a FunctionProvider internally.
+    generate_fn : Callable, optional
+        Function for text generation. Supports (prompt) or (prompt, system_prompt).
+        If provided without embed_fn, must also provide embed_fn.
+    provider : BaseEmbeddingProvider, optional
+        Provider for embeddings (and optionally LLM). If embed_fn is provided,
+        this is ignored for embeddings.
     embedding_model : str, optional
-        Embedding model name. Defaults to config.DEFAULT_EMBEDDING_MODEL.
+        Embedding model name (used with provider).
     llm_model : str, optional
-        LLM model name. Defaults to config.DEFAULT_LLM_MODEL.
+        LLM model name (used with provider).
     chunk_size : int, optional
         Chunk size for splitting documents (default: 512).
     chunk_overlap : int, optional
         Overlap between chunks (default: 50).
 
+    Raises
+    ------
+    ValueError
+        If neither embed_fn nor provider is provided.
+
     Note
     ----
     This class is NOT thread-safe. Each thread should have its own instance.
 
     Examples
     --------
-    >>> # From documents
-    >>> assistant = RAGAssistant([Document(id="doc1", content="...")])
+    >>> # With custom embedding function (retrieval-only)
+    >>> assistant = RAGAssistant(docs, embed_fn=my_embed)
+    >>> results = assistant.retrieve("query")
+    >>>
+    >>> # With custom embedding and LLM functions (full RAG)
+    >>> assistant = RAGAssistant(docs, embed_fn=my_embed, generate_fn=my_llm)
     >>> answer = assistant.ask("What is X?")
-
-    >>> # From file
-    >>> assistant = RAGAssistant("docs/tutorial.rst")
-    >>> answer = assistant.ask("How do I do Y?")
-
-    >>> # From directory
-    >>> assistant = RAGAssistant("docs/")
-    >>> answer = assistant.ask("Explain Z")
+    >>>
+    >>> # With explicit provider
+    >>> from ragit.providers import OllamaProvider
+    >>> assistant = RAGAssistant(docs, provider=OllamaProvider())
+    >>>
+    >>> # With SentenceTransformers (offline)
+    >>> from ragit.providers import SentenceTransformersProvider
+    >>> assistant = RAGAssistant(docs, provider=SentenceTransformersProvider())
     """
 
     def __init__(
         self,
         documents: list[Document] | str | Path,
-        provider: OllamaProvider | None = None,
+        embed_fn: Callable[[str], list[float]] | None = None,
+        generate_fn: Callable[..., str] | None = None,
+        provider: BaseEmbeddingProvider | BaseLLMProvider | None = None,
         embedding_model: str | None = None,
         llm_model: str | None = None,
         chunk_size: int = 512,
         chunk_overlap: int = 50,
     ):
-        self.provider = provider or OllamaProvider()
-        self.embedding_model = embedding_model or config.DEFAULT_EMBEDDING_MODEL
-        self.llm_model = llm_model or config.DEFAULT_LLM_MODEL
+        # Resolve provider from embed_fn/generate_fn or explicit provider
+        self._embedding_provider: BaseEmbeddingProvider
+        self._llm_provider: BaseLLMProvider | None = None
+
+        if embed_fn is not None:
+            # Create FunctionProvider from provided functions
+            function_provider = FunctionProvider(
+                embed_fn=embed_fn,
+                generate_fn=generate_fn,
+            )
+            self._embedding_provider = function_provider
+            if generate_fn is not None:
+                self._llm_provider = function_provider
+            elif provider is not None and isinstance(provider, BaseLLMProvider):
+                # Use explicit provider for LLM if function_provider doesn't have LLM
+                self._llm_provider = provider
+        elif provider is not None:
+            # Use explicit provider
+            if not isinstance(provider, BaseEmbeddingProvider):
+                raise ValueError(
+                    "Provider must implement BaseEmbeddingProvider for embeddings. "
+                    "Alternatively, provide embed_fn."
+                )
+            self._embedding_provider = provider
+            if isinstance(provider, BaseLLMProvider):
+                self._llm_provider = provider
+        else:
+            raise ValueError(
+                "Must provide embed_fn or provider for embeddings. "
+                "Examples:\n"
+                "  RAGAssistant(docs, embed_fn=my_embed_function)\n"
+                "  RAGAssistant(docs, provider=OllamaProvider())\n"
+                "  RAGAssistant(docs, provider=SentenceTransformersProvider())"
+            )
+
+        self.embedding_model = embedding_model or "default"
+        self.llm_model = llm_model or "default"
         self.chunk_size = chunk_size
         self.chunk_overlap = chunk_overlap
 
@@ -128,7 +181,7 @@ class RAGAssistant:
 
         # Batch embed all chunks at once (single API call)
         texts = [chunk.content for chunk in all_chunks]
-        responses = self.provider.embed_batch(texts, self.embedding_model)
+        responses = self._embedding_provider.embed_batch(texts, self.embedding_model)
 
         # Build embedding matrix directly (skip storing in chunks to avoid duplication)
         embedding_matrix = np.array([response.embedding for response in responses], dtype=np.float64)
@@ -169,7 +222,7 @@ class RAGAssistant:
             return []
 
         # Get query embedding and normalize
-        query_response = self.provider.embed(query, self.embedding_model)
+        query_response = self._embedding_provider.embed(query, self.embedding_model)
         query_vec = np.array(query_response.embedding, dtype=np.float64)
         query_norm = np.linalg.norm(query_vec)
         if query_norm == 0:
@@ -209,6 +262,15 @@ class RAGAssistant:
         results = self.retrieve(query, top_k)
         return "\n\n---\n\n".join(chunk.content for chunk, _ in results)
 
+    def _ensure_llm(self) -> BaseLLMProvider:
+        """Ensure LLM provider is available."""
+        if self._llm_provider is None:
+            raise NotImplementedError(
+                "No LLM configured. Provide generate_fn or a provider with LLM support "
+                "to use ask(), generate(), or generate_code() methods."
+            )
+        return self._llm_provider
+
     def generate(
         self,
         prompt: str,
@@ -231,8 +293,14 @@ class RAGAssistant:
         -------
         str
             Generated text.
+
+        Raises
+        ------
+        NotImplementedError
+            If no LLM is configured.
         """
-        response = self.provider.generate(
+        llm = self._ensure_llm()
+        response = llm.generate(
             prompt=prompt,
             model=self.llm_model,
             system_prompt=system_prompt,
@@ -266,6 +334,11 @@ class RAGAssistant:
         str
             Generated answer.
 
+        Raises
+        ------
+        NotImplementedError
+            If no LLM is configured.
+
         Examples
         --------
         >>> answer = assistant.ask("How do I create a REST API?")
@@ -315,6 +388,11 @@ Answer:"""
         str
             Generated code (cleaned, without markdown).
 
+        Raises
+        ------
+        NotImplementedError
+            If no LLM is configured.
+
         Examples
         --------
         >>> code = assistant.generate_code("create a REST API with user endpoints")
@@ -357,3 +435,8 @@ Generate the {language} code:"""
     def num_documents(self) -> int:
         """Return number of loaded documents."""
         return len(self.documents)
+
+    @property
+    def has_llm(self) -> bool:
+        """Check if LLM is configured."""
+        return self._llm_provider is not None

{ragit-0.7.5 → ragit-0.8.1}/ragit/config.py

@@ -6,6 +6,9 @@
 Ragit configuration management.
 
 Loads configuration from environment variables and .env files.
+
+Note: As of v0.8.0, ragit no longer has default LLM or embedding models.
+Users must explicitly configure providers.
 """
 
 import os
@@ -27,21 +30,27 @@ else:
 
 
 class Config:
-    """Ragit configuration loaded from environment variables."""
+    """Ragit configuration loaded from environment variables.
+
+    Note: As of v0.8.0, DEFAULT_LLM_MODEL and DEFAULT_EMBEDDING_MODEL are
+    no longer used as defaults. They are only read from environment variables
+    for backwards compatibility with user configurations.
+    """
 
-    # Ollama LLM API Configuration (can be cloud)
+    # Ollama LLM API Configuration (used when explicitly using OllamaProvider)
     OLLAMA_BASE_URL: str = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434")
     OLLAMA_API_KEY: str | None = os.getenv("OLLAMA_API_KEY")
     OLLAMA_TIMEOUT: int = int(os.getenv("OLLAMA_TIMEOUT", "120"))
 
-    # Ollama Embedding API Configuration (cloud doesn't support embeddings, use local)
+    # Ollama Embedding API Configuration
     OLLAMA_EMBEDDING_URL: str = os.getenv(
         "OLLAMA_EMBEDDING_URL", os.getenv("OLLAMA_BASE_URL", "http://localhost:11434")
     )
 
-    # Default Models
-    DEFAULT_LLM_MODEL: str = os.getenv("RAGIT_DEFAULT_LLM_MODEL", "qwen3-vl:235b-instruct")
-    DEFAULT_EMBEDDING_MODEL: str = os.getenv("RAGIT_DEFAULT_EMBEDDING_MODEL", "nomic-embed-text:latest")
+    # Model settings (only used if explicitly requested, no defaults)
+    # These can still be set via environment variables for convenience
+    DEFAULT_LLM_MODEL: str | None = os.getenv("RAGIT_DEFAULT_LLM_MODEL")
+    DEFAULT_EMBEDDING_MODEL: str | None = os.getenv("RAGIT_DEFAULT_EMBEDDING_MODEL")
 
     # Logging
     LOG_LEVEL: str = os.getenv("RAGIT_LOG_LEVEL", "INFO")