Installation

Basic install:

pip install ffai

Or with uv:

uv add ffai

Install directly from GitHub:

pip install git+https://github.com/antquinonez/ffai.git

Optional extras

RAG installs ChromaDB for persistent vector storage. OpenTelemetry installs OTLP span export for tracing.

Note

Quotes are required around ffai[rag] in zsh and some other shells, since brackets are special characters. Bash does not require quotes.

Vector store backends

FFAI’s RAG system supports multiple vector store backends. ChromaDB is included with ffai[rag]; others install separately:

Backend	Install	Mode
ChromaDB	Included with `ffai[rag]`	Local files (persistent client)
Qdrant	`pip install qdrant-client`	Local, server, or cloud
pgvector	`pip install psycopg asyncpg`	Server (Docker or managed PostgreSQL)
SQLite-vss	`pip install sqlite-vss`	Local files (SQLite extension)

All backends implement the same VectorStoreBase interface. You can swap backends without changing any other code.

See Vector Store Backends for configuration and usage details.

Running tests

Clone the repository and install dev dependencies:

git clone https://github.com/antquinonez/ffai.git
cd ffai
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,rag]"

Run the full test suite:

pytest tests/ -x -q

Run tests for a specific backend:

pytest tests/ -m chroma            # ChromaDB unit + integration
pytest tests/ -m qdrant            # Qdrant unit + integration
pytest tests/ -m pgvector          # pgvector unit tests (mocked)
pytest tests/ -m sqlite_vss        # SQLite-vss unit tests (mocked)

Run integration tests (require real packages installed):

pytest tests/integration/ -m integration -v

Integration tests for vector stores use synthetic embeddings (no LLM calls needed). They are excluded from the default pytest run via the -m 'not integration' filter in pyproject.toml.

Qdrant server-mode tests require a running Qdrant instance. Pass --qdrant-server to auto-start a Docker container:

pytest tests/integration/ -m integration --qdrant-server -v

Qdrant cloud-mode tests require environment variables:

export QDRANT_CLUSTER_ENDPOINT="https://your-cluster.qdrant.io"
export QDRANT_KEY="your-api-key"
pytest tests/integration/ -m integration -v -k Cloud

Requirements

Python >= 3.10