# Vector Store Client
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/vector-store-client)
Async client for Vector Store API with comprehensive JSON-RPC support. Provides high-level interface for all vector store operations including chunk creation, search, deletion, and system management.
## Features
- **Fully Async**: Built with `asyncio` and `httpx` for high-performance async operations
- **JSON-RPC 2.0**: Complete support for JSON-RPC 2.0 protocol
- **Type Safety**: Full type hints and Pydantic models for data validation
- **Comprehensive API**: Support for all Vector Store operations
- **Error Handling**: Detailed exception hierarchy with meaningful error messages
- **Batch Operations**: Efficient batch processing for large datasets
- **Connection Management**: Automatic connection pooling and retry logic
- **Logging**: Built-in logging for debugging and monitoring
## Installation
```bash
pip install vector-store-client
```
## Quick Start
```python
import asyncio
from vector_store_client import VectorStoreClient, SemanticChunk, ChunkType, LanguageEnum
async def main():
# Create client
client = await VectorStoreClient.create("http://localhost:8007")
# Check server health
health = await client.health_check()
print(f"Server status: {health.status}")
# Create a chunk
chunk = SemanticChunk(
body="Python is a high-level programming language.",
text="Python is a high-level programming language.",
type=ChunkType.DOC_BLOCK,
language=LanguageEnum.EN,
title="Python Introduction"
)
result = await client.create_chunks([chunk])
print(f"Created chunk: {result.uuids[0]}")
# Search chunks
results = await client.search_chunks("programming language", limit=5)
for chunk in results:
print(f"Found: {chunk.title}")
await client.close()
asyncio.run(main())
```
## API Reference
### Client Creation
```python
# Factory method (recommended)
client = await VectorStoreClient.create("http://localhost:8007")
# Direct instantiation
client = VectorStoreClient("http://localhost:8007")
```
### Health and System
```python
# Check server health
health = await client.health_check()
# Get help information
help_info = await client.get_help()
# Get/set configuration
config = await client.get_config("server.version")
await client.set_config("search.limit", 50)
```
### Chunk Operations
```python
# Create chunks
chunks = [
SemanticChunk(
body="Your text content here",
text="Your text content here",
type=ChunkType.DOC_BLOCK,
language=LanguageEnum.EN
)
]
result = await client.create_chunks(chunks)
# Search chunks
results = await client.search_chunks(
search_str="your search query",
metadata_filter={"category": "articles"},
limit=10
)
# Delete chunks
await client.delete_chunks({"type": "temporary"})
```
### Utility Methods
```python
# Create single text chunk
uuid = await client.create_text_chunk(
text="Simple text content",
chunk_type=ChunkType.DOC_BLOCK
)
# Search by text (simplified interface)
results = await client.search_by_text("query", limit=5)
# Find duplicate UUIDs
duplicates = await client.find_duplicate_uuids()
# Force delete by UUIDs
await client.force_delete_by_uuids(["uuid1", "uuid2"])
```
## Data Models
### SemanticChunk
The main data model for chunks with comprehensive metadata:
```python
chunk = SemanticChunk(
# Required fields
body="Original text content",
text="Normalized text for search",
# Auto-generated fields
uuid="auto-generated-uuid",
source_id="auto-generated-source-id",
language=LanguageEnum.EN,
type=ChunkType.DOC_BLOCK,
sha256="auto-generated-hash",
created_at="auto-generated-timestamp",
embedding=[0.1, 0.2, ...], # 384-dimensional vector
# Optional fields
title="Chunk title",
category="Business category",
tags=["tag1", "tag2"],
session_id="session-uuid",
message_id="message-uuid",
summary="Auto-generated summary",
status=ChunkStatus.ACTIVE,
metadata={"custom": "data"}
)
```
### SearchResult
Search results with relevance information:
```python
result = SearchResult(
chunk=SemanticChunk(...),
relevance_score=0.95,
distance=0.05,
rank=1,
highlight="...highlighted text...",
metadata={"search_metadata": "value"}
)
```
## Error Handling
The client provides a comprehensive exception hierarchy:
```python
from vector_store_client.exceptions import (
VectorStoreError, # Base exception
ConnectionError, # Network/connection issues
ValidationError, # Data validation failures
JsonRpcError, # JSON-RPC protocol errors
ServerError, # Server-side errors
NotFoundError, # Resource not found
DuplicateError # Duplicate resource errors
)
try:
await client.create_chunks(chunks)
except ValidationError as e:
print(f"Validation failed: {e.field_errors}")
except ConnectionError as e:
print(f"Connection failed: {e}")
except ServerError as e:
print(f"Server error: {e.server_message}")
```
## Configuration
### Logging
```python
import logging
from vector_store_client.utils import setup_logging
# Setup logging
logger = setup_logging(
level="INFO",
format_string="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
log_file="vector_store.log"
)
# Use with client
client = VectorStoreClient("http://localhost:8007", logger=logger)
```
### Timeouts and Retries
```python
# Custom timeout
client = await VectorStoreClient.create(
"http://localhost:8007",
timeout=60.0
)
# Retry logic is built-in for connection errors
# Custom retry can be implemented using utils.retry_with_backoff
```
## Examples
See the `examples/` directory for usage examples:
- `simple_example.py` - Basic operations (recommended for beginners)
- `working_api_example.py` - Complete API demonstration with real methods
- `advanced_usage.py` - Advanced features and patterns
- `comprehensive_api_example.py` - Legacy example (may contain non-working methods)
## Development
### Installation
```bash
git clone https://github.com/vasilyvz/vector_store_client.git
cd vector_store_client
pip install -e .
```
### Testing
```bash
# Run tests
pytest
# Run with coverage
pytest --cov=vector_store_client
# Run specific test file
pytest tests/test_client.py
```
### Code Quality
```bash
# Format code
black vector_store_client/
# Sort imports
isort vector_store_client/
# Type checking
mypy vector_store_client/
# Linting
flake8 vector_store_client/
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Vasily Zdanovskiy**
- Email: vasilyvz@gmail.com
- GitHub: [@vasilyvz](https://github.com/vasilyvz)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.
## Support
- **Issues**: [GitHub Issues](https://github.com/vasilyvz/vector_store_client/issues)
- **Documentation**: [GitHub Wiki](https://github.com/vasilyvz/vector_store_client/wiki)
- **Email**: vasilyvz@gmail.com
Raw data
{
"_id": null,
"home_page": "https://github.com/vector-store/vector_store_client",
"name": "vector-store-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "vector-store, semantic-search, embeddings, json-rpc, async",
"author": "Vasily Zdanovskiy",
"author_email": "Vasily Zdanovskiy <vasilyvz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/78/9f/6f4b3c693dba29fe9bd265bbd736dbb98be0fe8f3c5750c828c541043f41/vector_store_client-2.0.0.2.tar.gz",
"platform": null,
"description": "# Vector Store Client\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/vector-store-client)\n\nAsync client for Vector Store API with comprehensive JSON-RPC support. Provides high-level interface for all vector store operations including chunk creation, search, deletion, and system management.\n\n## Features\n\n- **Fully Async**: Built with `asyncio` and `httpx` for high-performance async operations\n- **JSON-RPC 2.0**: Complete support for JSON-RPC 2.0 protocol\n- **Type Safety**: Full type hints and Pydantic models for data validation\n- **Comprehensive API**: Support for all Vector Store operations\n- **Error Handling**: Detailed exception hierarchy with meaningful error messages\n- **Batch Operations**: Efficient batch processing for large datasets\n- **Connection Management**: Automatic connection pooling and retry logic\n- **Logging**: Built-in logging for debugging and monitoring\n\n## Installation\n\n```bash\npip install vector-store-client\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom vector_store_client import VectorStoreClient, SemanticChunk, ChunkType, LanguageEnum\n\nasync def main():\n # Create client\n client = await VectorStoreClient.create(\"http://localhost:8007\")\n \n # Check server health\n health = await client.health_check()\n print(f\"Server status: {health.status}\")\n \n # Create a chunk\n chunk = SemanticChunk(\n body=\"Python is a high-level programming language.\",\n text=\"Python is a high-level programming language.\",\n type=ChunkType.DOC_BLOCK,\n language=LanguageEnum.EN,\n title=\"Python Introduction\"\n )\n \n result = await client.create_chunks([chunk])\n print(f\"Created chunk: {result.uuids[0]}\")\n \n # Search chunks\n results = await client.search_chunks(\"programming language\", limit=5)\n for chunk in results:\n print(f\"Found: {chunk.title}\")\n \n await client.close()\n\nasyncio.run(main())\n```\n\n## API Reference\n\n### Client Creation\n\n```python\n# Factory method (recommended)\nclient = await VectorStoreClient.create(\"http://localhost:8007\")\n\n# Direct instantiation\nclient = VectorStoreClient(\"http://localhost:8007\")\n```\n\n### Health and System\n\n```python\n# Check server health\nhealth = await client.health_check()\n\n# Get help information\nhelp_info = await client.get_help()\n\n# Get/set configuration\nconfig = await client.get_config(\"server.version\")\nawait client.set_config(\"search.limit\", 50)\n```\n\n### Chunk Operations\n\n```python\n# Create chunks\nchunks = [\n SemanticChunk(\n body=\"Your text content here\",\n text=\"Your text content here\",\n type=ChunkType.DOC_BLOCK,\n language=LanguageEnum.EN\n )\n]\nresult = await client.create_chunks(chunks)\n\n# Search chunks\nresults = await client.search_chunks(\n search_str=\"your search query\",\n metadata_filter={\"category\": \"articles\"},\n limit=10\n)\n\n# Delete chunks\nawait client.delete_chunks({\"type\": \"temporary\"})\n```\n\n### Utility Methods\n\n```python\n# Create single text chunk\nuuid = await client.create_text_chunk(\n text=\"Simple text content\",\n chunk_type=ChunkType.DOC_BLOCK\n)\n\n# Search by text (simplified interface)\nresults = await client.search_by_text(\"query\", limit=5)\n\n# Find duplicate UUIDs\nduplicates = await client.find_duplicate_uuids()\n\n# Force delete by UUIDs\nawait client.force_delete_by_uuids([\"uuid1\", \"uuid2\"])\n```\n\n## Data Models\n\n### SemanticChunk\n\nThe main data model for chunks with comprehensive metadata:\n\n```python\nchunk = SemanticChunk(\n # Required fields\n body=\"Original text content\",\n text=\"Normalized text for search\",\n \n # Auto-generated fields\n uuid=\"auto-generated-uuid\",\n source_id=\"auto-generated-source-id\",\n language=LanguageEnum.EN,\n type=ChunkType.DOC_BLOCK,\n sha256=\"auto-generated-hash\",\n created_at=\"auto-generated-timestamp\",\n embedding=[0.1, 0.2, ...], # 384-dimensional vector\n \n # Optional fields\n title=\"Chunk title\",\n category=\"Business category\",\n tags=[\"tag1\", \"tag2\"],\n session_id=\"session-uuid\",\n message_id=\"message-uuid\",\n summary=\"Auto-generated summary\",\n status=ChunkStatus.ACTIVE,\n metadata={\"custom\": \"data\"}\n)\n```\n\n### SearchResult\n\nSearch results with relevance information:\n\n```python\nresult = SearchResult(\n chunk=SemanticChunk(...),\n relevance_score=0.95,\n distance=0.05,\n rank=1,\n highlight=\"...highlighted text...\",\n metadata={\"search_metadata\": \"value\"}\n)\n```\n\n## Error Handling\n\nThe client provides a comprehensive exception hierarchy:\n\n```python\nfrom vector_store_client.exceptions import (\n VectorStoreError, # Base exception\n ConnectionError, # Network/connection issues\n ValidationError, # Data validation failures\n JsonRpcError, # JSON-RPC protocol errors\n ServerError, # Server-side errors\n NotFoundError, # Resource not found\n DuplicateError # Duplicate resource errors\n)\n\ntry:\n await client.create_chunks(chunks)\nexcept ValidationError as e:\n print(f\"Validation failed: {e.field_errors}\")\nexcept ConnectionError as e:\n print(f\"Connection failed: {e}\")\nexcept ServerError as e:\n print(f\"Server error: {e.server_message}\")\n```\n\n## Configuration\n\n### Logging\n\n```python\nimport logging\nfrom vector_store_client.utils import setup_logging\n\n# Setup logging\nlogger = setup_logging(\n level=\"INFO\",\n format_string=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\",\n log_file=\"vector_store.log\"\n)\n\n# Use with client\nclient = VectorStoreClient(\"http://localhost:8007\", logger=logger)\n```\n\n### Timeouts and Retries\n\n```python\n# Custom timeout\nclient = await VectorStoreClient.create(\n \"http://localhost:8007\",\n timeout=60.0\n)\n\n# Retry logic is built-in for connection errors\n# Custom retry can be implemented using utils.retry_with_backoff\n```\n\n## Examples\n\nSee the `examples/` directory for usage examples:\n\n- `simple_example.py` - Basic operations (recommended for beginners)\n- `working_api_example.py` - Complete API demonstration with real methods\n- `advanced_usage.py` - Advanced features and patterns\n- `comprehensive_api_example.py` - Legacy example (may contain non-working methods)\n\n## Development\n\n### Installation\n\n```bash\ngit clone https://github.com/vasilyvz/vector_store_client.git\ncd vector_store_client\npip install -e .\n```\n\n### Testing\n\n```bash\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=vector_store_client\n\n# Run specific test file\npytest tests/test_client.py\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack vector_store_client/\n\n# Sort imports\nisort vector_store_client/\n\n# Type checking\nmypy vector_store_client/\n\n# Linting\nflake8 vector_store_client/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Vasily Zdanovskiy**\n- Email: vasilyvz@gmail.com\n- GitHub: [@vasilyvz](https://github.com/vasilyvz)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/vasilyvz/vector_store_client/issues)\n- **Documentation**: [GitHub Wiki](https://github.com/vasilyvz/vector_store_client/wiki)\n- **Email**: vasilyvz@gmail.com \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Async client for Vector Store API with comprehensive JSON-RPC support",
"version": "2.0.0.2",
"project_urls": {
"Changelog": "https://github.com/vasilyvz/vector_store_client/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/vasilyvz/vector_store_client/docs",
"Homepage": "https://github.com/vasilyvz/vector_store_client",
"Issues": "https://github.com/vasilyvz/vector_store_client/issues",
"Repository": "https://github.com/vasilyvz/vector_store_client.git"
},
"split_keywords": [
"vector-store",
" semantic-search",
" embeddings",
" json-rpc",
" async"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "89ca3b7f539d3e773763e0d0d9d1900db68939791ab2847af0f0267c79902fc2",
"md5": "a4672895bd85a7555ceca79ad88162c3",
"sha256": "e7a984a978495292e769aa9eb142702053c84f333e02122139828e9e26d08543"
},
"downloads": -1,
"filename": "vector_store_client-2.0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4672895bd85a7555ceca79ad88162c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 166186,
"upload_time": "2025-08-13T11:47:26",
"upload_time_iso_8601": "2025-08-13T11:47:26.330925Z",
"url": "https://files.pythonhosted.org/packages/89/ca/3b7f539d3e773763e0d0d9d1900db68939791ab2847af0f0267c79902fc2/vector_store_client-2.0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "789f6f4b3c693dba29fe9bd265bbd736dbb98be0fe8f3c5750c828c541043f41",
"md5": "74a02407064736bd995b18a3e052ea9e",
"sha256": "db1fb9a24f184b1ed0acb69d77d084dd78761a4ebdca29f3d9b1d1bd5a562160"
},
"downloads": -1,
"filename": "vector_store_client-2.0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "74a02407064736bd995b18a3e052ea9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 322833,
"upload_time": "2025-08-13T11:47:28",
"upload_time_iso_8601": "2025-08-13T11:47:28.204986Z",
"url": "https://files.pythonhosted.org/packages/78/9f/6f4b3c693dba29fe9bd265bbd736dbb98be0fe8f3c5750c828c541043f41/vector_store_client-2.0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 11:47:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vector-store",
"github_project": "vector_store_client",
"github_not_found": true,
"lcname": "vector-store-client"
}
JSON
