{"_id":"0g-vector-search","name":"0g-vector-search","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"0g-vector-search","version":"0.1.0","description":"Unified Vector Search service for 0G Storage — decentralized HNSW index on 0G's sharded KV layer","main":"dist/index.js","types":"dist/index.d.ts","repository":{"type":"git","url":"git+https://github.com/Sage-senpai/0g-vector-search.git"},"author":{"name":"Sage-senpai / Dvyne"},"scripts":{"build":"tsc","dev":"ts-node src/index.ts","test":"vitest run","test:watch":"vitest","lint":"eslint src/"},"keywords":["0g","vector-search","hnsw","decentralized","web3","vector-database"],"license":"MIT","dependencies":{"@0glabs/0g-ts-sdk":"^0.3.0"},"devDependencies":{"typescript":"^5.4.0","vitest":"^1.6.0","ts-node":"^10.9.0","@types/node":"^20.0.0"},"gitHead":"709bbf4bec75d8d87d60da30be1ebb4874d989d7","_id":"0g-vector-search@0.1.0","bugs":{"url":"https://github.com/Sage-senpai/0g-vector-search/issues"},"homepage":"https://github.com/Sage-senpai/0g-vector-search#readme","_nodeVersion":"22.18.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-blS9QOfZvXGYRtkNmmetER+EU0K2b2QYnyouJfZKwhxug/b90iJ2ahlQkxypoxkKNkHGJWexOwqiqhTwz4EHgQ==","shasum":"aada28b2e1fd53ce4cfbe421e67b8818d0d17b57","tarball":"https://registry.npmjs.org/0g-vector-search/-/0g-vector-search-0.1.0.tgz","fileCount":46,"unpackedSize":164857,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCVcTHFxeSeUdkAkMheX+/7GaTe59ECGfpcB/eO5u+hxwIhAJ2HbTX7Yo3el1/9ba6yPHAATsqtotFGPBdOG1g8tlNr"}]},"_npmUser":{"name":"sage-senpeak","email":"anyadikedivine0@gmail.com"},"directories":{},"maintainers":[{"name":"sage-senpeak","email":"anyadikedivine0@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/0g-vector-search_0.1.0_1772983200855_0.45137619188319333"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-08T15:20:00.782Z","0.1.0":"2026-03-08T15:20:01.025Z","modified":"2026-03-08T15:20:01.229Z"},"maintainers":[{"name":"sage-senpeak","email":"anyadikedivine0@gmail.com"}],"description":"Unified Vector Search service for 0G Storage — decentralized HNSW index on 0G's sharded KV layer","homepage":"https://github.com/Sage-senpai/0g-vector-search#readme","keywords":["0g","vector-search","hnsw","decentralized","web3","vector-database"],"repository":{"type":"git","url":"git+https://github.com/Sage-senpai/0g-vector-search.git"},"author":{"name":"Sage-senpai / Dvyne"},"bugs":{"url":"https://github.com/Sage-senpai/0g-vector-search/issues"},"license":"MIT","readme":"# ZeroG VectorSearch\n\n> Unified Vector Search on 0G Storage — a decentralized HNSW index built on 0G's sharded KV layer.\n\nTransforms 0G Labs from a Data Repository into a Reasoning Engine by implementing approximate nearest neighbor search directly on 0G's modular storage stack.\n\n## Features\n\n- **Decentralized HNSW Index** — O(log N) vector search with multi-layer graph traversal\n- **Deterministic Sharding** — FNV-1a consistent hashing maps vectors to 0G shards\n- **Hybrid Search** — BM25 keyword + semantic vector fusion (0gmem pattern)\n- **0G KV Persistence** — Hex-encoded key structure for native KV layer storage\n- **Security Layer** — PoRA verification, data availability guard, alignment verification\n- **Drop-in SDK** — Feels like a native extension of `@0glabs/0g-ts-sdk`\n\n## Quick Start\n\n```bash\nnpm install 0g-vector-search @0glabs/0g-ts-sdk ethers\n```\n\n```typescript\nimport { VectorStore } from \"0g-vector-search\";\n\n// Local development (no 0G network required)\nconst store = new VectorStore({ dimensions: 768 });\nawait store.initialize();\n\n// Insert vectors\nawait store.upsert(\n  \"doc_001\",\n  embedding,                          // Float32Array[768]\n  { source: \"arxiv\", topic: \"ml\" },   // metadata\n  \"Attention is all you need...\"      // text for keyword search\n);\n\n// Semantic search\nconst results = await store.search(queryEmbedding, { topK: 10 });\n\n// Hybrid search (recommended)\nconst results = await store.search(queryEmbedding, {\n  topK: 10,\n  hybrid: {\n    enabled: true,\n    semanticWeight: 0.7,\n    query: \"transformer architecture\",\n  },\n});\n```\n\n### With 0G Network\n\n```typescript\nconst store = new VectorStore({\n  dimensions: 768,\n  zeroG: {\n    endpoint: \"http://3.101.147.150:6789\",\n    streamId: \"your-stream-id\",\n    privateKey: \"0x...\",\n    flowContract: \"0x...\",\n    kvNodeCount: 1,\n  },\n});\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│                  VectorStore                     │\n│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │\n│  │  HNSW    │  │  BM25    │  │   Security    │ │\n│  │  Index   │  │  Index   │  │   Layer       │ │\n│  └────┬─────┘  └────┬─────┘  └───────┬───────┘ │\n│       │              │               │          │\n│  ┌────┴──────────────┴───────────────┴───────┐ │\n│  │          Shard Router (FNV-1a)             │ │\n│  └────────────────┬──────────────────────────┘ │\n│                   │                             │\n│  ┌────────────────┴──────────────────────────┐ │\n│  │     0G KV Layer (via Batcher / KvClient)  │ │\n│  └───────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────┘\n```\n\n### KV Key Structure\n\nAll data is stored in 0G's KV layer with hex-encoded keys:\n\n| Key Pattern | Description |\n|---|---|\n| `vec:<shard>:<node>` | Raw vector data (Float32 buffer) |\n| `idx:<shard>:<node>:<layer>` | HNSW graph connections per layer |\n| `meta:<shard>:<node>` | Vector metadata (JSON) |\n| `bm25:<shard>:<node>` | BM25 term frequencies |\n| `cfg:global:index_state` | Index config, entry point, max level |\n\n### Vector Upsert Flow\n\n1. `ShardRouter.getShardId(id)` → FNV-1a hash determines target shard\n2. `HNSWIndex.insert(id, vector)` → builds graph links across layers\n3. `BM25Index.addDocument(id, content)` → indexes text for keyword search\n4. `PoRAVerifier.generateCommitment()` → creates proof for 0G validators\n5. `GraphPersistence.save*()` → writes to 0G KV via Batcher\n\n### Vector Search Flow\n\n1. `DataAvailabilityGuard` checks shard health\n2. `HybridSearchEngine.search()` → HNSW + BM25 score fusion\n3. `AlignmentVerifier.verifyResults()` → checks for injection attacks\n4. Results returned sorted by fused score\n\n## Configuration\n\n| Parameter | Default | Description |\n|---|---|---|\n| `dimensions` | 768 | Vector dimensionality |\n| `M` | 16 | Max connections per HNSW layer |\n| `efConstruction` | 200 | Candidate list size during insertion |\n| `efSearch` | 50 | Candidate list size during search |\n| `metric` | cosine | Distance metric (cosine/euclidean/dot_product) |\n| `numShards` | 4 | Number of 0G storage shards |\n\n## Development\n\n```bash\nnpm install        # Install dependencies\nnpm test           # Run test suite (21 tests)\nnpm run build      # TypeScript compilation\n```\n\n## Security\n\n- **PoRA Compatibility**: Vector updates generate proof commitments for 0G validator verification\n- **Data Availability**: Shard health monitoring with fallback routing for offline shards\n- **Alignment Verification**: Detects suspicious result clustering indicating injection attacks\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-14fff3bf1c1a8b9194b196487a43335d"}