# 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