Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 29 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
8 changes: 5 additions & 3 deletions app/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading