haiku.rag 0.1.0__tar.gz

haiku_rag-0.1.0/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pytest:*)",
+      "Bash(uv add:*)",
+      "Bash(source:*)",
+      "Bash(pyright:*)",
+      "Bash(ruff check:*)",
+      "Bash(find:*)",
+      "Bash(. .venv/bin/activate)",
+      "Bash(mv:*)"
+    ],
+    "deny": []
+  }
+}

haiku_rag-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: ggozad

haiku_rag-0.1.0/.github/workflows/build-docs.yml

@@ -0,0 +1,28 @@
+name: build-docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

haiku_rag-0.1.0/.github/workflows/build-publish.yml

@@ -0,0 +1,18 @@
+name: Build & publish to pypi
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        run: curl -LsSf https://astral.sh/uv/0.3.0/install.sh | sh
+      - name: Set up Python 3.10
+        run: uv python install 3.10
+      - name: Build package
+        run: uvx --from build pyproject-build --installer uv
+      - name: Publish package
+        run: uvx twine upload -u __token__ -p ${{ secrets.PYPI_API_TOKEN }} dist/* --non-interactive

haiku_rag-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# tests
+.coverage*
+tests/data/
+.pytest_cache/
+.ruff_cache/
+
+# environment variables
+.env

haiku_rag-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.4
+    hooks:
+      # Run the linter.
+      - id: ruff
+      # Run the formatter.
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.399
+    hooks:
+      - id: pyright

haiku_rag-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

haiku_rag-0.1.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# Claude AI Assistant Configuration
+
+This file contains project-specific information and preferences for Claude AI assistant interactions.
+
+## Project Overview
+
+This is a SQLite-based RAG (Retrieval-Augmented Generation) system built with Haiku.
+
+## Development Commands
+
+- Install dependencies: `uv sync`
+- Run tests: `pytest`
+- Run specific test: `pytest path/to/test_file.py`
+- Run with coverage: `pytest --cov`
+- Type checking: `pyright`
+- Run MCP server: `python -m haiku.rag.mcp`
+
+## Project Structure
+
+- `src/` - Source code
+- `tests/` - Test files
+- `README.md` - Documentation
+
+## Notes
+
+- This is a Python project using uv for dependency management
+- Use pytest for testing
+- Prefer editing existing files over creating new ones
+- Follow existing code patterns and conventions
+- Remember to activate the .venv when you start working
+- Never use relative imports
+- Always run ruff as well as pyright after you are done
+- Do not be verbose with comments!
+- When you change something check if the README needs an update too.
+  

haiku_rag-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Yiorgis Gozadinos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

haiku_rag-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: haiku.rag
+Version: 0.1.0
+Summary: Retrieval Augmented Generation (RAG) with SQLite
+Author-email: Yiorgis Gozadinos <ggozadinos@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.8.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: markitdown[audio-transcription,docx,pdf,pptx,xlsx]>=0.1.2
+Requires-Dist: ollama>=0.5.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: typer>=0.16.0
+Requires-Dist: watchfiles>=1.1.0
+Provides-Extra: voyageai
+Requires-Dist: voyageai>=0.3.2; extra == 'voyageai'
+Description-Content-Type: text/markdown
+
+# Haiku SQLite RAG
+
+A SQLite-based Retrieval-Augmented Generation (RAG) system built for efficient document storage, chunking, and hybrid search capabilities.
+
+## Features
+- **Local SQLite**: No need to run additional servers
+- **Support for various embedding providers**: You can use Ollama, VoyageAI or add your own
+- **Hybrid Search**: Vector search using `sqlite-vec` combined with full-text search `FTS5`, using Reciprocal Rank Fusion
+- **Multi-format Support**: Parse 40+ file formats including PDF, DOCX, HTML, Markdown, audio and more. Or add a url!
+
+## Installation
+
+```bash
+uv pip install haiku.rag
+```
+
+By default Ollama (with the `mxbai-embed-large` model) is used for the embeddings.
+For other providers use:
+
+- **VoyageAI**: `uv pip install haiku.rag --extra voyageai`
+
+## Configuration
+
+If you want to use an alternative embeddings provider (Ollama being the default) you will need to set the provider details through environment variables:
+
+By default:
+
+```bash
+EMBEDDING_PROVIDER="ollama"
+EMBEDDING_MODEL="mxbai-embed-large" # or any other model
+EMBEDDING_VECTOR_DIM=1024
+```
+
+For VoyageAI:
+```bash
+EMBEDDING_PROVIDER="voyageai"
+EMBEDDING_MODEL="voyage-3.5" # or any other model
+EMBEDDING_VECTOR_DIM=1024
+```
+
+## Command Line Interface
+
+`haiku.rag` includes a CLI application for managing documents and performing searches from the command line:
+
+### Available Commands
+
+```bash
+# List all documents
+haiku-rag list
+
+# Add document from text
+haiku-rag add "Your document content here"
+
+# Add document from file or URL
+haiku-rag add-src /path/to/document.pdf
+haiku-rag add-src https://example.com/article.html
+
+# Get and display a specific document
+haiku-rag get 1
+
+# Delete a document by ID
+haiku-rag delete 1
+
+# Search documents
+haiku-rag search "machine learning"
+
+# Search with custom options
+haiku-rag search "python programming" --limit 10 --k 100
+
+# Start MCP server (default HTTP transport)
+haiku-rag serve # --stdio for stdio transport or --sse for SSE transport
+```
+
+All commands support the `--db` option to specify a custom database path. Run
+```bash
+haiku-rag command -h
+```
+to see additional parameters for a command.
+
+## MCP Server
+
+`haiku.rag` includes a Model Context Protocol (MCP) server that exposes RAG functionality as tools for AI assistants like Claude Desktop. The MCP server provides the following tools:
+
+- `add_document_from_file` - Add documents from local file paths
+- `add_document_from_url` - Add documents from URLs
+- `add_document_from_text` - Add documents from raw text content
+- `search_documents` - Search documents using hybrid search
+- `get_document` - Retrieve specific documents by ID
+- `list_documents` - List all documents with pagination
+- `delete_document` - Delete documents by ID
+
+You can start the server (using Streamble HTTP, stdio or SSE transports) with:
+
+```bash
+# Start with default HTTP transport
+haiku-rag serve # --stdio for stdio transport or --sse for SSE transport
+```
+
+## Using `haiku.rag` from python
+
+### Managing documents
+
+```python
+from pathlib import Path
+from haiku.rag.client import HaikuRAG
+
+# Use as async context manager (recommended)
+async with HaikuRAG("path/to/database.db") as client:
+    # Create document from text
+    doc = await client.create_document(
+        content="Your document content here",
+        uri="doc://example",
+        metadata={"source": "manual", "topic": "example"}
+    )
+
+    # Create document from file (auto-parses content)
+    doc = await client.create_document_from_source("path/to/document.pdf")
+
+    # Create document from URL
+    doc = await client.create_document_from_source("https://example.com/article.html")
+
+    # Retrieve documents
+    doc = await client.get_document_by_id(1)
+    doc = await client.get_document_by_uri("file:///path/to/document.pdf")
+
+    # List all documents with pagination
+    docs = await client.list_documents(limit=10, offset=0)
+
+    # Update document content
+    doc.content = "Updated content"
+    await client.update_document(doc)
+
+    # Delete document
+    await client.delete_document(doc.id)
+
+    # Search documents using hybrid search (vector + full-text)
+    results = await client.search("machine learning algorithms", limit=5)
+    for chunk, score in results:
+        print(f"Score: {score:.3f}")
+        print(f"Content: {chunk.content}")
+        print(f"Document ID: {chunk.document_id}")
+        print("---")
+```
+
+## Searching documents
+
+```python
+async with HaikuRAG("database.db") as client:
+
+    results = await client.search(
+        query="machine learning",
+        limit=5,  # Maximum results to return, defaults to 5
+        k=60      # RRF parameter for reciprocal rank fusion, defaults to 60
+    )
+
+    # Process results
+    for chunk, relevance_score in results:
+        print(f"Relevance: {relevance_score:.3f}")
+        print(f"Content: {chunk.content}")
+        print(f"From document: {chunk.document_id}")
+```

haiku_rag-0.1.0/README.md

@@ -0,0 +1,161 @@
+# Haiku SQLite RAG
+
+A SQLite-based Retrieval-Augmented Generation (RAG) system built for efficient document storage, chunking, and hybrid search capabilities.
+
+## Features
+- **Local SQLite**: No need to run additional servers
+- **Support for various embedding providers**: You can use Ollama, VoyageAI or add your own
+- **Hybrid Search**: Vector search using `sqlite-vec` combined with full-text search `FTS5`, using Reciprocal Rank Fusion
+- **Multi-format Support**: Parse 40+ file formats including PDF, DOCX, HTML, Markdown, audio and more. Or add a url!
+
+## Installation
+
+```bash
+uv pip install haiku.rag
+```
+
+By default Ollama (with the `mxbai-embed-large` model) is used for the embeddings.
+For other providers use:
+
+- **VoyageAI**: `uv pip install haiku.rag --extra voyageai`
+
+## Configuration
+
+If you want to use an alternative embeddings provider (Ollama being the default) you will need to set the provider details through environment variables:
+
+By default:
+
+```bash
+EMBEDDING_PROVIDER="ollama"
+EMBEDDING_MODEL="mxbai-embed-large" # or any other model
+EMBEDDING_VECTOR_DIM=1024
+```
+
+For VoyageAI:
+```bash
+EMBEDDING_PROVIDER="voyageai"
+EMBEDDING_MODEL="voyage-3.5" # or any other model
+EMBEDDING_VECTOR_DIM=1024
+```
+
+## Command Line Interface
+
+`haiku.rag` includes a CLI application for managing documents and performing searches from the command line:
+
+### Available Commands
+
+```bash
+# List all documents
+haiku-rag list
+
+# Add document from text
+haiku-rag add "Your document content here"
+
+# Add document from file or URL
+haiku-rag add-src /path/to/document.pdf
+haiku-rag add-src https://example.com/article.html
+
+# Get and display a specific document
+haiku-rag get 1
+
+# Delete a document by ID
+haiku-rag delete 1
+
+# Search documents
+haiku-rag search "machine learning"
+
+# Search with custom options
+haiku-rag search "python programming" --limit 10 --k 100
+
+# Start MCP server (default HTTP transport)
+haiku-rag serve # --stdio for stdio transport or --sse for SSE transport
+```
+
+All commands support the `--db` option to specify a custom database path. Run
+```bash
+haiku-rag command -h
+```
+to see additional parameters for a command.
+
+## MCP Server
+
+`haiku.rag` includes a Model Context Protocol (MCP) server that exposes RAG functionality as tools for AI assistants like Claude Desktop. The MCP server provides the following tools:
+
+- `add_document_from_file` - Add documents from local file paths
+- `add_document_from_url` - Add documents from URLs
+- `add_document_from_text` - Add documents from raw text content
+- `search_documents` - Search documents using hybrid search
+- `get_document` - Retrieve specific documents by ID
+- `list_documents` - List all documents with pagination
+- `delete_document` - Delete documents by ID
+
+You can start the server (using Streamble HTTP, stdio or SSE transports) with:
+
+```bash
+# Start with default HTTP transport
+haiku-rag serve # --stdio for stdio transport or --sse for SSE transport
+```
+
+## Using `haiku.rag` from python
+
+### Managing documents
+
+```python
+from pathlib import Path
+from haiku.rag.client import HaikuRAG
+
+# Use as async context manager (recommended)
+async with HaikuRAG("path/to/database.db") as client:
+    # Create document from text
+    doc = await client.create_document(
+        content="Your document content here",
+        uri="doc://example",
+        metadata={"source": "manual", "topic": "example"}
+    )
+
+    # Create document from file (auto-parses content)
+    doc = await client.create_document_from_source("path/to/document.pdf")
+
+    # Create document from URL
+    doc = await client.create_document_from_source("https://example.com/article.html")
+
+    # Retrieve documents
+    doc = await client.get_document_by_id(1)
+    doc = await client.get_document_by_uri("file:///path/to/document.pdf")
+
+    # List all documents with pagination
+    docs = await client.list_documents(limit=10, offset=0)
+
+    # Update document content
+    doc.content = "Updated content"
+    await client.update_document(doc)
+
+    # Delete document
+    await client.delete_document(doc.id)
+
+    # Search documents using hybrid search (vector + full-text)
+    results = await client.search("machine learning algorithms", limit=5)
+    for chunk, score in results:
+        print(f"Score: {score:.3f}")
+        print(f"Content: {chunk.content}")
+        print(f"Document ID: {chunk.document_id}")
+        print("---")
+```
+
+## Searching documents
+
+```python
+async with HaikuRAG("database.db") as client:
+
+    results = await client.search(
+        query="machine learning",
+        limit=5,  # Maximum results to return, defaults to 5
+        k=60      # RRF parameter for reciprocal rank fusion, defaults to 60
+    )
+
+    # Process results
+    for chunk, relevance_score in results:
+        print(f"Relevance: {relevance_score:.3f}")
+        print(f"Content: {chunk.content}")
+        print(f"From document: {chunk.document_id}")
+```

haiku_rag-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "haiku.rag"
+version = "0.1.0"
+description = "Retrieval Augmented Generation (RAG) with SQLite"
+authors = [{ name = "Yiorgis Gozadinos", email = "ggozadinos@gmail.com" }]
+license = { text = "MIT" }
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows :: Windows 10",
+    "Operating System :: Microsoft :: Windows :: Windows 11",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "fastmcp>=2.8.1",
+    "httpx>=0.28.1",
+    "markitdown[audio-transcription,docx,pdf,pptx,xlsx]>=0.1.2",
+    "ollama>=0.5.1",
+    "pydantic>=2.11.7",
+    "python-dotenv>=1.1.0",
+    "rich>=14.0.0",
+    "sqlite-vec>=0.1.6",
+    "tiktoken>=0.9.0",
+    "typer>=0.16.0",
+    "watchfiles>=1.1.0",
+]
+
+[project.optional-dependencies]
+voyageai = ["voyageai>=0.3.2"]
+
+[project.scripts]
+haiku-rag = "haiku.rag.cli:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/haiku"]
+
+[dependency-groups]
+dev = [
+    "datasets>=3.6.0",
+    "pre-commit>=4.2.0",
+    "pyright>=1.1.402",
+    "pytest>=8.4.0",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=6.2.1",
+    "ruff>=0.11.13",
+]
+
+[tool.ruff]
+line-length = 88
+# Enable Flake's "E" and "F" codes by default and "I" for sorting imports.
+# Exclude a variety of commonly ignored directories.
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "UP",
+    "I",
+] # Enable Flake's "E" and "F" codes by default and "I" for sorting imports
+ignore = ["E501"]
+per-file-ignores = { "__init__.py" = ["F401", "F403"] }
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "session"
+asyncio_mode = "auto"
+
+# pyproject.toml
+filterwarnings = ["error", "ignore::UserWarning", "ignore::DeprecationWarning"]