simplevecdb 1.0.0__tar.gz

simplevecdb-1.0.0/.env.example

@@ -0,0 +1,32 @@
+# SimpleVecDB Configuration
+
+# Embedding Model
+# Options: Any HuggingFace model ID compatible with SentenceTransformers
+
+# Default: Snowflake/snowflake-arctic-embed-xs (384-dim, best balance, fast)
+# Alternative: TaylorAI/bge-micro-v2 (384-dim, tiny, fast)
+
+# Note: All models converted to ONNX format for performance.
+
+EMBEDDING_MODEL=Snowflake/snowflake-arctic-embed-xs
+EMBEDDING_CACHE_DIR=~/.cache/simplevecdb  # Model cache directory
+# Optional: alias registry for allowed models (alias=repo_id,comma-separated)
+# EMBEDDING_MODEL_REGISTRY=default=Snowflake/snowflake-arctic-embed-xs,local-bge=TaylorAI/bge-micro-v2
+# Set to 0 to allow arbitrary repo IDs (default is locked)
+# EMBEDDING_MODEL_REGISTRY_LOCKED=1
+
+# Batch size for embedding inference (optional - auto-detected if not set)
+# Auto-detection considers: GPU VRAM, Apple Silicon, CPU cores, architecture
+# Override only if you need specific batch size for your use case
+# EMBEDDING_BATCH_SIZE=256
+
+# Embedding server controls
+# EMBEDDING_SERVER_MAX_REQUEST_ITEMS=128  # Max prompts per /v1/embeddings call
+# EMBEDDING_SERVER_API_KEYS=local-dev-token
+
+# Database
+DATABASE_PATH=./data/simplevecdb.db
+
+# Server Configuration
+SERVER_HOST=0.0.0.0
+SERVER_PORT=53287

simplevecdb-1.0.0/.github/FUNDING.yml

@@ -0,0 +1,6 @@
+github: [coderdayton]
+custom:
+  [
+    "https://simplevecdb.lemonsqueezy.com/",
+    "https://buymeacoffee.com/coderdayton",
+  ]

simplevecdb-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Test with pytest
+        run: uv run pytest tests/ -vv --cov=src/simplevecdb
+
+      - name: Check coverage
+        run: |
+          uv run coverage report -m --fail-under=90

simplevecdb-1.0.0/.github/workflows/update-sponsors.yml

@@ -0,0 +1,27 @@
+name: Update Sponsors
+on:
+  schedule:
+    - cron: "0 0 * * *" # daily
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Update Sponsors ❤️
+        uses: JamesIves/github-sponsors-readme-action@v1
+        with:
+          file: README.md
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Commit changes 📝
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git commit -m "Update sponsors list" || echo "No changes to commit"
+          git push origin HEAD:main

simplevecdb-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python / uv
+.venv/
+__pycache__/
+*.pyc
+.env
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Databases
+*.db
+*.sqlite
+
+# Project specific
+simplevecdb_plan.md
+AGENTS.md
+htmlcov/
+site/
+scripts
+.coverage
+README_OLD.md

simplevecdb-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff
+        entry: uv run ruff check . --fix
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy .
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest-cov
+        name: pytest coverage
+        entry: uv run pytest tests/ -vv --cov=src/simplevecdb
+        language: system
+        types: [python]
+        pass_filenames: false

simplevecdb-1.0.0/.python-version

@@ -0,0 +1 @@
+3.10

simplevecdb-1.0.0/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to SimpleVecDB 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).
+
+## [1.0.0] - 11-23-2025
+
+### 🎉 Initial Release
+
+SimpleVecDB's first stable release brings production-ready local vector search to a single SQLite file.
+
+### Added
+
+#### Core Features
+
+- **Multi-collection catalog system**: Organize documents in named collections within a single database
+- **Vector search**: Cosine, L2 (Euclidean), and L1 (Manhattan) distance metrics
+- **Quantization**: FLOAT32, INT8 (4x compression), and BIT (32x compression) support
+- **Metadata filtering**: JSON-based filtering with SQL `WHERE` clauses
+- **Batch processing**: Automatic batching for efficient bulk operations
+- **Persistence**: Single `.db` file with WAL mode for concurrent reads
+
+#### Hybrid Search
+
+- **BM25 keyword search**: Full-text search using SQLite FTS5
+- **Hybrid search**: Reciprocal Rank Fusion combining BM25 + vector similarity
+- **Query vector reuse**: Pass pre-computed embeddings to avoid redundant embedding calls
+- **Metadata filtering**: Works across all search modes (vector, keyword, hybrid)
+
+#### Embeddings Server
+
+- **OpenAI-compatible API**: `/v1/embeddings` endpoint for local embedding generation
+- **Model registry**: Configure allowed models or allow arbitrary HuggingFace repos
+- **Request limits**: Configurable max batch size per request
+- **API key authentication**: Optional Bearer token / X-API-Key authentication
+- **Usage tracking**: Per-key request and token metrics via `/v1/usage`
+- **Model listing**: `/v1/models` endpoint for registry inspection
+- **ONNX optimization**: Quantized ONNX runtime for fast CPU inference
+
+#### Hardware Optimization
+
+- **Auto-detection**: Automatically detects CUDA GPUs, Apple Silicon (MPS), ROCm, and CPU
+- **Adaptive batching**: Optimal batch sizes based on:
+  - NVIDIA GPUs: 64-512 (scaled by VRAM 4GB-24GB+)
+  - AMD GPUs: 256 (ROCm)
+  - Apple Silicon: 32-128 (M1/M2 vs M3/M4, base vs Max/Ultra)
+  - ARM CPUs: 4-16 (mobile, Raspberry Pi, servers)
+  - x86 CPUs: 8-64 (scaled by core count)
+- **Manual override**: `EMBEDDING_BATCH_SIZE` environment variable
+
+#### Integrations
+
+- **LangChain**: `SimpleVecDBVectorStore` with async support and MMR
+  - `similarity_search`, `similarity_search_with_score`
+  - `max_marginal_relevance_search`
+  - `keyword_search`, `hybrid_search`
+  - `add_texts`, `add_documents`, `delete`
+- **LlamaIndex**: `SimpleVecDBLlamaStore` with query mode support
+  - `VectorStoreQueryMode.DEFAULT` (dense vector)
+  - `VectorStoreQueryMode.SPARSE` / `TEXT_SEARCH` (BM25)
+  - `VectorStoreQueryMode.HYBRID` / `SEMANTIC_HYBRID` (fusion)
+  - Metadata filtering across all modes
+
+#### Examples & Documentation
+
+- **RAG notebooks**: LangChain, LlamaIndex, and Ollama integration examples
+- **Performance benchmarks**: Insertion speed, query latency, storage efficiency
+- **API documentation**: Full class and method reference via MkDocs
+- **Setup guide**: Environment variables and configuration options
+- **Contributing guide**: Development setup and testing instructions
+
+### Configuration
+
+- `EMBEDDING_MODEL`: HuggingFace model ID (default: `Snowflake/snowflake-arctic-embed-xs`)
+- `EMBEDDING_CACHE_DIR`: Model cache directory (default: `~/.cache/simplevecdb`)
+- `EMBEDDING_MODEL_REGISTRY`: Comma-separated `alias=repo_id` entries
+- `EMBEDDING_MODEL_REGISTRY_LOCKED`: Enforce registry allowlist (default: `1`)
+- `EMBEDDING_BATCH_SIZE`: Inference batch size (auto-detected if not set)
+- `EMBEDDING_SERVER_MAX_REQUEST_ITEMS`: Max prompts per `/v1/embeddings` call
+- `EMBEDDING_SERVER_API_KEYS`: Comma-separated API keys for authentication
+- `DATABASE_PATH`: SQLite database path (default: `:memory:`)
+- `SERVER_HOST`: Embeddings server host (default: `0.0.0.0`)
+- `SERVER_PORT`: Embeddings server port (default: `8000`)
+
+### Performance
+
+Benchmarks on i9-13900K & RTX 4090 with 10k vectors (384-dim):
+
+| Quantization | Storage  | Insert Speed | Query Time (k=10) |
+| ------------ | -------- | ------------ | ----------------- |
+| FLOAT32      | 15.50 MB | 15,585 vec/s | 3.55 ms           |
+| INT8         | 4.23 MB  | 27,893 vec/s | 3.93 ms           |
+| BIT          | 0.95 MB  | 32,321 vec/s | 0.27 ms           |
+
+### Testing
+
+- 177 unit and integration tests
+- 97% code coverage
+- Type-safe (mypy strict mode)
+- CI/CD on Python 3.10, 3.11, 3.12, 3.13
+
+### Dependencies
+
+- Core: `sqlite-vec>=0.1.6`, `numpy>=2.0`, `python-dotenv>=1.2.1`, `psutil>=5.9.0`
+- Server extras: `fastapi>=0.115`, `uvicorn[standard]>=0.30`, `sentence-transformers[onnx]==3.3.1`
+
+### Notes
+
+- Requires SQLite builds with FTS5 enabled for keyword/hybrid search (bundled with Python 3.10+)
+- Works on Linux, macOS, Windows, and WASM environments
+- Zero external dependencies beyond Python for core functionality
+
+---
+
+## Links
+
+- **GitHub**: https://github.com/coderdayton/simplevecdb
+- **PyPI**: https://pypi.org/project/simplevecdb/
+- **Documentation**: https://coderdayton.github.io/simplevecdb/
+- **License**: MIT
+
+[1.0.0]: https://github.com/coderdayton/simplevecdb/releases/tag/v1.0.0

simplevecdb-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,174 @@
+# Contributing to SimpleVecDB
+
+Thanks for considering a contribution to SimpleVecDB; your help steadily improves this local-first vector database.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- `uv` (recommended) or `pip`
+- Git
+
+### Local Setup
+
+```bash
+git clone https://github.com/coderdayton/simplevecdb.git
+cd simplevecdb
+
+# Install dependencies with development tools
+uv sync
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+### Project Structure
+
+```
+simplevecdb/
+├── src/simplevecdb/
+│   ├── core.py              # Main VectorDB class
+│   ├── types.py             # Document, DistanceStrategy types
+│   ├── config.py            # Configuration management
+│   ├── embeddings/
+│   │   ├── models.py        # Local embedding models
+│   │   └── server.py        # FastAPI embedding server
+│   └── integrations/
+│       ├── langchain.py     # LangChain VectorStore wrapper
+│       └── llamaindex.py    # LlamaIndex VectorStore wrapper
+├── tests/                   # Unit, integration and performance tests
+├── examples/                # RAG notebooks, demos
+└── docs/                    # Documentation
+```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# All tests
+pytest
+
+# With coverage
+pytest --cov=simplevecdb
+
+# Specific test file
+pytest tests/unit/test_search.py
+```
+
+### Code Style
+
+- Follow PEP 8 standards
+- Use type hints wherever possible (Python 3.10+ syntax: `list[str]` instead of `List[str]`)
+- Run a linter (consider using `ruff` or `black`)
+
+### Making Changes
+
+1. **Create a feature branch**
+
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Make your changes** and commit with clear messages
+
+   ```bash
+   git commit -m "feat: add cool feature" # or fix:, docs:, etc.
+   ```
+
+3. **Add/update tests** for any new functionality
+
+4. **Run tests locally** to ensure nothing breaks
+
+5. **Submit a pull request** with a clear description
+
+## Areas for Contribution
+
+### High Priority
+
+- **HNSW indexing**: Faster approximate nearest neighbor search (waiting on sqlite-vec)
+- **Advanced Metadata filtering**: Complex WHERE clause support (OR, nested queries)
+- **Documentation**: Docstrings, guides, API docs
+
+### Medium Priority
+
+- **Custom Quantization**: Support for custom quantization tables/centroids
+- **Performance benchmarks**: Add more comprehensive benchmarks (1M+ vectors)
+- **Integration tests**: Expand test coverage for LangChain/LlamaIndex
+
+### Lower Priority
+
+- **GUI**: Desktop app (Tauri-based)
+- **Encryption**: SQLCipher integration
+- **Analytics**: Query performance monitoring
+
+## Testing Guidelines
+
+- Write tests for all new features
+- Ensure tests pass locally before submitting PR
+- Aim for >80% code coverage
+- Test edge cases (empty vectors, large datasets, etc.)
+
+Example test structure:
+
+```python
+def test_similarity_search_with_k():
+    db = VectorDB(":memory:")
+    collection = db.collection("default")
+    collection.add_texts(["doc1", "doc2", "doc3"])
+    results = collection.similarity_search("query", k=2)
+    assert len(results) == 2
+    assert all(isinstance(score, float) for _, score in results)
+```
+
+## Documentation
+
+- Update docstrings for any API changes
+- Add examples in the `examples/` directory for new features
+- Update README.md if adding major features
+- Use type hints to make APIs self-documenting
+
+## Performance Considerations
+
+- SimpleVecDB prioritizes simplicity over maximum performance
+- Benchmark large-scale operations (10k+ vectors)
+- Use NumPy efficiently for vector operations
+- Minimize database round-trips
+
+## Debugging
+
+Enable verbose logging:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+Run the embedding server locally for testing:
+
+```bash
+simplevecdb-server
+# Server runs at http://localhost:53287 by default
+```
+
+## Submitting a Pull Request
+
+1. Ensure all tests pass: `pytest`
+2. Keep commits clean and focused
+3. Write a clear PR description explaining:
+   - What problem does it solve?
+   - How does it work?
+   - Any breaking changes?
+4. Link any related issues
+5. Be patient — we'll review as soon as we can!
+
+## Questions?
+
+- Open a GitHub issue for bugs or feature requests
+- Reach out to [@coderdayton](https://github.com/coderdayton) on GitHub
+- Check existing issues before filing a duplicate
+
+---
+
+**Thank you for contributing!** Every bit helps make SimpleVecDB better for everyone. 🚀

simplevecdb-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dayton Dunbar
+
+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.