swiftrag 0.1.0__tar.gz

swiftrag-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.pkl
+
+# Envs
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

swiftrag-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 swiftrag contributors
+
+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.

swiftrag-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: swiftrag
+Version: 0.1.0
+Summary: Instant, optimized Retrieval-Augmented Generation. Pass your text + a model, get a RAG-powered LLM in one line.
+Project-URL: Homepage, https://github.com/behradmoeini/swiftrag
+Project-URL: Repository, https://github.com/behradmoeini/swiftrag
+Project-URL: Issues, https://github.com/behradmoeini/swiftrag/issues
+Author: Behrad Moeini
+License: MIT
+License-File: LICENSE
+Keywords: ai,embeddings,llm,nlp,openai,rag,retrieval-augmented-generation,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == 'all'
+Requires-Dist: faiss-cpu>=1.7; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2; extra == 'all'
+Requires-Dist: tiktoken>=0.5; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7; extra == 'faiss'
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=2.2; extra == 'local'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: tokenize
+Requires-Dist: tiktoken>=0.5; extra == 'tokenize'
+Description-Content-Type: text/markdown
+
+# swiftrag
+
+[![CI](https://github.com/behradmoeini/swiftrag/actions/workflows/ci.yml/badge.svg)](https://github.com/behradmoeini/swiftrag/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/swiftrag.svg)](https://pypi.org/project/swiftrag/)
+[![Python versions](https://img.shields.io/pypi/pyversions/swiftrag.svg)](https://pypi.org/project/swiftrag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Instant, optimized Retrieval-Augmented Generation.** Pass your text and a model — get a RAG-powered LLM in one line.
+
+```python
+from swiftrag import RAG
+
+rag = RAG(
+    documents="The Eiffel Tower is 330 metres tall and located in Paris.",
+    embedding_model="openai:text-embedding-3-small",
+    llm_model="openai:gpt-4o-mini",
+)
+
+print(rag.query("How tall is the Eiffel Tower?"))
+# -> "The Eiffel Tower is 330 metres tall."
+```
+
+That's the whole API. You bring documents (a string, a list of strings, or dicts) and a model spec; swiftrag handles chunking, embedding, vector indexing, retrieval, and prompt construction.
+
+---
+
+## Why swiftrag
+
+- **One line to a working RAG.** No glue code, no framework to learn.
+- **Optimized core.** L2-normalized embeddings + a single BLAS matmul for search, `argpartition` top-k (no full sort), batched & concurrent embedding requests, token-aware chunking, and an optional FAISS backend for large corpora.
+- **Tiny footprint.** The core depends only on `numpy`. It installs in seconds.
+- **Runs offline out of the box.** With no API key it uses a built-in hashing embedder and an extractive answerer, so the full pipeline works in tests/CI/demos.
+- **Provider-agnostic.** OpenAI, Anthropic, local sentence-transformers, or any custom callable/object you plug in.
+- **MIT licensed.**
+
+## Install
+
+```bash
+pip install swiftrag                 # core (numpy only) — works offline
+pip install "swiftrag[openai]"       # OpenAI embeddings + LLM
+pip install "swiftrag[anthropic]"    # Claude LLM
+pip install "swiftrag[local]"        # local sentence-transformers embeddings
+pip install "swiftrag[faiss]"        # FAISS backend for big corpora
+pip install "swiftrag[all]"          # everything
+```
+
+## Usage
+
+### Pick your models with a simple `"provider:model"` string
+
+```python
+# OpenAI (needs OPENAI_API_KEY)
+RAG(documents=text, embedding_model="openai:text-embedding-3-small", llm_model="openai:gpt-4o-mini")
+
+# Anthropic for generation, local embeddings (no embedding API calls)
+RAG(documents=text, embedding_model="local:all-MiniLM-L6-v2", llm_model="anthropic:claude-3-5-sonnet-latest")
+
+# Fully offline (default) — no keys required
+RAG(documents=text)
+```
+
+### Build straight from files or a folder
+
+```python
+rag = RAG.from_files("docs/", embedding_model="openai:text-embedding-3-small")
+# each file becomes a document tagged with metadata={"source": <path>}
+
+resp = rag.query("What's our deployment process?")
+print(resp.answer)
+print(resp.format_sources())   # numbered, human-readable citations
+```
+
+### Documents can be a string, list, or dicts with metadata
+
+```python
+rag = RAG(documents=[
+    "Plain string document.",
+    {"text": "Document with metadata.", "metadata": {"source": "handbook", "page": 12}},
+])
+```
+
+### Query, stream, or just retrieve
+
+```python
+resp = rag.query("What does the handbook say about refunds?")
+print(resp.answer)
+for s in resp.sources:
+    print(s.score, s.metadata, s.text[:80])
+
+# Token streaming
+for token in rag.stream("Summarize the refund policy."):
+    print(token, end="", flush=True)
+
+# Retrieval only (no LLM call)
+chunks = rag.retrieve("refunds", top_k=5)
+```
+
+### Filter by metadata and score
+
+```python
+# Only consider chunks whose metadata matches, and drop weak matches.
+resp = rag.query(
+    "What is the refund window?",
+    where={"source": "handbook"},     # exact metadata match (or pass a Chunk -> bool callable)
+    min_score=0.25,                    # cosine threshold; weaker chunks are ignored
+    top_k=3,
+)
+```
+
+Repeated queries reuse a cached query embedding (LRU, configurable via
+`query_cache_size`), so re-asking the same question skips the embedding call.
+
+### Add documents incrementally, save, and reload
+
+```python
+rag = RAG().add("first batch").add("second batch")
+rag.save("index.pkl")
+
+rag = RAG.load("index.pkl", embedding_model="openai:text-embedding-3-small",
+               llm_model="openai:gpt-4o-mini")
+```
+
+### Batch and async
+
+```python
+# Answer many questions at once — embeddings are batched, generation is parallelized.
+responses = rag.query_many(["q1?", "q2?", "q3?"], max_workers=8)
+
+# Async API (non-blocking, great for web servers):
+resp = await rag.aquery("your question")
+async for token in rag.astream("your question"):
+    print(token, end="", flush=True)
+```
+
+### Bring your own provider
+
+```python
+# Any callable fn(prompt) -> str works as an LLM:
+rag = RAG(documents=text, llm_model=lambda prompt: my_model.generate(prompt))
+
+# Any object with embed_documents(list[str]) and embed_query(str) works as an embedder.
+```
+
+## Configuration
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `documents` | `None` | str / list[str] / list[dict] / `Document`(s) to index. |
+| `embedding_model` | `"hash"` | `"provider:model"` string or a custom provider. |
+| `llm_model` | `None` (offline) | `"provider:model"` string, callable, or provider. |
+| `chunk_size` | `512` | Target chunk size in tokens. |
+| `chunk_overlap` | `64` | Token overlap between chunks. |
+| `top_k` | `4` | Chunks retrieved per query. |
+| `use_mmr` | `False` | Maximal Marginal Relevance re-ranking for diverse results. |
+| `use_faiss` | `False` | Use FAISS index (install `swiftrag[faiss]`). |
+| `min_score` | `None` | Default cosine threshold for dropping weak matches. |
+| `max_context_tokens` | `None` | Cap the tokens of retrieved context packed into the prompt. |
+| `dedup` | `True` | Skip exact-duplicate chunks on ingest. |
+| `query_cache_size` | `128` | LRU size for cached query embeddings (`0` disables). |
+| `system_prompt` | grounded default | System prompt for the LLM. |
+
+## How it works
+
+```
+documents ─▶ chunk (token-aware) ─▶ embed (batched) ─▶ normalize ─▶ vector store
+                                                                         │
+query ─▶ embed ─▶ cosine (BLAS matmul) ─▶ top-k (argpartition) ─▶ context ─▶ LLM ─▶ answer
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

swiftrag-0.1.0/README.md

@@ -0,0 +1,180 @@
+# swiftrag
+
+[![CI](https://github.com/behradmoeini/swiftrag/actions/workflows/ci.yml/badge.svg)](https://github.com/behradmoeini/swiftrag/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/swiftrag.svg)](https://pypi.org/project/swiftrag/)
+[![Python versions](https://img.shields.io/pypi/pyversions/swiftrag.svg)](https://pypi.org/project/swiftrag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Instant, optimized Retrieval-Augmented Generation.** Pass your text and a model — get a RAG-powered LLM in one line.
+
+```python
+from swiftrag import RAG
+
+rag = RAG(
+    documents="The Eiffel Tower is 330 metres tall and located in Paris.",
+    embedding_model="openai:text-embedding-3-small",
+    llm_model="openai:gpt-4o-mini",
+)
+
+print(rag.query("How tall is the Eiffel Tower?"))
+# -> "The Eiffel Tower is 330 metres tall."
+```
+
+That's the whole API. You bring documents (a string, a list of strings, or dicts) and a model spec; swiftrag handles chunking, embedding, vector indexing, retrieval, and prompt construction.
+
+---
+
+## Why swiftrag
+
+- **One line to a working RAG.** No glue code, no framework to learn.
+- **Optimized core.** L2-normalized embeddings + a single BLAS matmul for search, `argpartition` top-k (no full sort), batched & concurrent embedding requests, token-aware chunking, and an optional FAISS backend for large corpora.
+- **Tiny footprint.** The core depends only on `numpy`. It installs in seconds.
+- **Runs offline out of the box.** With no API key it uses a built-in hashing embedder and an extractive answerer, so the full pipeline works in tests/CI/demos.
+- **Provider-agnostic.** OpenAI, Anthropic, local sentence-transformers, or any custom callable/object you plug in.
+- **MIT licensed.**
+
+## Install
+
+```bash
+pip install swiftrag                 # core (numpy only) — works offline
+pip install "swiftrag[openai]"       # OpenAI embeddings + LLM
+pip install "swiftrag[anthropic]"    # Claude LLM
+pip install "swiftrag[local]"        # local sentence-transformers embeddings
+pip install "swiftrag[faiss]"        # FAISS backend for big corpora
+pip install "swiftrag[all]"          # everything
+```
+
+## Usage
+
+### Pick your models with a simple `"provider:model"` string
+
+```python
+# OpenAI (needs OPENAI_API_KEY)
+RAG(documents=text, embedding_model="openai:text-embedding-3-small", llm_model="openai:gpt-4o-mini")
+
+# Anthropic for generation, local embeddings (no embedding API calls)
+RAG(documents=text, embedding_model="local:all-MiniLM-L6-v2", llm_model="anthropic:claude-3-5-sonnet-latest")
+
+# Fully offline (default) — no keys required
+RAG(documents=text)
+```
+
+### Build straight from files or a folder
+
+```python
+rag = RAG.from_files("docs/", embedding_model="openai:text-embedding-3-small")
+# each file becomes a document tagged with metadata={"source": <path>}
+
+resp = rag.query("What's our deployment process?")
+print(resp.answer)
+print(resp.format_sources())   # numbered, human-readable citations
+```
+
+### Documents can be a string, list, or dicts with metadata
+
+```python
+rag = RAG(documents=[
+    "Plain string document.",
+    {"text": "Document with metadata.", "metadata": {"source": "handbook", "page": 12}},
+])
+```
+
+### Query, stream, or just retrieve
+
+```python
+resp = rag.query("What does the handbook say about refunds?")
+print(resp.answer)
+for s in resp.sources:
+    print(s.score, s.metadata, s.text[:80])
+
+# Token streaming
+for token in rag.stream("Summarize the refund policy."):
+    print(token, end="", flush=True)
+
+# Retrieval only (no LLM call)
+chunks = rag.retrieve("refunds", top_k=5)
+```
+
+### Filter by metadata and score
+
+```python
+# Only consider chunks whose metadata matches, and drop weak matches.
+resp = rag.query(
+    "What is the refund window?",
+    where={"source": "handbook"},     # exact metadata match (or pass a Chunk -> bool callable)
+    min_score=0.25,                    # cosine threshold; weaker chunks are ignored
+    top_k=3,
+)
+```
+
+Repeated queries reuse a cached query embedding (LRU, configurable via
+`query_cache_size`), so re-asking the same question skips the embedding call.
+
+### Add documents incrementally, save, and reload
+
+```python
+rag = RAG().add("first batch").add("second batch")
+rag.save("index.pkl")
+
+rag = RAG.load("index.pkl", embedding_model="openai:text-embedding-3-small",
+               llm_model="openai:gpt-4o-mini")
+```
+
+### Batch and async
+
+```python
+# Answer many questions at once — embeddings are batched, generation is parallelized.
+responses = rag.query_many(["q1?", "q2?", "q3?"], max_workers=8)
+
+# Async API (non-blocking, great for web servers):
+resp = await rag.aquery("your question")
+async for token in rag.astream("your question"):
+    print(token, end="", flush=True)
+```
+
+### Bring your own provider
+
+```python
+# Any callable fn(prompt) -> str works as an LLM:
+rag = RAG(documents=text, llm_model=lambda prompt: my_model.generate(prompt))
+
+# Any object with embed_documents(list[str]) and embed_query(str) works as an embedder.
+```
+
+## Configuration
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `documents` | `None` | str / list[str] / list[dict] / `Document`(s) to index. |
+| `embedding_model` | `"hash"` | `"provider:model"` string or a custom provider. |
+| `llm_model` | `None` (offline) | `"provider:model"` string, callable, or provider. |
+| `chunk_size` | `512` | Target chunk size in tokens. |
+| `chunk_overlap` | `64` | Token overlap between chunks. |
+| `top_k` | `4` | Chunks retrieved per query. |
+| `use_mmr` | `False` | Maximal Marginal Relevance re-ranking for diverse results. |
+| `use_faiss` | `False` | Use FAISS index (install `swiftrag[faiss]`). |
+| `min_score` | `None` | Default cosine threshold for dropping weak matches. |
+| `max_context_tokens` | `None` | Cap the tokens of retrieved context packed into the prompt. |
+| `dedup` | `True` | Skip exact-duplicate chunks on ingest. |
+| `query_cache_size` | `128` | LRU size for cached query embeddings (`0` disables). |
+| `system_prompt` | grounded default | System prompt for the LLM. |
+
+## How it works
+
+```
+documents ─▶ chunk (token-aware) ─▶ embed (batched) ─▶ normalize ─▶ vector store
+                                                                         │
+query ─▶ embed ─▶ cosine (BLAS matmul) ─▶ top-k (argpartition) ─▶ context ─▶ LLM ─▶ answer
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

swiftrag-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "swiftrag"
+version = "0.1.0"
+description = "Instant, optimized Retrieval-Augmented Generation. Pass your text + a model, get a RAG-powered LLM in one line."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Behrad Moeini" }]
+keywords = [
+    "rag",
+    "retrieval-augmented-generation",
+    "llm",
+    "embeddings",
+    "vector-search",
+    "openai",
+    "ai",
+    "nlp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+# Core stays intentionally tiny. numpy is the only hard runtime dependency so
+# the package installs in seconds and works fully offline (hash embeddings +
+# echo LLM) with zero API keys.
+dependencies = [
+    "numpy>=1.21",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.25"]
+local = ["sentence-transformers>=2.2"]
+faiss = ["faiss-cpu>=1.7"]
+tokenize = ["tiktoken>=0.5"]
+# Everything you might want, in one shot.
+all = [
+    "openai>=1.0",
+    "anthropic>=0.25",
+    "sentence-transformers>=2.2",
+    "faiss-cpu>=1.7",
+    "tiktoken>=0.5",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/behradmoeini/swiftrag"
+Repository = "https://github.com/behradmoeini/swiftrag"
+Issues = "https://github.com/behradmoeini/swiftrag/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/swiftrag"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/swiftrag", "README.md", "LICENSE", "tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

swiftrag-0.1.0/src/swiftrag/__init__.py

@@ -0,0 +1,58 @@
+"""swiftrag — instant, optimized Retrieval-Augmented Generation.
+
+Pass your text and (optionally) a model. Get a RAG-powered LLM in one line.
+
+    from swiftrag import RAG
+
+    rag = RAG(
+        documents="your knowledge as a string (or a list of strings/dicts)",
+        embedding_model="openai:text-embedding-3-small",
+        llm_model="openai:gpt-4o-mini",
+    )
+    print(rag.query("your question"))
+"""
+
+from __future__ import annotations
+
+from .chunking import chunk_text, count_tokens
+from .core import RAG
+from .embeddings import (
+    EmbeddingProvider,
+    HashEmbeddings,
+    OpenAIEmbeddings,
+    SentenceTransformerEmbeddings,
+)
+from .exceptions import (
+    ConfigurationError,
+    DependencyError,
+    EmptyCorpusError,
+    SwiftRagError,
+)
+from .llms import AnthropicLLM, CallableLLM, EchoLLM, LLMProvider, OpenAILLM
+from .types import Chunk, Document, RAGResponse, ScoredChunk
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RAG",
+    "chunk_text",
+    "count_tokens",
+    "Document",
+    "Chunk",
+    "ScoredChunk",
+    "RAGResponse",
+    "EmbeddingProvider",
+    "HashEmbeddings",
+    "OpenAIEmbeddings",
+    "SentenceTransformerEmbeddings",
+    "LLMProvider",
+    "OpenAILLM",
+    "AnthropicLLM",
+    "EchoLLM",
+    "CallableLLM",
+    "SwiftRagError",
+    "ConfigurationError",
+    "DependencyError",
+    "EmptyCorpusError",
+    "__version__",
+]