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

argus_cortex-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,120 @@
+name: Release to PyPI
+
+# Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
+# a reusable workflow. Keep this file in sync across the suite via `copier update`.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-install:
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install wheel and smoke-test import
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install dist/*.whl
+          uv run --no-sync python -c "import argus_cortex; print(f'argus-cortex {argus_cortex.__version__} OK')"
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: test-install
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    # Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
+    # deliberately not gated on it. A TestPyPI-only fault — a missing trusted
+    # publisher, an index outage — must not silently withhold the real release:
+    # that failure mode shipped argus-proof images for two tags with no wheel on
+    # PyPI, and nothing surfaced it because publish-image is independent.
+    # Only the build + install gate is required; a TestPyPI failure still marks
+    # the whole run failed, so the problem stays loud.
+    needs: [test-install, publish-testpypi]
+    if: "!cancelled() && needs.test-install.result == 'success'"
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    # The GitHub Release is the last step, so it only appears once the version is
+    # actually on PyPI. Its notes are this version's CHANGELOG.md section.
+    # Gated on publish-pypi's own result, not the default success(): publish-pypi
+    # runs even when the TestPyPI rehearsal failed, and that must not skip this.
+    runs-on: ubuntu-latest
+    needs: publish-pypi
+    if: "!cancelled() && needs.publish-pypi.result == 'success'"
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract release notes from CHANGELOG.md
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v head="## [${version}]" 'index($0, head) == 1 {found = 1; next} found && /^## \[/ {exit} found' \
+            CHANGELOG.md > notes.md
+          if ! grep -q '[^[:space:]]' notes.md; then
+            echo "::error::CHANGELOG.md has no section for ${version}"
+            exit 1
+          fi
+      - name: Create or update the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          prerelease=""
+          case "$tag" in *-*|*rc*|*a[0-9]*|*b[0-9]*) prerelease="--prerelease" ;; esac
+          if gh release view "$tag" >/dev/null 2>&1; then
+            # Re-run of the workflow: refresh notes and assets rather than failing.
+            gh release edit "$tag" --notes-file notes.md
+            gh release upload "$tag" dist/* --clobber
+          else
+            gh release create "$tag" dist/* --verify-tag --title "$tag" --notes-file notes.md $prerelease
+          fi

argus_cortex-0.4.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-26
+
+### Added
+- **`argus_cortex.moderation`** — content-moderation clients shared by the
+  stages, hoisted from argus-curator. Both talk HTTP to a server the deployer
+  runs; nothing imports a detector.
+  - `NudeNetClient(base_url, timeout)` — a NudeNet server's `/infer`, returning
+    `NsfwResult` (detections, highest score per class, exposed score) and
+    raising `NudeNetCheckFailed` per image. `NudeNetLabel` / `NUDENET_LABELS`
+    are NudeNet's 18 classes; `DEFAULT_EXPOSED_LABELS` (the five exposed
+    buttocks/breast/genitalia/anus classes) and `exposed_score()` are the
+    suite's one definition of nudity.
+  - `SingGuardClient(base_url, timeout, thinking, policy, downscale)` — a
+    SingGuard server's `/api/guard/check`, returning `GuardResult` (verdict,
+    the rules that fired, explanation, model, policy name) and raising
+    `GuardCheckFailed`. `rule_matches()` / `rule_letter()` match rules by
+    letter or full name; `policy_name()` names a custom policy by a sha256
+    prefix.
+  - Proxies in the environment are ignored: images go only to the configured
+    server. Config errors (`ModerationConfigError`) never echo the URL. A
+    `user:password@` in the URL is sent as HTTP Basic auth.
+- `[images]` extra (Pillow), for `SingGuardClient`'s downscaling of images
+  over 1536 px / 4 MB; imported only when it downscales. Downscaling is on by
+  default, so without the extra `SingGuardClient(...)` raises
+  `ModerationConfigError` at construction unless given `downscale=False`.
+
+### Changed
+- `release.yml` now creates the **GitHub Release** for each `v*` tag once the
+  version is on PyPI, with that version's `CHANGELOG.md` section as notes and
+  the built sdist/wheel attached (a missing section fails the job; a re-run
+  edits the Release). Tags with `-`, `rc`, `a<n>` or `b<n>` are pre-releases.
+
+## [0.3.0] - 2026-10-25
+
+### Added
+- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation, hoisted
+  from argus-lens so lens (keywords/caption) and argus-curator (face regions,
+  content rating) share a writer. `write_xmp()` / `read_xmp()` /
+  `merge_xmp()` / `parse_xmp()` / `render_xmp()` / `sidecar_path()` over an
+  `XmpData` model, all exported from the top-level package.
+  - Namespaces: `dc` (subject, description), `xmp` (Rating, Label), `lr`
+    (hierarchicalSubject), `Iptc4xmpExt` (PersonInImage), `mwg-rs` regions
+    (`XmpRegions` / `XmpRegion`, MWG centre-based normalised coordinates), and a
+    new `argus` namespace for `ContentRating`. The `argus` namespace URI
+    (`https://github.com/smk762/argus-cortex/ns/xmp/1.0/`) is now a wire
+    contract.
+  - **Writes merge**: each property set in `XmpData` replaces that property
+    (latest write wins, element or attribute form, across every
+    `rdf:Description`); everything else in the sidecar — Lightroom develop
+    settings, GPS, another stage's fields, foreign namespace prefixes — is
+    preserved. `None` leaves a property untouched, an empty value removes it;
+    `replace=True` discards the existing sidecar.
+  - Writes are atomic (temp file + rename) and keep the existing file mode
+    (`0644` for a new sidecar). An unparseable existing sidecar raises
+    `XmpError` and is never clobbered; a DTD / entity declaration is refused.
+  - Stdlib `xml.etree` + pydantic only, so the top-level import stays
+    pydantic-only.
+- `CLAUDE.md` agent guide.
+
+### Security
+- **eMudhra/emSign CA incident.** The extras that make outbound TLS
+  connections (`[remote]` httpx, `[qdrant]`, `[s3]`) now require
+  `certifi>=2026.10.19`, which no longer trusts the compromised emSign
+  intermediates. See https://discuss.python.org/t/109576.
+
+## [0.2.0] - 2026-07-21
+
+### Added
+- **Optional stateful-services layer** (`argus_cortex.store`), each store opt-in
+  via `CORTEX_*` env vars and a `Null*` no-op when unset:
+  - Phase 1 — Postgres lineage store (`source_asset → caption → human_edit →
+    dataset_membership → training_run`), backed by a psycopg connection pool
+    with an atomic `transaction()` boundary (`[postgres]` extra).
+  - Phase 2 — Qdrant vector store for image / tag-set embeddings
+    (`[qdrant]` extra).
+  - Phase 3 — MinIO/S3 content-addressed blob store, keyed on sha256
+    (`content_key()` == `source_asset.sha256`) (`[s3]` extra).
+- **`argus_cortex.server`** — shared pure-ASGI `WriteGuard`, the
+  `constant_refuse()` / `cross_site_refuse()` predicates, `env_flag()` and the
+  `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants (`[server]` extra).
+
+### Fixed
+- Release: a TestPyPI failure no longer gates the real PyPI release.
+
+## [0.1.0] - 2026-07-08
+
+### Added
+- Initial release (renamed from `argus-core`; that PyPI name was taken):
+  - `argus_cortex.taxonomy` — `TargetProfile`, `TargetStyle`, `TargetCategory`.
+  - `argus_cortex.wire` — versioned wire-schema toolkit (`make_versioned_base`,
+    `check_version` with an injectable error type, `render_schema` /
+    `wire_schema`, `VersionError`).
+  - `argus_cortex.backends` — the local/remote AI-backend contract
+    (`LocalBackend`, `RemoteBackend`, `RemoteProvider`, `with_retries`
+    retrying only transient errors, `resolve_device`).
+
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/smk762/argus-cortex/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/smk762/argus-cortex/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/smk762/argus-cortex/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/smk762/argus-cortex/releases/tag/v0.1.0

argus_cortex-0.4.0/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md — argus-cortex
+
+Guidance for AI agents working in this repo. Human-facing usage lives in [README.md](README.md); this file is the orientation an agent needs to change code safely.
+
+## What this is
+
+The **shared foundation library** of the Argus suite (quarry → curator → lens → forge → proof). It holds the code the stages *share* so it lives in one place instead of copy-pasted per repo: the target taxonomy, the wire-schema versioning discipline, the local/remote AI-backend contract, and the optional stateful-services layer.
+
+Naming: the working directory is `argus-core`, but the GitHub repo, the PyPI package, and the import name are all **`argus-cortex`** (`src/argus_cortex/`). Don't "fix" the mismatch.
+
+Because everything here is imported by the downstream stages, **a change ripples across the whole suite** — treat this repo as an API, not a leaf. Read [README.md](README.md) for the *why* and worked examples; it is the source of truth for behaviour.
+
+## Layout
+
+`src/argus_cortex/` (top level is pydantic-only; everything heavier is behind an extra and lazily imported):
+
+- `taxonomy.py` — the "moat" types every stage inherits verbatim: `TargetProfile`, `TargetStyle`/`TargetCategory` literals. Keep it dependency-light; a change here retrains everyone's expectations.
+- `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]`.
+- `xmp.py` — the suite's XMP sidecar read/merge/write (`write_xmp`/`read_xmp`/`merge_xmp`/`parse_xmp`, `XmpData`/`XmpRegions`, `XmpError`), used by lens (keywords/caption) and curator (faces, content rating). Stdlib `xml.etree` only. **Writes merge — latest wins per property, foreign properties preserved; keep that.** `None` = leave untouched, empty = remove. A DTD is refused and an unparseable sidecar raises rather than being overwritten. The `argus` namespace URI is a wire contract — don't change it.
+- `moderation/` — content-moderation clients over HTTP: `nudenet.py` (`NudeNetClient`, `NsfwResult`, `DEFAULT_EXPOSED_LABELS` — **the suite's one definition of nudity; don't widen it casually**, every stage's NSFW numbers move with it), `singguard.py` (`SingGuardClient`, `GuardResult`, `rule_matches`), `_http.py` (shared POST, proxy-free opener, `CheckFailed`/`ModerationConfigError`). Stdlib + pydantic; Pillow lazily, behind `[images]`. Never import NudeNet (AGPL) — HTTP only. URLs are passed in; stages own their env config.
+- `store/` — the optional stateful-services layer, opt-in per `CORTEX_*` env var: `lineage.py` (Phase 1 Postgres DAG, `open_lineage_store()`), `vector.py` (Phase 2 Qdrant, `open_vector_store()`), `blob.py` (Phase 3 MinIO/S3, `open_blob_store()`), over `config.py`/`models.py`/`errors.py`. Each `open_*()` returns a `Null*` no-op when its URL is unset. Drivers are behind `[postgres]`/`[qdrant]`/`[s3]`.
+
+There is **no CLI and no committed schema in this repo** — the `schema`/`schema --check` pattern is something `wire.py` *enables* for downstream repos, not something cortex runs on itself.
+
+## Commands
+
+```bash
+make install   # uv venv + editable install with [dev]
+make test      # uv run --no-sync pytest --tb=short -q
+make lint      # ruff check + format --check (pinned ruff 0.15.16)
+make format    # ruff format + check --fix
+```
+
+Run one test: `uv run --no-sync pytest tests/test_wire.py::test_name -q`.
+
+## Conventions & gotchas
+
+- **This is shared code — changes ripple.** A `taxonomy.py` edit or a `wire.py`/`backends.py` semantics change lands in every stage on their next bump. Prefer additive, backward-compatible changes; if you break the wire contract, that is a **major** version (`check_version` is what refuses the old major downstream).
+- **Keep the top-level import pydantic-only.** `import argus_cortex` must not pull in starlette/httpx/psycopg/qdrant/minio — those are optional extras, imported lazily inside the module that needs them (see the `try/except ImportError` → "install `argus-cortex[extra]`" pattern). Don't hoist an optional import to module top level.
+- **Stores fail *open* to a no-op, not an error.** `open_*()` returns a `Null*` store when the `CORTEX_*` URL is unset, so a stage with no DB configured still runs. Preserve that; blob identity is content-addressed on sha256 (`content_key()` == `source_asset.sha256`) — storage, dedup, and lineage join share one identity.
+- **`WriteGuard` is pure ASGI on purpose** (not `BaseHTTPMiddleware`), so it never buffers the SSE/NDJSON streams downstream servers return. Register it *before* `CORSMiddleware`. `env_flag()` warns on a mistyped protection flag rather than silently disabling it — keep that fail-safe behaviour.
+- **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_cortex/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
+- Pydantic v2 everywhere; async tests via `asyncio_mode = auto`. Ruff pinned **0.15.16**, line-length 120, target py311.
+
+## CI / release
+
+CI runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow (ruff + pytest with the `dev` extra — which installs the real psycopg/qdrant/minio/starlette clients so each store's live driver path is exercised, not just fakes). Release publishes to PyPI (OIDC trusted publishing) on `v*` tags — **no container image, this is a library**. Scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template); run `copier update` to pull tooling changes.

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

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

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

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

{argus_cortex-0.2.0 → argus_cortex-0.4.0}/pyproject.toml

@@ -24,14 +24,17 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-remote = ["httpx>=0.27"]
+remote = ["httpx>=0.27", "certifi>=2026.10.19"]
 postgres = ["psycopg[binary,pool]>=3.1"]
-qdrant = ["qdrant-client>=1.10"]
-s3 = ["minio>=7.2"]
+qdrant = ["qdrant-client>=1.10", "certifi>=2026.10.19"]
+s3 = ["minio>=7.2", "certifi>=2026.10.19"]
 # The shared ASGI write-guard + env-flag scaffolding for the suite's servers
 # (argus_cortex.server). Starlette ships with FastAPI, so consumers already have
 # it via their own [server] extra.
 server = ["starlette>=0.37"]
+# Pillow, for SingGuardClient's downscaling of large images
+# (argus_cortex.moderation.singguard), imported only when it downscales.
+images = ["pillow>=10.0"]
 # The store drivers are in dev so each store's real client path (pool/enum/client
 # construction, error wrapping) is exercised in CI, not just via fakes.
 # starlette + httpx power the pure-ASGI guard tests (Starlette TestClient).
@@ -44,6 +47,9 @@ dev = [
     "minio>=7.2",
     "starlette>=0.37",
     "httpx>=0.27",
+    "httpx2>=2.7",
+    "pillow>=10.0",
+    "certifi>=2026.10.19",
 ]
 
 [project.urls]

{argus_cortex-0.2.0 → argus_cortex-0.4.0}/src/argus_cortex/__init__.py

@@ -23,6 +23,14 @@ from argus_cortex.backends import (
     resolve_device,
     with_retries,
 )
+from argus_cortex.moderation import (
+    CheckFailed,
+    GuardResult,
+    ModerationConfigError,
+    NsfwResult,
+    NudeNetClient,
+    SingGuardClient,
+)
 from argus_cortex.store import (
     IMAGE_COLLECTION,
     TAGSET_COLLECTION,
@@ -56,6 +64,18 @@ from argus_cortex.wire import (
     schema_major,
     wire_schema,
 )
+from argus_cortex.xmp import (
+    XmpData,
+    XmpError,
+    XmpRegion,
+    XmpRegions,
+    merge_xmp,
+    parse_xmp,
+    read_xmp,
+    render_xmp,
+    sidecar_path,
+    write_xmp,
+)
 
 __all__ = [
     "__version__",
@@ -70,6 +90,17 @@ __all__ = [
     "render_schema",
     "schema_major",
     "wire_schema",
+    # xmp sidecars
+    "XmpData",
+    "XmpError",
+    "XmpRegion",
+    "XmpRegions",
+    "merge_xmp",
+    "parse_xmp",
+    "read_xmp",
+    "render_xmp",
+    "sidecar_path",
+    "write_xmp",
     # backends
     "Backend",
     "BackendError",
@@ -79,6 +110,13 @@ __all__ = [
     "RemoteProvider",
     "resolve_device",
     "with_retries",
+    # moderation clients (NudeNet, SingGuard over HTTP)
+    "CheckFailed",
+    "GuardResult",
+    "ModerationConfigError",
+    "NsfwResult",
+    "NudeNetClient",
+    "SingGuardClient",
     # store (optional stateful services layer)
     "StoreConfig",
     "StoreError",

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

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

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

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

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