haiku.rag 0.4.0__tar.gz → 0.4.2__tar.gz

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiku.rag
-Version: 0.4.0
+Version: 0.4.2
 Summary: Retrieval Augmented Generation (RAG) with SQLite
 Author-email: Yiorgis Gozadinos <ggozadinos@gmail.com>
 License: MIT

haiku_rag-0.4.2/docs/benchmarks.md

@@ -0,0 +1,33 @@
+# Benchmarks
+
+We use the [repliqa](https://huggingface.co/datasets/ServiceNow/repliqa) dataset for the evaluation of `haiku.rag`.
+
+You can perform your own evaluations using as example the script found at
+`tests/generate_benchmark_db.py`.
+
+## Recall
+
+In order to calculate recall, we load the `News Stories` from `repliqa_3` which is 1035 documents and index them in a sqlite db. Subsequently, we run a search over the `question` field for each row of the dataset and check whether we match the document that answers the question.
+
+
+The recall obtained is ~0.73 for matching in the top result, raising to ~0.75 for the top 3 results.
+
+| Embedding Model                       | Document in top 1 | Document in top 3 | Reranker               |
+|---------------------------------------|-------------------|-------------------|------------------------|
+| Ollama / `mxbai-embed-large`          | 0.77              | 0.89              | None                   |
+| Ollama / `mxbai-embed-large`          | 0.81              | 0.91              | `mxbai-rerank-base-v2` |
+| Ollama / `nomic-embed-text`           | 0.74              | 0.88              | None                   |
+| OpenAI / `text-embeddings-3-small`    | 0.75              | 0.88              | None                   |
+| OpenAI / `text-embeddings-3-small`    | 0.75              | 0.88              | None                   |
+| OpenAI / `text-embeddings-3-small`    | 0.83              | 0.90              | Cohere / `rerank-v3.5` |
+
+## Question/Answer evaluation
+
+Again using the same dataset, we use a QA agent to answer the question. In addition we use an LLM judge (using the Ollama `qwen3`) to evaluate whether the answer is correct or not. The obtained accuracy is as follows:
+
+| Embedding Model                    | QA Model                          | Accuracy  | Reranker               |
+|------------------------------------|-----------------------------------|-----------|------------------------|
+| Ollama / `mxbai-embed-large`       | Ollama / `qwen3`                  | 0.64      | None                   |
+| Ollama / `mxbai-embed-large`       | Ollama / `qwen3`                  | 0.72      | `mxbai-rerank-base-v2` |
+| Ollama / `mxbai-embed-large`       | Anthropic / `Claude Sonnet 3.7`   | 0.79      | None                   |
+| OpenAI / `text-embeddings-3-small` | OpenAI / `gpt-4-turbo`            | 0.62      | None                   |

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/docs/configuration.md

@@ -33,7 +33,7 @@ EMBEDDINGS_VECTOR_DIM=1024
 If you want to use VoyageAI embeddings you will need to install `haiku.rag` with the VoyageAI extras,
 
 ```bash
-uv pip install haiku.rag --extra voyageai
+uv pip install haiku.rag[voyageai]
 ```
 
 ```bash
@@ -47,7 +47,7 @@ VOYAGE_API_KEY="your-api-key"
 If you want to use OpenAI embeddings you will need to install `haiku.rag` with the VoyageAI extras,
 
 ```bash
-uv pip install haiku.rag --extra openai
+uv pip install haiku.rag[openai]
 ```
 
 and set environment variables.
@@ -76,7 +76,7 @@ OLLAMA_BASE_URL="http://localhost:11434"
 For OpenAI QA, you need to install haiku.rag with OpenAI extras:
 
 ```bash
-uv pip install haiku.rag --extra openai
+uv pip install haiku.rag[openai]
 ```
 
 Then configure:
@@ -92,7 +92,7 @@ OPENAI_API_KEY="your-api-key"
 For Anthropic QA, you need to install haiku.rag with Anthropic extras:
 
 ```bash
-uv pip install haiku.rag --extra anthropic
+uv pip install haiku.rag[anthropic]
 ```
 
 Then configure:
@@ -125,7 +125,7 @@ RERANK_MODEL="mixedbread-ai/mxbai-rerank-base-v2"
 For Cohere reranking, install with Cohere extras:
 
 ```bash
-uv pip install haiku.rag --extra cohere
+uv pip install haiku.rag[cohere]
 ```
 
 Then configure:

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/docs/installation.md

@@ -15,19 +15,19 @@ For other embedding providers, install with extras:
 ### VoyageAI
 
 ```bash
-uv pip install haiku.rag --extra voyageai
+uv pip install haiku.rag[voyageai]
 ```
 
 ### OpenAI
 
 ```bash
-uv pip install haiku.rag --extra openai
+uv pip install haiku.rag[openai]
 ```
 
 ### Anthropic
 
 ```bash
-uv pip install haiku.rag --extra anthropic
+uv pip install haiku.rag[anthropic]
 ```
 
 ## Requirements

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/docs/python.md

@@ -27,6 +27,31 @@ doc = await client.create_document(
 )
 ```
 
+With custom externally generated chunks:
+```python
+from haiku.rag.store.models.chunk import Chunk
+
+# Create custom chunks with optional embeddings
+chunks = [
+    Chunk(
+        content="This is the first chunk",
+        metadata={"section": "intro"}
+    ),
+    Chunk(
+        content="This is the second chunk",
+        metadata={"section": "body"},
+        embedding=[0.1] * 1024  # Optional pre-computed embedding
+    ),
+]
+
+doc = await client.create_document(
+    content="Full document content",
+    uri="doc://custom",
+    metadata={"source": "manual"},
+    chunks=chunks  # Use provided chunks instead of auto-generating
+)
+```
+
 From file:
 ```python
 doc = await client.create_document_from_source("path/to/document.pdf")

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "haiku.rag"
-version = "0.4.0"
+version = "0.4.2"
 description = "Retrieval Augmented Generation (RAG) with SQLite"
 authors = [{ name = "Yiorgis Gozadinos", email = "ggozadinos@gmail.com" }]
 license = { text = "MIT" }

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/cli.py

@@ -5,7 +5,8 @@ import typer
 from rich.console import Console
 
 from haiku.rag.app import HaikuRAGApp
-from haiku.rag.utils import get_default_data_dir, is_up_to_date
+from haiku.rag.config import Config
+from haiku.rag.utils import is_up_to_date
 
 cli = typer.Typer(
     context_settings={"help_option_names": ["-h", "--help"]}, no_args_is_help=True
@@ -35,7 +36,7 @@ def main():
 @cli.command("list", help="List all stored documents")
 def list_documents(
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -50,7 +51,7 @@ def add_document_text(
         help="The text content of the document to add",
     ),
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -65,7 +66,7 @@ def add_document_src(
         help="The file path or URL of the document to add",
     ),
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -80,7 +81,7 @@ def get_document(
         help="The ID of the document to get",
     ),
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -95,7 +96,7 @@ def delete_document(
         help="The ID of the document to delete",
     ),
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -121,7 +122,7 @@ def search(
         help="Reciprocal Rank Fusion k parameter",
     ),
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -136,7 +137,7 @@ def ask(
         help="The question to ask",
     ),
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -157,7 +158,7 @@ def settings():
 )
 def rebuild(
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),
@@ -171,7 +172,7 @@ def rebuild(
 )
 def serve(
     db: Path = typer.Option(
-        get_default_data_dir() / "haiku.rag.sqlite",
+        Config.DEFAULT_DATA_DIR / "haiku.rag.sqlite",
         "--db",
         help="Path to the SQLite database file",
     ),

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/client.py

@@ -50,7 +50,11 @@ class HaikuRAG:
         return False
 
     async def create_document(
-        self, content: str, uri: str | None = None, metadata: dict | None = None
+        self,
+        content: str,
+        uri: str | None = None,
+        metadata: dict | None = None,
+        chunks: list[Chunk] | None = None,
     ) -> Document:
         """Create a new document with optional URI and metadata.
 
@@ -58,6 +62,7 @@ class HaikuRAG:
             content: The text content of the document.
             uri: Optional URI identifier for the document.
             metadata: Optional metadata dictionary.
+            chunks: Optional list of pre-created chunks to use instead of generating new ones.
 
         Returns:
             The created Document instance.
@@ -67,7 +72,7 @@ class HaikuRAG:
             uri=uri,
             metadata=metadata or {},
         )
-        return await self.document_repository.create(document)
+        return await self.document_repository.create(document, chunks)
 
     async def create_document_from_source(
         self, source: str | Path, metadata: dict = {}
@@ -278,7 +283,7 @@ class HaikuRAG:
         return await self.document_repository.list_all(limit=limit, offset=offset)
 
     async def search(
-        self, query: str, limit: int = 3, k: int = 60, rerank=Config.RERANK
+        self, query: str, limit: int = 5, k: int = 60, rerank=Config.RERANK
     ) -> list[tuple[Chunk, float]]:
         """Search for relevant chunks using hybrid search (vector similarity + full-text search) with reranking.
 
@@ -298,7 +303,6 @@ class HaikuRAG:
         search_results = await self.chunk_repository.search_chunks_hybrid(
             query, limit * 3, k
         )
-
         # Apply reranking
         reranker = get_reranker()
         chunks = [chunk for chunk, _ in search_results]

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/embeddings/__init__.py

@@ -18,7 +18,7 @@ def get_embedder() -> EmbedderBase:
             raise ImportError(
                 "VoyageAI embedder requires the 'voyageai' package. "
                 "Please install haiku.rag with the 'voyageai' extra:"
-                "uv pip install haiku.rag --extra voyageai"
+                "uv pip install haiku.rag[voyageai]"
             )
         return VoyageAIEmbedder(Config.EMBEDDINGS_MODEL, Config.EMBEDDINGS_VECTOR_DIM)
 
@@ -29,7 +29,7 @@ def get_embedder() -> EmbedderBase:
             raise ImportError(
                 "OpenAI embedder requires the 'openai' package. "
                 "Please install haiku.rag with the 'openai' extra:"
-                "uv pip install haiku.rag --extra openai"
+                "uv pip install haiku.rag[openai]"
             )
         return OpenAIEmbedder(Config.EMBEDDINGS_MODEL, Config.EMBEDDINGS_VECTOR_DIM)
 

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/qa/__init__.py

@@ -18,7 +18,7 @@ def get_qa_agent(client: HaikuRAG, model: str = "") -> QuestionAnswerAgentBase:
             raise ImportError(
                 "OpenAI QA agent requires the 'openai' package. "
                 "Please install haiku.rag with the 'openai' extra:"
-                "uv pip install haiku.rag --extra openai"
+                "uv pip install haiku.rag[openai]"
             )
         return QuestionAnswerOpenAIAgent(client, model or Config.QA_MODEL)
 
@@ -29,7 +29,7 @@ def get_qa_agent(client: HaikuRAG, model: str = "") -> QuestionAnswerAgentBase:
             raise ImportError(
                 "Anthropic QA agent requires the 'anthropic' package. "
                 "Please install haiku.rag with the 'anthropic' extra:"
-                "uv pip install haiku.rag --extra anthropic"
+                "uv pip install haiku.rag[anthropic]"
             )
         return QuestionAnswerAnthropicAgent(client, model or Config.QA_MODEL)
 

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/qa/ollama.py

@@ -4,7 +4,7 @@ from haiku.rag.client import HaikuRAG
 from haiku.rag.config import Config
 from haiku.rag.qa.base import QuestionAnswerAgentBase
 
-OLLAMA_OPTIONS = {"temperature": 0.0, "seed": 42, "num_ctx": 64000}
+OLLAMA_OPTIONS = {"temperature": 0.0, "seed": 42, "num_ctx": 16384}
 
 
 class QuestionAnswerOllamaAgent(QuestionAnswerAgentBase):

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/qa/prompts.py

@@ -15,7 +15,7 @@ Guidelines:
 - Indicate when information is incomplete or when you need to search for additional context
 - If the retrieved documents don't contain sufficient information, clearly state: "I cannot find enough information in the knowledge base to answer this question."
 - For complex questions, consider breaking them down and performing multiple searches
-- Stick to the answer, do not ellaborate or provde context unless asked for it.
+- Stick to the answer, do not ellaborate or provide context unless explicitly asked for it.
 
 Be concise, and always maintain accuracy over completeness. Prefer short, direct answers that are well-supported by the documents.
 """

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/reranking/__init__.py

@@ -29,7 +29,7 @@ def get_reranker() -> RerankerBase:
             raise ImportError(
                 "Cohere reranker requires the 'cohere' package. "
                 "Please install haiku.rag with the 'cohere' extra:"
-                "uv pip install haiku.rag --extra cohere"
+                "uv pip install haiku.rag[cohere]"
             )
         _reranker = CohereReranker()
         return _reranker

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/store/models/chunk.py

@@ -7,8 +7,9 @@ class Chunk(BaseModel):
     """
 
     id: int | None = None
-    document_id: int
+    document_id: int | None = None
     content: str
     metadata: dict = {}
     document_uri: str | None = None
     document_meta: dict = {}
+    embedding: list[float] | None = None

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/store/repositories/chunk.py

@@ -18,6 +18,8 @@ class ChunkRepository(BaseRepository[Chunk]):
         """Create a chunk in the database."""
         if self.store._connection is None:
             raise ValueError("Store connection is not available")
+        if entity.document_id is None:
+            raise ValueError("Chunk must have a document_id to be created")
 
         cursor = self.store._connection.cursor()
         cursor.execute(
@@ -34,9 +36,15 @@ class ChunkRepository(BaseRepository[Chunk]):
 
         entity.id = cursor.lastrowid
 
-        # Generate and store embedding
-        embedding = await self.embedder.embed(entity.content)
-        serialized_embedding = self.store.serialize_embedding(embedding)
+        # Generate and store embedding - use existing one if provided
+        if entity.embedding is not None:
+            # Use the provided embedding
+            serialized_embedding = self.store.serialize_embedding(entity.embedding)
+        else:
+            # Generate embedding from content
+            embedding = await self.embedder.embed(entity.content)
+            serialized_embedding = self.store.serialize_embedding(embedding)
+
         cursor.execute(
             """
             INSERT INTO chunk_embeddings (chunk_id, embedding)

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/src/haiku/rag/store/repositories/document.py

@@ -1,8 +1,12 @@
 import json
+from typing import TYPE_CHECKING
 
 from haiku.rag.store.models.document import Document
 from haiku.rag.store.repositories.base import BaseRepository
 
+if TYPE_CHECKING:
+    from haiku.rag.store.models.chunk import Chunk
+
 
 class DocumentRepository(BaseRepository[Document]):
     """Repository for Document database operations."""
@@ -16,7 +20,9 @@ class DocumentRepository(BaseRepository[Document]):
             chunk_repository = ChunkRepository(store)
         self.chunk_repository = chunk_repository
 
-    async def create(self, entity: Document) -> Document:
+    async def create(
+        self, entity: Document, chunks: list["Chunk"] | None = None
+    ) -> Document:
         """Create a document with its chunks and embeddings."""
         if self.store._connection is None:
             raise ValueError("Store connection is not available")
@@ -46,10 +52,20 @@ class DocumentRepository(BaseRepository[Document]):
             assert document_id is not None, "Failed to create document in database"
             entity.id = document_id
 
-            # Create chunks and embeddings using ChunkRepository
-            await self.chunk_repository.create_chunks_for_document(
-                document_id, entity.content, commit=False
-            )
+            # Create chunks - either use provided chunks or generate from content
+            if chunks is not None:
+                # Use provided chunks, but update their document_id and set order from list position
+                for order, chunk in enumerate(chunks):
+                    chunk.document_id = document_id
+                    # Ensure order is set from list position
+                    chunk.metadata = chunk.metadata.copy() if chunk.metadata else {}
+                    chunk.metadata["order"] = order
+                    await self.chunk_repository.create(chunk, commit=False)
+            else:
+                # Create chunks and embeddings using ChunkRepository
+                await self.chunk_repository.create_chunks_for_document(
+                    document_id, entity.content, commit=False
+                )
 
             cursor.execute("COMMIT")
             return entity

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/tests/llm_judge.py

@@ -13,7 +13,7 @@ class LLMJudgeResponseSchema(BaseModel):
 class LLMJudge:
     """LLM-as-judge for evaluating answer equivalence using Ollama."""
 
-    def __init__(self, model: str = "qwen3"):
+    def __init__(self, model: str = Config.QA_MODEL):
         self.model = model
         self.client = AsyncClient(host=Config.OLLAMA_BASE_URL)
 

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/tests/test_client.py

@@ -7,6 +7,7 @@ import pytest
 from datasets import Dataset
 
 from haiku.rag.client import HaikuRAG
+from haiku.rag.store.models.chunk import Chunk
 
 
 @pytest.mark.asyncio
@@ -449,3 +450,42 @@ async def test_client_async_context_manager():
     # Context manager should have automatically closed the connection
     # We can't easily test that the connection is closed without accessing internals,
     # but the test passing means the context manager methods work correctly
+
+
+@pytest.mark.asyncio
+async def test_client_create_document_with_custom_chunks():
+    """Test creating a document with pre-created chunks."""
+    async with HaikuRAG(":memory:") as client:
+        # Create some custom chunks with and without embeddings
+        chunks = [
+            Chunk(content="This is the first chunk", metadata={"custom": "metadata1"}),
+            Chunk(
+                content="This is the second chunk",
+                metadata={"custom": "metadata2"},
+                embedding=[0.1] * 1024,
+            ),  # With embedding
+            Chunk(content="This is the third chunk", metadata={"custom": "metadata3"}),
+        ]
+
+        # Create document with custom chunks
+        document = await client.create_document(
+            content="Full document content", chunks=chunks
+        )
+
+        assert document.id is not None
+        assert document.content == "Full document content"
+
+        # Verify the chunks were created correctly
+        doc_chunks = await client.chunk_repository.get_by_document_id(document.id)
+        assert len(doc_chunks) == 3
+
+        # Check chunks have correct content, document_id, and order from list position
+        for i, chunk in enumerate(doc_chunks):
+            assert chunk.document_id == document.id
+            assert chunk.content == chunks[i].content
+            assert (
+                chunk.metadata["order"] == i
+            )  # Order should be set from list position
+            assert (
+                chunk.metadata["custom"] == f"metadata{i + 1}"
+            )  # Original metadata preserved

{haiku_rag-0.4.0 → haiku_rag-0.4.2}/uv.lock

@@ -901,7 +901,7 @@ wheels = [
 
 [[package]]
 name = "haiku-rag"
-version = "0.4.0"
+version = "0.4.2"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },

haiku_rag-0.4.0/docs/benchmarks.md

@@ -1,30 +0,0 @@
-# Benchmarks
-
-We use the [repliqa](https://huggingface.co/datasets/ServiceNow/repliqa) dataset for the evaluation of `haiku.rag`.
-
-You can perform your own evaluations using as example the script found at
-`tests/generate_benchmark_db.py`.
-
-## Recall
-
-In order to calculate recall, we load the `News Stories` from `repliqa_3` which is 1035 documents and index them in a sqlite db. Subsequently, we run a search over the `question` field for each row of the dataset and check whether we match the document that answers the question.
-
-
-The recall obtained is ~0.73 for matching in the top result, raising to ~0.75 for the top 3 results.
-
-| Model                                 | Document in top 1 | Document in top 3 | Reranker             |
-|---------------------------------------|-------------------|-------------------|----------------------|
-| Ollama / `mxbai-embed-large`          | 0.77              | 0.89              | None                 |
-| Ollama / `mxbai-embed-large`          | 0.81              | 0.91              | mxbai-rerank-base-v2 |
-| Ollama / `nomic-embed-text`           | 0.74              | 0.88              | None                 |
-| OpenAI / `text-embeddings-3-small`    | 0.75              | 0.88              | None                 |
-
-## Question/Answer evaluation
-
-Again using the same dataset, we use a QA agent to answer the question. In addition we use an LLM judge (using the Ollama `qwen3`) to evaluate whether the answer is correct or not. The obtained accuracy is as follows:
-
-| Embedding Model              | QA Model                          | Accuracy  | Reranker             |
-|------------------------------|-----------------------------------|-----------|----------------------|
-| Ollama / `mxbai-embed-large` | Ollama / `qwen3`                  | 0.64      | None                 |
-| Ollama / `mxbai-embed-large` | Ollama / `qwen3`                  | 0.72      | mxbai-rerank-base-v2 |
-| Ollama / `mxbai-embed-large` | Anthropic / `Claude Sonnet 3.7`   | 0.79      | None                 |