ragit 0.7.5__py3-none-any.whl → 0.8.1__py3-none-any.whl

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/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/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")

ragit/core/experiment/experiment.py

@@ -9,6 +9,7 @@ This module provides the main experiment class for optimizing RAG hyperparameter
 """
 
 import time
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from itertools import product
 from typing import Any
@@ -16,9 +17,9 @@ from typing import Any
 import numpy as np
 from tqdm import tqdm
 
-from ragit.config import config
 from ragit.core.experiment.results import EvaluationResult
-from ragit.providers import OllamaProvider
+from ragit.providers.base import BaseEmbeddingProvider, BaseLLMProvider
+from ragit.providers.function_adapter import FunctionProvider
 
 
 @dataclass
@@ -145,14 +146,28 @@ class RagitExperiment:
         Documents to use as the knowledge base.
     benchmark : list[BenchmarkQuestion]
         Benchmark questions for evaluation.
-    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.
+    generate_fn : Callable, optional
+        Function for text generation.
+    provider : BaseEmbeddingProvider, optional
+        Provider for embeddings and LLM. If embed_fn is provided, this is
+        ignored for embeddings but can be used for LLM.
+
+    Raises
+    ------
+    ValueError
+        If neither embed_fn nor provider is provided.
 
     Examples
     --------
-    >>> documents = [Document(id="doc1", content="...")]
-    >>> benchmark = [BenchmarkQuestion(question="...", ground_truth="...")]
-    >>> experiment = RagitExperiment(documents, benchmark)
+    >>> # With custom functions
+    >>> experiment = RagitExperiment(docs, benchmark, embed_fn=my_embed, generate_fn=my_llm)
+    >>>
+    >>> # With explicit provider
+    >>> from ragit.providers import OllamaProvider
+    >>> experiment = RagitExperiment(docs, benchmark, provider=OllamaProvider())
+    >>>
     >>> results = experiment.run()
     >>> print(results[0].config)  # Best configuration
     """
@@ -161,14 +176,59 @@ class RagitExperiment:
         self,
         documents: list[Document],
         benchmark: list[BenchmarkQuestion],
-        provider: OllamaProvider | None = None,
+        embed_fn: Callable[[str], list[float]] | None = None,
+        generate_fn: Callable[..., str] | None = None,
+        provider: BaseEmbeddingProvider | BaseLLMProvider | None = None,
     ):
         self.documents = documents
         self.benchmark = benchmark
-        self.provider = provider or OllamaProvider()
         self.vector_store = SimpleVectorStore()
         self.results: list[EvaluationResult] = []
 
+        # Resolve provider from functions 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):
+                self._llm_provider = provider
+        elif provider is not None:
+            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"
+                "  RagitExperiment(docs, benchmark, embed_fn=my_embed, generate_fn=my_llm)\n"
+                "  RagitExperiment(docs, benchmark, provider=OllamaProvider())"
+            )
+
+        # LLM is required for evaluation
+        if self._llm_provider is None:
+            raise ValueError(
+                "RagitExperiment requires LLM for evaluation. "
+                "Provide generate_fn or a provider with LLM support."
+            )
+
+    @property
+    def provider(self) -> BaseEmbeddingProvider:
+        """Return the embedding provider (for backwards compatibility)."""
+        return self._embedding_provider
+
     def define_search_space(
         self,
         chunk_sizes: list[int] | None = None,
@@ -187,11 +247,11 @@ class RagitExperiment:
         chunk_overlaps : list[int], optional
             Chunk overlaps to test. Default: [50, 100]
         num_chunks_options : list[int], optional
-            Number of chunks to retrieve. Default: [2, 3, 5]
+            Number of chunks to retrieve. Default: [2, 3]
         embedding_models : list[str], optional
-            Embedding models to test. Default: from RAGIT_DEFAULT_EMBEDDING_MODEL env var
+            Embedding models to test. Default: ["default"]
         llm_models : list[str], optional
-            LLM models to test. Default: from RAGIT_DEFAULT_LLM_MODEL env var
+            LLM models to test. Default: ["default"]
 
         Returns
         -------
@@ -201,8 +261,8 @@ class RagitExperiment:
         chunk_sizes = chunk_sizes or [256, 512]
         chunk_overlaps = chunk_overlaps or [50, 100]
         num_chunks_options = num_chunks_options or [2, 3]
-        embedding_models = embedding_models or [config.DEFAULT_EMBEDDING_MODEL]
-        llm_models = llm_models or [config.DEFAULT_LLM_MODEL]
+        embedding_models = embedding_models or ["default"]
+        llm_models = llm_models or ["default"]
 
         configs = []
         pattern_num = 1
@@ -270,7 +330,7 @@ class RagitExperiment:
 
         # Batch embed all chunks at once (single API call)
         texts = [chunk.content for chunk in all_chunks]
-        responses = self.provider.embed_batch(texts, config.embedding_model)
+        responses = self._embedding_provider.embed_batch(texts, config.embedding_model)
 
         for chunk, response in zip(all_chunks, responses, strict=True):
             chunk.embedding = response.embedding
@@ -279,12 +339,15 @@ class RagitExperiment:
 
     def _retrieve(self, query: str, config: RAGConfig) -> list[Chunk]:
         """Retrieve relevant chunks for a query."""
-        query_response = self.provider.embed(query, config.embedding_model)
+        query_response = self._embedding_provider.embed(query, config.embedding_model)
         results = self.vector_store.search(query_response.embedding, top_k=config.num_chunks)
         return [chunk for chunk, _ in results]
 
     def _generate(self, question: str, context: str, config: RAGConfig) -> str:
         """Generate answer using RAG."""
+        if self._llm_provider is None:
+            raise ValueError("LLM provider is required for generation")
+
         system_prompt = """You are a helpful assistant. Answer questions based ONLY on the provided context.
 If the context doesn't contain enough information, say so. Be concise and accurate."""
 
@@ -295,7 +358,7 @@ Question: {question}
 
 Answer:"""
 
-        response = self.provider.generate(
+        response = self._llm_provider.generate(
             prompt=prompt,
             model=config.llm_model,
             system_prompt=system_prompt,
@@ -312,6 +375,8 @@ Answer:"""
         config: RAGConfig,
     ) -> EvaluationScores:
         """Evaluate a RAG response using LLM-as-judge."""
+        if self._llm_provider is None:
+            raise ValueError("LLM provider is required for evaluation")
 
         def extract_score(response: str) -> float:
             """Extract numeric score from LLM response."""
@@ -334,7 +399,7 @@ Generated Answer: {generated}
 
 Respond with ONLY a number 0-100."""
 
-        resp = self.provider.generate(correctness_prompt, config.llm_model)
+        resp = self._llm_provider.generate(correctness_prompt, config.llm_model)
         correctness = extract_score(resp.text)
 
         # Evaluate context relevance
@@ -345,7 +410,7 @@ Context: {context[:1000]}
 
 Respond with ONLY a number 0-100."""
 
-        resp = self.provider.generate(relevance_prompt, config.llm_model)
+        resp = self._llm_provider.generate(relevance_prompt, config.llm_model)
         relevance = extract_score(resp.text)
 
         # Evaluate faithfulness
@@ -356,7 +421,7 @@ Answer: {generated}
 
 Respond with ONLY a number 0-100."""
 
-        resp = self.provider.generate(faithfulness_prompt, config.llm_model)
+        resp = self._llm_provider.generate(faithfulness_prompt, config.llm_model)
         faithfulness = extract_score(resp.text)
 
         return EvaluationScores(

ragit/providers/__init__.py

@@ -6,15 +6,42 @@
 Ragit Providers - LLM and Embedding providers for RAG optimization.
 
 Supported providers:
-- Ollama (local)
-- Future: Gemini, Claude, OpenAI
+- OllamaProvider: Connect to local or remote Ollama servers
+- FunctionProvider: Wrap custom embedding/LLM functions
+- SentenceTransformersProvider: Offline embedding (requires ragit[transformers])
+
+Base classes for implementing custom providers:
+- BaseLLMProvider: Abstract base for LLM providers
+- BaseEmbeddingProvider: Abstract base for embedding providers
 """
 
-from ragit.providers.base import BaseEmbeddingProvider, BaseLLMProvider
+from ragit.providers.base import (
+    BaseEmbeddingProvider,
+    BaseLLMProvider,
+    EmbeddingResponse,
+    LLMResponse,
+)
+from ragit.providers.function_adapter import FunctionProvider
 from ragit.providers.ollama import OllamaProvider
 
 __all__ = [
+    # Base classes
     "BaseLLMProvider",
     "BaseEmbeddingProvider",
+    "LLMResponse",
+    "EmbeddingResponse",
+    # Built-in providers
     "OllamaProvider",
+    "FunctionProvider",
 ]
+
+# Conditionally export SentenceTransformersProvider if available
+try:
+    from ragit.providers.sentence_transformers import (
+        SentenceTransformersProvider as SentenceTransformersProvider,
+    )
+
+    __all__ += ["SentenceTransformersProvider"]
+except ImportError:
+    # sentence-transformers not installed, SentenceTransformersProvider not available
+    pass