Metadata-Version: 2.5
Name: faiss-vector-store
Version: 0.1.0
Summary: Standalone FAISS-backed vector store — `Document`, `FAISSIndex`, `FAISSVectorStore`. Works with `llmfy` embedding clients or any client matching the `EmbeddingClient` protocol.
Project-URL: Homepage, https://github.com/llmfy-labs/faiss-vector-store-python
Project-URL: Repository, https://github.com/llmfy-labs/faiss-vector-store-python
Project-URL: Issues, https://github.com/llmfy-labs/faiss-vector-store-python/issues
Author-email: irufano <irufano.official@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,embeddings,faiss,llm,llmfy,rag,vector-store
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic
Provides-Extra: all
Requires-Dist: faiss-cpu; extra == 'all'
Requires-Dist: numpy; extra == 'all'
Provides-Extra: faiss-cpu
Requires-Dist: faiss-cpu; extra == 'faiss-cpu'
Provides-Extra: numpy
Requires-Dist: numpy; extra == 'numpy'
Description-Content-Type: text/markdown

<div align="center">

  <a href="https://img.shields.io/github/actions/workflow/status/llmfy-labs/faiss-vector-store-python/release.yml">![faiss-vector-store](https://img.shields.io/github/actions/workflow/status/llmfy-labs/faiss-vector-store-python/release.yml?style=for-the-badge&logo=pypi&logoColor=blue&label=publish
  )</a>
  <a href="https://pypi.org/project/faiss-vector-store/0.1.0">![faiss-vector-store](https://img.shields.io/badge/faiss--vector--store-v0.1.0-31CA9C.svg?style=for-the-badge&logo=pypi&logoColor=yellow)</a>
  <a href="https://pypi.org/project/faiss-vector-store/">![faiss-vector-store](https://img.shields.io/pypi/v/faiss-vector-store?style=for-the-badge&label=latest&labelColor=691DC6&color=B77309)</a>
  <a href="">![python](https://img.shields.io/badge/python->=3.11-4392FF.svg?style=for-the-badge&logo=python&logoColor=4392FF)</a>

</div>

`faiss-vector-store` is a standalone FAISS-backed vector store: `Document`, `FAISSIndex`, and `FAISSVectorStore` for embedding, storing, and similarity-searching text documents. It has no dependency on `llmfy` or any other LLM framework — pass it an embedding client matching the `EmbeddingClient` protocol (`provider`, `model`, `encode_batch(...)`), such as one of [`llmfy`](https://github.com/llmfy-labs/llmfy-python)'s `BedrockEmbedding`/`OpenAIEmbedding`/`GoogleAIEmbedding`, or your own.

## How to install

```sh
# Using UV
uv add faiss-vector-store

# Using pip
pip install faiss-vector-store
```

Installing `faiss-vector-store` pulls in `pydantic` (used by `Document`) automatically — nothing else.

### FAISS / NumPy — required for actual vector store use

`faiss`/`numpy` are optional extras: importing `faiss_vector_store` never fails, but constructing a `FAISSIndex` or `FAISSVectorStore` raises `FAISSVectorStoreException` with an install hint if either is missing.

```sh
# Using UV
uv add "faiss-vector-store[all]"
# or individually
uv add "faiss-vector-store[faiss-cpu]"
uv add "faiss-vector-store[numpy]"

# Using pip
pip install "faiss-vector-store[all]"
```

## How to use

Any embedding client matching the `EmbeddingClient` protocol works — this example uses `llmfy`'s `BedrockEmbedding` (`pip install "llmfy[boto3]"`), but a custom class with `provider`/`model`/`encode_batch(...)` works just as well.

```python
from llmfy import BedrockEmbedding
from faiss_vector_store import Document, FAISSVectorStore

texts = [
    "The cat sits on the mat",
    "Dogs are loyal animals",
    "Artificial intelligence is transforming the world",
    "Quantum computing is the future of technology",
    "The sun rises in the east",
]

docs = [
    Document(id=str(i), text=text, author="irufano")
    for i, text in enumerate(texts)
]

embedding = BedrockEmbedding(model="amazon.titan-embed-text-v1")
store = FAISSVectorStore(embedding)
store.encode_documents(docs)
store.save_to_path("./kb/test_kb")

# --- Load it back and search ---
new_store = FAISSVectorStore(embedding)
new_store.load_from_path("./kb/test_kb")

results = new_store.search("Machine learning and AI", k=2)
for doc, score, idx in results:
    print(f"- Match: {doc.text}, Index: {idx}, score: {score:.4f}, author: {doc.author}")
```

See [`faiss_vector_store/example/faiss_store_example.py`](faiss_vector_store/example/faiss_store_example.py) for a full walkthrough of saving/loading both to a local path and to in-memory buffers (for S3/Redis-style storage), and [`docs/`](docs/) for the complete guide.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for commit message format, the automatic version-bump/release process, and local package development commands.
