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

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

@@ -7,6 +7,19 @@ 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
@@ -103,7 +116,8 @@ 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.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.4.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
@@ -99,6 +99,9 @@ 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

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

@@ -53,6 +53,9 @@ 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

{argus_cortex-0.4.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.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
 __commit_id__ = commit_id = None

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

@@ -9,7 +9,17 @@ 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}``.
+[{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 +37,7 @@ 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")
 # 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 +61,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 +117,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 +168,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.

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

@@ -102,7 +102,7 @@ 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"])))
@@ -115,7 +115,8 @@ class _SingGuard(_Fake):
         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]]:
@@ -239,7 +240,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):
@@ -269,6 +271,21 @@ def test_singguard_default_policy_is_not_sent(singguard_server) -> None:
     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)))