bibirags 0.1.0__tar.gz

bibirags-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# RAG indices (generated at runtime)
+rag_root_*/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

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

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements

bibirags-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-01
+
+### Added
+- Initial release.
+- Four vector-store backends: **txtai**, **Chroma**, **Qdrant**, **LightRAG**.
+- Consistent `save / search / query` API across all backends.
+- LiteLLM-powered embedding and completion helpers (sync + async).
+- `chunk_docs` utility for PDF and TXT document loading and splitting.
+- Optional extras for each backend (`pip install simplerags[qdrant]` etc.).
+- Full type annotations and Loguru structured logging.

bibirags-0.1.0/LICENSE

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

bibirags-0.1.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: install test lint fmt build publish clean
+
+install:
+	pip install -e ".[dev]"
+
+test:
+	pytest tests/ -v --cov=simplerags --cov-report=term-missing
+
+lint:
+	ruff check src/ tests/
+
+fmt:
+	ruff format src/ tests/
+
+build:
+	python -m build
+
+# Publish to TestPyPI first:  make publish-test
+# Then to PyPI:               make publish
+publish-test:
+	twine upload --repository testpypi dist/*
+
+publish:
+	twine upload dist/*
+
+clean:
+	rm -rf dist/ build/ *.egg-info .coverage htmlcov/ .pytest_cache/ .mypy_cache/ .ruff_cache/

bibirags-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: bibirags
+Version: 0.1.0
+Summary: A simple, unified interface for RAG across multiple vector store backends (txtai, Chroma, Qdrant, LightRAG)
+Project-URL: Homepage, https://github.com/bibiparrot/bibirags
+Project-URL: Repository, https://github.com/bibiparrot/bibirags
+Project-URL: Issues, https://github.com/bibiparrot/bibirags/issues
+Project-URL: Changelog, https://github.com/bibiparrot/bibirags/blob/main/CHANGELOG.md
+Author-email: chunqishi <scq830@163.com>
+License: MIT License
+        
+        Copyright (c) 2026 Bibi Parrot
+        
+        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.
+License-File: LICENSE
+Keywords: ai,embeddings,llm,rag,retrieval,vector-store
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Requires-Dist: litellm>=1.86.2
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: all
+Requires-Dist: langchain-chroma>=0.1.0; extra == 'all'
+Requires-Dist: langchain-classic>=0.1.0; extra == 'all'
+Requires-Dist: langchain-community>=0.2.0; extra == 'all'
+Requires-Dist: langchain-core>=0.2.0; extra == 'all'
+Requires-Dist: langchain-litellm>=0.1.0; extra == 'all'
+Requires-Dist: langchain-text-splitters>=0.2.0; extra == 'all'
+Requires-Dist: lightrag-hku>=1.0.0; extra == 'all'
+Requires-Dist: nest-asyncio>=1.6.0; extra == 'all'
+Requires-Dist: pypdf>=4.0.0; extra == 'all'
+Requires-Dist: qdrant-client>=1.9.0; extra == 'all'
+Requires-Dist: txtai[pipeline]>=7.0.0; extra == 'all'
+Provides-Extra: chroma
+Requires-Dist: langchain-chroma>=0.1.0; extra == 'chroma'
+Requires-Dist: langchain-classic>=0.1.0; extra == 'chroma'
+Requires-Dist: langchain-core>=0.2.0; extra == 'chroma'
+Requires-Dist: langchain-litellm>=0.1.0; extra == 'chroma'
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: langchain-chroma>=0.1.0; extra == 'dev'
+Requires-Dist: langchain-classic>=0.1.0; extra == 'dev'
+Requires-Dist: langchain-community>=0.2.0; extra == 'dev'
+Requires-Dist: langchain-core>=0.2.0; extra == 'dev'
+Requires-Dist: langchain-litellm>=0.1.0; extra == 'dev'
+Requires-Dist: langchain-text-splitters>=0.2.0; extra == 'dev'
+Requires-Dist: lightrag-hku>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: nest-asyncio>=1.6.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pypdf>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: qdrant-client>=1.9.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Requires-Dist: txtai[pipeline]>=7.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: langchain-community>=0.2.0; extra == 'docs'
+Requires-Dist: langchain-text-splitters>=0.2.0; extra == 'docs'
+Requires-Dist: pypdf>=4.0.0; extra == 'docs'
+Provides-Extra: lightrag
+Requires-Dist: lightrag-hku>=1.0.0; extra == 'lightrag'
+Requires-Dist: nest-asyncio>=1.6.0; extra == 'lightrag'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.9.0; extra == 'qdrant'
+Provides-Extra: txtai
+Requires-Dist: txtai[pipeline]>=7.0.0; extra == 'txtai'
+Description-Content-Type: text/markdown
+
+# simplerags
+
+**A simple, unified interface for RAG (Retrieval-Augmented Generation) across multiple vector store backends.**
+
+`simplerags` wraps [txtai](https://github.com/neuml/txtai), [Chroma](https://www.trychroma.com/), [Qdrant](https://qdrant.tech/), and [LightRAG](https://github.com/HKUDS/LightRAG) behind a consistent three-function API so you can swap backends without rewriting your pipeline.
+
+```
+save_<backend>(chunks, rag_root, embed_model, ...)  → index documents
+search_<backend>(query, rag_root, embed_model, ...) → retrieve chunks
+query_<backend>(query, rag_root, llm_model, ...)    → retrieve + answer
+```
+
+All LLM and embedding calls go through [LiteLLM](https://github.com/BerriAI/litellm), meaning any model provider (OpenAI, Anthropic, Cohere, Ollama, etc.) works out of the box.
+
+---
+
+## Installation
+
+Install the core package plus the backends you need:
+
+```bash
+# Qdrant only
+pip install simplerags[qdrant]
+
+# Chroma only
+pip install simplerags[chroma]
+
+# txtai only
+pip install simplerags[txtai]
+
+# LightRAG only
+pip install simplerags[lightrag]
+
+# All backends + document loading helpers
+pip install simplerags[all]
+```
+
+Add `[docs]` to get PDF and TXT loading via LangChain:
+
+```bash
+pip install simplerags[qdrant,docs]
+```
+
+---
+
+## Quick start
+
+### Index raw text chunks
+
+```python
+from simplerags import save_qdrant, search_qdrant, query_qdrant
+
+chunks = [
+    "The Eiffel Tower was completed in 1889.",
+    "The Louvre is the world's largest art museum.",
+    "Paris is the capital of France.",
+]
+
+embed_model = "text-embedding-3-small"   # any LiteLLM-compatible model
+llm_model   = "gpt-4o-mini"
+rag_root    = "./my_rag_index"
+
+# 1. Index
+save_qdrant(chunks, rag_root, embed_model)
+
+# 2. Semantic search
+results = search_qdrant("When was the Eiffel Tower built?", rag_root, embed_model)
+
+# 3. RAG query → answer + source chunks
+answer, sources = query_qdrant(
+    "When was the Eiffel Tower built?", rag_root, llm_model, embed_model
+)
+print(answer)
+```
+
+### Load documents from disk
+
+```python
+from simplerags import chunk_docs, save_chroma, query_chroma
+
+chunks = chunk_docs("./my_docs/", chunk_size=800, chunk_overlap=120)
+save_chroma(chunks, "./chroma_index", embed_model="text-embedding-3-small")
+
+answer, sources = query_chroma(
+    "What does the contract say about termination?",
+    rag_root="./chroma_index",
+    llm_model="gpt-4o",
+    embed_model="text-embedding-3-small",
+)
+```
+
+### Using Ollama (local models)
+
+```python
+from simplerags import save_txtai, query_txtai
+
+save_txtai(chunks, "./txtai_index", embed_model="ollama/bge-m3:latest")
+
+answer, sources = query_txtai(
+    "What happened in the news?",
+    rag_root="./txtai_index",
+    llm_model="ollama/gemma3:8b",
+    embed_model="ollama/bge-m3:latest",
+)
+```
+
+---
+
+## Backends at a glance
+
+| Backend  | Best for | Index format | Notes |
+|----------|----------|--------------|-------|
+| **Qdrant** | Production workloads, filtering | Local files or server | Cosine similarity, rich payload filtering |
+| **Chroma** | LangChain ecosystems | Local SQLite | Easy LangChain integration |
+| **txtai**  | All-in-one HuggingFace pipelines | SQLite + FAISS | Built-in pipeline support |
+| **LightRAG** | Knowledge-graph RAG | Local JSON + vector | Graph-enhanced hybrid retrieval |
+
+---
+
+## API reference
+
+### `chunk_docs`
+
+```python
+chunk_docs(docs_path, chunk_size=800, chunk_overlap=120) → list[str]
+```
+
+Recursively loads `.pdf` and `.txt` files from `docs_path` and returns text chunks.
+
+### `save_<backend>`
+
+```python
+save_qdrant(chunks, rag_root, embed_model)
+save_chroma(chunks, rag_root, embed_model)
+save_txtai(chunks, rag_root, embed_model)
+save_lightrag(chunks, rag_root, embed_model, llm_model)
+```
+
+### `search_<backend>`
+
+```python
+results: list[str] = search_qdrant(query, rag_root, embed_model, top_k=3)
+```
+
+Returns the `top_k` most relevant chunk texts.
+
+### `query_<backend>`
+
+```python
+answer, sources = query_qdrant(query, rag_root, llm_model, embed_model, top_k=3)
+```
+
+Returns `(answer_string, list_of_source_chunks)`.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/yourname/simplerags
+cd simplerags
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+---
+
+## License
+
+MIT – see [LICENSE](LICENSE).

bibirags-0.1.0/README.md

@@ -0,0 +1,171 @@
+# simplerags
+
+**A simple, unified interface for RAG (Retrieval-Augmented Generation) across multiple vector store backends.**
+
+`simplerags` wraps [txtai](https://github.com/neuml/txtai), [Chroma](https://www.trychroma.com/), [Qdrant](https://qdrant.tech/), and [LightRAG](https://github.com/HKUDS/LightRAG) behind a consistent three-function API so you can swap backends without rewriting your pipeline.
+
+```
+save_<backend>(chunks, rag_root, embed_model, ...)  → index documents
+search_<backend>(query, rag_root, embed_model, ...) → retrieve chunks
+query_<backend>(query, rag_root, llm_model, ...)    → retrieve + answer
+```
+
+All LLM and embedding calls go through [LiteLLM](https://github.com/BerriAI/litellm), meaning any model provider (OpenAI, Anthropic, Cohere, Ollama, etc.) works out of the box.
+
+---
+
+## Installation
+
+Install the core package plus the backends you need:
+
+```bash
+# Qdrant only
+pip install simplerags[qdrant]
+
+# Chroma only
+pip install simplerags[chroma]
+
+# txtai only
+pip install simplerags[txtai]
+
+# LightRAG only
+pip install simplerags[lightrag]
+
+# All backends + document loading helpers
+pip install simplerags[all]
+```
+
+Add `[docs]` to get PDF and TXT loading via LangChain:
+
+```bash
+pip install simplerags[qdrant,docs]
+```
+
+---
+
+## Quick start
+
+### Index raw text chunks
+
+```python
+from simplerags import save_qdrant, search_qdrant, query_qdrant
+
+chunks = [
+    "The Eiffel Tower was completed in 1889.",
+    "The Louvre is the world's largest art museum.",
+    "Paris is the capital of France.",
+]
+
+embed_model = "text-embedding-3-small"   # any LiteLLM-compatible model
+llm_model   = "gpt-4o-mini"
+rag_root    = "./my_rag_index"
+
+# 1. Index
+save_qdrant(chunks, rag_root, embed_model)
+
+# 2. Semantic search
+results = search_qdrant("When was the Eiffel Tower built?", rag_root, embed_model)
+
+# 3. RAG query → answer + source chunks
+answer, sources = query_qdrant(
+    "When was the Eiffel Tower built?", rag_root, llm_model, embed_model
+)
+print(answer)
+```
+
+### Load documents from disk
+
+```python
+from simplerags import chunk_docs, save_chroma, query_chroma
+
+chunks = chunk_docs("./my_docs/", chunk_size=800, chunk_overlap=120)
+save_chroma(chunks, "./chroma_index", embed_model="text-embedding-3-small")
+
+answer, sources = query_chroma(
+    "What does the contract say about termination?",
+    rag_root="./chroma_index",
+    llm_model="gpt-4o",
+    embed_model="text-embedding-3-small",
+)
+```
+
+### Using Ollama (local models)
+
+```python
+from simplerags import save_txtai, query_txtai
+
+save_txtai(chunks, "./txtai_index", embed_model="ollama/bge-m3:latest")
+
+answer, sources = query_txtai(
+    "What happened in the news?",
+    rag_root="./txtai_index",
+    llm_model="ollama/gemma3:8b",
+    embed_model="ollama/bge-m3:latest",
+)
+```
+
+---
+
+## Backends at a glance
+
+| Backend  | Best for | Index format | Notes |
+|----------|----------|--------------|-------|
+| **Qdrant** | Production workloads, filtering | Local files or server | Cosine similarity, rich payload filtering |
+| **Chroma** | LangChain ecosystems | Local SQLite | Easy LangChain integration |
+| **txtai**  | All-in-one HuggingFace pipelines | SQLite + FAISS | Built-in pipeline support |
+| **LightRAG** | Knowledge-graph RAG | Local JSON + vector | Graph-enhanced hybrid retrieval |
+
+---
+
+## API reference
+
+### `chunk_docs`
+
+```python
+chunk_docs(docs_path, chunk_size=800, chunk_overlap=120) → list[str]
+```
+
+Recursively loads `.pdf` and `.txt` files from `docs_path` and returns text chunks.
+
+### `save_<backend>`
+
+```python
+save_qdrant(chunks, rag_root, embed_model)
+save_chroma(chunks, rag_root, embed_model)
+save_txtai(chunks, rag_root, embed_model)
+save_lightrag(chunks, rag_root, embed_model, llm_model)
+```
+
+### `search_<backend>`
+
+```python
+results: list[str] = search_qdrant(query, rag_root, embed_model, top_k=3)
+```
+
+Returns the `top_k` most relevant chunk texts.
+
+### `query_<backend>`
+
+```python
+answer, sources = query_qdrant(query, rag_root, llm_model, embed_model, top_k=3)
+```
+
+Returns `(answer_string, list_of_source_chunks)`.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/yourname/simplerags
+cd simplerags
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+---
+
+## License
+
+MIT – see [LICENSE](LICENSE).

bibirags-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bibirags"
+version = "0.1.0"
+description = "A simple, unified interface for RAG across multiple vector store backends (txtai, Chroma, Qdrant, LightRAG)"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "chunqishi", email = "scq830@163.com" }]
+keywords = ["rag", "retrieval", "llm", "vector-store", "embeddings", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "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",
+]
+requires-python = ">=3.10"
+
+# Core dependencies (always installed)
+dependencies = [
+    "litellm>=1.86.2",
+    "loguru>=0.7.0",
+    "numpy>=1.24.0",
+]
+
+[project.optional-dependencies]
+# Backend extras – install only what you need
+
+txtai = [
+    "txtai[pipeline]>=7.0.0",
+]
+
+chroma = [
+    "langchain-chroma>=0.1.0",
+    "langchain-litellm>=0.1.0",
+    "langchain-classic>=0.1.0",
+    "langchain-core>=0.2.0",
+]
+
+qdrant = [
+    "qdrant-client>=1.9.0",
+]
+
+lightrag = [
+    "lightrag-hku>=1.0.0",
+    "nest-asyncio>=1.6.0",
+]
+
+# Document loading extras
+docs = [
+    "langchain-community>=0.2.0",
+    "langchain-text-splitters>=0.2.0",
+    "pypdf>=4.0.0",
+]
+
+# Install everything
+all = [
+    "bibirags[txtai]",
+    "bibirags[chroma]",
+    "bibirags[qdrant]",
+    "bibirags[lightrag]",
+    "bibirags[docs]",
+]
+
+# Development toolchain
+dev = [
+    "bibirags[all]",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "pre-commit>=3.7.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/bibiparrot/bibirags"
+Repository = "https://github.com/bibiparrot/bibirags"
+Issues = "https://github.com/bibiparrot/bibirags/issues"
+Changelog = "https://github.com/bibiparrot/bibirags/blob/main/CHANGELOG.md"
+
+# ---------------------------------------------------------------------------
+# Hatch build
+# ---------------------------------------------------------------------------
+[tool.hatch.build.targets.wheel]
+packages = ["src/bibirags"]
+
+# ---------------------------------------------------------------------------
+# Ruff (linting + formatting)
+# ---------------------------------------------------------------------------
+[tool.ruff]
+src = ["src"]
+line-length = 99
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "C4", "PIE", "SIM"]
+ignore = ["E501"]
+
+# ---------------------------------------------------------------------------
+# Mypy
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.10"
+strict = false
+ignore_missing_imports = true
+
+# ---------------------------------------------------------------------------
+# Pytest
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--tb=short -q"