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

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

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-10-30
+
+### Added
+- **`argus_cortex.gpu`**: GPU tenancy shared across the stages, generalised
+  from argus-lens's `gpu` coordinator.
+  - `GpuCoordinator`: the protocol. `lease(caller=, min_vram_mb=)` is a
+    context manager that holds a GPU slot for its body. `GpuLeaseTimeout` is a
+    `TimeoutError`.
+  - `NullCoordinator`: no gating, and the default.
+  - `LeaseCoordinator`: an exclusive `flock` that every argus process on the
+    host takes, then, while still holding it, a wait until `free_vram_mb()`
+    reports `min_vram_mb`. Unlike lens's lease, `min_vram_mb` is honoured. NVML
+    counts every process on the card, so ComfyUI and Ollama are accounted for
+    without taking part. One deadline covers both waits. A probe that cannot
+    run (no driver, no `[gpu]` extra, a CPU host) lets the lease through.
+  - `free_vram_mb(device)`: NVML free memory in MB, or `None`.
+  - `build_coordinator()` / `coordinator_from_env()`: `ARGUS_GPU_COORDINATOR`
+    (`none` / `lease`), `ARGUS_GPU_LEASE_PATH`, `ARGUS_GPU_LEASE_TIMEOUT_S`
+    (300 s) and `ARGUS_GPU_DEVICE`. These are the names lens already reads. An
+    unusable number logs a warning and falls back to the default.
+  - The default lock is `<tempdir>/argus-gpu.lock`. Containers have their own
+    `/tmp`, so a shared lock needs `ARGUS_GPU_LEASE_PATH` on a volume every
+    GPU service mounts. The lock file is `chmod 0o666` after create so a
+    restrictive umask does not block other container UIDs from opening it.
+- `[gpu]` extra: `nvidia-ml-py`, imported only when probed.
+
+## [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
@@ -116,7 +164,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.1...HEAD
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.3...HEAD
+[0.4.3]: https://github.com/smk762/argus-cortex/compare/v0.4.2...v0.4.3
+[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

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

@@ -18,8 +18,9 @@ Because everything here is imported by the downstream stages, **a change ripples
 - `wire.py` — the versioned wire-schema toolkit consumers build their contracts on: `make_versioned_base(field_name, current, majors)` (a Pydantic base that stamps + version-checks a field like `proof_version`/`manifest_version`), `check_version()` (the major-compatibility gate), `render_schema()`/`wire_schema()` (the canonical committed-schema string behind each consumer's `schema --check` CLI), and `VersionError`.
 - `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]`.
+- `gpu.py` — GPU tenancy (from argus-lens): the `GpuCoordinator` protocol (`lease(caller=, min_vram_mb=)`), `NullCoordinator`, `LeaseCoordinator` (host-wide `flock` **then** a wait for NVML free VRAM, so tenants outside the lock like ComfyUI and Ollama are accounted for), `free_vram_mb()`, `coordinator_from_env()` (`ARGUS_GPU_*` — host-wide names on purpose: every process must agree). NVML lazily, behind `[gpu]`; a probe that cannot run grants the lease. **The lock file must be on a volume every GPU container mounts** — per-container `/tmp` coordinates nothing.
 - `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.1 → argus_cortex-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.4.1
+Version: 0.4.3
 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,6 +20,7 @@ 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: nvidia-ml-py>=12.535; 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'
@@ -27,6 +28,8 @@ 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: gpu
+Requires-Dist: nvidia-ml-py>=12.535; extra == 'gpu'
 Provides-Extra: images
 Requires-Dist: pillow>=10.0; extra == 'images'
 Provides-Extra: postgres
@@ -58,6 +61,7 @@ Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (q
 - **`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.gpu`**: GPU tenancy, generalised from argus-lens. `coordinator_from_env()` returns a coordinator whose `lease(caller=, min_vram_mb=)` holds a GPU slot for a block of work. `none` (the default) grants every lease at once. `lease` takes an exclusive `flock` that every argus process on the host shares (one lock for the host, not per GPU), then waits until `free_vram_mb()` (NVML, behind `[gpu]`) reports `min_vram_mb` free across *every* process on the card, ComfyUI and Ollama included, which never take the lock. It raises `GpuLeaseTimeout` after `ARGUS_GPU_LEASE_TIMEOUT_S` (300 s). The VRAM check is a snapshot, not a reservation, and a probe that cannot run lets the lease through. Containers each have their own `/tmp`, so set `ARGUS_GPU_LEASE_PATH` to a file on a volume every GPU service mounts, or the lock coordinates nothing.
 - **`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.
@@ -103,10 +107,33 @@ guard = SingGuardClient("http://guard:9150", policy=None)  # None = SingGuard's
 # 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).
+
+```python
+from argus_cortex.gpu import GpuLeaseTimeout, coordinator_from_env
+
+gpu = coordinator_from_env()   # ARGUS_GPU_COORDINATOR=lease, ARGUS_GPU_LEASE_PATH=/shared/argus-gpu.lock
+try:
+    with gpu.lease(caller="faces", min_vram_mb=1500):   # one argus job at a time, and 1.5 GB free
+        run_the_model()
+except GpuLeaseTimeout:
+    ...   # no slot in time: back off, or answer 503
+```
+
 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.1 → argus_cortex-0.4.3}/README.md

@@ -12,6 +12,7 @@ Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (q
 - **`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.gpu`**: GPU tenancy, generalised from argus-lens. `coordinator_from_env()` returns a coordinator whose `lease(caller=, min_vram_mb=)` holds a GPU slot for a block of work. `none` (the default) grants every lease at once. `lease` takes an exclusive `flock` that every argus process on the host shares (one lock for the host, not per GPU), then waits until `free_vram_mb()` (NVML, behind `[gpu]`) reports `min_vram_mb` free across *every* process on the card, ComfyUI and Ollama included, which never take the lock. It raises `GpuLeaseTimeout` after `ARGUS_GPU_LEASE_TIMEOUT_S` (300 s). The VRAM check is a snapshot, not a reservation, and a probe that cannot run lets the lease through. Containers each have their own `/tmp`, so set `ARGUS_GPU_LEASE_PATH` to a file on a volume every GPU service mounts, or the lock coordinates nothing.
 - **`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.
@@ -57,10 +58,33 @@ guard = SingGuardClient("http://guard:9150", policy=None)  # None = SingGuard's
 # 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).
+
+```python
+from argus_cortex.gpu import GpuLeaseTimeout, coordinator_from_env
+
+gpu = coordinator_from_env()   # ARGUS_GPU_COORDINATOR=lease, ARGUS_GPU_LEASE_PATH=/shared/argus-gpu.lock
+try:
+    with gpu.lease(caller="faces", min_vram_mb=1500):   # one argus job at a time, and 1.5 GB free
+        run_the_model()
+except GpuLeaseTimeout:
+    ...   # no slot in time: back off, or answer 503
+```
+
 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.1 → argus_cortex-0.4.3}/pyproject.toml

@@ -35,6 +35,9 @@ 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"]
+# NVML (nvidia-ml-py, imported as pynvml), for argus_cortex.gpu's free-VRAM probe;
+# imported only when probed. Without it the lease skips the VRAM wait.
+gpu = ["nvidia-ml-py>=12.535"]
 # 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).
@@ -49,6 +52,7 @@ dev = [
     "httpx>=0.27",
     "httpx2>=2.7",
     "pillow>=10.0",
+    "nvidia-ml-py>=12.535",
     "certifi>=2026.10.19",
 ]
 

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

argus_cortex-0.4.3/src/argus_cortex/gpu.py

@@ -0,0 +1,242 @@
+"""GPU tenancy shared across the suite: one heavy argus job on a GPU at a time,
+and only once the card has room for it.
+
+Generalised from argus-lens's ``gpu`` coordinator so every stage that runs a
+model on a GPU it shares (lens captioning, curator's faces, alongside ComfyUI
+and an Ollama-backed SingGuard) takes the same lease.
+
+* :class:`GpuCoordinator`: the protocol: ``lease(caller=, min_vram_mb=)`` is a
+  context manager that holds a GPU slot for its body.
+* :class:`NullCoordinator`: no gating, the default.
+* :class:`LeaseCoordinator`: an advisory file lock (POSIX ``flock``) taken by
+  every argus process on the host, then a wait until :func:`free_vram_mb` reports
+  ``min_vram_mb`` free. The lock orders argus jobs among themselves; the VRAM wait
+  is what accounts for tenants that never take the lock (ComfyUI, Ollama), since
+  NVML reports free memory across every process on the card.
+* :func:`coordinator_from_env`: ``ARGUS_GPU_COORDINATOR`` (``none``/``lease``),
+  ``ARGUS_GPU_LEASE_PATH``, ``ARGUS_GPU_LEASE_TIMEOUT_S``, ``ARGUS_GPU_DEVICE``.
+  The names are host-wide, not per stage: every process must agree on them.
+  One lock serialises every argus GPU job on the host; ``ARGUS_GPU_DEVICE``
+  only selects which card NVML probes.
+
+The VRAM check is a snapshot, not a reservation: a tenant outside the lock can
+still allocate between the check and the job. Each stage owns its footprint
+estimates (``min_vram_mb``); a probe that cannot run (no driver, no NVML, a CPU
+host) lets the lease through rather than blocking forever.
+
+Containers have their own ``/tmp``: the lock only coordinates processes that see
+the same file, so point ``ARGUS_GPU_LEASE_PATH`` at a volume every GPU service
+mounts. ``flock`` works across containers on one host kernel. NVML is behind the
+``[gpu]`` extra (``nvidia-ml-py``) and imported only when probed.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import math
+import os
+import tempfile
+import threading
+import time
+from collections.abc import Callable, Iterator
+from typing import Protocol, runtime_checkable
+
+_log = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT_S = 300.0
+DEFAULT_POLL_S = 0.5
+COORDINATORS = ("none", "lease")
+
+_nvml_lock = threading.Lock()
+_nvml_ready: bool | None = None  # None: not tried yet; False: NVML cannot run here
+
+
+class GpuLeaseTimeout(TimeoutError):
+    """No GPU slot within the timeout: the lock stayed held, or the card never had room.
+
+    A ``TimeoutError``, so a caller can catch either, and tell "no GPU slot" from
+    a failed job and back off.
+    """
+
+
+@runtime_checkable
+class GpuCoordinator(Protocol):
+    """Gates a block of GPU work behind a lease."""
+
+    name: str
+
+    def lease(self, *, caller: str, min_vram_mb: int) -> contextlib.AbstractContextManager[None]:
+        """A context manager that holds a GPU slot for its body."""
+        ...
+
+
+class NullCoordinator:
+    """No gating: every lease is granted at once. The default."""
+
+    name = "none"
+
+    @contextlib.contextmanager
+    def lease(self, *, caller: str, min_vram_mb: int) -> Iterator[None]:
+        yield
+
+
+def free_vram_mb(device: int = 0) -> int | None:
+    """Free VRAM on NVML device *device*, in MB, across every process on it.
+
+    ``None`` when it cannot be read: no ``[gpu]`` extra, no driver, no such
+    device. NVML numbers devices as ``nvidia-smi`` does, which inside a container
+    means the GPUs the container was given.
+    """
+    global _nvml_ready
+    try:
+        import pynvml  # noqa: PLC0415 - optional, behind the [gpu] extra
+    except ImportError:
+        return None
+    with _nvml_lock:
+        if _nvml_ready is None:
+            try:
+                pynvml.nvmlInit()
+                _nvml_ready = True
+            except Exception:  # noqa: BLE001 - any NVML failure means "cannot probe"
+                _nvml_ready = False
+        if not _nvml_ready:
+            return None
+    try:
+        info = pynvml.nvmlDeviceGetMemoryInfo(pynvml.nvmlDeviceGetHandleByIndex(device))
+    except Exception:  # noqa: BLE001
+        return None
+    return max(0, int(info.free) // (1024 * 1024))
+
+
+def default_lock_path() -> str:
+    """``<tempdir>/argus-gpu.lock``: shared only by processes that share that directory."""
+    return os.path.join(tempfile.gettempdir(), "argus-gpu.lock")
+
+
+class LeaseCoordinator:
+    """One argus GPU job at a time on this host, started only when the card has room.
+
+    Takes an exclusive ``flock`` on *lock_path*, then (when *min_vram_mb* > 0)
+    waits until *probe* reports that much free, polling every *poll_s*. The lock
+    is held through the wait, so the next argus job cannot take the room first.
+    Both waits share one *timeout_s* deadline; past it :class:`GpuLeaseTimeout`
+    is raised and the lock released. A probe answering ``None`` grants the lease.
+    """
+
+    name = "lease"
+
+    def __init__(
+        self,
+        lock_path: str | None = None,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        poll_s: float = DEFAULT_POLL_S,
+        device: int = 0,
+        probe: Callable[[int], int | None] = free_vram_mb,
+    ) -> None:
+        if not math.isfinite(timeout_s):
+            raise ValueError("timeout_s must be a finite number")
+        self.lock_path = lock_path or default_lock_path()
+        self.timeout_s = max(0.0, timeout_s)
+        self.poll_s = poll_s
+        self.device = device
+        self.probe = probe
+
+    @contextlib.contextmanager
+    def lease(self, *, caller: str, min_vram_mb: int) -> Iterator[None]:
+        try:
+            import fcntl  # noqa: PLC0415 - POSIX only
+        except ImportError as exc:  # pragma: no cover - non-POSIX host
+            raise RuntimeError("the 'lease' GPU coordinator needs POSIX fcntl; use 'none'") from exc
+
+        deadline = time.monotonic() + self.timeout_s
+        directory = os.path.dirname(self.lock_path)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+        # 0o666: services in different containers may run as different users.
+        # os.open's mode is masked by umask, so chmod the fd or the file is
+        # 0644/0600 and the next UID cannot open it.
+        fd = os.open(self.lock_path, os.O_CREAT | os.O_RDWR, 0o666)
+        try:
+            with contextlib.suppress(OSError):
+                os.fchmod(fd, 0o666)
+            while True:
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    if time.monotonic() >= deadline:
+                        raise GpuLeaseTimeout(
+                            f"GPU lease not acquired within {self.timeout_s:g}s ({self.lock_path})"
+                        ) from None
+                    time.sleep(self.poll_s)
+            try:
+                self._wait_for_room(caller, min_vram_mb, deadline)
+                _log.debug("gpu lease acquired by %s (min %d MB, %s)", caller, min_vram_mb, self.lock_path)
+                yield
+            finally:
+                with contextlib.suppress(OSError):
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
+
+    def _wait_for_room(self, caller: str, min_vram_mb: int, deadline: float) -> None:
+        if min_vram_mb <= 0:
+            return
+        while True:
+            free = self.probe(self.device)
+            if free is None or free >= min_vram_mb:
+                return
+            if time.monotonic() >= deadline:
+                raise GpuLeaseTimeout(
+                    f"GPU {self.device} had {free} MB free, {caller} needs {min_vram_mb} MB, after {self.timeout_s:g}s"
+                )
+            time.sleep(self.poll_s)
+
+
+def build_coordinator(
+    name: str,
+    *,
+    lock_path: str | None = None,
+    timeout_s: float | None = None,
+    device: int = 0,
+) -> GpuCoordinator:
+    """A coordinator by name, one of :data:`COORDINATORS` (empty is ``none``)."""
+    key = (name or "none").strip().lower()
+    if key == "none":
+        return NullCoordinator()
+    if key == "lease":
+        return LeaseCoordinator(
+            lock_path=lock_path,
+            timeout_s=DEFAULT_TIMEOUT_S if timeout_s is None else timeout_s,
+            device=device,
+        )
+    raise ValueError(f"unknown GPU coordinator {name!r}; choose from: {', '.join(COORDINATORS)}")
+
+
+def _env_number(name: str, kind: type[float] | type[int]) -> float | int | None:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return None
+    try:
+        value = kind(raw)
+    except (ValueError, OverflowError):
+        value = -1
+    # inf/nan parse as float and never compare < 0, so the deadline never fires.
+    if isinstance(value, float) and not math.isfinite(value):
+        value = -1
+    if value < 0:
+        _log.warning("%s set to an unusable value %r; using the default", name, raw)
+        return None
+    return value
+
+
+def coordinator_from_env() -> GpuCoordinator:
+    """The coordinator the environment names; ``none`` when ``ARGUS_GPU_COORDINATOR`` is unset."""
+    device = _env_number("ARGUS_GPU_DEVICE", int)
+    return build_coordinator(
+        os.environ.get("ARGUS_GPU_COORDINATOR", "none"),
+        lock_path=os.environ.get("ARGUS_GPU_LEASE_PATH") or None,
+        timeout_s=_env_number("ARGUS_GPU_LEASE_TIMEOUT_S", float),
+        device=0 if device is None else int(device),
+    )

{argus_cortex-0.4.1 → argus_cortex-0.4.3}/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.3/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.1 → argus_cortex-0.4.3}/src/argus_cortex/moderation/singguard.py

@@ -8,7 +8,8 @@ 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:
+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.
@@ -38,6 +39,8 @@ from pydantic import BaseModel, Field
 from argus_cortex.moderation._http import CheckFailed, ModerationConfigError, post_json, service_url
 
 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
@@ -205,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.3/tests/test_gpu.py

@@ -0,0 +1,227 @@
+"""GPU coordination: the file lease, the VRAM wait, and configuration from the environment."""
+
+from __future__ import annotations
+
+import builtins
+import os
+import threading
+from pathlib import Path
+
+import pytest
+
+from argus_cortex import gpu
+
+
+@pytest.fixture(autouse=True)
+def _reset_nvml_ready(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(gpu, "_nvml_ready", None)
+
+
+def _lease(tmp_path: Path, probe=lambda device: None, timeout_s: float = 5.0) -> gpu.LeaseCoordinator:  # noqa: ANN001
+    return gpu.LeaseCoordinator(
+        lock_path=str(tmp_path / "locks" / "gpu.lock"), timeout_s=timeout_s, poll_s=0.01, probe=probe
+    )
+
+
+def test_null_coordinator_grants_at_once() -> None:
+    coordinator = gpu.NullCoordinator()
+    assert isinstance(coordinator, gpu.GpuCoordinator)
+    with coordinator.lease(caller="t", min_vram_mb=10**9):
+        pass
+
+
+def test_lock_file_is_world_writable_despite_umask(tmp_path: Path) -> None:
+    """os.open's mode is umask-masked; without fchmod the next container UID cannot open the lock."""
+    path = tmp_path / "locks" / "gpu.lock"
+    previous = os.umask(0o077)
+    try:
+        with gpu.LeaseCoordinator(lock_path=str(path), timeout_s=1, probe=lambda device: None).lease(
+            caller="a", min_vram_mb=0
+        ):
+            mode = path.stat().st_mode & 0o777
+    finally:
+        os.umask(previous)
+    assert mode == 0o666
+
+
+def test_lease_released_when_the_body_raises(tmp_path: Path) -> None:
+    with (
+        pytest.raises(RuntimeError, match="boom"),
+        _lease(tmp_path).lease(caller="a", min_vram_mb=0),
+    ):
+        raise RuntimeError("boom")
+    with _lease(tmp_path, timeout_s=0.05).lease(caller="b", min_vram_mb=0):
+        pass
+
+
+def test_lease_is_exclusive_and_released(tmp_path: Path) -> None:
+    """A second holder waits for the first; a holder that never lets go times the other out."""
+    holder, waiter = _lease(tmp_path), _lease(tmp_path, timeout_s=0.1)
+    assert isinstance(holder, gpu.GpuCoordinator)
+    with (
+        holder.lease(caller="a", min_vram_mb=0),
+        pytest.raises(gpu.GpuLeaseTimeout, match="not acquired"),
+        waiter.lease(caller="b", min_vram_mb=0),
+    ):
+        pass
+    with waiter.lease(caller="b", min_vram_mb=0):  # free again once the first exits
+        pass
+
+
+def test_lease_waits_for_the_holder_to_finish(tmp_path: Path) -> None:
+    order: list[str] = []
+    entered, release = threading.Event(), threading.Event()
+
+    def first() -> None:
+        with _lease(tmp_path).lease(caller="a", min_vram_mb=0):
+            entered.set()
+            release.wait(5)
+            order.append("a done")
+
+    thread = threading.Thread(target=first)
+    thread.start()
+    assert entered.wait(5)
+    threading.Timer(0.05, release.set).start()
+    with _lease(tmp_path).lease(caller="b", min_vram_mb=0):
+        order.append("b in")
+    thread.join(5)
+    assert order == ["a done", "b in"]
+
+
+def test_lease_waits_for_free_vram_while_holding_the_lock(tmp_path: Path) -> None:
+    readings = iter([1000, 2000, 9000])
+    seen: list[int] = []
+
+    def probe(device: int) -> int | None:
+        seen.append(device)
+        return next(readings)
+
+    coordinator = _lease(tmp_path, probe=probe)
+    # The lock is held during and after the wait: another argus job cannot take the room.
+    with (
+        coordinator.lease(caller="faces", min_vram_mb=4000),
+        pytest.raises(gpu.GpuLeaseTimeout),
+        _lease(tmp_path, timeout_s=0.05).lease(caller="lens", min_vram_mb=0),
+    ):
+        pass
+    assert seen == [0, 0, 0]
+
+
+def test_lease_times_out_when_the_card_never_has_room_and_lets_go(tmp_path: Path) -> None:
+    coordinator = _lease(tmp_path, probe=lambda device: 500, timeout_s=0.05)
+    with (
+        pytest.raises(gpu.GpuLeaseTimeout, match="500 MB free, faces needs 4000 MB"),
+        coordinator.lease(caller="faces", min_vram_mb=4000),
+    ):
+        pass
+    with _lease(tmp_path, timeout_s=0.05).lease(caller="next", min_vram_mb=0):  # the lock was released
+        pass
+
+
+def test_lease_proceeds_when_vram_cannot_be_read_or_is_not_needed(tmp_path: Path) -> None:
+    calls: list[int] = []
+    with _lease(tmp_path, probe=lambda device: calls.append(device)).lease(caller="cpu host", min_vram_mb=4000):
+        pass
+    assert calls == [0]  # asked once, got None, went ahead
+    with _lease(tmp_path, probe=lambda device: pytest.fail("probed")).lease(caller="tiny", min_vram_mb=0):
+        pass
+
+
+def test_free_vram_reads_bytes_for_the_asked_device(monkeypatch: pytest.MonkeyPatch) -> None:
+    import sys
+    import types
+
+    fake = types.ModuleType("pynvml")
+    seen: list[int] = []
+
+    class _Info:
+        free = 3 * 1024 * 1024 * 1024
+
+    def handle(index: int) -> str:
+        seen.append(index)
+        return f"dev{index}"
+
+    def memory_info(dev: str) -> _Info:
+        assert dev == "dev2"
+        return _Info()
+
+    fake.nvmlInit = lambda: None  # type: ignore[attr-defined]
+    fake.nvmlDeviceGetHandleByIndex = handle  # type: ignore[attr-defined]
+    fake.nvmlDeviceGetMemoryInfo = memory_info  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "pynvml", fake)
+    assert gpu.free_vram_mb(2) == 3072
+    assert seen == [2]
+
+
+def test_free_vram_is_none_without_nvml(monkeypatch: pytest.MonkeyPatch) -> None:
+    real_import = builtins.__import__
+
+    def no_pynvml(name: str, *args, **kwargs):  # noqa: ANN002, ANN003, ANN202
+        if name == "pynvml":
+            raise ImportError(name)
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", no_pynvml)
+    assert gpu.free_vram_mb() is None
+
+
+def test_free_vram_is_none_when_nvml_cannot_start(monkeypatch: pytest.MonkeyPatch) -> None:
+    """No driver: NVML init fails once and is not retried on every probe."""
+    import sys
+    import types
+
+    attempts: list[int] = []
+    fake = types.ModuleType("pynvml")
+
+    def init() -> None:
+        attempts.append(1)
+        raise RuntimeError("NVML Shared Library Not Found")
+
+    fake.nvmlInit = init  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "pynvml", fake)
+    monkeypatch.setattr(gpu, "_nvml_ready", None)
+    assert gpu.free_vram_mb() is None and gpu.free_vram_mb() is None
+    assert attempts == [1]
+
+
+def test_build_coordinator() -> None:
+    assert isinstance(gpu.build_coordinator(""), gpu.NullCoordinator)
+    assert isinstance(gpu.build_coordinator(" NONE "), gpu.NullCoordinator)
+    lease = gpu.build_coordinator("lease", lock_path="/x/gpu.lock", timeout_s=7, device=1)
+    assert isinstance(lease, gpu.LeaseCoordinator)
+    assert (lease.lock_path, lease.timeout_s, lease.device) == ("/x/gpu.lock", 7, 1)
+    assert gpu.build_coordinator("lease").lock_path == gpu.default_lock_path()
+    with pytest.raises(ValueError, match="none, lease"):
+        gpu.build_coordinator("gothmog")
+    with pytest.raises(ValueError, match="finite"):
+        gpu.LeaseCoordinator(timeout_s=float("inf"))
+    with pytest.raises(ValueError, match="finite"):
+        gpu.LeaseCoordinator(timeout_s=float("nan"))
+
+
+def test_coordinator_from_env(monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture) -> None:
+    for name in ("ARGUS_GPU_COORDINATOR", "ARGUS_GPU_LEASE_PATH", "ARGUS_GPU_LEASE_TIMEOUT_S", "ARGUS_GPU_DEVICE"):
+        monkeypatch.delenv(name, raising=False)
+    assert isinstance(gpu.coordinator_from_env(), gpu.NullCoordinator)
+    monkeypatch.setenv("ARGUS_GPU_COORDINATOR", "lease")
+    monkeypatch.setenv("ARGUS_GPU_LEASE_PATH", "/shared/argus-gpu.lock")
+    monkeypatch.setenv("ARGUS_GPU_LEASE_TIMEOUT_S", "30")
+    monkeypatch.setenv("ARGUS_GPU_DEVICE", "1")
+    lease = gpu.coordinator_from_env()
+    assert (lease.lock_path, lease.timeout_s, lease.device) == ("/shared/argus-gpu.lock", 30.0, 1)
+    monkeypatch.setenv("ARGUS_GPU_LEASE_TIMEOUT_S", "soon")
+    monkeypatch.setenv("ARGUS_GPU_DEVICE", "-1")
+    with caplog.at_level("WARNING"):
+        lease = gpu.coordinator_from_env()
+    assert (lease.timeout_s, lease.device) == (gpu.DEFAULT_TIMEOUT_S, 0)
+    assert "ARGUS_GPU_LEASE_TIMEOUT_S" in caplog.text and "ARGUS_GPU_DEVICE" in caplog.text
+    caplog.clear()
+    monkeypatch.setenv("ARGUS_GPU_LEASE_TIMEOUT_S", "inf")
+    with caplog.at_level("WARNING"):
+        assert gpu.coordinator_from_env().timeout_s == gpu.DEFAULT_TIMEOUT_S
+    assert "ARGUS_GPU_LEASE_TIMEOUT_S" in caplog.text
+    caplog.clear()
+    monkeypatch.setenv("ARGUS_GPU_LEASE_TIMEOUT_S", "nan")
+    with caplog.at_level("WARNING"):
+        assert gpu.coordinator_from_env().timeout_s == gpu.DEFAULT_TIMEOUT_S
+    assert "ARGUS_GPU_LEASE_TIMEOUT_S" in caplog.text

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

@@ -106,10 +106,14 @@ class _SingGuard(_Fake):
 
     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:
@@ -230,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:
@@ -265,6 +270,23 @@ 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))

argus_cortex-0.4.3/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")