faiss-vector-store 0.1.0

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's BedrockEmbedding/OpenAIEmbedding/GoogleAIEmbedding, or your own.

How to install

# 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.

# 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.

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 for a full walkthrough of saving/loading both to a local path and to in-memory buffers (for S3/Redis-style storage), and docs/ for the complete guide.

Contributing

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