sync: bring rag-params-finder CodeRabbit fixes onto fork main

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/<name>/` — 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/<name>/` 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.

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:**

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

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,88 @@ 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
+```
+
+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
+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
+
+**1. Gateway process alive** (`/healthz` ≠ model ready):
+
+```bash
+curl --connect-timeout 5 --max-time 15 \
+  -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz"
+# → ok
+```
+
+**2. Model can encode** — accept only HTTP **200**; retry **503** (warm-up);
+stop on terminal failures (e.g. **502**, **401**):
+
+```bash
+attempts=0
+# 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}' \
+    -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
+```
+
+**3. App sees SIE:**
 
 ```bash
-curl -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz"
 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
 ```
 
@@ -46,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:
 

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
 

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)