vision-agents-plugins-qdrant 0.6.3__tar.gz

vision_agents_plugins_qdrant-0.6.3/.gitignore

@@ -0,0 +1,102 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.cursor/*
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+develop-eggs/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+pip-wheel-metadata/
+MANIFEST
+*.egg-info/
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+nosetests.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Type checker / lint caches
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+.ruff_cache/
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env
+.env.local
+.env.*.local
+.env.bak
+pyvenv.cfg
+.python-version
+
+# Editors / IDEs
+.vscode/
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+
+# OS / Misc
+.DS_Store
+*.log
+
+# Tooling & repo-specific
+pyrightconfig.json
+shell.nix
+bin/*
+lib/*
+stream-py/
+
+# Example lock files (regenerated by uv sync)
+examples/*/uv.lock
+plugins/*/example/uv.lock
+
+# Artifacts / assets
+*.pt
+*.kef
+*.onnx
+profile.html
+
+/opencode.json
+.ralph-tui/
+.claude/*
+!.claude/skills/
+
+.uv-cache/
+
+# pytest json report
+.report.json

vision_agents_plugins_qdrant-0.6.3/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: vision-agents-plugins-qdrant
+Version: 0.6.3
+Summary: Qdrant RAG integration for Vision Agents with hybrid search
+Project-URL: Documentation, https://visionagents.ai/
+Project-URL: Website, https://visionagents.ai/
+Project-URL: Source, https://github.com/GetStream/Vision-Agents
+License-Expression: MIT
+Keywords: AI,RAG,agents,hybrid-search,qdrant,vector-search,voice agents
+Requires-Python: >=3.10
+Requires-Dist: langchain-text-splitters>=1.1.1
+Requires-Dist: qdrant-client[fastembed]<1.18.0,>=1.12.0
+Requires-Dist: vision-agents
+Description-Content-Type: text/markdown
+
+# Qdrant RAG Plugin
+
+Hybrid search RAG (Retrieval Augmented Generation) using Qdrant's built-in fastembed integration for dense and BM25 sparse embeddings.
+
+## Features
+
+- **Hybrid Search**: Dense vector (semantic) + BM25 sparse (keyword) via native Qdrant RRF fusion
+- **fastembed Native**: No external embedding dependencies — Qdrant client handles everything
+- **Implements RAG Interface**: Compatible with Vision Agents RAG base class
+
+## Installation
+
+```bash
+uv add "vision-agents[qdrant]"
+# or directly
+uv add vision-agents-plugins-qdrant
+```
+
+## Usage
+
+```python
+from vision_agents.plugins import qdrant
+
+# Initialize RAG (connects to local Qdrant by default)
+rag = qdrant.QdrantRAG(collection="my-knowledge")
+await rag.add_directory("./knowledge")
+
+# Hybrid search (default)
+results = await rag.search("How does the chat API work?")
+
+# Vector-only search
+results = await rag.search("How does the chat API work?", mode="vector")
+
+# BM25 search
+results = await rag.search("chat API pricing", mode="bm25")
+
+# Or use convenience function
+rag = await qdrant.create_rag(
+    collection="product-knowledge",
+    knowledge_dir="./knowledge"
+)
+```
+
+## Configuration
+
+| Parameter      | Description                                   | Default                                    |
+|----------------|-----------------------------------------------|--------------------------------------------|
+| `collection`   | Qdrant collection name                        | Required                                   |
+| `url`          | Qdrant server URL                             | `http://localhost:6333`                    |
+| `api_key`      | Qdrant API key (for Qdrant Cloud)             | `QDRANT_API_KEY` env var                   |
+| `dense_model`  | fastembed dense model for semantic search     | `sentence-transformers/all-MiniLM-L6-v2`  |
+| `sparse_model` | fastembed sparse model for BM25 search        | `Qdrant/bm25`                              |
+| `chunk_size`   | Size of text chunks for splitting documents   | `10000`                                    |
+| `chunk_overlap`| Overlap between chunks for context continuity | `200`                                      |
+| `cloud_inference` | Use Qdrant Cloud server-side inference instead of local fastembed | `False`               |
+
+## Environment Variables
+
+- `QDRANT_API_KEY`: Qdrant API key (for Qdrant Cloud; not needed for local)
+
+## Running Qdrant locally
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+
+## Dependencies
+
+- `qdrant-client[fastembed]`: Qdrant async client with built-in fastembed support
+- `langchain-text-splitters`: Text chunking utilities
+
+## References
+
+- [Qdrant Hybrid Queries](https://qdrant.tech/documentation/concepts/hybrid-queries/)
+- [fastembed Models](https://qdrant.github.io/fastembed/examples/Supported_Models/)

vision_agents_plugins_qdrant-0.6.3/README.md

@@ -0,0 +1,75 @@
+# Qdrant RAG Plugin
+
+Hybrid search RAG (Retrieval Augmented Generation) using Qdrant's built-in fastembed integration for dense and BM25 sparse embeddings.
+
+## Features
+
+- **Hybrid Search**: Dense vector (semantic) + BM25 sparse (keyword) via native Qdrant RRF fusion
+- **fastembed Native**: No external embedding dependencies — Qdrant client handles everything
+- **Implements RAG Interface**: Compatible with Vision Agents RAG base class
+
+## Installation
+
+```bash
+uv add "vision-agents[qdrant]"
+# or directly
+uv add vision-agents-plugins-qdrant
+```
+
+## Usage
+
+```python
+from vision_agents.plugins import qdrant
+
+# Initialize RAG (connects to local Qdrant by default)
+rag = qdrant.QdrantRAG(collection="my-knowledge")
+await rag.add_directory("./knowledge")
+
+# Hybrid search (default)
+results = await rag.search("How does the chat API work?")
+
+# Vector-only search
+results = await rag.search("How does the chat API work?", mode="vector")
+
+# BM25 search
+results = await rag.search("chat API pricing", mode="bm25")
+
+# Or use convenience function
+rag = await qdrant.create_rag(
+    collection="product-knowledge",
+    knowledge_dir="./knowledge"
+)
+```
+
+## Configuration
+
+| Parameter      | Description                                   | Default                                    |
+|----------------|-----------------------------------------------|--------------------------------------------|
+| `collection`   | Qdrant collection name                        | Required                                   |
+| `url`          | Qdrant server URL                             | `http://localhost:6333`                    |
+| `api_key`      | Qdrant API key (for Qdrant Cloud)             | `QDRANT_API_KEY` env var                   |
+| `dense_model`  | fastembed dense model for semantic search     | `sentence-transformers/all-MiniLM-L6-v2`  |
+| `sparse_model` | fastembed sparse model for BM25 search        | `Qdrant/bm25`                              |
+| `chunk_size`   | Size of text chunks for splitting documents   | `10000`                                    |
+| `chunk_overlap`| Overlap between chunks for context continuity | `200`                                      |
+| `cloud_inference` | Use Qdrant Cloud server-side inference instead of local fastembed | `False`               |
+
+## Environment Variables
+
+- `QDRANT_API_KEY`: Qdrant API key (for Qdrant Cloud; not needed for local)
+
+## Running Qdrant locally
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+
+## Dependencies
+
+- `qdrant-client[fastembed]`: Qdrant async client with built-in fastembed support
+- `langchain-text-splitters`: Text chunking utilities
+
+## References
+
+- [Qdrant Hybrid Queries](https://qdrant.tech/documentation/concepts/hybrid-queries/)
+- [fastembed Models](https://qdrant.github.io/fastembed/examples/Supported_Models/)

vision_agents_plugins_qdrant-0.6.3/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vision-agents-plugins-qdrant"
+dynamic = ["version"]
+description = "Qdrant RAG integration for Vision Agents with hybrid search"
+readme = "README.md"
+keywords = ["qdrant", "RAG", "vector-search", "hybrid-search", "AI", "voice agents", "agents"]
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "vision-agents",
+    "qdrant-client[fastembed]>=1.12.0,<1.18.0",
+    "langchain-text-splitters>=1.1.1",
+]
+
+[project.urls]
+Documentation = "https://visionagents.ai/"
+Website = "https://visionagents.ai/"
+Source = "https://github.com/GetStream/Vision-Agents"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "..", search_parent_directories = true, fallback_version = "0.0.0" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["vision_agents"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/vision_agents"]
+
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.0.0",
+    "testcontainers[redis,qdrant]>=4.0.0",
+]

vision_agents_plugins_qdrant-0.6.3/vision_agents/plugins/qdrant/__init__.py

@@ -0,0 +1,3 @@
+from .qdrant_rag import QdrantRAG, create_rag
+
+__all__ = ["QdrantRAG", "create_rag"]

vision_agents_plugins_qdrant-0.6.3/vision_agents/plugins/qdrant/qdrant_rag.py

@@ -0,0 +1,233 @@
+"""
+Qdrant Hybrid Search RAG implementation.
+
+Uses Qdrant's built-in fastembed integration for dense and BM25 sparse embeddings.
+Hybrid search uses Qdrant's native Reciprocal Rank Fusion (RRF).
+See: https://qdrant.tech/documentation/concepts/hybrid-queries/
+
+Usage:
+    from vision_agents.plugins import qdrant
+
+    # Initialize with a Qdrant collection
+    rag = qdrant.QdrantRAG(collection="my-knowledge")
+    await rag.add_directory("./knowledge")
+
+    # Hybrid search (vector + BM25)
+    results = await rag.search("How does the chat API work?")
+
+    # Vector-only search
+    results = await rag.search("How does the chat API work?", mode="vector")
+
+    # BM25-only search
+    results = await rag.search("chat API pricing", mode="bm25")
+
+Environment variables:
+    QDRANT_API_KEY: Qdrant API key (Optional)
+"""
+
+import logging
+import os
+import uuid
+from pathlib import Path
+from typing import Literal
+
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from qdrant_client import AsyncQdrantClient
+from qdrant_client import models
+
+from vision_agents.core.rag import RAG, Document
+
+logger = logging.getLogger(__name__)
+
+_DENSE = "dense"
+_SPARSE = "sparse"
+_DEFAULT_DENSE_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+_DEFAULT_SPARSE_MODEL = "Qdrant/bm25"
+
+
+class QdrantRAG(RAG):
+    def __init__(
+        self,
+        collection: str,
+        url: str = "http://localhost:6333",
+        api_key: str | None = None,
+        dense_model: str = _DEFAULT_DENSE_MODEL,
+        sparse_model: str = _DEFAULT_SPARSE_MODEL,
+        chunk_size: int = 10000,
+        chunk_overlap: int = 200,
+        cloud_inference: bool = False,
+    ):
+        self._collection = collection
+        self._client = AsyncQdrantClient(
+            url=url,
+            api_key=api_key or os.environ.get("QDRANT_API_KEY"),
+            cloud_inference=cloud_inference,
+        )
+        self._dense_model = dense_model
+        self._sparse_model = sparse_model
+        self._splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            length_function=len,
+        )
+        self._indexed_files: list[str] = []
+
+    @property
+    def indexed_files(self) -> list[str]:
+        return self._indexed_files
+
+    async def _ensure_collection(self) -> None:
+        if not await self._client.collection_exists(self._collection):
+            await self._client.create_collection(
+                collection_name=self._collection,
+                vectors_config={
+                    _DENSE: models.VectorParams(
+                        size=self._client.get_embedding_size(self._dense_model),
+                        distance=models.Distance.COSINE,
+                    ),
+                },
+                sparse_vectors_config={
+                    _SPARSE: models.SparseVectorParams(
+                        index=models.SparseIndexParams(on_disk=False),
+                    ),
+                },
+            )
+
+    async def add_documents(self, documents: list[Document]) -> int:
+        if not documents:
+            return 0
+
+        all_chunks: list[str] = []
+        chunk_sources: list[tuple[str, int]] = []
+        indexed_sources: list[str] = []
+
+        for doc in documents:
+            chunks = self._splitter.split_text(doc.text)
+            if not chunks:
+                logger.warning(f"No chunks generated from document: {doc.source}")
+                continue
+            for i, chunk in enumerate(chunks):
+                all_chunks.append(chunk)
+                chunk_sources.append((doc.source, i))
+            indexed_sources.append(doc.source)
+
+        if not all_chunks:
+            return 0
+
+        await self._ensure_collection()
+        await self._client.upsert(
+            collection_name=self._collection,
+            points=[
+                models.PointStruct(
+                    id=str(uuid.uuid5(uuid.NAMESPACE_DNS, f"{source}_{idx}")),
+                    vector={
+                        _DENSE: models.Document(text=chunk, model=self._dense_model),
+                        _SPARSE: models.Document(text=chunk, model=self._sparse_model),
+                    },
+                    payload={"text": chunk, "source": source, "chunk_index": idx},
+                )
+                for chunk, (source, idx) in zip(all_chunks, chunk_sources)
+            ],
+        )
+
+        self._indexed_files.extend(indexed_sources)
+        logger.info(f"Indexed {len(all_chunks)} chunks from {len(documents)} documents")
+        return len(all_chunks)
+
+    async def _search_single(
+        self, query: str, using: str, limit: int
+    ) -> list[models.ScoredPoint]:
+        model = self._dense_model if using == _DENSE else self._sparse_model
+        return (
+            await self._client.query_points(
+                collection_name=self._collection,
+                query=models.Document(text=query, model=model),
+                using=using,
+                limit=limit,
+                with_payload=["text", "source"],
+            )
+        ).points
+
+    async def search(
+        self,
+        query: str,
+        top_k: int = 3,
+        mode: Literal["hybrid", "vector", "bm25"] = "hybrid",
+    ) -> str:
+        if not await self._client.collection_exists(self._collection):
+            return "No relevant information found in the knowledge base."
+
+        if mode == "vector":
+            points = await self._search_single(query, _DENSE, top_k)
+        elif mode == "bm25":
+            points = await self._search_single(query, _SPARSE, top_k)
+        else:
+            results = await self._client.query_points(
+                collection_name=self._collection,
+                prefetch=[
+                    models.Prefetch(
+                        query=models.Document(text=query, model=self._dense_model),
+                        using=_DENSE,
+                        limit=top_k,
+                    ),
+                    models.Prefetch(
+                        query=models.Document(text=query, model=self._sparse_model),
+                        using=_SPARSE,
+                        limit=top_k,
+                    ),
+                ],
+                query=models.FusionQuery(fusion=models.Fusion.RRF),
+                limit=top_k,
+                with_payload=["text", "source"],
+            )
+            points = results.points
+
+        if not points:
+            return "No relevant information found in the knowledge base."
+
+        formatted_results = []
+        for i, p in enumerate(points, 1):
+            payload = p.payload or {}
+            formatted_results.append(
+                f"[{i}] From {payload.get('source', 'unknown')}:\n{payload.get('text', '')}"
+            )
+        return "\n\n".join(formatted_results)
+
+    async def clear(self) -> None:
+        if await self._client.collection_exists(self._collection):
+            await self._client.delete_collection(self._collection)
+        self._indexed_files = []
+        logger.info(f"Cleared collection: {self._collection}")
+
+    async def close(self) -> None:
+        await self._client.close()
+
+
+async def create_rag(
+    collection: str,
+    knowledge_dir: str | Path,
+    extensions: list[str] | None = None,
+    url: str = "http://localhost:6333",
+    api_key: str | None = None,
+    dense_model: str = _DEFAULT_DENSE_MODEL,
+    sparse_model: str = _DEFAULT_SPARSE_MODEL,
+    chunk_size: int = 10000,
+    chunk_overlap: int = 200,
+    cloud_inference: bool = False,
+) -> QdrantRAG:
+    rag = QdrantRAG(
+        collection=collection,
+        url=url,
+        api_key=api_key,
+        dense_model=dense_model,
+        sparse_model=sparse_model,
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        cloud_inference=cloud_inference,
+    )
+    try:
+        await rag.add_directory(knowledge_dir, extensions=extensions)
+    except Exception:
+        await rag.close()
+        raise
+    return rag