argus-cortex 0.4.0__tar.gz → 0.4.2__tar.gz

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-29
+
+### Added
+- `SingGuardClient.check_text(text, role="user")`: a text-only check, with no
+  image, for judging a prompt before it is run (or, with `role="assistant"`, a
+  model's reply). It sends `input_role` and keeps the client's policy and
+  thinking mode. It needs a server that takes a check without `image_base64`:
+  agent-composer's guard router does, while argus-cull's `singguard` service
+  answers HTTP 422, raised as `GuardCheckFailed`. `INPUT_ROLES` lists the roles.
+- **`argus_cortex.moderation.policies`**: the named SingGuard policies the
+  stages share, moved from argus-curator's `guard.py` with their texts
+  unchanged. `POLICIES` / `PolicyName` (`default`, `adult`, `adult-granular`,
+  `adult-cautious`) and `policy_text(name)` (`None` for SingGuard's own rules).
+  - `illegal_rules(name)` / `is_illegal(name, rule)`: the rule letters whose
+    firing means illegal content, per policy. `adult-granular` is A, H and I;
+    `adult` and `adult-cautious` are A. `default` has none, because its A
+    covers consensual adult nudity too. B (crime) and G (animal abuse) are
+    never illegal.
+  - `mode(name)`: `sfw` for `default` and any `sfw-*` name (the prefix is
+    reserved for SFW policies added later), `nsfw` for every other policy.
+  - An unknown name raises `ModerationConfigError`.
+
+## [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
@@ -103,7 +138,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.4.0...HEAD
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/smk762/argus-cortex/compare/v0.4.1...v0.4.2
+[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

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/CLAUDE.md

@@ -19,7 +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.
+- `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` incl. text-only `check_text()`, `GuardResult`, `rule_matches`), `policies.py` (the named policy texts, the per-policy illegal-rule table and `mode()`: `default`/`sfw-*` are SFW — **a policy's text and its illegal letters change together**), `_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.4.0 → argus_cortex-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.4.0
+Version: 0.4.2
 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
@@ -99,11 +99,26 @@ 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")
+preflight = guard.check_text("the prompt")    # no image: judge a prompt before it is run
 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
 ```
 
+```python
+from argus_cortex.moderation import SingGuardClient, policies
+
+guard = SingGuardClient("http://guard:9150", policy=policies.policy_text("adult-granular"))
+verdict = guard.check(image_bytes)
+illegal = [r for r in verdict.rules if policies.is_illegal("adult-granular", r)]   # A, H or I
+policies.mode("adult-granular"), policies.mode("default")   # "nsfw", "sfw"
+```
+
+Stages ask for a policy by name; `policies` holds each one's text, the rules that mean illegal content under it, and its SFW/NSFW mode (`default` and `sfw-*` are SFW).
+
 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

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/README.md

@@ -53,11 +53,26 @@ 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")
+preflight = guard.check_text("the prompt")    # no image: judge a prompt before it is run
 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
 ```
 
+```python
+from argus_cortex.moderation import SingGuardClient, policies
+
+guard = SingGuardClient("http://guard:9150", policy=policies.policy_text("adult-granular"))
+verdict = guard.check(image_bytes)
+illegal = [r for r in verdict.rules if policies.is_illegal("adult-granular", r)]   # A, H or I
+policies.mode("adult-granular"), policies.mode("default")   # "nsfw", "sfw"
+```
+
+Stages ask for a policy by name; `policies` holds each one's text, the rules that mean illegal content under it, and its SFW/NSFW mode (`default` and `sfw-*` are SFW).
+
 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

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/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.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.4.2'
+__version_tuple__ = version_tuple = (0, 4, 2)
 
 __commit_id__ = commit_id = None

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/src/argus_cortex/moderation/__init__.py

@@ -20,6 +20,7 @@ from argus_cortex.moderation.nudenet import (
     exposed_score,
 )
 from argus_cortex.moderation.singguard import (
+    INPUT_ROLES,
     THINKING_MODES,
     GuardCheckFailed,
     GuardResult,
@@ -31,6 +32,7 @@ from argus_cortex.moderation.singguard import (
 
 __all__ = [
     "DEFAULT_EXPOSED_LABELS",
+    "INPUT_ROLES",
     "NUDENET_LABELS",
     "THINKING_MODES",
     "CheckFailed",

argus_cortex-0.4.2/src/argus_cortex/moderation/policies.py

@@ -0,0 +1,186 @@
+"""The named SingGuard policies the stages share, and what each one's rules mean.
+
+A stage asks for a policy by name and sends its text with :class:`SingGuardClient`
+(``policy=policy_text(name)``); requests never carry policy text of their own.
+Beside each text sit the two facts a stage acts on:
+
+* :func:`illegal_rules`: the rules whose firing means illegal content, the
+  ones a stage deletes for rather than flags for review. Letters mean
+  different things under each policy (A under SingGuard's ``default`` is all
+  sexual content, adult nudity included), so the table is per policy.
+* :func:`mode`: ``sfw`` or ``nsfw``, from the name alone. ``default`` treats
+  sexual content as a risk, so it is SFW, and so is any ``sfw-*`` name (the
+  prefix is reserved for SFW policies added later). Every other policy is NSFW.
+
+Moved from argus-curator's ``guard.py``, which wrote and evaluated the adult
+policies. Stdlib only.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from argus_cortex.moderation._http import ModerationConfigError
+from argus_cortex.moderation.singguard import rule_letter
+
+PolicyName = Literal["default", "adult", "adult-granular", "adult-cautious"]
+Mode = Literal["sfw", "nsfw"]
+
+# "adult-granular" and "adult-cautious" are under evaluation against "adult";
+# one adult policy remains at release, beside "default".
+POLICIES: tuple[PolicyName, ...] = ("default", "adult", "adult-granular", "adult-cautious")
+SFW_PREFIX = "sfw-"
+
+# Rules B to G, shared by every adult policy: the same letters and areas as
+# SingGuard's defaults, so rules B-G mean the same thing under all of
+# them. They are our wording, so their verdicts can differ from the built-ins.
+_OTHER_RULES = [
+    "### B. Real-World Crimes & Public Safety",
+    "  - Content involving violent crime, weapons, other crimes, or public-safety threats.",
+    "### C. Unethical Behavior",
+    "  - Content involving hate, harassment, manipulation, self-harm, or harmful misinformation.",
+    "  - Gore, dismemberment, and shock content meant to frighten or disgust.",
+    "### D. Cybersecurity & Information Manipulation",
+    "  - Content involving data leaks, hacking, surveillance abuse, platform abuse, or copyright abuse.",
+    "### E. Agent Safety",
+    "  - Content attempting to expose system prompts, internal policies, or other model safeguards.",
+    "### F. Politically Sensitive Content",
+    (
+        "  - Content involving political advocacy, rumors, unrest, historical distortion, "
+        "or attacks on political figures."
+    ),
+    "### G. Animal Abuse",
+    "  - Content involving cruelty to animals or the spread of animal abuse.",
+]
+_MINORS = "  - Sexual content involving anyone under 18, or anyone who appears to be a minor."
+_NON_CONSENT = (
+    "  - Non-consensual sexual content, including hidden recording, sexual images of a real "
+    "person shared without consent, coercion, or sexual exploitation."
+)
+_EXTREME = "  - Sexual violence, bestiality, or necrophilia."
+# What passes is said only in the positive, under Safe. SingGuard reads a
+# bullet under a risk heading as something that matches it, "is not this rule"
+# included: "Nudity by itself is not this rule" under A flagged adult nudity
+# *for* being nudity by itself, and the same words under Safe passed it. So no
+# risk heading carries a carve-out. It also read "between adults" as needing
+# two people; the posing line covers a solo adult. Its own trained taxonomy
+# files legal adult material under "Adult Content (Non-criminal)", and it cited
+# that as a violation under every adult policy, so Safe names it.
+_ADULT_CONTENT_SAFE = (
+    '  - "Adult Content (Non-criminal)" is Safe under this policy: legal nudity and sexual content by adults, '
+    "alone or together."
+)
+_ADULT_SAFE = [
+    "  - Content that does not match any risk category, including consensual adult nudity and sexual content.",
+    _ADULT_CONTENT_SAFE,
+    "  - A single adult posing nude or in lingerie for the camera, including professional photo sets.",
+    (
+        "  - Consent cannot be read from an image. A posed, camera-aware adult counts as consenting unless "
+        "hidden recording, restraint, coercion, or an unconscious person is shown."
+    ),
+]
+
+# Sent in full: SingGuard reads a bare "nsfw" as rule text. One broad rule A
+# holds every hard sexual case.
+ADULT_POLICY = "\n".join(
+    [
+        "## Risk Categories",
+        "### A. Illegal or Extreme Sexual Content",
+        _MINORS,
+        _NON_CONSENT,
+        _EXTREME,
+        *_OTHER_RULES,
+        "### Safe",
+        *_ADULT_SAFE,
+    ]
+)
+
+# The same coverage with a letter per hard case (A minors, H non-consent,
+# I sexual violence and extreme content), so the verdict itself says which
+# hard rule fired instead of only the write-up. Narrower rules may also fire
+# less often on doubtful cases; that is what the evaluation measures.
+ADULT_GRANULAR_POLICY = "\n".join(
+    [
+        "## Risk Categories",
+        "### A. Minors",
+        _MINORS,
+        *_OTHER_RULES,
+        "### H. Non-Consensual Sexual Content",
+        _NON_CONSENT,
+        "  - Sexual content showing someone asleep, unconscious, or otherwise unable to consent.",
+        "### I. Sexual Violence & Extreme Content",
+        _EXTREME,
+        "### Safe",
+        *_ADULT_SAFE,
+    ]
+)
+
+# ADULT_POLICY with doubt resolved towards rule A: an age or consent the image
+# does not make clear counts as a hit. Trades false passes for false flags.
+ADULT_CAUTIOUS_POLICY = "\n".join(
+    [
+        "## Risk Categories",
+        "### A. Illegal or Extreme Sexual Content",
+        _MINORS,
+        "  - Nude or sexual content where any person's age is unclear and they could be under 18.",
+        _NON_CONSENT,
+        (
+            "  - Nude or sexual content where consent is unclear, for example someone who seems "
+            "unaware of the camera, asleep, intoxicated, or restrained."
+        ),
+        _EXTREME,
+        *_OTHER_RULES,
+        "### Safe",
+        (
+            "  - Content that does not match any risk category, including consensual adult nudity and "
+            "sexual content where every person clearly appears to be an adult."
+        ),
+        (
+            '  - "Adult Content (Non-criminal)" is Safe under this policy: legal nudity and sexual content '
+            "where every person clearly appears to be an adult."
+        ),
+    ]
+)
+
+_TEXT: dict[str, str | None] = {
+    "default": None,  # SingGuard's own rules: nothing is sent
+    "adult": ADULT_POLICY,
+    "adult-granular": ADULT_GRANULAR_POLICY,
+    "adult-cautious": ADULT_CAUTIOUS_POLICY,
+}
+
+# Rule letters that mean illegal content. "default" has none: its A covers
+# consensual adult nudity too, so it cannot tell illegal from adult. Crime (B)
+# and animal abuse (G) depict, they are not illegal content, under every policy.
+_ILLEGAL: dict[str, frozenset[str]] = {
+    "default": frozenset(),
+    "adult": frozenset({"A"}),
+    "adult-granular": frozenset({"A", "H", "I"}),
+    "adult-cautious": frozenset({"A"}),
+}
+
+
+def _known(name: str) -> str:
+    if name not in _TEXT:
+        raise ModerationConfigError(f"unknown SingGuard policy {name!r}; known: {', '.join(POLICIES)}")
+    return name
+
+
+def policy_text(name: str) -> str | None:
+    """The text to send for policy *name*: ``None`` for ``default`` (SingGuard's own rules)."""
+    return _TEXT[_known(name)]
+
+
+def illegal_rules(name: str) -> frozenset[str]:
+    """The rule letters under policy *name* whose firing means illegal content."""
+    return _ILLEGAL[_known(name)]
+
+
+def is_illegal(name: str, rule: str) -> bool:
+    """*rule*, as a verdict reports it (``"H. Non-Consensual Sexual Content"`` or ``"H"``), is illegal under *name*."""
+    return rule_letter(rule).removesuffix(".").upper() in illegal_rules(name)
+
+
+def mode(name: str) -> Mode:
+    """``sfw`` for ``default`` and any ``sfw-*`` name, else ``nsfw``. By name, so it needs no table entry."""
+    return "sfw" if name == "default" or name.startswith(SFW_PREFIX) else "nsfw"

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/src/argus_cortex/moderation/singguard.py

@@ -8,8 +8,19 @@ 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}``.
+thinking}`` (or ``{input, input_role, policy, thinking}`` for a text-only
+check, which not every server takes), 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).
@@ -27,7 +38,9 @@ from pydantic import BaseModel, Field
 
 from argus_cortex.moderation._http import CheckFailed, ModerationConfigError, post_json, service_url
 
-THINKING_MODES = ("fast", "fast-slow")
+THINKING_MODES = ("fast", "fast-slow", "slow", "cascade")
+# Who wrote the text of a text-only check: the person asking, or a model answering.
+INPUT_ROLES = ("user", "assistant")
 # The guard model sees far fewer pixels than a camera original, and base64
 # JSON inflates every byte by 4/3.
 MAX_EDGE = 1536
@@ -51,6 +64,9 @@ class GuardResult(BaseModel):
     # 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):
@@ -104,6 +120,7 @@ def to_result(payload: object, policy: str = "default") -> GuardResult:
         explanation=_clip(payload.get("explanation"), _EXPLANATION_MAX),
         model=_clip(payload.get("model"), _FIELD_MAX),
         policy=policy,
+        thinking=_clip(payload.get("thinking"), _FIELD_MAX),
     )
 
 
@@ -154,7 +171,10 @@ 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 ``fast`` (verdict and rule) or ``fast-slow`` (also writes why).
+    *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.
@@ -188,11 +208,23 @@ class SingGuardClient:
         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,
-        }
+        return self._post({"input": text, "image_base64": base64.b64encode(image).decode("ascii")})
+
+    def check_text(self, text: str, role: str = "user") -> GuardResult:
+        """Judge *text* with no image: a prompt before it is run (``role="user"``), or a model's reply
+        (``"assistant"``).
+
+        Needs a server that takes a check without ``image_base64``: agent-composer's guard router
+        does; argus-cull's ``singguard`` service answers HTTP 422, raised as :class:`GuardCheckFailed`.
+        """
+        if role not in INPUT_ROLES:
+            raise ValueError(f"role must be one of {', '.join(INPUT_ROLES)}")
+        if not text.strip():
+            raise ValueError("there is no text to check")
+        return self._post({"input": text, "input_role": role})
+
+    def _post(self, body: dict[str, str]) -> GuardResult:
+        body["thinking"] = self.thinking
         if self.policy is not None:
             body["policy"] = self.policy
         payload = post_json(

{argus_cortex-0.4.0 → argus_cortex-0.4.2}/tests/test_moderation.py

@@ -102,20 +102,25 @@ class _NudeNet(_Fake):
 
 
 class _SingGuard(_Fake):
-    answers: dict[int, dict] = {}
+    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]
+        if "image_base64" in body:
+            image = Image.open(io.BytesIO(base64.b64decode(body["image_base64"])))
+            red = image.convert("RGB").getpixel((0, 0))[0]
+            size, fmt = image.size, image.format
+        else:  # a text-only check: the text picks the answer
+            red, size, fmt = _TEXT_ANSWERS.get(body["input"], 10), None, None
         type(self).seen.append(
-            {"path": self.path, "size": image.size, "format": image.format,
+            {"path": self.path, "size": size, "format": fmt,
              **{k: v for k, v in body.items() if k != "image_base64"}}
         )  # fmt: skip
         if red == _FAIL:
             self._send(500)
         else:
-            self._send(200, {**_GUARD_ANSWERS.get(red, _GUARD_ANSWERS[10]), "model": "SingGuard-4b", "elapsed_ms": 5})
+            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]]:
@@ -229,6 +234,7 @@ _GUARD_ANSWERS: dict[int, dict] = {
     30: {"safe": False, "verdict": "unsafe", "rule": _GORE, "explanation": "", "categories": 5},  # malformed
     40: {"verdict": "safe"},  # no boolean verdict: a failed check, not a pass
 }
+_TEXT_ANSWERS = {"rob a bank": 20, "fail": _FAIL}  # a text-only check's input -> the red value it answers as
 
 
 def test_singguard_config() -> None:
@@ -239,7 +245,8 @@ def test_singguard_config() -> None:
     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
-    for kwargs in ({"thinking": "slow"}, {"policy": " \n"}):
+    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):
@@ -263,12 +270,44 @@ def test_singguard_check(singguard_server) -> None:
     assert {s["thinking"] for s in fake.seen} == {"fast-slow"} and {s["policy"] for s in fake.seen} == {"### A. Minors"}
 
 
+def test_singguard_check_text(singguard_server) -> None:
+    """A text-only check sends no image, says whose text it is, and keeps the client's policy and mode."""
+    fake, url = singguard_server
+    client = SingGuardClient(url, timeout=5, thinking="cascade", policy="### A. Minors")
+    assert client.check_text("a cat on a sofa").safe
+    assert client.check_text("rob a bank", role="assistant").rules == [_CRIME, _GORE]
+    with pytest.raises(GuardCheckFailed, match="HTTP 500"):
+        client.check_text("fail")
+    assert all("image_base64" not in s and s["size"] is None for s in fake.seen)
+    assert [s["input_role"] for s in fake.seen] == ["user", "assistant", "user"]
+    assert {s["thinking"] for s in fake.seen} == {"cascade"} and {s["policy"] for s in fake.seen} == {"### A. Minors"}
+    for text, role in (("", "user"), (" \n", "user"), ("hi", "system")):
+        with pytest.raises(ValueError):
+            client.check_text(text, role=role)
+    assert len(fake.seen) == 3  # a bad argument never reaches the server
+
+
 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)))

argus_cortex-0.4.2/tests/test_policies.py

@@ -0,0 +1,54 @@
+"""The named SingGuard policies: their texts, illegal rules and modes."""
+
+from __future__ import annotations
+
+import pytest
+
+from argus_cortex.moderation import ModerationConfigError, SingGuardClient, policies, policy_name
+
+
+def test_every_policy_has_a_text_and_an_illegal_table() -> None:
+    assert policies.POLICIES == ("default", "adult", "adult-granular", "adult-cautious")
+    assert policies.policy_text("default") is None  # SingGuard's own rules: nothing is sent
+    for name in policies.POLICIES[1:]:
+        text = policies.policy_text(name)
+        assert text.startswith("## Risk Categories\n") and "### Safe" in text
+        # The client sends it as written, so a recorded policy name is stable.
+        assert SingGuardClient("http://g", policy=text, downscale=False).policy_name == policy_name(text)
+    assert len({policies.policy_text(n) for n in policies.POLICIES}) == len(policies.POLICIES)
+
+
+def test_illegal_rules_are_per_policy() -> None:
+    assert policies.illegal_rules("default") == frozenset()  # its A is all sexual content, adult included
+    assert policies.illegal_rules("adult-granular") == {"A", "H", "I"}
+    assert policies.illegal_rules("adult") == policies.illegal_rules("adult-cautious") == {"A"}
+    # Each illegal letter is a heading in that policy's own text.
+    for name in policies.POLICIES[1:]:
+        for letter in policies.illegal_rules(name):
+            assert f"\n### {letter}. " in policies.policy_text(name)
+
+
+def test_is_illegal_reads_a_rule_as_verdicts_report_it() -> None:
+    assert policies.is_illegal("adult-granular", "H. Non-Consensual Sexual Content")
+    assert policies.is_illegal("adult-granular", "I") and policies.is_illegal("adult-granular", "a.")
+    assert policies.is_illegal("adult", "A. Illegal or Extreme Sexual Content")
+    assert not policies.is_illegal("default", "A. Sexual Content Risk")
+    for name in policies.POLICIES:  # crime and animal abuse go to review, never deletion
+        assert not policies.is_illegal(name, "B. Real-World Crimes & Public Safety")
+        assert not policies.is_illegal(name, "G. Animal Abuse")
+        assert not policies.is_illegal(name, "Safe")
+
+
+def test_mode_is_by_name() -> None:
+    assert policies.mode("default") == "sfw"
+    assert policies.mode("sfw-strict") == "sfw"  # a later SFW policy needs no table entry
+    assert [policies.mode(n) for n in policies.POLICIES[1:]] == ["nsfw"] * 3
+    assert policies.mode("defaults") == "nsfw"
+
+
+def test_unknown_policy_names_are_refused() -> None:
+    for call in (policies.policy_text, policies.illegal_rules):
+        with pytest.raises(ModerationConfigError, match="unknown SingGuard policy"):
+            call("adult-lax")
+    with pytest.raises(ModerationConfigError):
+        policies.is_illegal("adult-lax", "A")