voice-rag 0.1.0__tar.gz

voice_rag-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.qdrant/
+.venv/
+dist/
+build/
+coverage/
+.DS_Store

voice_rag-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# 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).
+
+## [0.1.0] - 2026-03-16
+
+### Added
+
+- `KnowledgeAgent` high-level Python API: `ingest()`, `query()`, `create_app()`
+- CLI: `voice-rag init`, `ingest`, `serve`, `query`, `inspect`, `doctor`
+- Voice adapters: ElevenLabs, Deepgram
+- LLM clients: OpenAI, Anthropic, Gemini (with streaming)
+- Embedding client: OpenAI (`text-embedding-3-small` default)
+- Vector store: Qdrant with hybrid dense + BM25 retrieval
+- Document parsers: `.txt`, `.md`, `.pdf` (via PyMuPDF), `.docx`
+- `VoiceRagConfig` with YAML and environment variable support
+- FastAPI webhook serving OpenAI-style `/v1/chat/completions` (SSE streaming)
+- `voice-rag.yaml` annotated example config
+- GitHub Actions CI (Python 3.11, 3.12) and publish pipeline (TestPyPI → PyPI)

voice_rag-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing to voice-rag
+
+Thank you for contributing! This guide covers how to add new connectors.
+
+## Project structure
+
+```text
+voice_rag/
+  agent.py              # KnowledgeAgent high-level API; connector registries here
+  core/
+    config.py           # VoiceRagConfig pydantic model
+    models.py           # Chunk, RetrievedChunk data models
+    chunking.py         # Text/markdown chunking logic
+    retrieval.py        # Prompt augmentation with retrieved chunks
+    streaming.py        # SSE streaming helpers
+  connectors/
+    llm/                # LLM chat clients (openai, anthropic, gemini)
+    voice/              # Voice adapters (elevenlabs, deepgram)
+    embeddings/         # Embedding clients (openai)
+    vector_stores/      # Vector store clients (qdrant)
+    parsers/            # Document loaders (text, markdown, pdf, docx)
+  cli/
+    commands.py         # Click commands
+    __main__.py         # CLI entry point
+  server.py             # FastAPI app factory
+tests/                  # pytest tests (mirror voice_rag/ structure)
+```
+
+## Adding a new LLM connector
+
+1. Create `voice_rag/connectors/llm/<provider>.py`:
+
+```python
+from voice_rag.connectors.llm.base import BaseChatClient
+from typing import Iterator
+
+class MyProviderChatClient(BaseChatClient):
+    def __init__(self, api_key: str):
+        self.client = MyProviderSDK(api_key=api_key)
+
+    def stream_chat_completion(self, messages: list[dict], model: str) -> Iterator[str]:
+        # yield SSE-formatted chunks: "data: {...}\n\n"
+        for chunk in self.client.stream(messages=messages, model=model):
+            yield f"data: {chunk.to_json()}\n\n"
+        yield "data: [DONE]\n\n"
+```
+
+2. Register it in `voice_rag/agent.py`:
+
+```python
+_LLM_CLIENTS = {
+    "openai": "voice_rag.connectors.llm.openai:OpenAIChatClient",
+    "anthropic": "voice_rag.connectors.llm.anthropic:AnthropicChatClient",
+    "gemini": "voice_rag.connectors.llm.gemini:GeminiChatClient",
+    "myprovider": "voice_rag.connectors.llm.myprovider:MyProviderChatClient",
+}
+```
+
+3. Add the optional dependency in `pyproject.toml`:
+
+```toml
+[project.optional-dependencies]
+myprovider = ["myprovider-sdk>=1.0.0"]
+all = ["voice-rag[anthropic,gemini,deepgram,elevenlabs,myprovider,pdf,docx]"]
+```
+
+4. Add a test in `tests/test_llm_myprovider.py` (see `tests/test_llm_openai.py` for the pattern).
+
+## Adding a new voice connector
+
+Same pattern as LLM. Implement `BaseVoiceAdapter` from `voice_rag/connectors/voice/base.py` and register in `_VOICE_ADAPTERS` in `agent.py`.
+
+## Adding a new vector store connector
+
+Implement `BaseVectorStore` from `voice_rag/connectors/vector_stores/base.py`. There is no auto-registry yet — wire it manually in `KnowledgeAgent._init_components()` with a provider name check. Open a PR and we'll add registry support if needed.
+
+## Adding a new document parser
+
+Implement `BaseLoader` from `voice_rag/connectors/parsers/` and register the file extension in `_PARSERS` in `agent.py`.
+
+## Running tests
+
+**On macOS (to avoid arm64/x86_64 Rosetta issues):**
+
+```bash
+arch -arm64 .venv/bin/python -m pytest tests/ -v
+```
+
+**On Linux / CI:**
+
+```bash
+pytest tests/ -v
+```
+
+## Submitting a PR
+
+- Branch name: `feat/<connector-name>` or `fix/<description>`
+- Every new connector must have tests
+- Run the full test suite before opening the PR
+- Reviewers will check: does it implement the base class, is it registered, does it have tests, does it add the optional dep?

voice_rag-0.1.0/LICENSE

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

voice_rag-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.3
+Name: voice-rag
+Version: 0.1.0
+Summary: Provider-agnostic voice RAG pipeline. Plug in your voice provider, LLM, vector store, and document parsers.
+Project-URL: Homepage, https://github.com/kytona/voice-rag
+Project-URL: Repository, https://github.com/kytona/voice-rag
+Project-URL: Changelog, https://github.com/kytona/voice-rag/blob/main/CHANGELOG.md
+Author-email: Gaurang Torvekar <info@kytona.com>
+Maintainer-email: Kytona Limited <info@kytona.com>
+License: MIT
+Keywords: ai,chatbot,elevenlabs,fastapi,llm,qdrant,rag,retrieval,vector-search,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: fastembed>=0.6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic-settings>=2.2.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qdrant-client>=1.10.0
+Requires-Dist: uvicorn>=0.27.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40.0; extra == 'all'
+Requires-Dist: deepgram-sdk>=3.0.0; extra == 'all'
+Requires-Dist: elevenlabs>=1.0.0; extra == 'all'
+Requires-Dist: google-genai>=1.0.0; extra == 'all'
+Requires-Dist: pymupdf>=1.24.0; extra == 'all'
+Requires-Dist: python-docx>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: deepgram
+Requires-Dist: deepgram-sdk>=3.0.0; extra == 'deepgram'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.40.0; extra == 'dev'
+Requires-Dist: deepgram-sdk>=3.0.0; extra == 'dev'
+Requires-Dist: elevenlabs>=1.0.0; extra == 'dev'
+Requires-Dist: google-genai>=1.0.0; extra == 'dev'
+Requires-Dist: pymupdf>=1.24.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: python-docx>=1.0.0; extra == 'dev'
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.0.0; extra == 'docx'
+Provides-Extra: elevenlabs
+Requires-Dist: elevenlabs>=1.0.0; extra == 'elevenlabs'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
+Provides-Extra: pdf
+Requires-Dist: pymupdf>=1.24.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# voice-rag
+
+[![PyPI version](https://img.shields.io/pypi/v/voice-rag)](https://pypi.org/project/voice-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kytona/voice-rag/blob/main/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/voice-rag)](https://pypi.org/project/voice-rag/)
+
+`voice-rag` is a Python package for voice-oriented RAG pipelines: ingest local documents, store them in Qdrant, serve an OpenAI-style chat-completions webhook, and swap voice or LLM providers behind a stable interface.
+
+## What it includes
+
+- Python SDK via `KnowledgeAgent`
+- CLI for `init`, `ingest`, `serve`, `query`, `inspect`, and `doctor`
+- Built-in voice adapters for `elevenlabs` and `deepgram`
+- Built-in LLM clients for `openai`, `anthropic`, and `gemini`
+- Built-in parsers for `.txt`, `.md`, `.pdf`, and `.docx`
+- Qdrant vector store integration with hybrid dense + BM25 retrieval
+
+## Quickstart
+
+```bash
+pip install "voice-rag[elevenlabs]"
+export OPENAI_API_KEY=your_api_key_here
+voice-rag init
+```
+
+Edit `voice-rag.yaml`, then ingest and serve:
+
+```bash
+voice-rag ingest ./data/sample_docs/claude-code-changelog.md --recreate
+voice-rag serve
+```
+
+Point your voice platform to `http://localhost:8000/v1` if it expects an OpenAI-style Custom LLM endpoint.
+By default, `voice-rag` uses an embedded local Qdrant store in `.qdrant`, so you do not need to start a separate Qdrant server unless you set `vector_store.url`.
+
+## CLI
+
+```bash
+voice-rag init [--dir PATH]
+voice-rag ingest <path> [--recreate] [--config PATH]
+voice-rag serve [--host HOST] [--port PORT] [--reload] [--config PATH]
+voice-rag query <text> [--limit N] [--config PATH]
+voice-rag inspect [--config PATH]
+voice-rag doctor
+```
+
+## Python API
+
+```python
+from voice_rag import KnowledgeAgent, VoiceRagConfig
+
+config = VoiceRagConfig()
+agent = KnowledgeAgent(config=config)
+agent.ingest("./docs", recreate=True)
+app = agent.create_app()
+```
+
+## Configuration
+
+`voice-rag` reads configuration from `voice-rag.yaml` and environment variables. It does not auto-load `.env` files.
+
+| Key                                 | Env                            | Default                    |
+| ----------------------------------- | ------------------------------ | -------------------------- |
+| `llm.api_key` / `embedding.api_key` | `OPENAI_API_KEY`               | (required for OpenAI)      |
+| `llm.provider`                      | `LLM_PROVIDER`                 | `openai`                   |
+| `llm.model`                         | `LLM_MODEL`                    | `gpt-4o-mini`              |
+| `embedding.model`                   | `EMBEDDING_MODEL`              | `text-embedding-3-small`   |
+| `vector_store.url`                  | `VECTOR_STORE_URL`             | empty; use local `.qdrant` |
+| `vector_store.collection_name`      | `VECTOR_STORE_COLLECTION_NAME` | `knowledge_base`           |
+| `vector_store.local_path`           | `VECTOR_STORE_LOCAL_PATH`      | `.qdrant`                  |
+| `server.port`                       | `SERVER_PORT`                  | `8000`                     |
+
+See [voice-rag.yaml](https://github.com/kytona/voice-rag/blob/main/voice-rag.yaml) for the full schema.
+
+## Development
+
+```bash
+pip install -e ".[all,dev]"
+pytest tests/ -v
+```
+
+Use [CONTRIBUTING.md](https://github.com/kytona/voice-rag/blob/main/CONTRIBUTING.md) for connector and packaging guidelines.
+
+## Publishing to PyPI
+
+With `PYPI_TOKEN` and the `release` environment configured in the repo, push a version tag to trigger the GitHub Actions workflow:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs smoke test → build → publish to PyPI.

voice_rag-0.1.0/README.md

@@ -0,0 +1,93 @@
+# voice-rag
+
+[![PyPI version](https://img.shields.io/pypi/v/voice-rag)](https://pypi.org/project/voice-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kytona/voice-rag/blob/main/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/voice-rag)](https://pypi.org/project/voice-rag/)
+
+`voice-rag` is a Python package for voice-oriented RAG pipelines: ingest local documents, store them in Qdrant, serve an OpenAI-style chat-completions webhook, and swap voice or LLM providers behind a stable interface.
+
+## What it includes
+
+- Python SDK via `KnowledgeAgent`
+- CLI for `init`, `ingest`, `serve`, `query`, `inspect`, and `doctor`
+- Built-in voice adapters for `elevenlabs` and `deepgram`
+- Built-in LLM clients for `openai`, `anthropic`, and `gemini`
+- Built-in parsers for `.txt`, `.md`, `.pdf`, and `.docx`
+- Qdrant vector store integration with hybrid dense + BM25 retrieval
+
+## Quickstart
+
+```bash
+pip install "voice-rag[elevenlabs]"
+export OPENAI_API_KEY=your_api_key_here
+voice-rag init
+```
+
+Edit `voice-rag.yaml`, then ingest and serve:
+
+```bash
+voice-rag ingest ./data/sample_docs/claude-code-changelog.md --recreate
+voice-rag serve
+```
+
+Point your voice platform to `http://localhost:8000/v1` if it expects an OpenAI-style Custom LLM endpoint.
+By default, `voice-rag` uses an embedded local Qdrant store in `.qdrant`, so you do not need to start a separate Qdrant server unless you set `vector_store.url`.
+
+## CLI
+
+```bash
+voice-rag init [--dir PATH]
+voice-rag ingest <path> [--recreate] [--config PATH]
+voice-rag serve [--host HOST] [--port PORT] [--reload] [--config PATH]
+voice-rag query <text> [--limit N] [--config PATH]
+voice-rag inspect [--config PATH]
+voice-rag doctor
+```
+
+## Python API
+
+```python
+from voice_rag import KnowledgeAgent, VoiceRagConfig
+
+config = VoiceRagConfig()
+agent = KnowledgeAgent(config=config)
+agent.ingest("./docs", recreate=True)
+app = agent.create_app()
+```
+
+## Configuration
+
+`voice-rag` reads configuration from `voice-rag.yaml` and environment variables. It does not auto-load `.env` files.
+
+| Key                                 | Env                            | Default                    |
+| ----------------------------------- | ------------------------------ | -------------------------- |
+| `llm.api_key` / `embedding.api_key` | `OPENAI_API_KEY`               | (required for OpenAI)      |
+| `llm.provider`                      | `LLM_PROVIDER`                 | `openai`                   |
+| `llm.model`                         | `LLM_MODEL`                    | `gpt-4o-mini`              |
+| `embedding.model`                   | `EMBEDDING_MODEL`              | `text-embedding-3-small`   |
+| `vector_store.url`                  | `VECTOR_STORE_URL`             | empty; use local `.qdrant` |
+| `vector_store.collection_name`      | `VECTOR_STORE_COLLECTION_NAME` | `knowledge_base`           |
+| `vector_store.local_path`           | `VECTOR_STORE_LOCAL_PATH`      | `.qdrant`                  |
+| `server.port`                       | `SERVER_PORT`                  | `8000`                     |
+
+See [voice-rag.yaml](https://github.com/kytona/voice-rag/blob/main/voice-rag.yaml) for the full schema.
+
+## Development
+
+```bash
+pip install -e ".[all,dev]"
+pytest tests/ -v
+```
+
+Use [CONTRIBUTING.md](https://github.com/kytona/voice-rag/blob/main/CONTRIBUTING.md) for connector and packaging guidelines.
+
+## Publishing to PyPI
+
+With `PYPI_TOKEN` and the `release` environment configured in the repo, push a version tag to trigger the GitHub Actions workflow:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs smoke test → build → publish to PyPI.