Metadata-Version: 2.4
Name: langchain-faiss-vectorstore
Version: 0.1.0
Summary: Langchain vector store for Faiss.
Project-URL: Homepage, https://github.com/amany9000/langchain-vectorstore
Project-URL: Repository, https://github.com/amany9000/langchain-vectorstore
Project-URL: Issues, https://github.com/amany9000/langchain-vectorstore/issues
Requires-Python: <4.0.0,>=3.10.0
Requires-Dist: faiss-cpu<2.0.0,>=1.7.4
Requires-Dist: langchain-core<2.0.0,>=1.2.0
Description-Content-Type: text/markdown

# Faiss

Langchain vector store for [FAISS](https://github.com/facebookresearch/faiss). Supports save/load to disk.

## Install

```bash
pip install langchain-faiss-vectorstore
```

or

```bash
uv add langchain-faiss-vectorstore
```

## API Reference

### `__init__`

```python
def __init__(
    self,
    embedding_function: Embeddings | None = None,
    index: faiss.Index | None = None,
    **kwargs,
)
```

| Parameter | Type | Description |
|---|---|---|
| `embedding_function` | `Embeddings \| None` | Embedding function used to embed queries and texts (e.g., `FastEmbedEmbeddings`). |
| `index` | `faiss.Index \| None` | Optional pre-built FAISS index. If `None`, creates an `IndexIDMap` wrapping `IndexFlatL2` with dimension 0 (auto-sized on first `add_texts`). |

---

### `from_texts`

```python
def from_texts(
    cls,
    texts: list[str],
    embedding: Embeddings | None = None,
    metadatas: list[dict] | None = None,
    ids: list[str] | None = None,
    **kwargs,
) -> Faiss
```

| Parameter | Type | Description |
|---|---|---|
| `texts` | `list[str]` | Texts to index. |
| `embedding` | `Embeddings \| None` | Embedding function. |
| `metadatas` | `list[dict] \| None` | Optional metadata dicts, one per text. |
| `ids` | `list[str] \| None` | Optional document IDs. Auto-generated if not provided. |

**Returns:** `Faiss` — a new vector store with the texts indexed.

---

### `add_texts`

```python
def add_texts(
    self,
    texts: list[str],
    metadatas: list[dict] | None = None,
    ids: list[str] | None = None,
    **kwargs,
) -> list[str]
```

| Parameter | Type | Description |
|---|---|---|
| `texts` | `list[str]` | Texts to add to the index. |
| `metadatas` | `list[dict] \| None` | Optional metadata dicts, one per text. Defaults to `{}`. |
| `ids` | `list[str] \| None` | Optional document IDs. Auto-generated if not provided. |

**Returns:** `list[str]` — the IDs of the added texts.

---

### `delete`

```python
def delete(
    self,
    ids: list[str] | None = None,
    **kwargs,
) -> bool | None
```

| Parameter | Type | Description |
|---|---|---|
| `ids` | `list[str] \| None` | List of document IDs to remove. |

**Returns:** `bool` — `True` if deletion succeeded. Raises `ValueError` if `ids` is `None`.

---

### `similarity_search`

```python
def similarity_search(
    self,
    query: str,
    k: int = 4,
    **kwargs,
) -> list[Document]
```

| Parameter | Type | Description |
|---|---|---|
| `query` | `str` | Query text. |
| `k` | `int` | Number of documents to return. Default `4`. |

**Returns:** `list[Document]` — documents most similar to the query, ordered by L2 distance (ascending).

---

### `similarity_search_with_score`

```python
def similarity_search_with_score(
    self,
    query: str,
    k: int = 4,
    **kwargs,
) -> list[tuple[Document, float]]
```

| Parameter | Type | Description |
|---|---|---|
| `query` | `str` | Query text. |
| `k` | `int` | Number of documents to return. Default `4`. |

**Returns:** `list[tuple[Document, float]]` — tuples of `(Document, L2_distance)`. **Lower distance = more similar.**

---

### `save_local`

```python
def save_local(
    self,
    folder_path: str | Path,
) -> None
```

| Parameter | Type | Description |
|---|---|---|
| `folder_path` | `str \| Path` | Directory to save the index and document data. Created if it doesn't exist. |

Writes two files into `folder_path`:
- `index.faiss` — the serialized FAISS index.
- `docs.json` — document contents and metadata.

---

### `load_local`

```python
def load_local(
    cls,
    folder_path: str | Path,
    embedding_function: Embeddings,
    allow_dangerous_deserialization: bool = False,
) -> Faiss
```

| Parameter | Type | Description |
|---|---|---|
| `folder_path` | `str \| Path` | Directory containing `index.faiss` and `docs.json`. |
| `embedding_function` | `Embeddings` | Embedding function to use for future queries. |
| `allow_dangerous_deserialization` | `bool` | Safety flag (acknowledged). Default `False`. |

**Returns:** `Faiss` — a restored vector store instance.