vectrixdb 1.0.0__tar.gz

vectrixdb-1.0.0/.gitattributes

@@ -0,0 +1 @@
+*.onnx filter=lfs diff=lfs merge=lfs -text

vectrixdb-1.0.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+.venv/
+env/
+.env
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Database files
+*.db
+*.db-shm
+*.db-wal
+*.usearch
+*.hnsw
+vectrixdb_data/
+example_data/
+test_data/
+
+# Jupyter checkpoints
+.ipynb_checkpoints/
+
+# Downloaded multilingual models (exclude from repo, download from GitHub releases)
+vectrixdb/models/data/dense/
+vectrixdb/models/data/reranker/
+vectrixdb/models/data/bge-m3/
+vectrixdb/models/data/rebel/
+releases/
+
+# English models are BUNDLED (do NOT exclude):
+# - vectrixdb/models/data/dense_en/
+# - vectrixdb/models/data/reranker_en/
+# - vectrixdb/models/data/colbert/
+# - vectrixdb/models/data/sparse/
+
+# Node
+node_modules/
+dashboard/dist/
+dashboard/.cache/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Misc
+*.bak
+*.tmp

vectrixdb-1.0.0/LICENSE

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

vectrixdb-1.0.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: vectrixdb
+Version: 1.0.0
+Summary: Where vectors come alive - A lightweight, visual-first vector database with embedded ML models
+Project-URL: Homepage, https://github.com/knowusuboaky/VectrixDB
+Project-URL: Documentation, https://github.com/knowusuboaky/VectrixDB#readme
+Project-URL: Repository, https://github.com/knowusuboaky/VectrixDB
+Author-email: Kwadwo Daddy Nyame Owusu - Boakye <kwadwo.owusuboakye@outlook.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai,approximate-nearest-neighbors,embeddings,hnsw,machine-learning,similarity-search,vector-database
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: onnxruntime>=1.15.0
+Requires-Dist: orjson>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tokenizers>=0.15.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: usearch>=2.0.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: all
+Requires-Dist: black>=23.0.0; extra == 'all'
+Requires-Dist: fastembed>=0.2.0; extra == 'all'
+Requires-Dist: mypy>=1.0.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
+Requires-Dist: pytest>=7.0.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.3.0; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
+Requires-Dist: umap-learn>=0.5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: fastembed>=0.2.0; extra == 'embeddings'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
+Provides-Extra: fastembed
+Requires-Dist: fastembed>=0.2.0; extra == 'fastembed'
+Provides-Extra: hf
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'hf'
+Provides-Extra: setup-models
+Requires-Dist: optimum[onnxruntime]>=1.12.0; extra == 'setup-models'
+Requires-Dist: torch>=2.0.0; extra == 'setup-models'
+Requires-Dist: transformers>=4.30.0; extra == 'setup-models'
+Provides-Extra: viz
+Requires-Dist: scikit-learn>=1.3.0; extra == 'viz'
+Requires-Dist: umap-learn>=0.5.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# VectrixDB
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python Versions](https://img.shields.io/pypi/pyversions/vectrixdb.svg)](https://pypi.org/project/vectrixdb/)
+[![VectrixDB Version](https://img.shields.io/pypi/v/vectrixdb.svg)](https://pypi.org/project/vectrixdb/)
+[![Downloads](https://pepy.tech/badge/vectrixdb)](https://pepy.tech/project/vectrixdb)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/knowusuboaky/VectrixDB/main.yml)](https://github.com/knowusuboaky/VectrixDB/actions)
+[![Issues](https://img.shields.io/github/issues/knowusuboaky/VectrixDB)](https://github.com/knowusuboaky/VectrixDB/issues)
+[![Contact](https://img.shields.io/badge/Email-Contact-green.svg)](mailto:kwadwo.owusuboakye@outlook.com)
+
+**Where vectors come alive.**
+
+A lightweight, visual-first vector database with embedded ML models - no API keys required.
+
+## Why VectrixDB?
+
+| Feature | VectrixDB | Qdrant | Chroma | Pinecone |
+|---------|-----------|--------|--------|----------|
+| Beautiful Dashboard | Yes | Basic | No | No |
+| Embedded ML Models | Yes | No | No | No |
+| 4 Search Tiers | Yes | No | No | No |
+| GraphRAG Built-in | Yes | No | No | No |
+| Zero Config | Yes | No | Yes | Yes |
+| No API Keys Needed | Yes | Yes | No | No |
+| Open Source | Yes | Yes | Yes | No |
+
+## Quick Start
+
+```bash
+pip install vectrixdb
+```
+
+```python
+from vectrixdb import Vectrix
+
+# Create database with hybrid search (uses bundled English models)
+db = Vectrix("my_docs", tier="hybrid", language="en")
+
+# Add documents
+db.add([
+    "Python is great for data science",
+    "JavaScript powers the web",
+    "Rust is known for memory safety"
+])
+
+# Search
+results = db.search("programming languages")
+print(results.top.text)  # Best match
+```
+
+## 4-Tier System
+
+| Tier | Features | Use Case |
+|------|----------|----------|
+| **dense** | Vector similarity | Fast semantic search |
+| **hybrid** | + BM25 sparse | Better keyword matching |
+| **ultimate** | + ColBERT late interaction | Maximum accuracy |
+| **graph** | + Knowledge graph | Complex reasoning (GraphRAG) |
+
+```python
+# Dense tier (fastest)
+db = Vectrix("docs", tier="dense")
+
+# Hybrid tier (balanced)
+db = Vectrix("docs", tier="hybrid")
+
+# Ultimate tier (best quality)
+db = Vectrix("docs", tier="ultimate")
+
+# Graph tier (GraphRAG)
+db = Vectrix("docs", tier="graph")
+```
+
+## Search Modes
+
+```python
+# Dense - vector similarity
+results = db.search("AI", mode="dense")
+
+# Sparse - BM25 keyword
+results = db.search("machine learning", mode="sparse")
+
+# Hybrid - combined
+results = db.search("neural networks", mode="hybrid")
+
+# Rerank - with cross-encoder
+results = db.search("deep learning", mode="rerank")
+```
+
+## With Metadata
+
+```python
+db.add(
+    texts=["iPhone 15", "Galaxy S24", "Pixel 8"],
+    metadata=[
+        {"brand": "Apple", "price": 999},
+        {"brand": "Samsung", "price": 899},
+        {"brand": "Google", "price": 699}
+    ]
+)
+
+# Filter by metadata
+results = db.search("smartphone", filter={"brand": "Apple"})
+```
+
+## Embedded Models
+
+VectrixDB bundles English models (~386MB) - no downloads needed:
+
+| Model | Purpose | Size |
+|-------|---------|------|
+| e5-small-v2 | Dense embeddings | 129MB |
+| ms-marco-MiniLM | Reranking | 129MB |
+| answerai-colbert-small | Late interaction | 129MB |
+| BM25 vocab | Sparse search | 17KB |
+
+### Multilingual Models (auto-download)
+
+For 100+ languages, models download from GitHub on first use:
+
+```python
+# Multilingual (downloads ~450MB on first use)
+db = Vectrix("docs", tier="hybrid")  # or language="multi"
+
+# English only (bundled, no download)
+db = Vectrix("docs", tier="hybrid", language="en")
+```
+
+| Model | Purpose | Languages |
+|-------|---------|-----------|
+| multilingual-e5-small | Dense | 100+ |
+| mmarco-mMiniLMv2 | Reranking | 15+ |
+| BGE-M3 | Late interaction | 100+ |
+| mREBEL | GraphRAG extraction | 18 |
+
+## REST API & Dashboard
+
+```bash
+# Start server
+VECTRIXDB_API_KEY=your_key vectrixdb serve --port 7337
+
+# Open dashboard
+# http://localhost:7337/dashboard
+```
+
+```bash
+# Create collection
+curl -X POST http://localhost:7337/api/v1/collections \
+  -H "api-key: your_key" \
+  -d '{"name": "docs", "dimension": 384}'
+
+# Add with auto-embedding
+curl -X POST http://localhost:7337/api/v1/collections/docs/text-upsert \
+  -H "api-key: your_key" \
+  -d '{"points": [{"id": "1", "text": "Hello world"}]}'
+
+# Search
+curl -X POST http://localhost:7337/api/v1/collections/docs/text-search \
+  -H "api-key: your_key" \
+  -d '{"query_text": "greeting", "limit": 10}'
+```
+
+## Project Structure
+
+```
+VectrixDB/
+├── vectrixdb/
+│   ├── core/           # Vector index, storage, search
+│   │   ├── graphrag/   # Knowledge graph
+│   │   └── search/     # Search algorithms
+│   ├── api/            # FastAPI server
+│   ├── models/         # Embedded ONNX models
+│   │   └── data/       # Bundled English models
+│   ├── dashboard/      # Web UI
+│   └── cli.py          # Command line
+├── tests/              # Jupyter notebooks
+└── requirements.txt
+```
+
+## Installation from Source
+
+```bash
+git clone https://github.com/knowusuboaky/VectrixDB.git
+cd VectrixDB
+pip install -e .
+```
+
+## Requirements
+
+- Python 3.9+
+- No external API keys
+- Models bundled or auto-downloaded
+
+## License
+
+Apache 2.0
+
+## Author
+
+**Kwadwo Daddy Nyame Owusu - Boakye**
+
+GitHub: [@knowusuboaky](https://github.com/knowusuboaky)
+
+---
+
+*Where vectors come alive.*

vectrixdb-1.0.0/README.md

@@ -0,0 +1,206 @@
+# VectrixDB
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python Versions](https://img.shields.io/pypi/pyversions/vectrixdb.svg)](https://pypi.org/project/vectrixdb/)
+[![VectrixDB Version](https://img.shields.io/pypi/v/vectrixdb.svg)](https://pypi.org/project/vectrixdb/)
+[![Downloads](https://pepy.tech/badge/vectrixdb)](https://pepy.tech/project/vectrixdb)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/knowusuboaky/VectrixDB/main.yml)](https://github.com/knowusuboaky/VectrixDB/actions)
+[![Issues](https://img.shields.io/github/issues/knowusuboaky/VectrixDB)](https://github.com/knowusuboaky/VectrixDB/issues)
+[![Contact](https://img.shields.io/badge/Email-Contact-green.svg)](mailto:kwadwo.owusuboakye@outlook.com)
+
+**Where vectors come alive.**
+
+A lightweight, visual-first vector database with embedded ML models - no API keys required.
+
+## Why VectrixDB?
+
+| Feature | VectrixDB | Qdrant | Chroma | Pinecone |
+|---------|-----------|--------|--------|----------|
+| Beautiful Dashboard | Yes | Basic | No | No |
+| Embedded ML Models | Yes | No | No | No |
+| 4 Search Tiers | Yes | No | No | No |
+| GraphRAG Built-in | Yes | No | No | No |
+| Zero Config | Yes | No | Yes | Yes |
+| No API Keys Needed | Yes | Yes | No | No |
+| Open Source | Yes | Yes | Yes | No |
+
+## Quick Start
+
+```bash
+pip install vectrixdb
+```
+
+```python
+from vectrixdb import Vectrix
+
+# Create database with hybrid search (uses bundled English models)
+db = Vectrix("my_docs", tier="hybrid", language="en")
+
+# Add documents
+db.add([
+    "Python is great for data science",
+    "JavaScript powers the web",
+    "Rust is known for memory safety"
+])
+
+# Search
+results = db.search("programming languages")
+print(results.top.text)  # Best match
+```
+
+## 4-Tier System
+
+| Tier | Features | Use Case |
+|------|----------|----------|
+| **dense** | Vector similarity | Fast semantic search |
+| **hybrid** | + BM25 sparse | Better keyword matching |
+| **ultimate** | + ColBERT late interaction | Maximum accuracy |
+| **graph** | + Knowledge graph | Complex reasoning (GraphRAG) |
+
+```python
+# Dense tier (fastest)
+db = Vectrix("docs", tier="dense")
+
+# Hybrid tier (balanced)
+db = Vectrix("docs", tier="hybrid")
+
+# Ultimate tier (best quality)
+db = Vectrix("docs", tier="ultimate")
+
+# Graph tier (GraphRAG)
+db = Vectrix("docs", tier="graph")
+```
+
+## Search Modes
+
+```python
+# Dense - vector similarity
+results = db.search("AI", mode="dense")
+
+# Sparse - BM25 keyword
+results = db.search("machine learning", mode="sparse")
+
+# Hybrid - combined
+results = db.search("neural networks", mode="hybrid")
+
+# Rerank - with cross-encoder
+results = db.search("deep learning", mode="rerank")
+```
+
+## With Metadata
+
+```python
+db.add(
+    texts=["iPhone 15", "Galaxy S24", "Pixel 8"],
+    metadata=[
+        {"brand": "Apple", "price": 999},
+        {"brand": "Samsung", "price": 899},
+        {"brand": "Google", "price": 699}
+    ]
+)
+
+# Filter by metadata
+results = db.search("smartphone", filter={"brand": "Apple"})
+```
+
+## Embedded Models
+
+VectrixDB bundles English models (~386MB) - no downloads needed:
+
+| Model | Purpose | Size |
+|-------|---------|------|
+| e5-small-v2 | Dense embeddings | 129MB |
+| ms-marco-MiniLM | Reranking | 129MB |
+| answerai-colbert-small | Late interaction | 129MB |
+| BM25 vocab | Sparse search | 17KB |
+
+### Multilingual Models (auto-download)
+
+For 100+ languages, models download from GitHub on first use:
+
+```python
+# Multilingual (downloads ~450MB on first use)
+db = Vectrix("docs", tier="hybrid")  # or language="multi"
+
+# English only (bundled, no download)
+db = Vectrix("docs", tier="hybrid", language="en")
+```
+
+| Model | Purpose | Languages |
+|-------|---------|-----------|
+| multilingual-e5-small | Dense | 100+ |
+| mmarco-mMiniLMv2 | Reranking | 15+ |
+| BGE-M3 | Late interaction | 100+ |
+| mREBEL | GraphRAG extraction | 18 |
+
+## REST API & Dashboard
+
+```bash
+# Start server
+VECTRIXDB_API_KEY=your_key vectrixdb serve --port 7337
+
+# Open dashboard
+# http://localhost:7337/dashboard
+```
+
+```bash
+# Create collection
+curl -X POST http://localhost:7337/api/v1/collections \
+  -H "api-key: your_key" \
+  -d '{"name": "docs", "dimension": 384}'
+
+# Add with auto-embedding
+curl -X POST http://localhost:7337/api/v1/collections/docs/text-upsert \
+  -H "api-key: your_key" \
+  -d '{"points": [{"id": "1", "text": "Hello world"}]}'
+
+# Search
+curl -X POST http://localhost:7337/api/v1/collections/docs/text-search \
+  -H "api-key: your_key" \
+  -d '{"query_text": "greeting", "limit": 10}'
+```
+
+## Project Structure
+
+```
+VectrixDB/
+├── vectrixdb/
+│   ├── core/           # Vector index, storage, search
+│   │   ├── graphrag/   # Knowledge graph
+│   │   └── search/     # Search algorithms
+│   ├── api/            # FastAPI server
+│   ├── models/         # Embedded ONNX models
+│   │   └── data/       # Bundled English models
+│   ├── dashboard/      # Web UI
+│   └── cli.py          # Command line
+├── tests/              # Jupyter notebooks
+└── requirements.txt
+```
+
+## Installation from Source
+
+```bash
+git clone https://github.com/knowusuboaky/VectrixDB.git
+cd VectrixDB
+pip install -e .
+```
+
+## Requirements
+
+- Python 3.9+
+- No external API keys
+- Models bundled or auto-downloaded
+
+## License
+
+Apache 2.0
+
+## Author
+
+**Kwadwo Daddy Nyame Owusu - Boakye**
+
+GitHub: [@knowusuboaky](https://github.com/knowusuboaky)
+
+---
+
+*Where vectors come alive.*