component decomposition is done

docs/02_components/helpers/h04_faiss_index_manager_spec.md

@@ -0,0 +1,84 @@
+# Faiss Index Manager Helper
+
+## Interface Definition
+
+**Interface Name**: `IFaissIndexManager`
+
+### Interface Methods
+
+```python
+class IFaissIndexManager(ABC):
+    @abstractmethod
+    def build_index(self, descriptors: np.ndarray, index_type: str) -> FaissIndex:
+        pass
+    
+    @abstractmethod
+    def add_descriptors(self, index: FaissIndex, descriptors: np.ndarray) -> bool:
+        pass
+    
+    @abstractmethod
+    def search(self, index: FaissIndex, query: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
+        pass
+    
+    @abstractmethod
+    def save_index(self, index: FaissIndex, path: str) -> bool:
+        pass
+    
+    @abstractmethod
+    def load_index(self, path: str) -> FaissIndex:
+        pass
+```
+
+## Component Description
+
+Manages Faiss indices for AnyLoc retrieval (IVF, HNSW options).
+
+## API Methods
+
+### `build_index(descriptors: np.ndarray, index_type: str) -> FaissIndex`
+
+**Description**: Builds Faiss index from descriptors.
+
+**Index Types**:
+- **"IVF"**: Inverted File (fast for large databases)
+- **"HNSW"**: Hierarchical Navigable Small World (best accuracy/speed trade-off)
+- **"Flat"**: Brute force (exact, slow for large datasets)
+
+**Input**: (N, D) descriptors array
+
+---
+
+### `add_descriptors(index: FaissIndex, descriptors: np.ndarray) -> bool`
+
+**Description**: Adds more descriptors to existing index.
+
+---
+
+### `search(index: FaissIndex, query: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]`
+
+**Description**: Searches for k nearest neighbors.
+
+**Output**: (distances, indices) - shape (k,)
+
+---
+
+### `save_index(index: FaissIndex, path: str) -> bool`
+
+**Description**: Saves index to disk for fast startup.
+
+---
+
+### `load_index(path: str) -> FaissIndex`
+
+**Description**: Loads pre-built index from disk.
+
+## Dependencies
+
+**External**: faiss-gpu or faiss-cpu
+
+## Test Cases
+
+1. Build index with 10,000 descriptors → succeeds
+2. Search query → returns top-k matches
+3. Save/load index → index restored correctly
+