From 57a2c26ebbdf2ec1bf82c2d8af4b674c7a171a82 Mon Sep 17 00:00:00 2001 From: Mani Sarkar Date: Fri, 21 Aug 2026 15:35:28 +0100 Subject: [PATCH 1/4] docs(examples): address CodeRabbit review on rag-params-finder guide Export MONGODB_URI before the SIE handoff, recreate Compose for env reload, require encode readiness before sweeps, and document the gitignored input PDF prerequisite for example-sie.yaml. Co-authored-by: Cursor --- examples/rag-params-finder/getting-started.md | 10 +++- examples/rag-params-finder/sie-integration.md | 57 +++++++++++++++++-- 2 files changed, 61 insertions(+), 6 deletions(-) diff --git a/examples/rag-params-finder/getting-started.md b/examples/rag-params-finder/getting-started.md index 5dc6365b2..cad608c8b 100644 --- a/examples/rag-params-finder/getting-started.md +++ b/examples/rag-params-finder/getting-started.md @@ -49,4 +49,12 @@ Step-by-step install and first experiment: ## Next -Wire SIE and run one sweep: [SIE integration](./sie-integration.md). +Before the host CLI / SIE handoff, export the URI the startup script printed +(leave `.env` placeholders unchanged for Atlas Local): + +```bash +# value also printed by ./start-services.sh --mongodb-local +export MONGODB_URI="mongodb://localhost:27017/rag_params_finder?directConnection=true" +``` + +Then wire SIE and run one sweep: [SIE integration](./sie-integration.md). diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md index e03a07feb..e511dfd64 100644 --- a/examples/rag-params-finder/sie-integration.md +++ b/examples/rag-params-finder/sie-integration.md @@ -8,7 +8,8 @@ dashboard only — they never start SIE. ## Happy path — remote gateway (recommended) -Finish [Getting started](./getting-started.md) first so `:8001` is up. +Finish [Getting started](./getting-started.md) first so `:8001` is up and +`MONGODB_URI` is exported for the host CLI. In the project `.env`: @@ -18,20 +19,66 @@ SIE_ENDPOINT=https://your-sie-gateway.example.com SIE_API_KEY=your_gateway_token ``` -Restart or reload the rag-params-finder server after changing `.env`. +Reload the server so it picks up the new env (a plain restart is not enough for +Compose — env is baked in at container create time): -Check the gateway, then the app health: +```bash +# Compose (typical after ./start-services.sh) +docker compose up -d --force-recreate server + +# Host-run server instead: reload or restart uvicorn +``` + +Source `.env` into the **current shell** before gateway curls (editing the file +does not update existing variables): + +```bash +set -a && source .env && set +a +``` + +### Readiness checks + +**1. Gateway process alive** (`/healthz` ≠ model ready): ```bash curl -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz" +# → ok +``` + +**2. Model can encode** — wait for HTTP **200** (503 during warm-up is expected): + +```bash +until curl -sf -o /dev/null -X POST "$SIE_ENDPOINT/v1/encode/BAAI/bge-m3" \ + -H "Authorization: Bearer $SIE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"text":"readiness probe"}]}'; do + echo "SIE encode not ready yet — waiting 10s..." + sleep 10 +done +``` + +**3. App sees SIE:** + +```bash curl -s http://localhost:8001/health # → "sie":"reachable" ``` -**First success:** `"sie":"reachable"`, then one sweep: +### First success + +Provide an input PDF (`input_data/` is gitignored). Either copy a file to the +path expected by the example config, or point `data_paths` at an existing PDF: + +```bash +mkdir -p input_data/pdfs +cp /path/to/your-document.pdf \ + input_data/pdfs/The_Federal_Pell_Grant_Program.pdf +# or edit data_paths in configs/mongodb/example-sie.yaml +``` + +Then run one sweep (CLI installed per project QUICKSTART): ```bash -# from the rag-params-finder repo root, with CLI installed (see project QUICKSTART) rag-params-finder run --config configs/mongodb/example-sie.yaml ``` From 05290bdf5b7146afb28ff77f79c186b90de05e4f Mon Sep 17 00:00:00 2001 From: Mani Sarkar Date: Fri, 21 Aug 2026 15:49:49 +0100 Subject: [PATCH 2/4] docs(examples): preserve MONGODB_URI and bound encode wait Avoid sourcing .env wholesale (it clobbers the host CLI Atlas Local URI) and stop the encode readiness loop on terminal HTTP failures. Co-authored-by: Cursor --- examples/rag-params-finder/sie-integration.md | 40 ++++++++++++++----- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md index e511dfd64..29d0d7561 100644 --- a/examples/rag-params-finder/sie-integration.md +++ b/examples/rag-params-finder/sie-integration.md @@ -29,11 +29,15 @@ docker compose up -d --force-recreate server # Host-run server instead: reload or restart uvicorn ``` -Source `.env` into the **current shell** before gateway curls (editing the file -does not update existing variables): +Load only SIE vars into the **current shell** before gateway curls (do not +`source .env` wholesale — that overwrites the host CLI `MONGODB_URI` export +from [Getting started](./getting-started.md) with the Atlas placeholder): ```bash -set -a && source .env && set +a +export SIE_ENABLED=true +export SIE_ENDPOINT=https://your-sie-gateway.example.com +export SIE_API_KEY=your_gateway_token +# keep the earlier MONGODB_URI export for Atlas Local host CLI ``` ### Readiness checks @@ -41,18 +45,34 @@ set -a && source .env && set +a **1. Gateway process alive** (`/healthz` ≠ model ready): ```bash -curl -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz" +curl --connect-timeout 5 --max-time 15 \ + -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz" # → ok ``` -**2. Model can encode** — wait for HTTP **200** (503 during warm-up is expected): +**2. Model can encode** — accept only HTTP **200**; retry **503** (warm-up); +stop on terminal failures (e.g. **502**, **401**): ```bash -until curl -sf -o /dev/null -X POST "$SIE_ENDPOINT/v1/encode/BAAI/bge-m3" \ - -H "Authorization: Bearer $SIE_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{"items":[{"text":"readiness probe"}]}'; do - echo "SIE encode not ready yet — waiting 10s..." +attempts=0 +max_attempts=60 # ~10 minutes at 10s interval +while true; do + attempts=$((attempts + 1)) + code=$(curl --connect-timeout 5 --max-time 30 -s -o /dev/null -w '%{http_code}' \ + -X POST "$SIE_ENDPOINT/v1/encode/BAAI/bge-m3" \ + -H "Authorization: Bearer $SIE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"items":[{"text":"readiness probe"}]}' || true) + case "$code" in + 200) echo "SIE encode ready"; break ;; + 503) echo "SIE warm-up ($attempts/$max_attempts) — waiting 10s..." ;; + 000) echo "SIE unreachable ($attempts/$max_attempts) — waiting 10s..." ;; + *) echo "SIE encode failed with HTTP $code — abort"; exit 1 ;; + esac + if [ "$attempts" -ge "$max_attempts" ]; then + echo "SIE encode not ready after $max_attempts attempts — abort" + exit 1 + fi sleep 10 done ``` From 2ae9b5f402551134ba1f8b7f3bcbdf647f20f9e6 Mon Sep 17 00:00:00 2001 From: Mani Sarkar Date: Fri, 21 Aug 2026 15:52:22 +0100 Subject: [PATCH 3/4] docs(examples): apply tripwire gallery lessons to rag-params-finder Port CodeRabbit patterns from #244: separate local vs optional SIE paths, encode/score primitive naming, config-specific Mongo indexes, and an external-guide submission path in the gallery README. Co-authored-by: Cursor --- examples/README.md | 18 ++++++++++++++++-- examples/rag-params-finder/README.md | 7 ++++--- examples/rag-params-finder/troubleshooting.md | 9 ++++++--- examples/rag-params-finder/what-sie-does.md | 2 +- 4 files changed, 27 insertions(+), 9 deletions(-) diff --git a/examples/README.md b/examples/README.md index 476b21a93..9bed844f3 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,6 +1,10 @@ # Examples -A project gallery of full end-to-end applications built with SIE. Each project lives in its own subdirectory. Clone it, run it, learn from it. +A project gallery of full end-to-end applications built with SIE. Most entries +are self-contained under `examples//` — clone this repo, run them locally, +and learn from them. Rows marked **External project guide** are docs-only +landings that deep-link to a separately maintained repository (clone and run +there). New to SIE? Start with the **[quickstart notebook](./quickstart.ipynb)** [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/superlinked/sie/blob/main/examples/quickstart.ipynb): encode, score, and extract in 5 minutes, then pick a project below. @@ -43,14 +47,24 @@ benchmark and evaluation examples for deeper technical users. We welcome contributions. To add your project to the gallery: +### Runnable examples (default) + 1. **Create a subdirectory** with a short, descriptive name (e.g. `wikipedia-search/`, `pdf-rag/`) 2. **Include a README** that covers: - What the project does - How to run it (`docker compose up`, a script, etc.) - Which SIE features it uses (encode, score, extract, cluster, etc.) -3. **Keep it self-contained** - include a `requirements.txt` or `package.json`, a docker-compose if needed, and sample data or instructions to fetch it +3. **Keep it self-contained** — include a `requirements.txt` or `package.json`, a docker-compose if needed, and sample data or instructions to fetch it 4. **Open a PR** against `main` +### External project guides + +Use this path only when vendoring a runnable copy is impractical (large multi-service +apps). Ship a thin `examples//` landing (README + short sibling pages) that +deep-links to the external repo’s QUICKSTART/SIE setup, set Status to +**External project guide**, and do **not** require in-tree `requirements.txt` / +compose / sample data. See `examples/rag-params-finder/` for the shape. + ### Review workflow Maintainers apply the `coderabbit-direct` label to eligible PRs that change content under `examples/**` or the root `README.md`. The label opts the PR into CodeRabbit review and allows CodeRabbit to formally approve it once review comments are resolved and required checks pass. diff --git a/examples/rag-params-finder/README.md b/examples/rag-params-finder/README.md index b1f9708cb..bbc162d2a 100644 --- a/examples/rag-params-finder/README.md +++ b/examples/rag-params-finder/README.md @@ -17,14 +17,15 @@ optional `score` (SIE rerank). SIE is **opt-in** — the default stack runs with | New to SIE, found this in the gallery | [Getting started](./getting-started.md) → [SIE integration](./sie-integration.md) | | New to rag-params-finder, want SIE embeddings | Same path — then [What SIE does here](./what-sie-does.md) | -Both audiences share one happy path: local MongoDB stack → enable a remote SIE -gateway → one `example-sie.yaml` sweep → dashboard. +Both audiences share the same **local** starting path (MongoDB stack + +dashboard). SIE is optional afterward: enable a remote gateway, then run one +`example-sie.yaml` sweep. ## Start here 1. [Getting started](./getting-started.md) — clone, prereqs, local Mongo path, dashboard 2. [SIE integration](./sie-integration.md) — env vars, health checks, first SIE sweep -3. [What SIE does here](./what-sie-does.md) — models, encode/rerank, vs Voyage/local +3. [What SIE does here](./what-sie-does.md) — models, encode/score, vs Voyage/local 4. [Troubleshooting](./troubleshooting.md) — short FAQ + deep-links **Canonical docs in the project:** diff --git a/examples/rag-params-finder/troubleshooting.md b/examples/rag-params-finder/troubleshooting.md index 7dc094765..e0130e3ad 100644 --- a/examples/rag-params-finder/troubleshooting.md +++ b/examples/rag-params-finder/troubleshooting.md @@ -20,9 +20,12 @@ Short FAQ for gallery readers. Full tables and recovery steps: ## Sweep with `provider: sie` fails immediately -SIE guard runs preflight. Fix health/`SIE_ENABLED` first, then re-run. Confirm -indexes for your storage backend (`vector_index_1024` + text index on Mongo for -typical SIE configs — see project MongoDB setup). +SIE guard runs preflight. Fix health/`SIE_ENABLED` first, then re-run. Index +requirements come from the **selected config**, not from `provider: sie` alone. +For [`configs/mongodb/example-sie.yaml`](https://github.com/neomatrix369/rag-params-finder/blob/main/configs/mongodb/example-sie.yaml) +(dense BGE-M3 / Stella-v5), create `vector_index_1024` and `text_search_index` +on Mongo — see project MongoDB setup. Sparse-only models can need different +indexes; do not treat `vector_index_1024` as universal. ## `./start-services.sh` did not bring up SIE diff --git a/examples/rag-params-finder/what-sie-does.md b/examples/rag-params-finder/what-sie-does.md index 56e69dd0f..4b24b8ca7 100644 --- a/examples/rag-params-finder/what-sie-does.md +++ b/examples/rag-params-finder/what-sie-does.md @@ -47,7 +47,7 @@ You can compare providers across sweeps; SIE does not replace the vector store Your corpus + questions │ ▼ -rag-params-finder server ──encode/rerank──► SIE (remote or :8720) +rag-params-finder server ──encode/score──► SIE (remote or :8720) │ ▼ MongoDB / Postgres (vectors + scores) From af93dac4d45c499f631cf4168d006b6e8c01dacb Mon Sep 17 00:00:00 2001 From: Mani Sarkar Date: Fri, 21 Aug 2026 15:57:28 +0100 Subject: [PATCH 4/4] docs(examples): fix encode wait bound and HF_TOKEN wording Align the readiness-loop comment with the real ~40m worst-case budget, and state that self-hosted SIE requires HF_TOKEN for model downloads. Co-authored-by: Cursor --- examples/rag-params-finder/sie-integration.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md index 29d0d7561..a7a1d9d34 100644 --- a/examples/rag-params-finder/sie-integration.md +++ b/examples/rag-params-finder/sie-integration.md @@ -55,7 +55,9 @@ stop on terminal failures (e.g. **502**, **401**): ```bash attempts=0 -max_attempts=60 # ~10 minutes at 10s interval +# 60 attempts × (up to 30s request + 10s sleep) ≈ 40 minutes worst case — +# first-run model download/load can exceed a short 10-minute budget. +max_attempts=60 while true; do attempts=$((attempts + 1)) code=$(curl --connect-timeout 5 --max-time 30 -s -o /dev/null -w '%{http_code}' \ @@ -113,7 +115,8 @@ Compare results in the dashboard at **http://localhost:5374**. ## Alternate — self-hosted Docker Use when you have no remote gateway. Needs Docker, disk for model weights, and -usually `HF_TOKEN` on the **SIE container** (not for app routing). +**requires** `HF_TOKEN` on the **SIE container** for Hugging Face weight +downloads during warm-up (not used for app routing). Typical host endpoint: