Ready examples

Run these examples from the repository root. Start Ollama and pull the default models before running an example:

ollama pull embeddinggemma
ollama pull gemma3:4b

Basic RAG

Example	Purpose	Command
`examples/basic/basic_rag.py`	Smallest in-memory RAG flow.	`python examples/basic/basic_rag.py`
`examples/basic/chat.py`	Interactive in-memory chat with concise provider errors.	`python examples/basic/chat.py`
`examples/basic/custom_providers.py`	Explicitly select Ollama embedding and chat providers with model names.	`python examples/basic/custom_providers.py`

Persistent SQLite RAG

Index first, then use either query example against the same database.

python examples/persistence/index_text_directory.py
python examples/persistence/query_text_index.py
python examples/persistence/query_with_providers.py

index_text_directory.py uses the bundled examples/hybrid_knowledge/ corpus by default. Pass --directory /path/to/text-files and --db my_index.db to use your own text directory and database path.

PostgreSQL + pgvector RAG

Install the optional PostgreSQL dependency and enable pgvector in the target database. Then index once and reopen the same collection for queries.

Example	Purpose	Command
`examples/postgres/index.py`	Create the managed schema and index the bundled text directory.	`python examples/postgres/index.py`
`examples/postgres/query.py`	Generate an answer using PostgreSQL hybrid retrieval.	`python examples/postgres/query.py`
`examples/postgres/search.py`	Inspect retrieval scores, metadata, and chunks without answer generation.	`python examples/postgres/search.py`
`examples/postgres/connection_factory.py`	Use an application-owned connection factory.	`python examples/postgres/connection_factory.py`
`examples/postgres/custom_schema.py`	Map required fields to application-selected PostgreSQL names.	`python examples/postgres/custom_schema.py`

See PostgreSQL + pgvector for secure connection setup, schema modes, retrieval configuration, and production operations.

Metadata indexing

Each script indexes the bundled corpus into a separate SQLite database. They are indexing examples; use a persistent query example afterwards.

Example	Metadata source	Command
`examples/metadata/index_single_file_metadata.py`	Fields supplied directly in application code.	`python examples/metadata/index_single_file_metadata.py`
`examples/metadata/index_folder_metadata.py`	Folder names and file names.	`python examples/metadata/index_folder_metadata.py`
`examples/metadata/index_csv_metadata.py`	Root-relative paths and JSON metadata in `metadata.csv`.	`python examples/metadata/index_csv_metadata.py`
`examples/metadata/index_llm_metadata.py`	A bounded file sample classified by the configured chat provider.	`python examples/metadata/index_llm_metadata.py`

The CSV manifest contains one row for every text file in its selected directory. The LLM metadata example makes one additional chat-model request per file.

Hybrid retrieval

Hybrid retrieval combines SQLite FTS5 keyword matches with vector retrieval. Index first, then query the saved database.

python examples/hybrid_retrieval/index.py
python examples/hybrid_retrieval/query.py "What does policy FIN-042 require?"

See hybrid retrieval for ranking and migration behavior.

Reranking, citations, and evaluation

Example	Purpose	Command
`examples/reranking/in_memory_evaluation.py`	Custom reranking, verified citations, Recall@k, and MRR with in-memory data.	`python examples/reranking/in_memory_evaluation.py`
`examples/reranking/hybrid_directory.py`	Directory indexing, hybrid retrieval, custom reranking, and verified citations.	`python examples/reranking/hybrid_directory.py`

The included KeywordReranker is deliberately simple and dependency-free. For a real application, replace it with a local cross-encoder or hosted reranking provider as described in reranking and verified citations.

Observability

Example	Purpose	Command
`examples/observability/rag_events.py`	Opt in to sanitized logging and application-owned JSONL event storage.	`python examples/observability/rag_events.py`

See observability and evaluation for event privacy and report details.