From ad5e12dd641e9cb5e25ac8c84f860bcaea8a2fe7 Mon Sep 17 00:00:00 2001 From: Sahil Sharma Date: Wed, 14 Oct 2026 15:48:04 -0400 Subject: [PATCH] Document SENTINEL_* settings and tighten README wording. --- README.md | 42 +++++++++++++++++++++++++++++------------- app/config.py | 8 +++++--- 2 files changed, 34 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3718e93..7c3ed65 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,15 @@ A thin FastAPI wrapper around [Roblox/sentinel](https://github.com/Roblox/sentin (`/score`, `/health`, `/banks/*`) instead of as a Python library you import directly. Sentinel detects rare text patterns (e.g. grooming, hate speech) via contrastive learning — comparing text -against positive (rare/harmful) and negative (common/normal) example banks. This repo doesn't change any of -that logic; it just puts a small, reviewable HTTP layer in front of it so any service in any language can -call it. +against positive (rare/harmful) and negative (common/normal) example banks. This repository places the +Sentinel library behind a lightweight HTTP layer. ## Why this exists Roblox's own [`Dockerfile`](https://github.com/Roblox/sentinel/blob/main/Dockerfile) packages the `sentinel` -library and runs example scripts — there's no HTTP service upstream. This repo installs the **unmodified -upstream library** at a pinned commit as a normal dependency, and `app/` is a small FastAPI app that imports -it, same as any other consumer of the `sentinel` package would. - -`app/` originated from [UMass-Rescue's fork](https://github.com/UMass-Rescue/Sentinel), which vendored an API -layer directly into a full clone of the library. Here it's adapted to import the **installed** `sentinel` -package instead of relative imports into a sibling source tree, and keeps Roblox's original Apache-2.0 -license headers. +library and runs example scripts — there's no HTTP service upstream. This repository installs the +**unmodified upstream library** at a pinned commit as a normal dependency, and `app/` is a small FastAPI app +that imports it, same as any other consumer of the `sentinel` package would. `app/dependencies.py` and `app/routes/scoring.py` are the files that actually reach into `sentinel`'s internals (`sentinel_local_index`, `embeddings.sbert`, `score_formulae`, `io.index_io`) — if Roblox renames @@ -32,8 +26,30 @@ docker run --rm -p 8000:8000 sentinel-api curl http://localhost:8000/health ``` -Configuration is env-driven — see `app/config.py` for the full list of `SENTINEL_*` variables (bank path, -scoring defaults, etc.). +## Configuration + +Runtime settings are read from environment variables with the `SENTINEL_` prefix (see `app/config.py`). +They are defined by this API, not by the upstream Sentinel library. Set them on the process (for Docker, +pass `-e` / `--env-file` to `docker run`). + +| Variable | Default | Meaning | +| --- | --- | --- | +| `SENTINEL_AUTO_LOAD_BANKS_PATH` | unset | Directory of a saved bank (`embeddings.safetensors` + config JSON). If set, banks are loaded at startup. | +| `SENTINEL_DEFAULT_TOP_K` | `5` | How many nearest neighbors in each bank to use when scoring a message. Overridable per request via `top_k` on `POST /score`. | +| `SENTINEL_DEFAULT_MIN_SCORE` | `0.1` | Per-message scores below this are treated as 0. Overridable per request via `min_score_to_consider` on `POST /score`. | +| `SENTINEL_DEFAULT_MIN_SIZE_OF_SCORES` | `5` | Minimum number of per-message scores needed before skewness aggregation is treated as meaningful. Passed through to Sentinel's `skewness()` as `min_size_of_scores`. Not overridable per request. | + +Example: + +```bash +docker run --rm -p 8000:8000 \ + -e SENTINEL_AUTO_LOAD_BANKS_PATH=/data/banks/my_model \ + -v /path/on/host/banks:/data/banks \ + sentinel-api +``` + +`SENTINEL_COMMIT` in the `Dockerfile` is a build argument (which upstream commit to install), not a runtime +setting. ## Upgrading the pinned commit diff --git a/app/config.py b/app/config.py index 86b3c22..daebd98 100644 --- a/app/config.py +++ b/app/config.py @@ -19,14 +19,16 @@ class Settings(BaseSettings): - """Application settings loaded from environment variables.""" + """Runtime settings from SENTINEL_* environment variables (this API, not upstream Sentinel).""" - # Bank auto-loading (e.g., /data/banks/my_model) + # SENTINEL_AUTO_LOAD_BANKS_PATH: saved-bank directory; loaded at startup if set. auto_load_banks_path: Optional[str] = None - # Scoring defaults + # SENTINEL_DEFAULT_TOP_K: nearest neighbors per bank; overridable via POST /score `top_k`. default_top_k: int = 5 + # SENTINEL_DEFAULT_MIN_SCORE: zero out weaker per-message scores; overridable via `min_score_to_consider`. default_min_score: float = 0.1 + # SENTINEL_DEFAULT_MIN_SIZE_OF_SCORES: min messages for skewness aggregation; not overridable per request. default_min_size_of_scores: int = 5 class Config: