Gemma4 guardrails

.claude/skills/screening-azure-ops/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: screening-azure-ops
+description: Operating the Screening service's Azure infrastructure without accidentally starting a GPU. Rules for Container Apps revisions, scale-to-zero, checking what is billing, and the traps that have cost real money on this subscription. Use before ANY az containerapp command, before deploying, and whenever asked whether something is running or costing money.
+---
+
+# Screening — Azure operations
+
+The GPU app (`screening-gemma`) runs an A100 at **~€2.16/hour**. Every rule here exists
+because it was broken once and billed for it.
+
+## Rule 0 — Name the subscription explicitly in every command
+
+Without `--subscription`, every command below runs against whatever the CLI's default
+happens to be. A preflight check can then report on one subscription while the GPU is
+billing on another, which makes "nothing is running" a false negative rather than an answer.
+
+```bash
+export AZURE_SUBSCRIPTION_ID=<id>   # once per session
+```
+
+Append `--subscription "$AZURE_SUBSCRIPTION_ID"` to every `az containerapp` command in this
+file, and use the same id in the `az rest` URL. The id is not written here — this file is in
+a public repository.
+
+## Rule 1 — Check what is running BEFORE starting work, not only after
+
+Two separate incidents cost money because a session began without checking state: an A100
+left running for 1h38m (~€3.50), and an app left at `minReplicas: 1` overnight.
+
+```bash
+for a in screening-app screening-gemma; do
+  echo "$a: replicas=$(az containerapp revision list -n $a -g screening-rg --subscription "$AZURE_SUBSCRIPTION_ID" --query 'sum([].properties.replicas)' -o tsv)"
+  echo "  app-template min=$(az containerapp show -n $a -g screening-rg --subscription "$AZURE_SUBSCRIPTION_ID" --query 'properties.template.scale.minReplicas' -o tsv)"
+done
+```
+
+Both lines matter — see Rule 3.
+
+## Rule 2 — PURGE revisions before updating, never deactivate after
+
+`az containerapp update` **reactivates deactivated revisions**. A revision that was born with
+`minReplicas: 1` immediately starts a replica when reactivated. This has happened five times.
+
+Wrong:
+```bash
+az containerapp update ...                  # resurrects old revisions
+az containerapp revision deactivate ...     # clean up after noticing
+```
+
+Right:
+```bash
+# 1. find every revision carrying min>0
+az containerapp revision list -n <app> -g screening-rg \
+  --query "[].{rev:name, active:properties.active, min:properties.template.scale.minReplicas}" -o table
+# 2. deactivate those FIRST
+az containerapp revision deactivate -n <app> -g screening-rg --revision <NAME>
+# 3. then update
+# 4. then verify replicas again
+```
+
+## Rule 3 — The app template and its revisions are different things
+
+Deactivating every revision stops everything running. It does **not** change the app
+template. If the template says `minReplicas: 1`, the next revision created from it — by any
+update, for any reason — starts a replica.
+
+Fixing the template is itself an update, so it starts a GPU. Expect that and plan for it:
+either use the boot for something needed, or deactivate immediately after.
+
+## Rule 4 — `replica list` without `--revision` lies
+
+It reports only the newest revision. It once showed an empty list while an A100 billed for
+two more hours. Always use `revision list` with a `sum()`, or pass `--revision` explicitly.
+
+## Rule 5 — An interrupted command may still have run
+
+A rejected/interrupted tool call reached Azure anyway on 2026-08-10 and started an A100 that
+ran unnoticed for 1h38m. After any interrupted `az` command, **verify state** rather than
+assuming it did not execute.
+
+## Rule 6 — A new revision always boots once, even with minReplicas: 0
+
+It must prove itself healthy. On the GPU app that is a ~13 minute, ~€0.50 boot. Never create
+a revision on `screening-gemma` casually.
+
+## Verifying independently
+
+When the answer matters, check by a second path:
+
+```bash
+# every container app in the whole subscription, not just the ones you remember
+az containerapp list --query "[].{name:name, rg:resourceGroup, min:properties.template.scale.minReplicas}" -o table
+
+# actual spend, a completely separate data path
+az rest --method post \
+  --url "https://management.azure.com/subscriptions/<SUB>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" \
+  --body '{"type":"ActualCost","timeframe":"MonthToDate","dataset":{"granularity":"Daily","aggregation":{"totalCost":{"name":"Cost","function":"Sum"}},"grouping":[{"type":"Dimension","name":"ServiceName"}]}}'
+```
+
+Idle baseline for this subscription is **~€0.17–0.60/day**. A day above that means something
+ran.
+
+## Known costs
+
+| Thing | Cost |
+|---|---|
+| A100 (`Consumption NC24-A100`) | €2.16/hour, only while a replica runs |
+| Premium file share, 100 GiB @ 135 MiB/s | ~€25/month, always |
+| Everything else idle | ~€5/month |
+
+Full reasoning and measurements: `infra/gemma/README.md`.

.claude/skills/screening-conventions/SKILL.md

@@ -61,7 +61,26 @@ the framework docs can't know.
 - Config is environment-driven via `pydantic-settings` (`SCREENING_` prefix);
   `.env.example` is the committed template, `.env` is never committed.
 
-## 6. Test-first — verified, not assumed
+## 6. Docstrings — Google style, factual
+
+- **Every module, class and public function has a Google-style docstring**: a summary
+  line, then `Args:` / `Returns:` / `Raises:` for functions, `Attributes:` for models.
+- **State the property, not the incident that taught it.** "Does not raise; any
+  exception is recorded as a failed job" — not "we learned the hard way that an
+  uncaught exception leaves the job pending forever".
+- **No war stories, no dates, no measurements, no "we".** Decision records and
+  measured findings belong in `infra/*/README.md` or the commit message, where a
+  reader is looking for history. A docstring is read by someone trying to use the
+  thing.
+- **Self-contained.** Do not explain one symbol by referring to another
+  ("an enum for the same reason as NextStep"). Say what *this* one does.
+- **No prose constants.** A block of explanation assigned to a module-level string
+  is dead code, not documentation.
+- Exception to all of the above: `#` comments *inside* a function body may carry the
+  non-obvious "why", including a measurement, when the code would otherwise look
+  wrong or invite a regression.
+
+## 7. Test-first — verified, not assumed
 
 - Two tiers, and a change isn't done until the right tier is green:
   - `pytest -m "not live"` — deterministic, uses **fakes behind the ports** (canned +

.env.example

@@ -10,6 +10,18 @@ SCREENING_LLM_API_KEY=ollama
 SCREENING_LLM_MODEL=qwen2.5:3b
 SCREENING_LLM_TIMEOUT_S=60
 
+# Self-hosted Gemma-4 endpoint the guardrail calls.
+# The default points at a local vLLM. In any deployed environment this MUST be
+# set to the detector's internal FQDN (Fully Qualified Domain Name)
+SCREENING_LLM_GUARDRAIL_BASE_URL=http://localhost:8001/v1
+SCREENING_LLM_GUARDRAIL_MODEL=google/gemma-4-31B-it
+# The endpoint scales to zero, so the first request after an idle period
+# waits for a GPU to boot and load weights (~13 min). The default 60s
+# timeout is too short for that and would make the request fail before
+# the model is even ready — 15 min is ample enough to survive the activation
+# window
+SCREENING_LLM_GUARDRAIL_TIMEOUT_S=900
+
 # Confident AI (DeepEval online evals). 
 CONFIDENT_API_KEY=
 CONFIDENT_BASE_URL=https://eu.api.confident-ai.com

.gitignore

@@ -23,3 +23,4 @@ wheels/
 .agents/*
 
 .deepeval/
+.coverage

Dockerfile

@@ -17,12 +17,23 @@ COPY app ./app
 RUN useradd -m screening-user
 USER screening-user
 
-# Presidio recognizers (incl. GLiNER) lazy-load on first `.analyze()` call, not
-# at construction, so building the guardrail alone doesn't fetch GLiNER's
-# weights. Run an actual scrub so every model — spaCy, GLiNER, the injection
-# classifier — is downloaded and cached into the image before HF_HUB_OFFLINE
-# is set below; otherwise the first real request fails offline.
-RUN python -c "import asyncio; from app.adapters.guard_classifier import ClassifierGuardrail; asyncio.run(ClassifierGuardrail().scrub('warmup'))"
+# Warm the model caches into the image before HF_HUB_OFFLINE is set below;
+# otherwise the first real request fails offline. Constructing the guardrail is
+# enough: the only things that download are spaCy's en_core_web_sm and the
+# injection classifier, and both load in `ClassifierGuardrail.__init__`.
+#
+# Deliberately NOT a real `.scrub()` any more. Article 9 detection is now an
+# HTTP call to the Gemma endpoint (LLMGuardrailRecognizer), which does not exist
+# at build time, and that recognizer fails closed on purpose — so a scrub here
+# would abort the build. GLiNER, whose lazy loading was the original reason for
+# running a scrub, is gone.
+#
+# SCREENING_SERVICE_API_KEY is a build-only placeholder passed to this one
+# command (not an ENV, so it is never baked into the image): guard_classifier
+# now imports app.config transitively, and Settings refuses to construct without
+# a key.
+RUN SCREENING_SERVICE_API_KEY=build-warmup-not-a-real-secret \
+    python -c "from app.adapters.guard_classifier import ClassifierGuardrail; ClassifierGuardrail()"
 EXPOSE 8000
 
 ENV HF_HUB_OFFLINE=1