Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,79 @@
+---
+library_name: custom
+tags:
+  - vector-search
+  - hnsw
+  - nearest-neighbor
+  - information-retrieval
+  - from-scratch
+license: mit
+---
+
+# HNSW Vector Engine
+
+A zero-dependency implementation of Hierarchical Navigable Small World (HNSW) approximate nearest-neighbor search, built directly from the [Malkov & Yashunin 2018 paper](https://arxiv.org/abs/1603.09320).
+
+Part of [Citadel](https://github.com/dbhavery/citadel), an open-source AI operations platform.
+
+## Why From Scratch?
+
+Most vector search tools wrap existing libraries (FAISS, Annoy, HNSWlib). This implementation builds the full HNSW index from first principles — multi-layer graph construction, greedy search with backtracking, configurable M/ef parameters — to demonstrate deep understanding of the algorithm, not just API usage.
+
+## Features
+
+- **Multi-layer graph** with probabilistic level assignment
+- **Greedy beam search** with configurable ef (exploration factor)
+- **Cosine similarity** distance metric
+- **Batch insert and query** with REST API wrapper
+- **Persistent storage** to disk
+- **18 tests** covering index construction, search accuracy, edge cases
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `M` | 16 | Max connections per node per layer |
+| `ef_construction` | 200 | Beam width during index building |
+| `ef_search` | 50 | Beam width during query |
+| `max_elements` | 10000 | Pre-allocated index size |
+
+## Usage
+
+```python
+from citadel_vector import VectorStore
+
+store = VectorStore(collection="docs", dim=384)
+store.add(vectors=embeddings, metadata=metadata)
+results = store.search(query_vector, k=10)
+```
+
+## Architecture
+
+```
+Query Vector
+    |
+    v
+[Top Layer] -- sparse graph, long-range connections
+    |
+    v
+[Layer N-1] -- denser graph
+    |
+    v
+[Layer 0]   -- full graph, all nodes, local connections
+    |
+    v
+Top-K Results (sorted by cosine similarity)
+```
+
+## Part of Citadel
+
+This vector engine is one of 6 independently installable packages in the Citadel AI Operations Platform:
+
+- **citadel-gateway** — LLM proxy with routing, caching, circuit breakers
+- **citadel-vector** — This package (HNSW vector search)
+- **citadel-agents** — ReAct agent runtime with tool registry
+- **citadel-ingest** — Document parsing and chunking pipeline
+- **citadel-trace** — LLM observability and cost tracking
+- **citadel-dashboard** — Real-time operations UI
+
+[GitHub Repository](https://github.com/dbhavery/citadel) | [Author](https://github.com/dbhavery)