{"id":43236618,"url":"https://github.com/knowusuboaky/vectrixdb","last_synced_at":"2026-05-26T07:02:16.479Z","repository":{"id":335819714,"uuid":"1146455288","full_name":"knowusuboaky/VectrixDB","owner":"knowusuboaky","description":"Where vectors come alive - A lightweight, visual-first vector database with embedded ML models. No API keys required.","archived":false,"fork":false,"pushed_at":"2026-05-15T18:32:09.000Z","size":706,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T20:58:01.363Z","etag":null,"topics":["embeddings","graphrag","machine-learning","onnx","python","semantic-search","similarity-search","vector-database"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/vectrixdb/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knowusuboaky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-31T05:47:14.000Z","updated_at":"2026-05-15T18:13:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/knowusuboaky/VectrixDB","commit_stats":null,"previous_names":["knowusuboaky/vectrixdb"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/knowusuboaky/VectrixDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowusuboaky%2FVectrixDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowusuboaky%2FVectrixDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowusuboaky%2FVectrixDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowusuboaky%2FVectrixDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knowusuboaky","download_url":"https://codeload.github.com/knowusuboaky/VectrixDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowusuboaky%2FVectrixDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33508317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embeddings","graphrag","machine-learning","onnx","python","semantic-search","similarity-search","vector-database"],"created_at":"2026-02-01T11:00:58.902Z","updated_at":"2026-05-26T07:02:16.468Z","avatar_url":"https://github.com/knowusuboaky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VectrixDB\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python Versions](https://img.shields.io/pypi/pyversions/vectrixdb.svg)](https://pypi.org/project/vectrixdb/)\n[![VectrixDB Version](https://img.shields.io/pypi/v/vectrixdb.svg)](https://pypi.org/project/vectrixdb/)\n[![Downloads](https://pepy.tech/badge/vectrixdb)](https://pepy.tech/project/vectrixdb)\n[![Issues](https://img.shields.io/github/issues/knowusuboaky/VectrixDB)](https://github.com/knowusuboaky/VectrixDB/issues)\n[![Contact](https://img.shields.io/badge/Email-Contact-green.svg)](mailto:kwadwo.owusuboakye@outlook.com)\n\n**Where vectors come alive.**\n\nA lightweight vector database with embedded ML models, beautiful dashboard, and GraphRAG - no API keys required.\n\n---\n\n## Features\n\n- **4 Search Modes** - Dense, Hybrid, Ultimate, and Graph (GraphRAG)\n- **8 Storage Backends** - Memory, SQLite, Lakebase, DeltaLake, CosmosDB, PostgreSQL, OpenSearch, Aurora PostgreSQL\n- **Embedded Models** - Works offline with bundled ONNX models\n- **Model Selection** - Choose from bundled, HuggingFace, or GitHub release models\n- **Document Index** - Hierarchical document storage with chunking\n- **Visual Dashboard** - Built-in web UI for managing collections\n- **Zero Config** - Just `pip install` and start using\n\n---\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install vectrixdb\n```\n\n### From GitHub (Latest)\n\n```bash\npip install git+https://github.com/knowusuboaky/VectrixDB.git\n```\n\n### Specific Version from GitHub\n\n```bash\npip install git+https://github.com/knowusuboaky/VectrixDB.git@v2.0.0\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/knowusuboaky/VectrixDB.git\ncd VectrixDB\npip install -e .\n```\n\n### Optional Dependencies\n\n```bash\n# HuggingFace sentence-transformers\npip install vectrixdb[hf]\n\n# FastEmbed (lightweight ONNX embeddings)\npip install vectrixdb[fastembed]\n\n# All embedding providers\npip install vectrixdb[embeddings]\n\n# Visualization (UMAP)\npip install vectrixdb[viz]\n\n# Everything\npip install vectrixdb[all]\n```\n\n---\n\n## Quick Start\n\n```python\nfrom vectrixdb import Vectrix\n\ndb = Vectrix(\"my_docs\")\ndb.add([\"Python is great\", \"JavaScript powers the web\", \"Rust is fast\"])\n\nresults = db.search(\"programming\")\nprint(results.top.text)\n```\n\n---\n\n## Search Modes\n\nVectrixDB offers 4 search modes, each building on the previous:\n\n| Mode | Components | Best For |\n|------|------------|----------|\n| `dense` | Vector similarity | Fast semantic search |\n| `hybrid` | Dense + Sparse + Reranker | Keyword + semantic matching |\n| `ultimate` | Hybrid + ColBERT | Maximum accuracy |\n| `graph` | Ultimate + Knowledge Graph | Complex reasoning (GraphRAG) |\n\n```python\n# Choose your mode\ndb = Vectrix(\"docs\", mode=\"dense\")     # Fastest\ndb = Vectrix(\"docs\", mode=\"hybrid\")    # Balanced\ndb = Vectrix(\"docs\", mode=\"ultimate\")  # Best quality\ndb = Vectrix(\"docs\", mode=\"graph\")     # GraphRAG\n```\n\n---\n\n## Model Selection\n\nCustomize models for each component. Models load from 3 sources:\n\n### 1. Bundled Models (Offline, No Downloads)\n\nPre-packaged ONNX models that work without internet (~100MB total):\n\n```python\ndb = Vectrix(\n    \"docs\",\n    mode=\"ultimate\",\n    dense_model=\"e5-small\",            # 384 dim, 33MB\n    sparse_model=\"bm25\",               # 1MB\n    reranker_model=\"L12\",              # 33MB\n    late_interaction_model=\"colbert\",  # 33MB\n)\n```\n\n| Component | Alias | Model | Dimension | Size |\n|-----------|-------|-------|-----------|------|\n| Dense | `e5-small` | intfloat/e5-small-v2 | 384 | 33MB |\n| Sparse | `bm25` | BM25 vocabulary | - | 1MB |\n| Reranker | `L12` | ms-marco-MiniLM-L12-v2 | - | 33MB |\n| ColBERT | `colbert` | answerai-colbert-small-v1 | 128 | 33MB |\n\n### 2. GitHub Release Models (Auto-Downloaded)\n\nLarger models hosted on GitHub releases (downloaded on first use):\n\n```python\ndb = Vectrix(\n    \"docs\",\n    mode=\"ultimate\",\n    dense_model=\"bge-base\",            # 768 dim, higher quality\n    sparse_model=\"bm25\",\n    reranker_model=\"bge-reranker\",     # Higher quality\n    late_interaction_model=\"colbert-v2\",\n)\n```\n\n| Alias | Model | Dimension | Size |\n|-------|-------|-----------|------|\n| `bge-base` | BAAI/bge-base-en-v1.5 | 768 | 110MB |\n| `bge-small` | BAAI/bge-small-en-v1.5 | 384 | 127MB |\n| `bge-reranker` | BAAI/bge-reranker-base | - | 212MB |\n| `colbert-v2` | colbert-ir/colbertv2.0 | 128 | 67MB |\n| `splade` | SPLADE++ | - | 508MB |\n\n### 3. HuggingFace Models\n\nUse any compatible model from HuggingFace (requires `pip install vectrixdb[hf]`):\n\n```python\ndb = Vectrix(\n    \"docs\",\n    mode=\"hybrid\",\n    dense_model=\"BAAI/bge-large-en-v1.5\",\n    sparse_model=\"naver/splade-cocondenser-ensembledistil\",\n    reranker_model=\"cross-encoder/ms-marco-MiniLM-L-12-v2\",\n)\n```\n\n**Compatible models:**\n- Dense: `BAAI/bge-large-en-v1.5`, `intfloat/e5-large-v2`, `sentence-transformers/all-mpnet-base-v2`\n- Sparse: `naver/splade-cocondenser-ensembledistil`\n- Reranker: `cross-encoder/ms-marco-MiniLM-L-12-v2`, `BAAI/bge-reranker-base`\n- ColBERT: `jinaai/jina-colbert-v2`, `colbert-ir/colbertv2.0`\n\n---\n\n## Storage Backends\n\nVectrixDB supports 8 storage backends:\n\n| Backend | Type | Persistence | Modes | Best For |\n|---------|------|-------------|-------|----------|\n| `memory` | In-Memory | No | All | Testing, small datasets |\n| `sqlite` | File-based | Yes | All | Local development |\n| `lakebase` | PostgreSQL + pgvector | Yes | All | Databricks Lakebase |\n| `delta_lake` | Delta Lake | Yes | All | Databricks Unity Catalog |\n| `cosmosdb` | Azure CosmosDB | Yes | All | Azure cloud |\n| `postgresql` | PostgreSQL + pgvector | Yes | All | Self-hosted PostgreSQL |\n| `opensearch` | AWS OpenSearch | Yes | Dense, Hybrid | AWS managed search |\n| `aurora_postgresql` | AWS Aurora + pgvector | Yes | All | AWS managed PostgreSQL |\n\n### Memory Storage (Default)\n\n```python\nfrom vectrixdb import VectrixDB, StorageConfig, StorageBackend\n\n# In-memory (default, no persistence)\ndb = VectrixDB()\n\n# Or explicitly\nconfig = StorageConfig(backend=StorageBackend.MEMORY)\ndb = VectrixDB(storage_config=config)\n```\n\n### SQLite Storage (Local Persistence)\n\n```python\nfrom vectrixdb import VectrixDB\n\n# SQLite with file path\ndb = VectrixDB(path=\"./my_vectors\")\n\n# Creates: ./my_vectors/vectrix.db\n```\n\n### Lakebase Storage (Databricks)\n\n```python\nfrom vectrixdb import Vectrix, VectrixDB\n\n# Connect to Lakebase (PostgreSQL + pgvector)\nlakebase = VectrixDB.with_lakebase(\n    host=\"your-lakebase-host.cloud.databricks.com\",\n    database=\"databricks_postgres\",\n    user=\"your-user\",\n    password=\"your-oauth-token\",  # OAuth JWT from Lakebase Connect\n    port=5432,\n    schema=\"public\",  # Optional, defaults to \"public\"\n)\n\n# Use with Vectrix\ndb = Vectrix(\n    \"products\",\n    mode=\"ultimate\",\n    storage_backend=lakebase,\n)\n\ndb.add(texts=[\"Product A\", \"Product B\"])\nresults = db.search(\"query\")\n```\n\n### Delta Lake Storage (Databricks Unity Catalog)\n\n```python\nfrom vectrixdb import VectrixDB\n\n# Connect to Delta Lake via Databricks SQL\ndelta = VectrixDB.with_delta_lake(\n    workspace_url=\"https://your-workspace.cloud.databricks.com\",\n    token=\"dapi_your_token\",\n    catalog=\"main\",\n    schema=\"vectrixdb\",\n    warehouse_id=\"your_warehouse_id\",\n)\n\n# Use with Vectrix\ndb = Vectrix(\"products\", mode=\"hybrid\", storage_backend=delta)\n```\n\n### CosmosDB Storage (Azure)\n\n```python\nfrom vectrixdb import VectrixDB, StorageConfig, StorageBackend\n\nconfig = StorageConfig(\n    backend=StorageBackend.COSMOSDB,\n    cosmos_endpoint=\"https://your-account.documents.azure.com:443/\",\n    cosmos_key=\"your-primary-key\",\n    cosmos_database=\"vectrixdb\",\n)\n\ndb = VectrixDB(storage_config=config)\n```\n\n### OpenSearch Storage (AWS)\n\nAWS OpenSearch Serverless with native k-NN vector search.\n\n\u003e **Note**: OpenSearch supports `dense` and `hybrid` modes only.\n\n```python\nfrom vectrixdb import VectrixDB\n\nopensearch = VectrixDB.with_opensearch(\n    endpoint=\"https://xxx.us-east-1.aoss.amazonaws.com\",\n    region=\"us-east-1\",\n)\n```\n\n### Aurora PostgreSQL Storage (AWS)\n\nAWS Aurora PostgreSQL with pgvector. Supports all modes including `ultimate`.\n\n```python\nfrom vectrixdb import VectrixDB\n\naurora = VectrixDB.with_aurora_postgresql(\n    host=\"cluster.xxx.us-east-1.rds.amazonaws.com\",\n    database=\"vectrixdb\",\n    user=\"admin\",\n    password=\"password\",\n)\n```\n\n### Adaptive Schema\n\nSchema adapts based on selected mode:\n\n| Mode | Columns Created |\n|------|-----------------|\n| `dense` | `id`, `dense_embedding`, `metadata`, `text_content`, `created_at`, `updated_at` |\n| `hybrid` | + `sparse_embedding` |\n| `ultimate` | + `late_interaction_embedding` |\n| `graph` | Same as ultimate + graph tables |\n\n---\n\n## Document Index\n\nHierarchical document storage with automatic chunking:\n\n```python\nfrom vectrixdb import DocumentIndex, chunk_text, chunk_with_context\n\n# Create document index\ndoc_index = DocumentIndex(\"./docs_index\")\n\n# Chunk text (simple)\nchunks = chunk_text(\n    \"Your long document text here...\",\n    chunk_size=1000,\n    chunk_overlap=200,\n)\n\n# Chunk markdown with context (preserves headings)\nchunks = chunk_with_context(\n    markdown_text,\n    chunk_size=1200,\n    chunk_overlap=200,\n)\n# Returns: [{\"content\": \"...\", \"heading\": \"Section Title\", \"level\": 2}, ...]\n\n# Build tree from markdown\nfrom vectrixdb import build_tree_from_markdown, build_tree_from_pdf\n\ntree = build_tree_from_markdown(markdown_content)\ntree = build_tree_from_pdf(pdf_path)\n```\n\n### Document Index with Storage Backend\n\n```python\nfrom vectrixdb import DocumentIndex, VectrixDB\n\n# Connect to storage\nlakebase = VectrixDB.with_lakebase(...)\n\n# Document index uses storage backend\ndoc_index = DocumentIndex(storage=lakebase)\n\n# Save documents and nodes\ndoc_index.save_document({\n    \"doc_id\": \"doc_001\",\n    \"title\": \"My Document\",\n    \"doc_type\": \"markdown\",\n    \"page_count\": 5,\n})\n\n# Query documents\ndocs = doc_index.list_documents()\nnodes = doc_index.get_document_nodes(\"doc_001\")\n```\n\n---\n\n## Metadata \u0026 Filtering\n\n```python\ndb.add(\n    texts=[\"iPhone 15\", \"Galaxy S24\", \"Pixel 8\"],\n    metadata=[\n        {\"brand\": \"Apple\", \"price\": 999},\n        {\"brand\": \"Samsung\", \"price\": 899},\n        {\"brand\": \"Google\", \"price\": 699}\n    ]\n)\n\n# Filter by metadata\nresults = db.search(\"smartphone\", filter={\"brand\": \"Apple\"})\n\n# Complex filters\nresults = db.search(\"phone\", filter={\n    \"brand\": {\"$in\": [\"Apple\", \"Samsung\"]},\n    \"price\": {\"$lt\": 1000}\n})\n```\n\n---\n\n## Advanced API\n\nFor full control, use the `VectrixDB` class directly:\n\n```python\nfrom vectrixdb import VectrixDB, Collection\n\n# Create database\ndb = VectrixDB(path=\"./my_db\")\n\n# Create collection with specific dimension\ncoll = db.create_collection(\"products\", dimension=384)\n\n# Add vectors directly\ncoll.add(\n    ids=[\"p1\", \"p2\"],\n    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],\n    metadata=[{\"name\": \"Product A\"}, {\"name\": \"Product B\"}],\n)\n\n# Search with vectors\nresults = coll.search(query=[0.1, 0.2, ...], limit=10)\n\n# List collections\ncollections = db.list_collections()\n\n# Delete collection\ndb.delete_collection(\"products\")\n```\n\n---\n\n## Embedded Models API\n\nUse embedding models directly:\n\n```python\nfrom vectrixdb import (\n    DenseEmbedder,\n    SparseEmbedder,\n    RerankerEmbedder,\n    LateInteractionEmbedder,\n)\n\n# Dense embeddings\ndense = DenseEmbedder(model=\"e5-small\")\nvectors = dense.embed([\"Hello world\", \"How are you?\"])\n\n# Sparse embeddings (BM25)\nsparse = SparseEmbedder()\nsparse_vectors = sparse.embed([\"Hello world\"])\n\n# Reranker\nreranker = RerankerEmbedder(model=\"L12\")\nscores = reranker.rerank(\"query\", [\"doc1\", \"doc2\", \"doc3\"])\n\n# Late interaction (ColBERT)\ncolbert = LateInteractionEmbedder(model=\"colbert\")\ntoken_embeddings = colbert.embed([\"Hello world\"])\n```\n\n---\n\n## REST API\n\nStart the server:\n\n```bash\nVECTRIXDB_API_KEY=your_secret vectrixdb serve --port 7337\n```\n\nOpen the dashboard at `http://localhost:7337/dashboard`\n\n### API Examples\n\n```bash\n# Create collection\ncurl -X POST http://localhost:7337/api/v1/collections \\\n  -H \"Content-Type: application/json\" \\\n  -H \"api-key: your_secret\" \\\n  -d '{\"name\": \"docs\", \"dimension\": 384}'\n\n# Add documents (auto-embedding)\ncurl -X POST http://localhost:7337/api/v1/collections/docs/text-upsert \\\n  -H \"Content-Type: application/json\" \\\n  -H \"api-key: your_secret\" \\\n  -d '{\"points\": [{\"id\": \"1\", \"text\": \"Hello world\"}]}'\n\n# Search\ncurl -X POST http://localhost:7337/api/v1/collections/docs/text-search \\\n  -H \"Content-Type: application/json\" \\\n  -H \"api-key: your_secret\" \\\n  -d '{\"query_text\": \"greeting\", \"limit\": 10}'\n```\n\n---\n\n## GraphRAG\n\nBuild knowledge graphs from documents:\n\n```python\nfrom vectrixdb import Vectrix, create_openai_config\n\n# Create with graph mode\ndb = Vectrix(\"docs\", mode=\"graph\")\n\n# Or with custom LLM config\nconfig = create_openai_config(\n    api_key=\"your-openai-key\",\n    model=\"gpt-4o-mini\",\n)\n\ndb = Vectrix(\n    \"docs\",\n    mode=\"graph\",\n    graphrag_config=config,\n)\n\n# Add documents (extracts entities \u0026 relationships)\ndb.add([\"Apple announced the iPhone 15 in September 2023.\"])\n\n# Search with graph reasoning\nresults = db.search(\"What products did Apple release?\")\n```\n\n---\n\n## Project Structure\n\n```\nVectrixDB/\n├── vectrixdb/\n│   ├── core/           # Vector index, storage, search\n│   │   ├── storage.py  # All storage backends\n│   │   ├── collection.py\n│   │   ├── database.py\n│   │   ├── document_index.py\n│   │   ├── graphrag/   # Knowledge graph\n│   │   └── search/     # Search algorithms\n│   ├── api/            # FastAPI server\n│   ├── models/         # Embedded ONNX models\n│   │   └── data/       # Bundled model files\n│   ├── dashboard/      # Web UI\n│   ├── easy.py         # Vectrix simple API\n│   └── cli.py          # Command line\n├── tests/\n└── pyproject.toml\n```\n\n---\n\n## Requirements\n\n- Python 3.9+\n- No API keys needed (for bundled models)\n- Models are bundled or auto-downloaded\n\n---\n\n## License\n\nApache 2.0\n\n---\n\n## Author\n\n**Kwadwo Daddy Nyame Owusu - Boakye**\n\nGitHub: [@knowusuboaky](https://github.com/knowusuboaky)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowusuboaky%2Fvectrixdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknowusuboaky%2Fvectrixdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowusuboaky%2Fvectrixdb/lists"}