argus-cortex 0.4.7__tar.gz → 0.6.0__tar.gz

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/.cursor/rules/agent-coding-packs.mdc

@@ -17,13 +17,17 @@ The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in th
    CLI equivalent: `ai-audit packs --bundle --repo argus-cortex`.
 2. **Claim** the specialist pack you pick:
    `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>/status` `{"status":"claimed"}`
-   (send `X-API-Token: $AI_AUDIT_API_TOKEN`).
+   (send `X-API-Token: $AI_AUDIT_API_TOKEN`; the token is in your environment, set for Claude Code
+   in `~/.claude/settings.json`. If it is empty or you get a 401, ask the user; don't search env files).
 3. **Fix:** `ai-audit repair --pack-id <id>` (agent-composer repair loop; fetches the pack for you;
    HTTP: `POST http://127.0.0.1:9150/api/repair/run` `{"pack_id":"<id>","mode":"review"}`),
    or read `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>` / `.../brief` and implement it yourself.
 4. **Close:** `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/validate_patch` `{"repo":"argus-cortex","patch":"<diff>","pack_id":"<id>"}`
    — a passing run marks the pack `resolved`.
 
+**Search** before crawling: `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/search?q=<question>&repo=argus-cortex&kind=wiki`
+(wiki sections and packs with links; CLI `ai-audit search "<question>" --repo argus-cortex`).
+
 World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
 Full flow: ai-code-auditor `AGENTS.md`.
 <!-- ai-audit:agent-packs:end -->

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/.github/workflows/release.yml

@@ -159,7 +159,7 @@ jobs:
             exit 1
           fi
           failed=0
-          for repo in argus-curator argus-lens argus-proof argus-forge argus-darkroom; do
+          for repo in argus-curator argus-lens argus-proof argus-forge argus-darkroom argus-mint; do
             if gh api "repos/${GITHUB_REPOSITORY_OWNER}/${repo}/dispatches" \
                 -f event_type=cortex-released -f "client_payload[version]=${tag#v}"; then
               echo "Dispatched cortex-released to $repo"

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/.gitignore

@@ -10,3 +10,5 @@ build/
 .env
 # hatch-vcs writes this at build time (version derived from git tags)
 src/argus_cortex/_version.py
+# generated GitHub social previews (brand/tools/panoptes.py social)
+brand/social/

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/AGENTS.md

@@ -12,13 +12,17 @@ The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in th
    CLI equivalent: `ai-audit packs --bundle --repo argus-cortex`.
 2. **Claim** the specialist pack you pick:
    `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>/status` `{"status":"claimed"}`
-   (send `X-API-Token: $AI_AUDIT_API_TOKEN`).
+   (send `X-API-Token: $AI_AUDIT_API_TOKEN`; the token is in your environment, set for Claude Code
+   in `~/.claude/settings.json`. If it is empty or you get a 401, ask the user; don't search env files).
 3. **Fix:** `ai-audit repair --pack-id <id>` (agent-composer repair loop; fetches the pack for you;
    HTTP: `POST http://127.0.0.1:9150/api/repair/run` `{"pack_id":"<id>","mode":"review"}`),
    or read `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>` / `.../brief` and implement it yourself.
 4. **Close:** `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/validate_patch` `{"repo":"argus-cortex","patch":"<diff>","pack_id":"<id>"}`
    — a passing run marks the pack `resolved`.
 
+**Search** before crawling: `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/search?q=<question>&repo=argus-cortex&kind=wiki`
+(wiki sections and packs with links; CLI `ai-audit search "<question>" --repo argus-cortex`).
+
 World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
 Full flow: ai-code-auditor `AGENTS.md`.
 <!-- ai-audit:agent-packs:end -->

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/CHANGELOG.md

@@ -7,6 +7,99 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-11-15
+
+### Added
+- **GPU broker client (`argus_cortex.gpu_broker`).** `BrokerCoordinator` asks argus-iris, the suite's GPU broker,
+  for a lease; iris places it on a node, queues it by priority, reserves the VRAM and evicts idle models to make
+  room. Select it with `ARGUS_GPU_COORDINATOR=broker` and `ARGUS_GPU_BROKER_URL` (optional
+  `ARGUS_GPU_BROKER_TOKEN`, `ARGUS_GPU_TENANT`, `ARGUS_GPU_TENANT_MANIFEST`). A lease long-polls while queued,
+  heartbeats in the background, re-attaches if the broker restarts, and reports its outcome (`ok`, `failed`,
+  `oom`, `cancelled`) and peak VRAM on release. Each request carries a `request_id`, so the one retry after a
+  lost response gets the same lease. It fails open: if the broker is unreachable or answers 5xx, the lease comes
+  from `ARGUS_GPU_BROKER_FALLBACK` (`lease`, the default, or `none`). A 4xx or an incompatible version raises
+  `BrokerError`; a refusal raises the new `GpuLeaseRefused`. httpx is behind `[remote]` (#78).
+- **GPU wire models (`argus_cortex.gpu_wire`).** The lease contract (`LeaseRequest`, `LeaseStatus`, `Heartbeat`,
+  `HeartbeatReply`, `LeaseRelease`; `lease_version` 1.0) and `TenantManifest` (`tenant_version` 1.0), the
+  `gpu-tenant.yaml` every repo that uses a GPU commits: its kinds of work with target, footprint (`vram_mb`, and
+  `model_mb` for the weights that stay loaded), priority and preemptibility, and its resident models with the
+  routes and hints the broker uses to reach, unload, evict and warm them. Committed `gpu-lease-schema.json` and
+  `gpu-tenant-schema.json` (#78).
+- **`lease()` options and handle.** Every coordinator's `lease()` takes optional `priority`, `target`, `kind`,
+  `preemptible`, `constraints` and `model_mb`, which only the broker uses, and yields a `GpuLease` (`node`,
+  `base_url`, `should_yield()`, `report_peak_vram()`). Every coordinator gains an async `alease()`. Existing
+  `with coordinator.lease(caller=, min_vram_mb=):` calls are unchanged (#78).
+- **`[yaml]` extra** (PyYAML) for `load_tenant_manifest()` reading YAML; JSON needs nothing (#78).
+- `SUITE.md`: a row for argus-handbook, the suite's public docs at docs.dragonhound.dev.
+- `brand/`: the suite's identity (vesica-iris suite mark, one mark per package, Panoptes lettering font, the
+  identity sheet, and `brand/tools/panoptes.py` to regenerate them). Panoptes 0.2 adds capitals, digits and basic
+  punctuation (85 glyphs); glyphs made only of dots, like the colon, keep every dot in the font build. Favicon sets
+  for every web UI (`mark/favicon/`, `packages/<pkg>/favicon/`) and `panoptes.py favicons` to regenerate them;
+  `brand/README.md` says where each UI puts them. Not part of the package: excluded from the wheel and the sdist.
+
+### Changed
+- `SUITE.md`: the "Share the GPU" row points at the broker and asks each repo to declare its GPU use in a
+  `gpu-tenant.yaml` (#78). argus-studio's row says its `/docs` keeps only the captioning concept pages; the setup
+  guides and package docs moved to argus-handbook, and the old paths 301 there.
+- `release.yml` also sends `cortex-released` to argus-mint, whose image installs cortex from its `server` extra's
+  range and now rebuilds on it (argus-mint#29).
+- **Behaviour changes a stage may notice on this bump (#73):**
+  - `cross_site_refuse()` no longer trusts a same-host write by bare hostname (DNS rebinding). A same-host
+    `Origin` passes only when the host is an IP literal, `localhost`, or listed in the new `trusted_hosts`
+    argument; a server reached by a DNS name must pass it (or list the origin in `trusted_origins`).
+  - `RemoteBackend.post_json()` retries only failures where the request never reached the server (connect
+    errors, pool timeouts), not a `ReadTimeout`; pass `idempotent=True` to keep the old retries.
+  - `policies.mode()` raises `ModerationConfigError` for an unknown policy name instead of returning `nsfw`.
+  - `QdrantVectorStore.search()` returns the key passed to `upsert()` as `VectorHit.id`, not its UUID5; the
+    original key rides in the reserved `_point_id` payload field (`POINT_ID_FIELD`), stripped from `payload`.
+  - `SingGuardClient` refuses a multi-frame image (animated GIF/WebP/APNG, multi-page TIFF) with
+    `GuardCheckFailed` instead of judging frame 0.
+  - `CORTEX_S3_ENDPOINT` refuses a scheme other than `http://`/`https://`.
+
+### Fixed
+- `LeaseCoordinator` refuses a symlinked or non-regular lock file and chmods it only when it owns it (#73).
+- The lineage schema refuses a dataset membership whose `edit_id` belongs to another caption (a trigger, so it
+  reaches existing tables) (#73).
+- XMP: regions are written as valid RDF (no `parseType` on attribute-form structs) and read back from nested
+  `rdf:Description` forms; a sidecar's prefixes no longer rebind the process-wide ElementTree registry; concurrent
+  `write_xmp()` merges into one directory take an exclusive lock so neither drops the other's properties (#73).
+- `ensure_schema()` serialises on a Postgres advisory lock and creates the membership trigger in one statement, so
+  several stages starting against one database no longer fail with "tuple concurrently updated" or "trigger
+  already exists".
+- `BrokerCoordinator` gives up a queued request whenever the wait ends without a grant (a 5xx or a dropped
+  connection mid-poll, a bad payload, an interrupt), not only on timeout or cancellation, so the broker never grants
+  an orphaned lease while the work runs on the fallback.
+- `LeaseCoordinator.alease()` waits on its own thread instead of the loop's default executor, so more concurrent
+  waiters than executor threads can no longer starve the holder's release.
+- Docs: `slow` and `cascade` are supported by agent-composer's guard router as well as argus-cull's `singguard`
+  service, not by argus-cull's alone (`SingGuardClient` docstrings, README). Code is unchanged.
+
+## [0.5.0] - 2026-11-14
+
+### Added
+- **`argus_cortex.provenance`.** `Provenance`, `ProvenanceKind` and `CLEARED_KINDS`, hoisted from
+  argus-mask so every package that stores where a face, voice or image came from reads one shape,
+  with a committed `provenance-schema.json` (#35).
+- **`argus_cortex.consent`.** `ConsentRecord`, a real person's likeness release as argus-mask#26
+  defined it, keyed by the `release_sha256` a `consented` `Provenance` names. `consent_valid()`
+  returns a `ConsentVerdict` with one of a closed set of refusal codes, checked in a fixed order
+  (`revoked`, `not-yet-signed`, `expired`, `likeness-not-covered`, `use-not-covered`,
+  `delivery-not-covered`), so every stage refuses for the same reasons. `consent_matches()` checks
+  that a record is the release and subject a provenance names. Committed `consent-schema.json` (#53).
+  A record is frozen and its sequences are tuples, so it cannot be changed after its checks pass.
+  It is refused when the age check names nobody or comes after signing, when a revocation is
+  requested before signing, or when a listed voice delivery is blank (#56).
+- **`Provenance.generator`.** An optional `model`, `model_sha256`, `seed` and `prompt` for how a
+  generated source was made, allowed only on `synthetic` and `personal` sources (#53).
+
+### Changed
+- **`Provenance` is strict, as argus-mask's is (argus-mask#64).** Unknown fields are refused instead
+  of dropped (`additionalProperties: false` in the schema). `licence` is read as `license`; both given
+  and different is refused. A `source` of only whitespace is refused. The derived `cleared` in a dumped
+  record is dropped on read and recomputed.
+- **README:** lists the `[images]` and `[gpu]` extras, `ARGUS_GPU_DEVICE`, and the moderation policy
+  names with their illegal-rule letters (#42).
+
 ## [0.4.7] - 2026-11-13
 
 ### Added
@@ -229,7 +322,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.7...HEAD
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/smk762/argus-cortex/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/smk762/argus-cortex/compare/v0.4.7...v0.5.0
 [0.4.7]: https://github.com/smk762/argus-cortex/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/smk762/argus-cortex/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/smk762/argus-cortex/compare/v0.4.4...v0.4.5

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/CLAUDE.md

@@ -23,15 +23,19 @@ their own rows land here. Keep it short, because it is loaded into every session
 `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, and `taxonomy_schema()` (the source of the committed `taxonomy-schema.json`). Keep it dependency-light; a change here retrains everyone's expectations.
+- `provenance.py` — `Provenance`/`ProvenanceKind`/`CLEARED_KINDS` for face, voice and image sources, hoisted from argus-mask (#19/#57): `personal` (never cleared) vs cleared `stock`/`synthetic`/`consented` (licence required; `consented` needs `subject` + `release_sha256`); `curated` reserved. **argus-mask owns the meaning of each field — change it only in step with mask.** Optional `generator` (model, sha256, seed, prompt) on `synthetic`/`personal` only. `provenance_schema()` renders the committed `provenance-schema.json` (`make schema`; drift-tested).
+- `consent.py` — `ConsentRecord` (keyed by `release_sha256`, the join to a `consented` `Provenance`), `consent_valid()` → `ConsentVerdict` with a closed `ConsentRefusal` reason (checks in a fixed order; the first failure wins), `consent_matches()`, and `consent_schema()` → the committed `consent-schema.json`. Defined in argus-mask#26; **mask owns the meaning — change it only in step with mask.** `consent_valid` takes `at` from the caller (tz-aware, compared as a UTC day) and never reads the clock; an unknown use is refused, not raised. A record names a person: services return verdicts, never records.
 - `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.
+- `gpu.py` — GPU tenancy (from argus-lens): the `GpuCoordinator` protocol (`lease(caller=, min_vram_mb=, priority=, target=, kind=, preemptible=, constraints=)` and async `alease()`, both yielding a `GpuLease` handle; local coordinators ignore the broker-only arguments), `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.
+- `gpu_wire.py` — the GPU broker's wire models (pydantic only): `LeaseRequest`/`LeaseStatus`/`Heartbeat`/`HeartbeatReply`/`LeaseRelease` (`lease_version`) and `TenantManifest` (`tenant_version`, the `gpu-tenant.yaml` every GPU-using repo commits), with `lease_schema()`/`tenant_schema()` rendering the committed `gpu-lease-schema.json`/`gpu-tenant-schema.json`. **argus-iris serves this contract — change it only in step with iris**, and additively within a major (replies ignore unknown fields; manifests forbid them, so a new manifest field needs the schema regenerated and iris bumped).
+- `gpu_broker.py` — `BrokerCoordinator`, the client for argus-iris (`ARGUS_GPU_COORDINATOR=broker`): register manifest → `POST /leases` → long-poll `GET /leases/{id}?wait_s=` → background heartbeat (sets `should_yield()`, re-attaches with `resume` on 404) → `POST /leases/{id}/release` with outcome and peak VRAM. **Fails open** to its fallback coordinator on transport errors, 5xx or a missing route; raises `BrokerError` on other 4xx or an incompatible major. httpx lazily, behind `[remote]`.
 - `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` 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.
+- `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, the known adult policies NSFW, any other name raises — **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 in this repo**. The one committed schema is `taxonomy-schema.json` (from `taxonomy_schema()`; `make schema` regenerates it and `tests/test_taxonomy.py` fails when it is stale). Studio generates its taxonomy types from it, so a `taxonomy.py` change needs `make schema` in the same commit.
+There is **no CLI in this repo**. The committed schemas are `taxonomy-schema.json` (from `taxonomy_schema()`), `provenance-schema.json` (from `provenance_schema()`), `consent-schema.json` (from `consent_schema()`), and `gpu-lease-schema.json` / `gpu-tenant-schema.json` (from `gpu_wire`); `make schema` regenerates all five and `tests/test_taxonomy.py` / `tests/test_provenance.py` / `tests/test_consent.py` / `tests/test_gpu_wire.py` fail when one is stale. Studio generates its taxonomy types from the first, so a `taxonomy.py`, `provenance.py`, `consent.py` or `gpu_wire.py` change needs `make schema` in the same commit.
 
 ## Commands
 
@@ -55,7 +59,7 @@ Run one test: `uv run --no-sync pytest tests/test_wire.py::test_name -q`.
 
 ## Branches
 
-`dev` is the default branch and the base for every PR. Cut feature branches from `origin/dev` and bring them up to date by merging `origin/dev`, never `main`. Never open a PR against `main` or push work to it directly: `main` must never be ahead of `dev`. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected and needs a PR, merge the release PR, then immediately merge `main` back into `dev` so the merge commit is not left on `main` alone.
+`dev` is the default branch and the base for every PR. Cut feature branches from `origin/dev` and bring them up to date by merging `origin/dev`, never `main`. Never push work to `main` or open a PR against it, except the release PR from `dev`: `main` must never be ahead of `dev`, with one exception. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected, the release is a reviewed PR from `dev` into `main`, and merging it leaves a merge commit on `main` alone. That merge commit is the one exception to the rule: it leaves `main` one commit ahead of `dev` with an identical tree. Leave it there and don't merge `main` back into `dev`. Anything else on `main` that `dev` lacks is a mistake (`git diff origin/dev origin/main` must be empty). Once `main` carries such a commit it can't be fast-forwarded, so later releases are PRs too.
 
 ## CI / release
 

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/Makefile

@@ -20,8 +20,8 @@ format:  ## Ruff autoformat + autofix
 test:  ## Run the test suite
 	$(UV) run --no-sync pytest --tb=short -q
 
-schema:  ## Regenerate the committed taxonomy-schema.json
-	$(UV) run --no-sync python -c "from pathlib import Path; from argus_cortex.taxonomy import taxonomy_schema; Path('taxonomy-schema.json').write_text(taxonomy_schema(), encoding='utf-8')"
+schema:  ## Regenerate the committed taxonomy, provenance, consent, gpu-lease and gpu-tenant schemas
+	$(UV) run --no-sync python -c "from pathlib import Path; from argus_cortex.taxonomy import taxonomy_schema; from argus_cortex.provenance import provenance_schema; from argus_cortex.consent import consent_schema; from argus_cortex.gpu_wire import lease_schema, tenant_schema; [Path(f).write_text(r(), encoding='utf-8') for f, r in (('taxonomy-schema.json', taxonomy_schema), ('provenance-schema.json', provenance_schema), ('consent-schema.json', consent_schema), ('gpu-lease-schema.json', lease_schema), ('gpu-tenant-schema.json', tenant_schema))]"
 
 build:  ## Build sdist + wheel
 	$(UV) build

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.4.7
+Version: 0.6.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
@@ -25,6 +25,7 @@ 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: pyyaml>=6.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'
@@ -45,9 +46,16 @@ 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'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
 Description-Content-Type: text/markdown
 
-# argus-cortex
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/cortex/argus-cortex-lockup-dark.svg">
+    <img alt="argus-cortex" src="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/cortex/argus-cortex-lockup-light.svg" height="52">
+  </picture>
+</h1>
 
 Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract.
 
@@ -56,12 +64,16 @@ Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/
 ## What's here
 
 - **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim. `taxonomy_schema()` renders them into the committed `taxonomy-schema.json` (`make schema` regenerates it; a test fails when it is stale), so non-Python clients generate their types instead of copying the literals.
+- **`argus_cortex.provenance`**: `Provenance` / `ProvenanceKind`, where a face, voice or image came from (the shape argus-mask#19 defined). `personal` needs only a `source` and is never `cleared`; `stock`, `synthetic` and `consented` are cleared, each states its licence, and `consented` also names its `subject` and the `release_sha256` of the signed release (never the document). `curated` is reserved and not cleared. Strict: unknown fields and a blank `source` are refused, `licence` is read as `license`, and a stored `cleared` is recomputed. A `synthetic` or `personal` source may name its `generator` (`model`, `model_sha256`, `seed`, `prompt`; optional, refused on other kinds). `provenance_schema()` renders the committed `provenance-schema.json` (`make schema`; a test fails when it is stale).
+- **`argus_cortex.consent`**: a real person's likeness release, as argus-mask#26 defined it. `ConsentRecord` is keyed by the `release_sha256` a `consented` `Provenance` names, and holds the subject, who collected it, signing and expiry dates (expiry must be stated, `null` for none), the age check (who and when, never the ID), the `face`/`voice` opt-ins, voice `deliveries`, `uses` (`avatar`, `video`, `speech`, `training`; training is off unless listed), sha256s of the reference images and recordings, revocation terms and any `revocation`. `consent_valid(record, use=, likeness=, at=, delivery=)` returns a `ConsentVerdict` (`ok`, `reason`, `detail`), checking in order `revoked`, `not-yet-signed`, `expired`, `likeness-not-covered`, `use-not-covered`, `delivery-not-covered`; `at` must be timezone-aware and dates compare as UTC days, so the check never reads the clock. `consent_matches(record, provenance)` checks the record is the release and subject a provenance names. A record names a person, so services return only verdicts, never records. `consent_schema()` renders the committed `consent-schema.json`.
 - **`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.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; a same-host write is trusted only for an IP literal, `localhost` or a name in `trusted_hosts`, so DNS rebinding cannot pass it), 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 + pydantic 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.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_GPU_DEVICE` (default `0`; an invalid value warns and falls back to `0`) picks which card NVML probes for free VRAM; the lock stays host-wide.
+  - **Broker.** `ARGUS_GPU_COORDINATOR=broker` asks the suite's GPU broker, argus-iris, at `ARGUS_GPU_BROKER_URL` (bearer `ARGUS_GPU_BROKER_TOKEN`, optional) instead. The broker places the lease on a node (morpheus, dragon, jarrah), queues it by priority, holds a real VRAM reservation, and evicts idle models to make room. `lease()` now also takes optional `priority` (`realtime`/`interactive`/`batch`/`background`), `target` (`comfyui`, `ollama:<model>`, `in-process`), `kind`, `preemptible`, `constraints` (`GpuConstraints`: `node`, `min_cc`, `bf16`) and `model_mb` (the part of `min_vram_mb` that is weights the service keeps loaded after the lease, such as a ComfyUI checkpoint or an Ollama model, so the broker counts them once rather than per lease); the local coordinators ignore them. Every coordinator yields a `GpuLease`: `node` and `base_url` say where the broker placed the work (call that URL; `None` means use your own), `should_yield()` turns true when the broker wants the GPU back (release at the next safe point; nothing is killed), and `report_peak_vram(mb)` feeds the broker's footprint learning. `alease()` is the async form on every coordinator; the file lease waits in a worker thread. Each lease carries a fresh `request_id`, so the one retry after a lost POST response returns the same lease rather than a second one. A broker lease heartbeats in the background, re-attaches if the broker restarts, and reports its outcome (`ok`/`failed`/`oom`/`cancelled`) on release. **It fails open**: unreachable or 5xx, and the lease comes from `ARGUS_GPU_BROKER_FALLBACK` (`lease`, the default, or `none`) with `via="fallback"`; a 4xx or an incompatible `lease_version` raises `BrokerError`, a refusal `GpuLeaseRefused`. httpx behind `[remote]`.
+  - **Tenant manifests.** Every repo that uses a GPU commits a `gpu-tenant.yaml` (`argus_cortex.gpu_wire.TenantManifest`): its kinds of work with target, declared VRAM, default priority and preemptibility, and the models it keeps resident with keepalive and idle-kill hints. `ARGUS_GPU_TENANT_MANIFEST` points the broker coordinator at it, and it is registered with the broker before the first lease; `ARGUS_GPU_TENANT` names the tenant if there is no manifest. `load_tenant_manifest()` reads YAML (behind `[yaml]`) or JSON. The lease wire models and the manifest render the committed `gpu-lease-schema.json` and `gpu-tenant-schema.json` (`make schema`; drift-tested), so non-Python callers and repos validate against those.
 - **`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.
@@ -105,7 +117,7 @@ result.exposed_score    # 0.0-1.0 over DEFAULT_EXPOSED_LABELS; result.labels = p
 guard = SingGuardClient("http://guard:9150", policy=None)  # None = SingGuard's default rules
 # thinking="fast" (default) is a verdict and rule; "fast-slow" also writes why; "slow" writes why
 # with no fast verdict ahead of the reasoning; "cascade" is fast, then slow only for what fast
-# flagged (the last two: argus-cull's singguard service only).
+# flagged (the last two: agent-composer's guard or argus-cull's singguard service).
 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"]
@@ -121,7 +133,17 @@ illegal = [r for r in verdict.rules if policies.is_illegal("adult-granular", r)]
 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).
+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). The known names are `policies.POLICIES`; any other name raises `ModerationConfigError` (an `sfw-*` name gets mode `sfw` but has no text):
+
+| Policy | Mode | Illegal rules |
+|---|---|---|
+| `default` (SingGuard's own rules, no text sent) | sfw | none |
+| `adult` | nsfw | A |
+| `adult-granular` | nsfw | A, H, I |
+| `adult-cautious` | nsfw | A |
+| `adult-cinematic` | nsfw | A |
+
+`adult-granular`, `adult-cautious` and `adult-cinematic` are under evaluation against `adult`; one adult policy remains at release, beside `default`.
 
 ```python
 from argus_cortex.gpu import GpuLeaseTimeout, coordinator_from_env
@@ -134,6 +156,20 @@ except GpuLeaseTimeout:
     ...   # no slot in time: back off, or answer 503
 ```
 
+Through the broker, the same code can ask for a placement and honour a yield:
+
+```python
+gpu = coordinator_from_env()   # ARGUS_GPU_COORDINATOR=broker, ARGUS_GPU_BROKER_URL=http://morpheus:8120
+async with gpu.alease(caller="expand", min_vram_mb=6000, target="ollama:qwen3:8b", priority="interactive") as lease:
+    ollama = lease.base_url or settings.ollama_url   # dragon, or jarrah when dragon is full
+    ...
+with gpu.lease(caller="bake", min_vram_mb=9000, target="comfyui", priority="batch", preemptible=True) as lease:
+    for tile in tiles:
+        if lease.should_yield():
+            break   # requeue the rest; a higher-priority job wants the card
+        bake(tile)
+```
+
 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
@@ -186,11 +222,14 @@ link = blobs.url(sha, expires=3600)      # presigned GET URL
 
 ```bash
 uv pip install argus-cortex              # core (pydantic only)
-uv pip install "argus-cortex[remote]"    # + httpx for RemoteBackend
+uv pip install "argus-cortex[remote]"    # + httpx for RemoteBackend and the GPU broker client
 uv pip install "argus-cortex[server]"    # + starlette for argus_cortex.server (WriteGuard, env_flag)
 uv pip install "argus-cortex[postgres]"  # + psycopg for the lineage store
 uv pip install "argus-cortex[qdrant]"    # + qdrant-client for the vector store
 uv pip install "argus-cortex[s3]"        # + minio for the blob store
+uv pip install "argus-cortex[images]"    # + Pillow for SingGuardClient downscaling (on by default)
+uv pip install "argus-cortex[gpu]"       # + nvidia-ml-py for the GPU lease's free-VRAM probe
+uv pip install "argus-cortex[yaml]"      # + PyYAML for reading a gpu-tenant.yaml (JSON needs nothing)
 ```
 
 The stateful services are configured via `CORTEX_*` env vars — see [`.env.example`](.env.example). Each is optional: leave a URL unset and that feature degrades to a no-op.

{argus_cortex-0.4.7 → argus_cortex-0.6.0}/README.md

@@ -1,4 +1,9 @@
-# argus-cortex
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/cortex/argus-cortex-lockup-dark.svg">
+    <img alt="argus-cortex" src="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/cortex/argus-cortex-lockup-light.svg" height="52">
+  </picture>
+</h1>
 
 Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract.
 
@@ -7,12 +12,16 @@ Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/
 ## What's here
 
 - **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim. `taxonomy_schema()` renders them into the committed `taxonomy-schema.json` (`make schema` regenerates it; a test fails when it is stale), so non-Python clients generate their types instead of copying the literals.
+- **`argus_cortex.provenance`**: `Provenance` / `ProvenanceKind`, where a face, voice or image came from (the shape argus-mask#19 defined). `personal` needs only a `source` and is never `cleared`; `stock`, `synthetic` and `consented` are cleared, each states its licence, and `consented` also names its `subject` and the `release_sha256` of the signed release (never the document). `curated` is reserved and not cleared. Strict: unknown fields and a blank `source` are refused, `licence` is read as `license`, and a stored `cleared` is recomputed. A `synthetic` or `personal` source may name its `generator` (`model`, `model_sha256`, `seed`, `prompt`; optional, refused on other kinds). `provenance_schema()` renders the committed `provenance-schema.json` (`make schema`; a test fails when it is stale).
+- **`argus_cortex.consent`**: a real person's likeness release, as argus-mask#26 defined it. `ConsentRecord` is keyed by the `release_sha256` a `consented` `Provenance` names, and holds the subject, who collected it, signing and expiry dates (expiry must be stated, `null` for none), the age check (who and when, never the ID), the `face`/`voice` opt-ins, voice `deliveries`, `uses` (`avatar`, `video`, `speech`, `training`; training is off unless listed), sha256s of the reference images and recordings, revocation terms and any `revocation`. `consent_valid(record, use=, likeness=, at=, delivery=)` returns a `ConsentVerdict` (`ok`, `reason`, `detail`), checking in order `revoked`, `not-yet-signed`, `expired`, `likeness-not-covered`, `use-not-covered`, `delivery-not-covered`; `at` must be timezone-aware and dates compare as UTC days, so the check never reads the clock. `consent_matches(record, provenance)` checks the record is the release and subject a provenance names. A record names a person, so services return only verdicts, never records. `consent_schema()` renders the committed `consent-schema.json`.
 - **`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.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; a same-host write is trusted only for an IP literal, `localhost` or a name in `trusted_hosts`, so DNS rebinding cannot pass it), 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 + pydantic 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.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_GPU_DEVICE` (default `0`; an invalid value warns and falls back to `0`) picks which card NVML probes for free VRAM; the lock stays host-wide.
+  - **Broker.** `ARGUS_GPU_COORDINATOR=broker` asks the suite's GPU broker, argus-iris, at `ARGUS_GPU_BROKER_URL` (bearer `ARGUS_GPU_BROKER_TOKEN`, optional) instead. The broker places the lease on a node (morpheus, dragon, jarrah), queues it by priority, holds a real VRAM reservation, and evicts idle models to make room. `lease()` now also takes optional `priority` (`realtime`/`interactive`/`batch`/`background`), `target` (`comfyui`, `ollama:<model>`, `in-process`), `kind`, `preemptible`, `constraints` (`GpuConstraints`: `node`, `min_cc`, `bf16`) and `model_mb` (the part of `min_vram_mb` that is weights the service keeps loaded after the lease, such as a ComfyUI checkpoint or an Ollama model, so the broker counts them once rather than per lease); the local coordinators ignore them. Every coordinator yields a `GpuLease`: `node` and `base_url` say where the broker placed the work (call that URL; `None` means use your own), `should_yield()` turns true when the broker wants the GPU back (release at the next safe point; nothing is killed), and `report_peak_vram(mb)` feeds the broker's footprint learning. `alease()` is the async form on every coordinator; the file lease waits in a worker thread. Each lease carries a fresh `request_id`, so the one retry after a lost POST response returns the same lease rather than a second one. A broker lease heartbeats in the background, re-attaches if the broker restarts, and reports its outcome (`ok`/`failed`/`oom`/`cancelled`) on release. **It fails open**: unreachable or 5xx, and the lease comes from `ARGUS_GPU_BROKER_FALLBACK` (`lease`, the default, or `none`) with `via="fallback"`; a 4xx or an incompatible `lease_version` raises `BrokerError`, a refusal `GpuLeaseRefused`. httpx behind `[remote]`.
+  - **Tenant manifests.** Every repo that uses a GPU commits a `gpu-tenant.yaml` (`argus_cortex.gpu_wire.TenantManifest`): its kinds of work with target, declared VRAM, default priority and preemptibility, and the models it keeps resident with keepalive and idle-kill hints. `ARGUS_GPU_TENANT_MANIFEST` points the broker coordinator at it, and it is registered with the broker before the first lease; `ARGUS_GPU_TENANT` names the tenant if there is no manifest. `load_tenant_manifest()` reads YAML (behind `[yaml]`) or JSON. The lease wire models and the manifest render the committed `gpu-lease-schema.json` and `gpu-tenant-schema.json` (`make schema`; drift-tested), so non-Python callers and repos validate against those.
 - **`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.
@@ -56,7 +65,7 @@ result.exposed_score    # 0.0-1.0 over DEFAULT_EXPOSED_LABELS; result.labels = p
 guard = SingGuardClient("http://guard:9150", policy=None)  # None = SingGuard's default rules
 # thinking="fast" (default) is a verdict and rule; "fast-slow" also writes why; "slow" writes why
 # with no fast verdict ahead of the reasoning; "cascade" is fast, then slow only for what fast
-# flagged (the last two: argus-cull's singguard service only).
+# flagged (the last two: agent-composer's guard or argus-cull's singguard service).
 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"]
@@ -72,7 +81,17 @@ illegal = [r for r in verdict.rules if policies.is_illegal("adult-granular", r)]
 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).
+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). The known names are `policies.POLICIES`; any other name raises `ModerationConfigError` (an `sfw-*` name gets mode `sfw` but has no text):
+
+| Policy | Mode | Illegal rules |
+|---|---|---|
+| `default` (SingGuard's own rules, no text sent) | sfw | none |
+| `adult` | nsfw | A |
+| `adult-granular` | nsfw | A, H, I |
+| `adult-cautious` | nsfw | A |
+| `adult-cinematic` | nsfw | A |
+
+`adult-granular`, `adult-cautious` and `adult-cinematic` are under evaluation against `adult`; one adult policy remains at release, beside `default`.
 
 ```python
 from argus_cortex.gpu import GpuLeaseTimeout, coordinator_from_env
@@ -85,6 +104,20 @@ except GpuLeaseTimeout:
     ...   # no slot in time: back off, or answer 503
 ```
 
+Through the broker, the same code can ask for a placement and honour a yield:
+
+```python
+gpu = coordinator_from_env()   # ARGUS_GPU_COORDINATOR=broker, ARGUS_GPU_BROKER_URL=http://morpheus:8120
+async with gpu.alease(caller="expand", min_vram_mb=6000, target="ollama:qwen3:8b", priority="interactive") as lease:
+    ollama = lease.base_url or settings.ollama_url   # dragon, or jarrah when dragon is full
+    ...
+with gpu.lease(caller="bake", min_vram_mb=9000, target="comfyui", priority="batch", preemptible=True) as lease:
+    for tile in tiles:
+        if lease.should_yield():
+            break   # requeue the rest; a higher-priority job wants the card
+        bake(tile)
+```
+
 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
@@ -137,11 +170,14 @@ link = blobs.url(sha, expires=3600)      # presigned GET URL
 
 ```bash
 uv pip install argus-cortex              # core (pydantic only)
-uv pip install "argus-cortex[remote]"    # + httpx for RemoteBackend
+uv pip install "argus-cortex[remote]"    # + httpx for RemoteBackend and the GPU broker client
 uv pip install "argus-cortex[server]"    # + starlette for argus_cortex.server (WriteGuard, env_flag)
 uv pip install "argus-cortex[postgres]"  # + psycopg for the lineage store
 uv pip install "argus-cortex[qdrant]"    # + qdrant-client for the vector store
 uv pip install "argus-cortex[s3]"        # + minio for the blob store
+uv pip install "argus-cortex[images]"    # + Pillow for SingGuardClient downscaling (on by default)
+uv pip install "argus-cortex[gpu]"       # + nvidia-ml-py for the GPU lease's free-VRAM probe
+uv pip install "argus-cortex[yaml]"      # + PyYAML for reading a gpu-tenant.yaml (JSON needs nothing)
 ```
 
 The stateful services are configured via `CORTEX_*` env vars — see [`.env.example`](.env.example). Each is optional: leave a URL unset and that feature degrades to a no-op.