argus-cortex 0.3.0__tar.gz → 0.4.1__tar.gz

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/.github/workflows/release.yml

@@ -78,3 +78,43 @@ jobs:
           name: dist
           path: dist/
       - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    # The GitHub Release is the last step, so it only appears once the version is
+    # actually on PyPI. Its notes are this version's CHANGELOG.md section.
+    # Gated on publish-pypi's own result, not the default success(): publish-pypi
+    # runs even when the TestPyPI rehearsal failed, and that must not skip this.
+    runs-on: ubuntu-latest
+    needs: publish-pypi
+    if: "!cancelled() && needs.publish-pypi.result == 'success'"
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract release notes from CHANGELOG.md
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v head="## [${version}]" 'index($0, head) == 1 {found = 1; next} found && /^## \[/ {exit} found' \
+            CHANGELOG.md > notes.md
+          if ! grep -q '[^[:space:]]' notes.md; then
+            echo "::error::CHANGELOG.md has no section for ${version}"
+            exit 1
+          fi
+      - name: Create or update the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          prerelease=""
+          case "$tag" in *-*|*rc*|*a[0-9]*|*b[0-9]*) prerelease="--prerelease" ;; esac
+          if gh release view "$tag" >/dev/null 2>&1; then
+            # Re-run of the workflow: refresh notes and assets rather than failing.
+            gh release edit "$tag" --notes-file notes.md
+            gh release upload "$tag" dist/* --clobber
+          else
+            gh release create "$tag" dist/* --verify-tag --title "$tag" --notes-file notes.md $prerelease
+          fi

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-27
+
+### Added
+- `SingGuardClient(thinking="slow")` and `thinking="cascade"`: the argus-cull
+  `singguard` service's modes. `slow` reasons with no fast first-line verdict,
+  so the reasoning is not anchored to a verdict made before it; `cascade` runs
+  `fast` on every image and `slow` only on the ones fast flags, and slow's
+  verdict stands. `THINKING_MODES` lists them. A SingGuard server without a
+  mode answers HTTP 400, raised as `GuardCheckFailed` per check.
+- `GuardResult.thinking`: the mode the server says it judged in (`None` from a
+  server that does not say). The argus-cull service can be forced server-side
+  to a mode other than the one asked for, and this records which it used.
+
+## [0.4.0] - 2026-10-26
+
+### Added
+- **`argus_cortex.moderation`** — content-moderation clients shared by the
+  stages, hoisted from argus-curator. Both talk HTTP to a server the deployer
+  runs; nothing imports a detector.
+  - `NudeNetClient(base_url, timeout)` — a NudeNet server's `/infer`, returning
+    `NsfwResult` (detections, highest score per class, exposed score) and
+    raising `NudeNetCheckFailed` per image. `NudeNetLabel` / `NUDENET_LABELS`
+    are NudeNet's 18 classes; `DEFAULT_EXPOSED_LABELS` (the five exposed
+    buttocks/breast/genitalia/anus classes) and `exposed_score()` are the
+    suite's one definition of nudity.
+  - `SingGuardClient(base_url, timeout, thinking, policy, downscale)` — a
+    SingGuard server's `/api/guard/check`, returning `GuardResult` (verdict,
+    the rules that fired, explanation, model, policy name) and raising
+    `GuardCheckFailed`. `rule_matches()` / `rule_letter()` match rules by
+    letter or full name; `policy_name()` names a custom policy by a sha256
+    prefix.
+  - Proxies in the environment are ignored: images go only to the configured
+    server. Config errors (`ModerationConfigError`) never echo the URL. A
+    `user:password@` in the URL is sent as HTTP Basic auth.
+- `[images]` extra (Pillow), for `SingGuardClient`'s downscaling of images
+  over 1536 px / 4 MB; imported only when it downscales. Downscaling is on by
+  default, so without the extra `SingGuardClient(...)` raises
+  `ModerationConfigError` at construction unless given `downscale=False`.
+
+### Changed
+- `release.yml` now creates the **GitHub Release** for each `v*` tag once the
+  version is on PyPI, with that version's `CHANGELOG.md` section as notes and
+  the built sdist/wheel attached (a missing section fails the job; a re-run
+  edits the Release). Tags with `-`, `rc`, `a<n>` or `b<n>` are pre-releases.
+
 ## [0.3.0] - 2026-10-25
 
 ### Added
@@ -71,7 +116,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     (`LocalBackend`, `RemoteBackend`, `RemoteProvider`, `with_retries`
     retrying only transient errors, `resolve_device`).
 
-[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/smk762/argus-cortex/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/smk762/argus-cortex/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/smk762/argus-cortex/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/smk762/argus-cortex/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/smk762/argus-cortex/releases/tag/v0.1.0

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/CLAUDE.md

@@ -19,6 +19,7 @@ Because everything here is imported by the downstream stages, **a change ripples
 - `backends.py` — the AI-backend contract: `Backend`/`LocalBackend`/`RemoteBackend` (point at a hosted service via `from_host(host, port)` or `from_provider(RemoteProvider.…)`), plus `with_retries()` and `resolve_device()`. httpx is lazy, behind `[remote]`.
 - `server.py` — the shared FastAPI/ASGI scaffolding other repos' micro-servers mount: `WriteGuard` (pure-ASGI method gate), the `constant_refuse()` (read-only/replay) and `cross_site_refuse()` (cross-origin write) predicates, `env_flag()`, and the `UNSAFE_METHODS`/`TRUTHY`/`FALSY` constants. Starlette is behind `[server]`.
 - `xmp.py` — the suite's XMP sidecar read/merge/write (`write_xmp`/`read_xmp`/`merge_xmp`/`parse_xmp`, `XmpData`/`XmpRegions`, `XmpError`), used by lens (keywords/caption) and curator (faces, content rating). Stdlib `xml.etree` only. **Writes merge — latest wins per property, foreign properties preserved; keep that.** `None` = leave untouched, empty = remove. A DTD is refused and an unparseable sidecar raises rather than being overwritten. The `argus` namespace URI is a wire contract — don't change it.
+- `moderation/` — content-moderation clients over HTTP: `nudenet.py` (`NudeNetClient`, `NsfwResult`, `DEFAULT_EXPOSED_LABELS` — **the suite's one definition of nudity; don't widen it casually**, every stage's NSFW numbers move with it), `singguard.py` (`SingGuardClient`, `GuardResult`, `rule_matches`), `_http.py` (shared POST, proxy-free opener, `CheckFailed`/`ModerationConfigError`). Stdlib + pydantic; Pillow lazily, behind `[images]`. Never import NudeNet (AGPL) — HTTP only. URLs are passed in; stages own their env config.
 - `store/` — the optional stateful-services layer, opt-in per `CORTEX_*` env var: `lineage.py` (Phase 1 Postgres DAG, `open_lineage_store()`), `vector.py` (Phase 2 Qdrant, `open_vector_store()`), `blob.py` (Phase 3 MinIO/S3, `open_blob_store()`), over `config.py`/`models.py`/`errors.py`. Each `open_*()` returns a `Null*` no-op when its URL is unset. Drivers are behind `[postgres]`/`[qdrant]`/`[s3]`.
 
 There is **no CLI and no committed schema in this repo** — the `schema`/`schema --check` pattern is something `wire.py` *enables* for downstream repos, not something cortex runs on itself.

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.3.0
+Version: 0.4.1
 Summary: Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract
 Project-URL: Repository, https://github.com/smk762/argus-cortex
 Author: smk762
@@ -20,12 +20,15 @@ Requires-Dist: certifi>=2026.10.19; extra == 'dev'
 Requires-Dist: httpx2>=2.7; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: minio>=7.2; extra == 'dev'
+Requires-Dist: pillow>=10.0; extra == 'dev'
 Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: qdrant-client>=1.10; extra == 'dev'
 Requires-Dist: ruff==0.15.16; extra == 'dev'
 Requires-Dist: starlette>=0.37; extra == 'dev'
+Provides-Extra: images
+Requires-Dist: pillow>=10.0; extra == 'images'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'postgres'
 Provides-Extra: qdrant
@@ -54,6 +57,7 @@ Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (q
 - **`argus_cortex.backends`** — the AI-backend contract generalised from argus-lens: `Backend` / `LocalBackend` / `RemoteBackend` (point at a hosted service by `base_url`, `host`/`port`, or a known `RemoteProvider`), plus `with_retries()` and `resolve_device()`. httpx lives behind the `[remote]` extra.
 - **`argus_cortex.server`** — shared write-guard + env-flag scaffolding for the suite's FastAPI micro-servers: `WriteGuard` (a pure-ASGI method-gate that never buffers streaming responses), the `constant_refuse()` / `cross_site_refuse()` predicates (read-only/replay mode and cross-site-write protection are two configs of the one guard), the `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants, and `env_flag()` (warns on a mistyped protection flag rather than silently disabling it). Starlette lives behind the `[server]` extra.
 - **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib only.
+- **`argus_cortex.moderation`** — the suite's content-moderation clients, over HTTP to servers the deployer runs (nothing here imports a detector): `NudeNetClient` (a NudeNet server's `/infer` → `NsfwResult`: detections, per-class maxima, and an **exposed score**) and `SingGuardClient` (a SingGuard server's `/api/guard/check` → `GuardResult`: verdict, the policy rules that fired, explanation; optional custom policy text). `DEFAULT_EXPOSED_LABELS` is the suite's **one definition of nudity**: the five exposed buttocks/breast/genitalia/anus classes — faces, covered parts, and bare feet, belly, armpits or male chest never count. Stdlib + pydantic; Pillow (for SingGuard's downscaling of large images, on by default) is behind `[images]`: without it `SingGuardClient(...)` raises `ModerationConfigError` at construction unless given `downscale=False`. A `user:password@` in a URL is sent as HTTP Basic auth. URLs are passed in, never read from the environment here: each stage owns its config. NudeNet itself is AGPL-3.0, which is why it stays behind an HTTP boundary.
 - **`argus_cortex.store`** — the optional **stateful services layer** (the suite's persistent "memory"). External and opt-in — every store is configured by `CORTEX_*` env vars and no-ops when its URL is unset.
   - **Phase 1 — Postgres lineage store.** Persists the `source_asset → caption → human_edit → dataset_membership → training_run` DAG for LoRA reproducibility, edit capture, and the feedback loop. Backed by a psycopg connection **pool** (concurrent `asyncio.to_thread` calls are safe; a dropped connection is replaced), with a `transaction()` boundary for atomic multi-step writes. `open_lineage_store()` returns a no-op store when `CORTEX_PG_URL` is unset; psycopg lives behind the `[postgres]` extra.
   - **Phase 2 — Qdrant vector store.** Stores image + tag-set embeddings for retrieval-augmented few-shot and near-duplicate curation; put a `caption_id`/`asset_id` in a point's payload and a search hit joins straight back to the lineage. `open_vector_store()` no-ops when `CORTEX_QDRANT_URL` is unset; qdrant-client lives behind the `[qdrant]` extra. cortex stores vectors it's *handed* — computing embeddings is the caller's job.
@@ -87,6 +91,24 @@ write_xmp(
 )
 ```
 
+```python
+from argus_cortex.moderation import NudeNetClient, SingGuardClient, rule_matches
+
+nudenet = NudeNetClient("http://nudenet:8080")                  # its origin; /infer is appended
+result = nudenet.check(image_bytes, "beach.jpg")
+result.exposed_score    # 0.0-1.0 over DEFAULT_EXPOSED_LABELS; result.labels = per-class maxima
+
+guard = SingGuardClient("http://guard:9150", policy=None)  # None = SingGuard's default rules
+# thinking="fast" (default) is a verdict and rule; "fast-slow" also writes why; "slow" writes why
+# with no fast verdict ahead of the reasoning; "cascade" is fast, then slow only for what fast
+# flagged (the last two: argus-cull's singguard service only).
+verdict = guard.check(image_bytes, text="the prompt, if any")
+verdict.safe, verdict.rules   # False, ["B. Real-World Crimes & Public Safety"]
+any(rule_matches(r, "B") for r in verdict.rules)   # match a rule by letter or full name
+```
+
+Each `check()` raises `CheckFailed` (`NudeNetCheckFailed` / `GuardCheckFailed`) for a network error or an unusable answer, so a caller checking many images can record "unchecked" against the one image — and should treat unchecked as *not* safe. Bad configuration raises `ModerationConfigError`, whose message never echoes the URL.
+
 ```python
 from argus_cortex.store import open_lineage_store, SourceAsset, Caption, HumanEdit
 

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/README.md

@@ -11,6 +11,7 @@ Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (q
 - **`argus_cortex.backends`** — the AI-backend contract generalised from argus-lens: `Backend` / `LocalBackend` / `RemoteBackend` (point at a hosted service by `base_url`, `host`/`port`, or a known `RemoteProvider`), plus `with_retries()` and `resolve_device()`. httpx lives behind the `[remote]` extra.
 - **`argus_cortex.server`** — shared write-guard + env-flag scaffolding for the suite's FastAPI micro-servers: `WriteGuard` (a pure-ASGI method-gate that never buffers streaming responses), the `constant_refuse()` / `cross_site_refuse()` predicates (read-only/replay mode and cross-site-write protection are two configs of the one guard), the `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants, and `env_flag()` (warns on a mistyped protection flag rather than silently disabling it). Starlette lives behind the `[server]` extra.
 - **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib only.
+- **`argus_cortex.moderation`** — the suite's content-moderation clients, over HTTP to servers the deployer runs (nothing here imports a detector): `NudeNetClient` (a NudeNet server's `/infer` → `NsfwResult`: detections, per-class maxima, and an **exposed score**) and `SingGuardClient` (a SingGuard server's `/api/guard/check` → `GuardResult`: verdict, the policy rules that fired, explanation; optional custom policy text). `DEFAULT_EXPOSED_LABELS` is the suite's **one definition of nudity**: the five exposed buttocks/breast/genitalia/anus classes — faces, covered parts, and bare feet, belly, armpits or male chest never count. Stdlib + pydantic; Pillow (for SingGuard's downscaling of large images, on by default) is behind `[images]`: without it `SingGuardClient(...)` raises `ModerationConfigError` at construction unless given `downscale=False`. A `user:password@` in a URL is sent as HTTP Basic auth. URLs are passed in, never read from the environment here: each stage owns its config. NudeNet itself is AGPL-3.0, which is why it stays behind an HTTP boundary.
 - **`argus_cortex.store`** — the optional **stateful services layer** (the suite's persistent "memory"). External and opt-in — every store is configured by `CORTEX_*` env vars and no-ops when its URL is unset.
   - **Phase 1 — Postgres lineage store.** Persists the `source_asset → caption → human_edit → dataset_membership → training_run` DAG for LoRA reproducibility, edit capture, and the feedback loop. Backed by a psycopg connection **pool** (concurrent `asyncio.to_thread` calls are safe; a dropped connection is replaced), with a `transaction()` boundary for atomic multi-step writes. `open_lineage_store()` returns a no-op store when `CORTEX_PG_URL` is unset; psycopg lives behind the `[postgres]` extra.
   - **Phase 2 — Qdrant vector store.** Stores image + tag-set embeddings for retrieval-augmented few-shot and near-duplicate curation; put a `caption_id`/`asset_id` in a point's payload and a search hit joins straight back to the lineage. `open_vector_store()` no-ops when `CORTEX_QDRANT_URL` is unset; qdrant-client lives behind the `[qdrant]` extra. cortex stores vectors it's *handed* — computing embeddings is the caller's job.
@@ -44,6 +45,24 @@ write_xmp(
 )
 ```
 
+```python
+from argus_cortex.moderation import NudeNetClient, SingGuardClient, rule_matches
+
+nudenet = NudeNetClient("http://nudenet:8080")                  # its origin; /infer is appended
+result = nudenet.check(image_bytes, "beach.jpg")
+result.exposed_score    # 0.0-1.0 over DEFAULT_EXPOSED_LABELS; result.labels = per-class maxima
+
+guard = SingGuardClient("http://guard:9150", policy=None)  # None = SingGuard's default rules
+# thinking="fast" (default) is a verdict and rule; "fast-slow" also writes why; "slow" writes why
+# with no fast verdict ahead of the reasoning; "cascade" is fast, then slow only for what fast
+# flagged (the last two: argus-cull's singguard service only).
+verdict = guard.check(image_bytes, text="the prompt, if any")
+verdict.safe, verdict.rules   # False, ["B. Real-World Crimes & Public Safety"]
+any(rule_matches(r, "B") for r in verdict.rules)   # match a rule by letter or full name
+```
+
+Each `check()` raises `CheckFailed` (`NudeNetCheckFailed` / `GuardCheckFailed`) for a network error or an unusable answer, so a caller checking many images can record "unchecked" against the one image — and should treat unchecked as *not* safe. Bad configuration raises `ModerationConfigError`, whose message never echoes the URL.
+
 ```python
 from argus_cortex.store import open_lineage_store, SourceAsset, Caption, HumanEdit
 

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/pyproject.toml

@@ -32,6 +32,9 @@ s3 = ["minio>=7.2", "certifi>=2026.10.19"]
 # (argus_cortex.server). Starlette ships with FastAPI, so consumers already have
 # it via their own [server] extra.
 server = ["starlette>=0.37"]
+# Pillow, for SingGuardClient's downscaling of large images
+# (argus_cortex.moderation.singguard), imported only when it downscales.
+images = ["pillow>=10.0"]
 # The store drivers are in dev so each store's real client path (pool/enum/client
 # construction, error wrapping) is exercised in CI, not just via fakes.
 # starlette + httpx power the pure-ASGI guard tests (Starlette TestClient).
@@ -45,6 +48,7 @@ dev = [
     "starlette>=0.37",
     "httpx>=0.27",
     "httpx2>=2.7",
+    "pillow>=10.0",
     "certifi>=2026.10.19",
 ]
 

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/src/argus_cortex/__init__.py

@@ -23,6 +23,14 @@ from argus_cortex.backends import (
     resolve_device,
     with_retries,
 )
+from argus_cortex.moderation import (
+    CheckFailed,
+    GuardResult,
+    ModerationConfigError,
+    NsfwResult,
+    NudeNetClient,
+    SingGuardClient,
+)
 from argus_cortex.store import (
     IMAGE_COLLECTION,
     TAGSET_COLLECTION,
@@ -102,6 +110,13 @@ __all__ = [
     "RemoteProvider",
     "resolve_device",
     "with_retries",
+    # moderation clients (NudeNet, SingGuard over HTTP)
+    "CheckFailed",
+    "GuardResult",
+    "ModerationConfigError",
+    "NsfwResult",
+    "NudeNetClient",
+    "SingGuardClient",
     # store (optional stateful services layer)
     "StoreConfig",
     "StoreError",

{argus_cortex-0.3.0 → argus_cortex-0.4.1}/src/argus_cortex/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
 __commit_id__ = commit_id = None

argus_cortex-0.4.1/src/argus_cortex/moderation/__init__.py

@@ -0,0 +1,50 @@
+"""Content-moderation clients the stages share: NudeNet and SingGuard over HTTP.
+
+Each client talks to a server the deployer runs; nothing here imports a
+detector. Stdlib + pydantic only (Pillow, for SingGuard's downscaling, is
+behind the ``[images]`` extra and imported only when used). Configuration is
+the caller's: each stage reads its own environment and passes a URL in.
+"""
+
+from __future__ import annotations
+
+from argus_cortex.moderation._http import CheckFailed, ModerationConfigError
+from argus_cortex.moderation.nudenet import (
+    DEFAULT_EXPOSED_LABELS,
+    NUDENET_LABELS,
+    NsfwDetection,
+    NsfwResult,
+    NudeNetCheckFailed,
+    NudeNetClient,
+    NudeNetLabel,
+    exposed_score,
+)
+from argus_cortex.moderation.singguard import (
+    THINKING_MODES,
+    GuardCheckFailed,
+    GuardResult,
+    SingGuardClient,
+    policy_name,
+    rule_letter,
+    rule_matches,
+)
+
+__all__ = [
+    "DEFAULT_EXPOSED_LABELS",
+    "NUDENET_LABELS",
+    "THINKING_MODES",
+    "CheckFailed",
+    "GuardCheckFailed",
+    "GuardResult",
+    "ModerationConfigError",
+    "NsfwDetection",
+    "NsfwResult",
+    "NudeNetCheckFailed",
+    "NudeNetClient",
+    "NudeNetLabel",
+    "SingGuardClient",
+    "exposed_score",
+    "policy_name",
+    "rule_letter",
+    "rule_matches",
+]

argus_cortex-0.4.1/src/argus_cortex/moderation/_http.py

@@ -0,0 +1,72 @@
+"""The one HTTP path the moderation clients share. Stdlib only."""
+
+from __future__ import annotations
+
+import base64
+import http.client
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+# Ignore HTTP(S)_PROXY: images go straight to the configured server, never
+# through whatever proxy happens to be in the environment.
+_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+class ModerationConfigError(ValueError):
+    """A moderation client was configured with an unusable URL or option."""
+
+
+class CheckFailed(RuntimeError):
+    """One image could not be checked (network error, bad response)."""
+
+
+def service_url(base: str, path: str, service: str) -> str:
+    """*base* (a server's origin) with *path* appended to its path; a *base*
+    whose path already ends in *path* is used as is. A query string is kept.
+
+    The error names *service* but not *base*: a URL can carry a credential, and
+    callers surface this message.
+    """
+    parts = urlsplit(base.strip())
+    if parts.scheme not in {"http", "https"} or not parts.hostname:
+        raise ModerationConfigError(f"the {service} URL must be an http(s) URL")
+    base_path = parts.path.rstrip("/")
+    if not base_path.endswith(path):
+        base_path += path
+    return urlunsplit((parts.scheme, parts.netloc, base_path, parts.query, ""))
+
+
+def _split_credentials(url: str) -> tuple[str, dict[str, str]]:
+    """*url* without its ``user:password@`` part, plus the Basic auth header it
+    stood for (urllib would otherwise take the userinfo for part of the host)."""
+    parts = urlsplit(url)
+    if parts.username is None:
+        return url, {}
+    netloc = parts.netloc.rpartition("@")[2]
+    userinfo = f"{unquote(parts.username)}:{unquote(parts.password or '')}"
+    auth = f"Basic {base64.b64encode(userinfo.encode()).decode('ascii')}"
+    return urlunsplit(parts._replace(netloc=netloc)), {"Authorization": auth}
+
+
+def post_json(
+    url: str, body: bytes, content_type: str, timeout: float, service: str, failed: type[CheckFailed]
+) -> object:
+    """POST *body* to *url* and return the decoded JSON answer.
+
+    Every transport or decoding problem is raised as *failed*, so a caller
+    checking many images can record it against the one image.
+    """
+    url, headers = _split_credentials(url)
+    req = urllib.request.Request(url, data=body, headers={"Content-Type": content_type, **headers}, method="POST")
+    try:
+        with _OPENER.open(req, timeout=timeout) as resp:  # noqa: S310 - caller-configured URL
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        exc.close()  # the exception outlives the request as __cause__; its socket need not
+        raise failed(f"{service} returned HTTP {exc.code}") from exc
+    except (urllib.error.URLError, http.client.HTTPException, TimeoutError, OSError) as exc:
+        raise failed(f"{service} request failed: {exc}") from exc
+    except ValueError as exc:
+        raise failed(f"{service} returned a body that is not JSON") from exc

argus_cortex-0.4.1/src/argus_cortex/moderation/nudenet.py

@@ -0,0 +1,162 @@
+"""NudeNet client: nudity detection through a NudeNet server over HTTP.
+
+The suite never imports NudeNet (AGPL-3.0): it posts images to a NudeNet
+server (``ghcr.io/notai-tech/nudenet`` or any server speaking the same API)
+and records the detections. Running that server is the deployer's choice;
+cortex and the stages stay MIT.
+
+This module is also the suite's one definition of what counts as nudity:
+:data:`DEFAULT_EXPOSED_LABELS`. Faces, covered body parts, and exposed feet,
+belly, armpits or male chest are detected too but do not count towards
+:attr:`NsfwResult.exposed_score`.
+
+API: ``POST /infer`` with each image as a multipart field ``f1``, ``f2``, …,
+answered by ``{"prediction": [[{"class", "score", "box"}, ...], ...],
+"success": true}`` in field order. ``box`` is ``[x, y, w, h]`` in source
+pixels, and the server drops detections scoring under
+:data:`MIN_REPORTED_SCORE` (as does :func:`to_result`, whatever the server).
+
+Note: the upstream ``ghcr.io/notai-tech/nudenet`` image reports ``y`` offset by
+the letterbox padding on non-square images (scores are unaffected).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import uuid
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from argus_cortex.moderation._http import CheckFailed, post_json, service_url
+
+# NudeNet's 18 detector classes, verbatim (they are its API vocabulary).
+NudeNetLabel = Literal[
+    "FEMALE_GENITALIA_COVERED",
+    "FACE_FEMALE",
+    "BUTTOCKS_EXPOSED",
+    "FEMALE_BREAST_EXPOSED",
+    "FEMALE_GENITALIA_EXPOSED",
+    "MALE_BREAST_EXPOSED",
+    "ANUS_EXPOSED",
+    "FEET_EXPOSED",
+    "BELLY_COVERED",
+    "FEET_COVERED",
+    "ARMPITS_COVERED",
+    "ARMPITS_EXPOSED",
+    "FACE_MALE",
+    "BELLY_EXPOSED",
+    "MALE_GENITALIA_EXPOSED",
+    "ANUS_COVERED",
+    "FEMALE_BREAST_COVERED",
+    "BUTTOCKS_COVERED",
+]
+NUDENET_LABELS: tuple[NudeNetLabel, ...] = NudeNetLabel.__args__
+# The classes an image's exposed score (its "total" NSFW score) is taken over.
+DEFAULT_EXPOSED_LABELS: tuple[NudeNetLabel, ...] = (
+    "BUTTOCKS_EXPOSED",
+    "FEMALE_BREAST_EXPOSED",
+    "FEMALE_GENITALIA_EXPOSED",
+    "MALE_GENITALIA_EXPOSED",
+    "ANUS_EXPOSED",
+)
+# NudeNet servers report nothing scoring under this.
+MIN_REPORTED_SCORE = 0.2
+
+
+class NsfwDetection(BaseModel):
+    """One NudeNet detection."""
+
+    label: NudeNetLabel
+    score: float
+    bbox: list[float] = Field(..., min_length=4, max_length=4, description="[x, y, w, h]")
+
+
+class NsfwResult(BaseModel):
+    """NudeNet's view of one image.
+
+    Only detections scoring >= :data:`MIN_REPORTED_SCORE` are kept, so a class
+    missing from ``labels`` scored below that. ``exposed_score`` is the highest score among
+    :data:`DEFAULT_EXPOSED_LABELS`; filters can recompute it over another set.
+    """
+
+    detections: list[NsfwDetection] = Field(default_factory=list)
+    # Highest score per class, highest first.
+    labels: dict[NudeNetLabel, float] = Field(default_factory=dict)
+    exposed_score: float = 0.0
+
+
+class NudeNetCheckFailed(CheckFailed):
+    """One image could not be checked by NudeNet."""
+
+
+def exposed_score(labels: dict[str, float], exposed: tuple[str, ...] | list[str] = DEFAULT_EXPOSED_LABELS) -> float:
+    """The highest score among the *exposed* classes (0.0 when none was detected)."""
+    return max((labels[c] for c in exposed if c in labels), default=0.0)
+
+
+def _is_number(value: object) -> bool:
+    # json.loads accepts bare NaN/Infinity; a NaN score would compare False
+    # against every threshold and pass the image as safe.
+    return isinstance(value, int | float) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def to_result(raw: list) -> NsfwResult:
+    """One image's detections as recorded, plus the per-class maxima and exposed score."""
+    known = set(NUDENET_LABELS)
+    dets: list[NsfwDetection] = []
+    for d in raw:
+        if not isinstance(d, dict):
+            continue
+        label, score, box = d.get("class"), d.get("score"), d.get("box")
+        if (
+            not isinstance(label, str)
+            or label not in known
+            or not _is_number(score)
+            or score < MIN_REPORTED_SCORE
+            or not isinstance(box, list)
+            or len(box) != 4
+            or not all(_is_number(v) for v in box)
+        ):
+            continue  # an unknown class or malformed entry is not evidence either way
+        dets.append(NsfwDetection(label=label, score=round(float(score), 4), bbox=[round(float(v), 1) for v in box]))
+    dets.sort(key=lambda d: -d.score)
+    labels: dict[str, float] = {}
+    for d in dets:
+        labels.setdefault(d.label, d.score)
+    return NsfwResult(detections=dets, labels=labels, exposed_score=exposed_score(labels))
+
+
+def _multipart(data: bytes, filename: str) -> tuple[bytes, str]:
+    # The name lands in a header: keep it to characters that cannot break it.
+    filename = re.sub(r"[^A-Za-z0-9._-]", "_", filename)[-100:] or "image"
+    boundary = uuid.uuid4().hex
+    head = (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="f1"; filename="{filename}"\r\n'
+        "Content-Type: application/octet-stream\r\n\r\n"
+    ).encode()
+    return head + data + f"\r\n--{boundary}--\r\n".encode(), f"multipart/form-data; boundary={boundary}"
+
+
+class NudeNetClient:
+    """A NudeNet server at *base_url* (its origin, e.g. ``http://nudenet:8080``).
+
+    Thread-safe: :meth:`check` holds no state, so one client can serve a pool.
+    """
+
+    def __init__(self, base_url: str, timeout: float = 30.0) -> None:
+        self.url = service_url(base_url, "/infer", "NudeNet")
+        self.timeout = timeout
+
+    def check(self, data: bytes, filename: str = "image") -> NsfwResult:
+        """Post one image and parse the answer; raises :class:`NudeNetCheckFailed`."""
+        body, content_type = _multipart(data, filename)
+        payload = post_json(self.url, body, content_type, self.timeout, "NudeNet", NudeNetCheckFailed)
+        prediction = payload.get("prediction") if isinstance(payload, dict) else None
+        if not (isinstance(payload, dict) and payload.get("success") is True and isinstance(prediction, list)):
+            raise NudeNetCheckFailed("NudeNet did not report success")
+        if len(prediction) != 1 or not isinstance(prediction[0], list):
+            raise NudeNetCheckFailed(f"NudeNet returned {len(prediction)} results for one image")
+        return to_result(prediction[0])

argus_cortex-0.4.1/src/argus_cortex/moderation/singguard.py

@@ -0,0 +1,218 @@
+"""SingGuard client: a policy verdict from a SingGuard server over HTTP.
+
+Where NudeNet scores nudity per body part, SingGuard judges an image (and
+optionally text) against a whole moderation policy and answers with a verdict
+and the rule that fired. Its default rules are A. Sexual Content Risk, B.
+Real-World Crimes & Public Safety, C. Unethical Behavior (hate, self-harm,
+gore), D. Cybersecurity, E. Agent Safety, F. Politically Sensitive and G.
+Animal Abuse. A custom policy text replaces them. It gives no scores.
+
+API: ``POST /api/guard/check`` with JSON ``{input, image_base64, policy,
+thinking}``, answered by ``{safe, verdict, rule, explanation, categories:
+[{code, label, why}], model, elapsed_ms}`` and, from the argus-cull
+``singguard`` service, ``thinking``: the mode the server judged in, which
+its ``SINGGUARD_FORCE_THINKING`` can make differ from the one asked for.
+
+``thinking`` is ``fast`` (a verdict and rule), ``fast-slow`` (SingGuard's own
+reasoning mode: a fast first-line verdict, then the reasoning and a final
+answer), ``slow`` (the argus-cull service's variant with no first-line
+verdict, so the reasoning is not anchored to a verdict made before it) or
+``cascade`` (that service's ``fast`` for every image and ``slow`` for the ones
+fast flags, slow's verdict standing). Servers without ``slow`` and ``cascade``
+answer HTTP 400 to them.
+
+Large images are downscaled before sending (Pillow, from the ``[images]``
+extra, imported only when downscaling is on).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import importlib.util
+import io
+import json
+
+from pydantic import BaseModel, Field
+
+from argus_cortex.moderation._http import CheckFailed, ModerationConfigError, post_json, service_url
+
+THINKING_MODES = ("fast", "fast-slow", "slow", "cascade")
+# The guard model sees far fewer pixels than a camera original, and base64
+# JSON inflates every byte by 4/3.
+MAX_EDGE = 1536
+MAX_BYTES = 4 * 1024 * 1024
+_MIN_EDGE = 256  # below this, give up rather than send SingGuard a postage stamp
+_NEEDS_PILLOW = "downscaling images needs: pip install argus-cortex[images] (or pass downscale=False)"
+_EXPLANATION_MAX = 4000
+_FIELD_MAX = 200
+
+
+class GuardResult(BaseModel):
+    """SingGuard's verdict on one image. A verdict, not a score: SingGuard
+    reports which policy rules fired, not how confident it is."""
+
+    safe: bool
+    # The rules that made the image unsafe, as the policy names them
+    # (e.g. "A. Sexual Content Risk"); empty when safe.
+    rules: list[str] = Field(default_factory=list)
+    explanation: str | None = None
+    # The guard model, and the policy judged against: "default" (SingGuard's
+    # own rules) or "custom-<sha256 prefix>" of the policy text.
+    model: str | None = None
+    policy: str = "default"
+    # The thinking mode the server judged in, when it says (the argus-cull
+    # service does; it can be forced server-side to differ from the request).
+    thinking: str | None = None
+
+
+class GuardCheckFailed(CheckFailed):
+    """One image could not be checked by SingGuard."""
+
+
+def policy_name(text: str | None) -> str:
+    """How a result records the policy: ``default``, or ``custom-`` + a sha256 prefix of *text*.
+
+    *text* is stripped first, as :class:`SingGuardClient` strips the policy it sends.
+    """
+    return "default" if text is None else f"custom-{hashlib.sha256(text.strip().encode()).hexdigest()[:12]}"
+
+
+def rule_letter(rule: str) -> str:
+    """*rule* by its letter (``"A"`` for ``"A. Sexual Content Risk"``), else in full."""
+    head, sep, _ = rule.strip().partition(".")
+    return head if sep and len(head) == 1 else rule
+
+
+def rule_matches(fired: str, wanted: str) -> bool:
+    """*wanted* names *fired*: in full, or by its letter (``"A"`` or ``"A."`` for ``"A. Sexual Content Risk"``)."""
+    fired, wanted = fired.strip().casefold(), wanted.strip().casefold()
+    return fired == wanted or fired.startswith(f"{wanted.removesuffix('.')}.")
+
+
+def _clip(value: object, limit: int) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    return value.strip()[:limit]
+
+
+def to_result(payload: object, policy: str = "default") -> GuardResult:
+    """SingGuard's answer as recorded. A missing verdict is a failure, not a pass."""
+    if not isinstance(payload, dict) or not isinstance(payload.get("safe"), bool):
+        raise GuardCheckFailed("SingGuard returned no verdict")
+    safe = payload["safe"]
+    rules: list[str] = []
+    if not safe:
+        categories = payload.get("categories")
+        for cat in categories if isinstance(categories, list) else []:
+            code = _clip(cat.get("code"), _FIELD_MAX) if isinstance(cat, dict) else None
+            if code and code not in rules:
+                rules.append(code)
+        rule = _clip(payload.get("rule"), _FIELD_MAX)
+        if not rules and rule:
+            rules.append(rule)
+    return GuardResult(
+        safe=safe,
+        rules=rules,
+        explanation=_clip(payload.get("explanation"), _EXPLANATION_MAX),
+        model=_clip(payload.get("model"), _FIELD_MAX),
+        policy=policy,
+        thinking=_clip(payload.get("thinking"), _FIELD_MAX),
+    )
+
+
+def downscale(data: bytes, max_edge: int = MAX_EDGE, max_bytes: int = MAX_BYTES) -> bytes:
+    """*data* as is when small enough, else downscaled to a JPEG (a PNG when it
+    has alpha) of at most *max_edge* px and *max_bytes*, shrinking further if
+    the first encoding is still too large.
+
+    Raises :class:`GuardCheckFailed` for an image Pillow cannot read or shrink
+    under *max_bytes*.
+    """
+    try:
+        from PIL import Image, ImageOps
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ModerationConfigError(_NEEDS_PILLOW) from exc
+    try:
+        with Image.open(io.BytesIO(data)) as im:
+            if max(im.size) <= max_edge and len(data) <= max_bytes:
+                return data
+            # Shrink first, so a JPEG decodes at reduced scale (draft mode);
+            # the box is square, so transposing after gives the same size.
+            im.thumbnail((max_edge, max_edge))
+            # Upright, as a viewer would see it: re-encoding drops the EXIF tag.
+            out = ImageOps.exif_transpose(im)
+            alpha = out.mode in ("RGBA", "LA", "PA") or (out.mode == "P" and "transparency" in out.info)
+            if not alpha:
+                out = out.convert("RGB")
+            edge = max(out.size)
+            while True:
+                buf = io.BytesIO()
+                if alpha:
+                    # Flattening onto black would hide dark content drawn on a
+                    # transparent background; keep the alpha, as a small PNG goes.
+                    out.save(buf, "PNG", optimize=True)
+                else:
+                    out.save(buf, "JPEG", quality=90)
+                if buf.tell() <= max_bytes:
+                    return buf.getvalue()
+                if edge <= _MIN_EDGE:
+                    raise GuardCheckFailed("image could not be shrunk under the SingGuard size limit")
+                edge = max(_MIN_EDGE, edge * 3 // 4)
+                out.thumbnail((edge, edge))
+    except (OSError, ValueError, Image.DecompressionBombError) as exc:
+        raise GuardCheckFailed(f"image could not be prepared for SingGuard: {exc}") from exc
+
+
+class SingGuardClient:
+    """A SingGuard server at *base_url* (its origin, e.g. ``http://guard:9150``).
+
+    *policy* is the policy text (``None`` = SingGuard's default rules);
+    *thinking* is one of :data:`THINKING_MODES`: ``fast`` (verdict and rule),
+    ``fast-slow`` (also writes why), ``slow`` (writes why, with no fast
+    verdict ahead of the reasoning) or ``cascade`` (fast, then slow only for
+    what fast flagged); the last two need the argus-cull ``singguard`` service.
+    With *downscale* on (the default, needs ``[images]``), images over
+    :data:`MAX_EDGE` px or :data:`MAX_BYTES` are shrunk before sending.
+    Thread-safe: :meth:`check` holds no state.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 90.0,
+        thinking: str = "fast",
+        policy: str | None = None,
+        downscale: bool = True,
+    ) -> None:
+        if thinking not in THINKING_MODES:
+            raise ModerationConfigError(f"SingGuard thinking must be one of {', '.join(THINKING_MODES)}")
+        if policy is not None and not policy.strip():
+            raise ModerationConfigError("the SingGuard policy is empty (pass None for the default rules)")
+        if downscale and importlib.util.find_spec("PIL") is None:
+            # Fail at startup, not as a config error out of every check().
+            raise ModerationConfigError(_NEEDS_PILLOW)
+        self.url = service_url(base_url, "/api/guard/check", "SingGuard")
+        self.timeout = timeout
+        self.thinking = thinking
+        self.policy = policy.strip() if policy is not None else None
+        self.policy_name = policy_name(self.policy)
+        self.downscale = downscale
+
+    def check(self, data: bytes, text: str = "") -> GuardResult:
+        """Judge one image, with *text* (e.g. the prompt that made it) judged alongside.
+
+        Raises :class:`GuardCheckFailed`.
+        """
+        image = downscale(data) if self.downscale else data
+        body: dict[str, str] = {
+            "input": text,
+            "image_base64": base64.b64encode(image).decode("ascii"),
+            "thinking": self.thinking,
+        }
+        if self.policy is not None:
+            body["policy"] = self.policy
+        payload = post_json(
+            self.url, json.dumps(body).encode(), "application/json", self.timeout, "SingGuard", GuardCheckFailed
+        )
+        return to_result(payload, self.policy_name)

argus_cortex-0.4.1/tests/test_moderation.py

@@ -0,0 +1,359 @@
+"""Moderation clients against fake NudeNet and SingGuard servers.
+
+The fakes speak each server's API (shapes taken from live servers), so the
+real urllib path, multipart/JSON encoding and response parsing all run.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import subprocess
+import sys
+import threading
+from collections.abc import Iterator
+from email.parser import BytesParser
+from email.policy import HTTP
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+from PIL import Image
+
+from argus_cortex.moderation import (
+    DEFAULT_EXPOSED_LABELS,
+    GuardCheckFailed,
+    GuardResult,
+    ModerationConfigError,
+    NsfwResult,
+    NudeNetCheckFailed,
+    NudeNetClient,
+    SingGuardClient,
+    exposed_score,
+    nudenet,
+    policy_name,
+    rule_letter,
+    rule_matches,
+    singguard,
+)
+
+_FAIL = 99  # this red value gets an HTTP 500 from either fake
+
+
+def _png(red: int, size: tuple[int, int] = (64, 48), mode: str = "RGB") -> bytes:
+    buf = io.BytesIO()
+    Image.new(mode, size, (red, 0, 0, 255)[: len(mode)]).save(buf, "PNG")
+    return buf.getvalue()
+
+
+def _red(data: bytes) -> int:
+    return Image.open(io.BytesIO(data)).convert("RGB").getpixel((0, 0))[0]
+
+
+class _Fake(BaseHTTPRequestHandler):
+    seen: list[dict] = []
+
+    def log_message(self, *args) -> None:  # keep test output quiet
+        pass
+
+    def _send(self, status: int, payload: object | None = None) -> None:
+        out = json.dumps(payload).encode() if payload is not None else b""
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(out)))
+        self.end_headers()
+        self.wfile.write(out)
+
+
+# ---------------------------------------------------------------------------
+# NudeNet
+# ---------------------------------------------------------------------------
+
+_DETECTIONS = {
+    10: [],
+    20: [
+        {"class": "FACE_FEMALE", "score": 0.91, "box": [10, 10, 30, 30]},
+        {"class": "BELLY_EXPOSED", "score": 0.4, "box": [10, 50, 30, 20]},
+    ],
+    30: [
+        {"class": "FEMALE_BREAST_EXPOSED", "score": 0.72, "box": [5, 5, 20, 20]},
+        {"class": "FEMALE_BREAST_EXPOSED", "score": 0.66, "box": [30, 5, 20, 20]},
+        {"class": "FACE_FEMALE", "score": 0.8, "box": [10, 0, 10, 10]},
+    ],
+}
+
+
+class _NudeNet(_Fake):
+    def do_POST(self) -> None:
+        body = self.rfile.read(int(self.headers["Content-Length"]))
+        msg = BytesParser(policy=HTTP).parsebytes(
+            f"Content-Type: {self.headers['Content-Type']}\r\n\r\n".encode() + body
+        )
+        part = next(msg.iter_parts())
+        red = _red(part.get_content())
+        type(self).seen.append(
+            {"path": self.path, "field": part.get_param("name", header="content-disposition"),
+             "filename": part.get_filename(), "auth": self.headers["Authorization"]}
+        )  # fmt: skip
+        if red == _FAIL:
+            self._send(500)
+        else:
+            self._send(200, {"prediction": [_DETECTIONS.get(red, [])], "success": True})
+
+
+class _SingGuard(_Fake):
+    answers: dict[int, dict] = {}  # a test's overrides of _GUARD_ANSWERS, by red value
+
+    def do_POST(self) -> None:
+        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+        image = Image.open(io.BytesIO(base64.b64decode(body["image_base64"])))
+        red = image.convert("RGB").getpixel((0, 0))[0]
+        type(self).seen.append(
+            {"path": self.path, "size": image.size, "format": image.format,
+             **{k: v for k, v in body.items() if k != "image_base64"}}
+        )  # fmt: skip
+        if red == _FAIL:
+            self._send(500)
+        else:
+            answer = self.answers.get(red) or _GUARD_ANSWERS.get(red, _GUARD_ANSWERS[10])
+            self._send(200, {**answer, "model": "SingGuard-4b", "elapsed_ms": 5})
+
+
+def _serve(handler: type[_Fake]) -> Iterator[tuple[type[_Fake], str]]:
+    handler.seen = []
+    server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    try:
+        yield handler, f"http://127.0.0.1:{server.server_port}"
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+@pytest.fixture
+def nudenet_server() -> Iterator[tuple[type[_Fake], str]]:
+    yield from _serve(_NudeNet)
+
+
+@pytest.fixture
+def singguard_server() -> Iterator[tuple[type[_Fake], str]]:
+    yield from _serve(_SingGuard)
+
+
+def test_nudenet_url() -> None:
+    assert NudeNetClient("http://nudenet:8080/").url == "http://nudenet:8080/infer"
+    assert NudeNetClient("https://n.lan/x/infer").url == "https://n.lan/x/infer"
+    with pytest.raises(ModerationConfigError) as exc:
+        NudeNetClient("ftp://user:secret@nudenet")
+    assert "secret" not in str(exc.value)  # callers surface this message
+    # A host named like the path is still a host, and a query stays a query.
+    assert NudeNetClient("http://infer").url == "http://infer/infer"
+    assert NudeNetClient("http://h:8080?token=x").url == "http://h:8080/infer?token=x"
+
+
+def test_credentials_in_the_url_become_basic_auth(nudenet_server) -> None:
+    fake, url = nudenet_server
+    NudeNetClient(url.replace("http://", "http://us%40er:p%3Aw@"), timeout=5).check(_png(10))
+    assert fake.seen[0]["auth"] == "Basic " + base64.b64encode(b"us@er:p:w").decode()
+
+
+def test_nudenet_check(nudenet_server) -> None:
+    fake, url = nudenet_server
+    client = NudeNetClient(url, timeout=5)
+    assert client.check(_png(10)) == NsfwResult()
+    portrait = client.check(_png(20), 'we"ird\r\nname.png')
+    assert portrait.exposed_score == 0.0  # a face and a belly are not exposed nudity
+    assert portrait.labels == {"FACE_FEMALE": 0.91, "BELLY_EXPOSED": 0.4}
+    topless = client.check(_png(30))
+    assert topless.exposed_score == 0.72 and len(topless.detections) == 3
+    assert list(topless.labels) == ["FACE_FEMALE", "FEMALE_BREAST_EXPOSED"]  # highest first
+    with pytest.raises(NudeNetCheckFailed, match="HTTP 500"):
+        client.check(_png(_FAIL))
+    assert {s["path"] for s in fake.seen} == {"/infer"} and {s["field"] for s in fake.seen} == {"f1"}
+    assert "we_ird__name.png" in {s["filename"] for s in fake.seen}  # header-safe
+
+
+def test_nudenet_parsing_ignores_malformed_entries() -> None:
+    r = nudenet.to_result(
+        [
+            {"class": "BUTTOCKS_EXPOSED", "score": 0.6, "box": [0, 0, 1, 1]},
+            {"class": "NOT_A_CLASS", "score": 0.99, "box": [0, 0, 1, 1]},
+            {"class": "ANUS_EXPOSED", "score": "high", "box": [0, 0, 1, 1]},
+            {"class": "ANUS_EXPOSED", "score": True, "box": [0, 0, 1, 1]},
+            {"class": "ANUS_EXPOSED", "score": 0.9, "box": [0, 0, 1]},
+            {"class": "ANUS_EXPOSED", "score": float("nan"), "box": [0, 0, 1, 1]},
+            {"class": "ANUS_EXPOSED", "score": 0.9, "box": [0, 0, float("inf"), 1]},
+            {"class": "ANUS_EXPOSED", "score": nudenet.MIN_REPORTED_SCORE / 2, "box": [0, 0, 1, 1]},
+            {"class": ["ANUS_EXPOSED"], "score": 0.9, "box": [0, 0, 1, 1]},
+            {"class": {"x": 1}, "score": 0.9, "box": [0, 0, 1, 1]},
+            "not a detection",
+        ]
+    )
+    assert r.labels == {"BUTTOCKS_EXPOSED": 0.6} and r.exposed_score == 0.6
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [{"prediction": [[]], "success": False}, {"prediction": [[], []], "success": True}, {"success": True}, ["x"]],
+)
+def test_nudenet_bad_responses_are_failures(monkeypatch: pytest.MonkeyPatch, payload) -> None:
+    monkeypatch.setattr(nudenet, "post_json", lambda *a, **k: payload)
+    with pytest.raises(NudeNetCheckFailed):
+        NudeNetClient("http://n").check(_png(10))
+
+
+def test_exposed_set_is_the_five_exposed_nudity_classes() -> None:
+    assert set(DEFAULT_EXPOSED_LABELS) == {
+        "BUTTOCKS_EXPOSED", "FEMALE_BREAST_EXPOSED", "FEMALE_GENITALIA_EXPOSED", "MALE_GENITALIA_EXPOSED",
+        "ANUS_EXPOSED",
+    }  # fmt: skip
+    labels = {"FEET_EXPOSED": 0.9, "MALE_BREAST_EXPOSED": 0.9, "BUTTOCKS_EXPOSED": 0.3}
+    assert exposed_score(labels) == 0.3
+    assert exposed_score(labels, ["MALE_BREAST_EXPOSED"]) == 0.9
+
+
+# ---------------------------------------------------------------------------
+# SingGuard
+# ---------------------------------------------------------------------------
+
+_CRIME = "B. Real-World Crimes & Public Safety"
+_GORE = "C. Unethical Behavior"
+_GUARD_ANSWERS: dict[int, dict] = {
+    10: {"safe": True, "verdict": "safe", "rule": "Safe", "explanation": "Safe.", "categories": []},
+    20: {
+        "safe": False,
+        "verdict": "unsafe",
+        "rule": _CRIME,
+        "explanation": f"Triggered rule: {_CRIME}.",
+        "categories": [{"code": _CRIME, "label": _CRIME, "why": "-"}, {"code": _GORE, "label": _GORE, "why": "-"}],
+    },
+    30: {"safe": False, "verdict": "unsafe", "rule": _GORE, "explanation": "", "categories": 5},  # malformed
+    40: {"verdict": "safe"},  # no boolean verdict: a failed check, not a pass
+}
+
+
+def test_singguard_config() -> None:
+    client = SingGuardClient("http://192.168.1.198:9150/")
+    assert client.url == "http://192.168.1.198:9150/api/guard/check"
+    assert client.policy is None and client.policy_name == "default" and client.thinking == "fast"
+    custom = SingGuardClient("http://g", policy="  ### A. Minors\n")
+    assert custom.policy == "### A. Minors" and custom.policy_name == policy_name("### A. Minors")
+    assert custom.policy_name == policy_name("  ### A. Minors\n")  # a policy read from a file matches
+    assert custom.policy_name.startswith("custom-") and len(custom.policy_name) == len("custom-") + 12
+    assert [SingGuardClient("http://g", thinking=m).thinking for m in ("slow", "cascade")] == ["slow", "cascade"]
+    for kwargs in ({"thinking": "slower"}, {"thinking": "FAST"}, {"policy": " \n"}):
+        with pytest.raises(ModerationConfigError):
+            SingGuardClient("http://g", **kwargs)
+    with pytest.raises(ModerationConfigError):
+        SingGuardClient("gopher://g")
+
+
+def test_singguard_check(singguard_server) -> None:
+    fake, url = singguard_server
+    client = SingGuardClient(url, timeout=5, thinking="fast-slow", policy="### A. Minors")
+    safe = client.check(_png(10), text="a cat on a sofa")
+    assert safe == GuardResult(safe=True, explanation="Safe.", model="SingGuard-4b", policy=client.policy_name)
+    assert client.check(_png(20)).rules == [_CRIME, _GORE]
+    gore = client.check(_png(30))
+    assert gore.rules == [_GORE] and gore.explanation is None  # no categories: the rule itself
+    with pytest.raises(GuardCheckFailed, match="no verdict"):
+        client.check(_png(40))
+    with pytest.raises(GuardCheckFailed, match="HTTP 500"):
+        client.check(_png(_FAIL))
+    assert {s["path"] for s in fake.seen} == {"/api/guard/check"}
+    assert fake.seen[0]["input"] == "a cat on a sofa" and fake.seen[1]["input"] == ""
+    assert {s["thinking"] for s in fake.seen} == {"fast-slow"} and {s["policy"] for s in fake.seen} == {"### A. Minors"}
+
+
+def test_singguard_default_policy_is_not_sent(singguard_server) -> None:
+    fake, url = singguard_server
+    SingGuardClient(url).check(_png(10))
+    assert "policy" not in fake.seen[0]
+
+
+def test_singguard_slow_is_sent_and_the_mode_used_is_recorded(singguard_server) -> None:
+    """The argus-cull service answers with the mode it judged in, which a
+    server-side force can make differ from the request; it is recorded as sent.
+    A server that says nothing leaves it None."""
+    fake, url = singguard_server
+    client = SingGuardClient(url, timeout=5, thinking="slow")
+    assert client.check(_png(10)).thinking is None
+    fake.answers = {10: {**_GUARD_ANSWERS[10], "thinking": "fast-slow"}}
+    try:
+        assert client.check(_png(10)).thinking == "fast-slow"
+    finally:
+        fake.answers = {}
+    assert {s["thinking"] for s in fake.seen} == {"slow"}
+
+
+def test_singguard_downscales_large_images(singguard_server) -> None:
+    fake, url = singguard_server
+    SingGuardClient(url).check(_png(10, (4000, 3000)))
+    SingGuardClient(url).check(_png(10, (4000, 3000), "RGBA"))
+    SingGuardClient(url, downscale=False).check(_png(10, (4000, 3000)))
+    assert [(s["size"], s["format"]) for s in fake.seen] == [
+        ((1536, 1152), "JPEG"),
+        ((1536, 1152), "PNG"),  # alpha kept, not flattened onto black
+        ((4000, 3000), "PNG"),
+    ]
+    small = _png(10)
+    assert singguard.downscale(small) is small
+    exif = Image.Exif()
+    exif[0x0112] = 6  # rotate 90 degrees to view
+    buf = io.BytesIO()
+    Image.new("RGB", (4000, 3000)).save(buf, "JPEG", exif=exif)
+    assert Image.open(io.BytesIO(singguard.downscale(buf.getvalue()))).size == (1152, 1536)  # upright
+    with pytest.raises(GuardCheckFailed, match="prepared"):
+        singguard.downscale(b"not an image")
+
+
+def test_downscale_enforces_the_byte_limit() -> None:
+    noisy = Image.effect_noise((1200, 900), 100).convert("RGB")
+    buf = io.BytesIO()
+    noisy.save(buf, "PNG")
+    out = singguard.downscale(buf.getvalue(), max_bytes=100_000)
+    assert len(out) <= 100_000 and max(Image.open(io.BytesIO(out)).size) < 1200
+    with pytest.raises(GuardCheckFailed, match="size limit"):
+        singguard.downscale(buf.getvalue(), max_bytes=100)
+
+
+def test_singguard_without_pillow_fails_at_construction(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(singguard.importlib.util, "find_spec", lambda name: None)
+    with pytest.raises(ModerationConfigError, match="images"):
+        SingGuardClient("http://g")
+    assert SingGuardClient("http://g", downscale=False).downscale is False
+
+
+@pytest.mark.parametrize(
+    ("fired", "wanted", "expected"),
+    [(_CRIME, "B", True), (_CRIME, "b.", True), (_CRIME, _CRIME.lower(), True), (_CRIME, "B. Real", False),
+     (_CRIME, "C", False), ("Minors", "minors", True)],
+)  # fmt: skip
+def test_rule_matches(fired: str, wanted: str, expected: bool) -> None:
+    assert rule_matches(fired, wanted) is expected
+
+
+def test_rule_letter() -> None:
+    assert rule_letter(_CRIME) == "B" and rule_letter("Minors") == "Minors"
+
+
+# ---------------------------------------------------------------------------
+# Transport and packaging
+# ---------------------------------------------------------------------------
+
+
+def test_proxies_in_the_environment_are_ignored(nudenet_server, monkeypatch: pytest.MonkeyPatch) -> None:
+    _fake, url = nudenet_server
+    monkeypatch.setenv("HTTP_PROXY", "http://127.0.0.1:9")  # nothing listens there
+    monkeypatch.setenv("http_proxy", "http://127.0.0.1:9")
+    assert NudeNetClient(url, timeout=5).check(_png(10)) == NsfwResult()
+
+
+def test_unreachable_server_is_a_failed_check() -> None:
+    with pytest.raises(NudeNetCheckFailed, match="request failed"):
+        NudeNetClient("http://127.0.0.1:9", timeout=2).check(_png(10))
+
+
+def test_import_does_not_pull_in_pillow() -> None:
+    code = "import sys, argus_cortex, argus_cortex.moderation; assert 'PIL' not in sys.modules"
+    subprocess.run([sys.executable, "-c", code], check=True)