Examples#
examples/ in the repository is a runnable, numbered walk through the whole
SDK — ingest → index → retrieve → rerank → query → stream → serve → ask →
benchmark — each file introducing one new piece and reusing everything the
previous ones already built. Examples 01–16 read execution-time environment
overrides through examples/_runtime.py; defaults target the Compose services
and public sitemap. Use an isolated cache schema and collection for local smoke
runs. The Docling scripts also accept execution-time XLSX and vision settings.
The AgrospAI fetching script separately exposes CLI/environment configuration;
querying loads its adjacent dotenv at execution without replacing existing
environment values and shares fetching’s runtime configuration.
See Development setup for repository service prerequisites.
cp .env.example .env # optional; the defaults match Compose
docker compose up -d
task index # or: uv run python examples/05_indexing.py
The indexing examples run entirely against the Compose stack — PostgreSQL
for the cache, Milvus for the vectors, and Model2VecEmbedder computing
embeddings in-process — no API key, no remote endpoint. The querying and
serving examples add Ollama, which Compose also starts and pre-pulls.
File |
Subject |
|---|---|
|
A |
|
Feed fetched sources into an |
|
Chunk a parsed document with |
|
Embed the chunks with |
|
The whole fetch → parse → chunk → embed → |
|
The same pipeline under |
|
The raw |
|
A |
|
|
|
|
|
|
|
Retrieve context, render a |
|
Render retrieved context, then stream |
|
Serve the grounded-answer API on |
|
The |
|
A chunk-size sweep scored with retrieval metrics, saved and compared. |
|
|
|
The same XLSX chunked two ways: |
The two docling/ scripts stand outside the numbered sequence: each is
self-contained (FileSource(cache=False)), needs no docker compose up -d,
and demonstrates the optional docling extra’s DoclingParser/
DoclingChunker on a real spreadsheet rather than building on the example
before it. parse_xlsx.py is the one exception to “no services”: describing
the spreadsheet’s images needs an OpenAI-compatible vision endpoint, read
from FASTRAG_VISION_BASE_URL, FASTRAG_VISION_API_KEY and FASTRAG_VISION_MODEL (defaults use local Ollama).
Run any pipeline example twice to see the shape caching is supposed to have:
run 1: fetched 20 / cached 0 | parsed 20 / cached 0 | chunked N / cached 0
run 2: fetched 0 / cached 20 | parsed 0 / cached 20 | chunked 0 / cached N
Parse and chunk are keyed on content, not URI (Caching), so two sources that happen to fetch the same bytes from two different hosts parse them exactly once between the two.
examples runs against whatever is on disk in src/ (the package is
installed editable by uv sync), which is what makes CI catch a public-API
break before a release ships one.
See also#
Quickstart for the same shape compressed into one file;
Serving for what 14_serving.py and 15_asking.py build on.
Structural alternative#
The sequence retains the character-splitter baseline for comparison. For exact embedding budgets, source maps and parent context, see Structure-aware ingestion; replace the chunking stage while preserving the rest of the lazy graph. The AgrospAI fetching script now defaults to structural chunks and indexes unless an explicit inspection checkpoint is selected. Remote fixture sites and provider availability are separate from SDK correctness; the final example smoke workflow must exercise the same main paths with bounded local inputs and isolated destinations.
Execution-time overrides#
These examples retain the real SDK crawler, parser, splitter, Model2Vec, store and retrieval paths. They fail on empty ingestion output or missing retrieved context; logger examples require successful destination events. Provider failures are surfaced. Importing an example does not run its main.
Environment variable |
Purpose / default |
|---|---|
|
Public AgrospAI sitemap; select a fixture sitemap for smoke runs. |
|
Second crawler root for 08/09; defaults to Pontus-X docs. |
|
Positive finite crawler limit, default 200. |
|
PostgreSQL endpoint / cache namespace. |
|
Milvus endpoint / explicit collection, default |
|
Model2Vec model, default |
|
|
|
URL regex for the Docusaurus route in 09; defaults to any host’s |
|
Retrieval/chat question, default “What is AgrospAI?”. |
|
OpenAI-compatible chat endpoint/model/key for 12–14 and the optional benchmark judge. |
|
Cohere-compatible rerank endpoint/model/key for 11. |
|
Positive operation/provider timeout in seconds, default 60; ingestion retries are zero. |
Reuse the same collection and local embedding model when running 10–15 after
05. These examples do not delete collections or schemas. The service-backed
regression in tests/test_example_runtime.py executes original indexing,
logging and retrieval mains against generated test namespaces and the fixture
HTTP site, then independently checks stored vectors and source URLs. The tests in tests/test_remaining_example_runtime.py additionally execute
server health/authenticated SSE, the real interactive CLI, separate benchmark
collections and both pictured XLSX mains.
Additional environment variable |
Purpose / default |
|---|---|
|
14 bind address, default |
|
14 Postgres chat namespace, default |
|
Optional nonnegative lifetime; zero serves until interrupted. |
|
15 backend / owned token location; default backend |
|
Distinct integers >=2, comma separated; default |
|
16 QA JSON path / results directory. |
|
Docling workbook URL / positive displayed chunk limit (default 3). |
|
Explicit remote vision service for pictured XLSX; default local Ollama/llava. |
16 opens <FASTRAG_COLLECTION>_recursive_<size> for each configuration. Its
retriever reads that same store; the save fingerprint does not select the
collection. Each run requires nonempty successful results without errored or
incomplete samples. Comparison uses only results from the current sweep. The optional --judge phase
uses TokenOverlap/Faithfulness/Latency; the SDK chat contract returns plaintext,
so token usage is unavailable and no token counts are fabricated.
Owned local smoke workflow#
From the SDK root, after installing all extras:
.venv/bin/python scripts/test_services.py start
.venv/bin/python scripts/test_services.py probe
.venv/bin/python scripts/example_smoke.py
The workflow invokes all 20 original script entry points, and runs fetching again for warm replay and its compatible OpenAI-embedding path in a separate collection. It starts a loopback fixture site and generated workbook with an embedded picture, plus deterministic compatible chat/SSE/vision/embedding/rerank HTTP APIs. These APIs validate protocol plumbing, not model quality. The numbered embedding examples and AgrospAI pipeline use actual local Model2Vec weights; PostgreSQL, Milvus, Docling and the optional browser renderer remain real.
Unique UUID-owned schemas/collections, benchmark destinations, token file and
results are torn down after each run, including failures. Service containers stay
available for other tests. The workflow never selects default collections or
production providers. Every script subprocess has a finite timeout; 14 must pass
health and authenticated source/text/end SSE, 15 consumes a scripted question and
/quit, and 14 must exit cleanly when its lifetime expires.
Select any original path using --only (repeatable); required indexing is performed
automatically. Browser fetching can be exercised with the installed Playwright
browser via --renderer browser:
.venv/bin/python scripts/example_smoke.py --only examples/09_filters.py --renderer browser
.venv/bin/python scripts/example_smoke.py --only examples/docling/parse_xlsx.py
.venv/bin/python scripts/example_smoke.py --only examples/14_serving.py --only examples/15_asking.py
These local fixture runs complement real external-site/provider attempts; they do not establish the availability or answer quality of external services.