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

{argus_cortex-0.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → argus_cortex-0.6.0}/CHANGELOG.md

@@ -7,6 +7,73 @@ 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
@@ -255,7 +322,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     (`LocalBackend`, `RemoteBackend`, `RemoteProvider`, `with_retries`
     retrying only transient errors, `resolve_device`).
 
-[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.5.0...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

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

@@ -28,12 +28,14 @@ their own rows land here. Keep it short, because it is loaded into every session
 - `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 committed schemas are `taxonomy-schema.json` (from `taxonomy_schema()`), `provenance-schema.json` (from `provenance_schema()`) and `consent-schema.json` (from `consent_schema()`); `make schema` regenerates all three and `tests/test_taxonomy.py` / `tests/test_provenance.py` / `tests/test_consent.py` fail when one is stale. Studio generates its taxonomy types from the first, so a `taxonomy.py`, `provenance.py` or `consent.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
 

{argus_cortex-0.5.0 → 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, provenance-schema.json and consent-schema.json
-	$(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; [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))]"
+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.5.0 → argus_cortex-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.5.0
+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.
 
@@ -60,10 +68,12 @@ Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/
 - **`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.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_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.
@@ -107,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"]
@@ -146,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
@@ -198,13 +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.5.0 → 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.
 
@@ -11,10 +16,12 @@ Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/
 - **`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.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_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.
@@ -58,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"]
@@ -97,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
@@ -149,13 +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.

{argus_cortex-0.5.0 → argus_cortex-0.6.0}/SUITE.md

@@ -14,25 +14,26 @@ GitHub: `smk762/<repo>`. Ports are each service's default.
 
 | Repo | Kind | Port | What it is for |
 |---|---|---|---|
-| **argus-cortex** | library | n/a | Shared foundation: taxonomy, wire-schema versioning, AI-backend contract, server guards, GPU lease, XMP, moderation clients, likeness provenance and consent records, optional lineage/vector/blob stores. |
+| **argus-cortex** | library | n/a | Shared foundation: taxonomy, wire-schema versioning, AI-backend contract, server guards, GPU lease and the GPU broker client, XMP, moderation clients, likeness provenance and consent records, optional lineage/vector/blob stores. |
 | **argus-quarry** | service | 8102 | Acquire public-domain / CC0 images with provenance and licence into a category-sorted raw pool. Searches local metadata archives of PD12M and Megalith-10m (filters, plus CLIP semantic and "more like this" search over PD12M) and lands chosen slices, with Megalith's Drawthings mirror as a fallback for photos gone from Flickr. Acquisition only. |
-| **argus-curator** | service | 8101 | Decide which images belong in a LoRA training set (quality, near-dup, faces, NSFW, diversity) and export them with a `manifest.jsonl`. |
-| **argus-lens** | service | 8100 (8080 standalone) | Structured, category-bucketed captions, `.txt` sidecars and XMP keywords. Records live captions to the cortex lineage store (the tape lightbox and replay read); runs read-only with `LENS_READ_ONLY`. |
+| **argus-curator** | service | 8101 | Decide which images belong in a LoRA training set (quality, near-dup, faces, NSFW, diversity) and export them with a `manifest.jsonl` (2.3: each row's primary face and the set's age). Its `face_source` preset shortlists source portraits for mask: one adult identity, frontal, sharp, eyes open, close to a reference. PyPI `argus-curator`. |
+| **argus-lens** | service | 8100 (8080 standalone) | Structured, category-bucketed captions, `.txt` sidecars and XMP keywords. Records live captions to the cortex lineage store (the tape lightbox and replay read); runs read-only with `LENS_READ_ONLY`. Each caption request may pick its backend (`backend`, pinned with `ARGUS_ALLOWED_BACKENDS`). `serve` binds loopback unless given `--host`, and `POST /caption/url` fetches only public hosts or those in `LENS_URL_ALLOWED_HOSTS`. PyPI `argus-lens`, image `ghcr.io/smk762/argus-lens`. |
 | **argus-forge** | service | 8103 | Turn a curated, captioned export into runnable kohya_ss / OneTrainer / diffusers configs. |
-| **argus-proof** | service | 8104 | Evaluate a trained LoRA against its dataset: sample grid, scores, pass/fail. |
+| **argus-proof** | service | 8104 | Evaluate a trained LoRA (SDXL or Flux) against its dataset: generates a sample grid (ComfyUI, diffusers, A1111 or a remote engine; every model pinned by SHA256 in a `RunManifest`), scores identity, quality, diversity, nudity (NudeNet server) and policy categories (Llama Guard 3), and gives a pass/fail verdict over near-duplicate groups with HITL review. Serves a passed run's validated setup at `GET /report/{id}/manifest`; devmode `POST /purge` clears QA runs. PyPI `argus-proof`, image `ghcr.io/smk762/argus-proof`. |
 | **argus-atlas** | service | 8105 | Bake georeferenced fantasy-map overlays from real terrain (GDAL controls plus a cartography LoRA), to GeoTIFF / PMTiles. |
-| **argus-darkroom** | service | 8106 | Guarded image generation: checks the prompt, generates via ComfyUI, checks each output, and keeps a record of every attempt. |
-| **argus-survey** | service | 8107 | Point-cloud deliverables for land surveyors (LAS/LAZ/COPC/E57 in): QA, ground, DTM/DSM/CHM, contours, stockpile volumes and cut/fill (grid and ground-scaled), change between epochs, profiles, ASPRS Edition 2 (v2, 2024) accuracy, LAS 1.4 / E57 export for ReCap and Civil 3D. Explicit datum operations (MGA2020, AHD via AUSGeoid2020), every command recorded in `job.json`. PyPI `argus-survey`, image `ghcr.io/smk762/argus-survey`. |
+| **argus-darkroom** | service | 8106 | Guarded image generation: checks the prompt (and any input image), generates via ComfyUI, checks each output, and keeps a record of every attempt. Text-to-image, image-to-image and inpainting, on SDXL, Flux, Flux Klein and SD3.5 checkpoints. PyPI `argus-darkroom`, image `ghcr.io/smk762/argus-darkroom`. |
+| **argus-survey** | service | 8107 | Point-cloud deliverables for land surveyors (LAS/LAZ/COPC/E57 in): QA, ground, DTM/DSM/CHM, contours, stockpile volumes and cut/fill (grid and ground-scaled), change between epochs, profiles, ASPRS Edition 2 (v2, 2024) accuracy, LAS 1.4 / E57 export for ReCap and Civil 3D. Explicit datum operations (MGA2020, AHD via AUSGeoid2020), every command recorded in `job.json`. Reference docs (`docs/`: datums, steps, methods, provenance, API, CLI) are imported by sightline and the handbook. PyPI `argus-survey`, image `ghcr.io/smk762/argus-survey`. |
 | **argus-mint** | service | 8108 | Provenance tokens for game assets: renders reviewed templates (fixed variable lists, no free prompts) through darkroom, checks each template against darkroom's checkpoints and workflows before approval, frames cards and writes their bios, and has the moderator and owner (SIWE) approve every image before it is pinned to IPFS. Mints ERC-721 cards and soulbound deeds whose metadata records the render's template, variables, checkpoint, LoRAs and seed, and anchors Merkle roots and commit/reveal secrets (Base). PyPI `argus-mint`, image `ghcr.io/smk762/argus-mint`. |
-| **argus-mask** | service | 8109 | A talking face: audio in (or text through a TTS service), ARKit facial-animation frames out (an energy driver on CPU, or NVIDIA Audio2Face-3D as a separate image), rendered in a browser on any LAN screen. Mesh (`.glb`) and LAM Gaussian-splat heads, each with provenance (`personal` or cleared); an optional face editor builds MakeHuman heads with Blender. PyPI `argus-mask`, image `ghcr.io/smk762/argus-mask`. |
-| **argus-studio** | UI + compose | 3000 | The suite web UI, and the compose stack that runs the services from GHCR images. No backend code. |
+| **argus-mask** | service | 8109 | A talking face: audio in (or text through a TTS service), ARKit facial-animation frames out (an energy driver on CPU, or NVIDIA Audio2Face-3D as a separate image), rendered in a browser on any LAN screen. Mesh (`.glb`) and LAM Gaussian-splat heads, each with provenance (`personal` or cleared; a generated face records its model, seed and prompt in `generator`), and procedural backdrops behind a mesh face (`?scene=ftl`, also in `record`); an optional face editor builds MakeHuman heads with Blender, and its Voices page makes cloned voices with provenance. A real person's face or voice is used only under a consent record (`argus-mask consent new\|list\|revoke`, cortex's `ConsentRecord`), and is always shown with a disclosure label. PyPI `argus-mask`, image `ghcr.io/smk762/argus-mask`. |
+| **argus-studio** | UI + compose | 3000 | The suite web UI, and the compose stack that runs the services from GHCR images. No backend code. `/forge` starts, follows and cancels forge training runs when the opt-in `compose.train.yaml` arms forge's `-train` image on a trusted GPU host (never a public demo). `/darkroom` links on to Forge, and to mask and assay when their URLs are set. Its `/docs` holds the captioning concept pages; the setup guides and package docs moved to argus-handbook, and its old `/docs/setup` and `/docs/packages` paths 301 there. |
 | **argus-safelight** | UI | 3097 | Demo UI for darkroom: prompt and pre-flight, text-to-image, image-to-image and inpainting over SSE, the per-policy shield grid, history, and darkroom's docs in `/docs` with in-context help. Follows darkroom's `dev` at a recorded commit (`web/schema/pins.json`: docs, wire types and fixture move together), not a release; built from source by darkroom's compose, no image. |
 | **argus-cull** | UI + compose | 3000 | Demo UI for curator: which images make the set and why, plus the paths to act on. Its compose runs curator with NudeNet, EraX-NSFW and watermark sidecars (NudeNet-shaped `POST /infer`); SingGuard is darkroom's agent-composer. Follows curator's `dev` at a recorded commit, not a release; web image `ghcr.io/smk762/argus-cull`. |
 | **argus-lightbox** | UI (static) + compose | 3000 | Demo gallery navigated by lens captions. Bakes the recorded tape from cortex stores into a static site (the hosted demo), or captions a photo folder through lens in its compose stack, where a small server also lets you pick each photo's final caption. `/docs` links lens's docs at the baked version. |
 | **argus-sightline** | UI | 3107 | Workspace UI for survey: every step over SSE, a map of the derived views with drawing tools, a COPC point view, datums always on screen, a guided demo measured against analytic truth, and a "Made with" line per step from `job.json`. Follows survey's `dev` at a recorded commit (`schema/pins.json`: wire types, demo numbers and docs links move together), not a release; built from source by its compose, no published image yet. |
 | **argus-assay** | UI | 3108 | Review UI for mint. The moderator (token) approves or rejects every card; the owner signs for theirs (EIP-4361 via the wallet) and can change its text and style with a live preview, which both then review again. Templates, frames and bio templates are approved in its catalogue, with sample runs. New drafts render through darkroom on a reviewed checkpoint and LoRAs, or come from mint's pre-rendered portrait library with no GPU, shown as a checkpoint comparison grid. A mock serves mint's recorded fixture for demo mode (`make mock`). Pins a mint release (`web/schema/pins.json`, now v0.2.0: wire types and fixture move together); built from source by its compose, no image. |
+| **argus-handbook** | docs (static) | n/a | The suite's public docs at docs.dragonhound.dev: setup of the external services (ComfyUI, Ollama, NudeNet, SingGuard, models, GPU host), the moderation stack across packages, a what-to-run matrix per UI, and each package's README and `docs/` imported at its `dev` HEAD behind an opsec gate. Static export, deployed from CI. The private `argus-docs` repo is ai-code-auditor's DeepWiki export bundle, which the handbook will build in under `/wiki/`. |
 | **argus-halo** | infra | n/a | Terraform for the public demo (`argus.dragonhound.dev`): read-only replay services plus a private data host. |
-| **argus-ci** | infra | n/a | Reusable GitHub Actions workflows (uv, ruff, pytest, build, release). |
+| **argus-ci** | infra | n/a | Reusable GitHub Actions workflows, pinned `@v1`: `python-ci.yml` (uv, ruff, pytest matrix, build), `suite-check.yml` (CLAUDE.md suite block + SUITE.md row), `docs-check.yml` (generated Typer `docs/cli.md` must match the CLI; published docs scanned for private IPs, home/server paths, emails and a private denylist). Not release: PyPI trusted publishing can't run in a reusable workflow, so `release.yml` comes from argus-pkg-template. |
 | **argus-pkg-template** | infra | n/a | Copier template for new Argus Python packages; `copier update` pulls tooling changes. |
 
 **How they fit.** The LoRA pipeline is `quarry → curator → lens → forge → (trainer) → proof → atlas`; curator, lens,
@@ -43,15 +44,15 @@ atlas. Every Python service except quarry depends on cortex. UIs are thin client
 shows.
 
 **API and UI pairs.** darkroom ↔ safelight · curator ↔ cull · lens ↔ lightbox · survey ↔ sightline · mint ↔ assay.
-Studio has a page for lens, curator, quarry, forge, proof, atlas and darkroom, and links out to sightline.
+Studio has a page for lens, curator, quarry, forge, proof, atlas and darkroom, and links out to sightline, mask and assay.
 
 ## Need it? Use it
 
 | Need | Use | Don't |
 |---|---|---|
-| Generate an image (a plate, a background, art, a sample) | **darkroom** `POST /generate/stream` (SSE), `GET /image/{id}`. Its record id, model and seed are your provenance. Example client: mint's `DarkroomClient`. | Call ComfyUI directly or generate without checks. |
+| Generate an image (a plate, a background, art, a sample), or rework or inpaint one | **darkroom** `POST /generate/stream` (SSE; `init_image`, with `mask_base64` to inpaint), `GET /image/{id}`. Its record id, model and seed are your provenance. Example client: mint's `DarkroomClient`. | Call ComfyUI directly or generate without checks. |
 | Check an image for nudity, or text/an image against a policy | `argus_cortex.moderation` (`NudeNetClient`, `SingGuardClient`, `policies`) | Write your own nudity definition or policy text. |
-| Share the GPU with other services | `argus_cortex.gpu` (`coordinator_from_env()`, `lease()`) | Assume the GPU is free. |
+| Share the GPU with other services | `argus_cortex.gpu` (`coordinator_from_env()`, `lease()`/`alease()`); `ARGUS_GPU_COORDINATOR=broker` asks argus-iris, which places, prioritises and makes room across nodes. Declare your GPU use in a committed `gpu-tenant.yaml` (`gpu-tenant-schema.json`). | Assume the GPU is free, or keep your own idle-unload or keep-alive policy. |
 | Call a local or hosted model | `argus_cortex.backends` (`LocalBackend`, `RemoteBackend`, `with_retries`) | Hand-roll an HTTP client per model. |
 | Version a wire payload, commit its schema | `argus_cortex.wire` (`make_versioned_base`, `render_schema`) | Ship an unversioned contract. |
 | Guard a FastAPI server's writes, or run read-only | `argus_cortex.server` (`WriteGuard`, `env_flag`) | Use `BaseHTTPMiddleware`, which buffers streams. |
@@ -63,14 +64,17 @@ Studio has a page for lens, curator, quarry, forge, proof, atlas and darkroom, a
 | Acquire source photos with licence and provenance | **quarry** | Scrape inside another stage. |
 | Find public-domain photos by caption, filters or meaning, then land a slice | **quarry** `GET /archives/{name}/search` (`semantic=`, `similar_to=` on PD12M), `POST /archives/{name}/fetch` (opt-in, `QUARRY_ALLOW_FETCH=1`) | Download PD12M or Megalith wholesale to search it. |
 | Score, dedupe or select images; faces; content rating | **curator** | Re-score in a later stage. |
-| Caption or keyword images | **lens** | Write ad-hoc captions. |
+| Shortlist source portraits for a mask face | **curator** `face_source` on `POST /scan/{id}/select` / `POST /export` (CLI `--face-source`, `--face-reference`); each image left out says which check it failed | Pick a face source by eye, or take one from quarry. |
+| Caption or keyword images | **lens** `POST /caption` (upload), `/caption/folder` or `/caption/manifest` (paths under its source root), `/caption/url` (public or allow-listed hosts); optional `backend` per request | Write ad-hoc captions, or hand lens a LAN URL it hasn't been told to trust. |
 | Training configs, or evaluating a LoRA | **forge**, **proof** | |
+| Reuse the checkpoint, LoRAs and sampling a LoRA passed evaluation with | **proof** `GET /report/{run_id}/manifest` (field names from `ModelRef`, `LoRARef`, `SamplingParams`; `410` once the run dir is pruned) | Re-enter the setup by hand. |
 | Terrain, georeferencing, map tiles | **atlas** (stylised), **survey** (survey-grade) | |
 | Point clouds: ground classification, DTM/DSM, volumes, datum transformations (geoid heights, GDA94→GDA2020) | **survey** (CLI, or `POST /jobs/{id}/{step}` over SSE); its GeoTIFFs feed `argus-atlas controls --dem` | Let PROJ pick a transformation, or reproject heights without a geoid grid. |
-| A face that speaks | **mask** `POST /speak?face=<id>` (text), `POST /push?face=<id>` (a WAV or PCM you already have) or the `/session/<id>/source` socket; screens open `/?face=<id>` | Drive a face's animation yourself, or render it per stage. |
+| A face that speaks | **mask** `POST /speak` (JSON `{"face", "text"}`), `POST /push?face=<id>` (a WAV or PCM you already have) or the `/session/<id>/source` socket; screens open `/?face=<id>` (`&scene=ftl` for a backdrop) | Drive a face's animation yourself, or render it per stage. |
 | On-chain provenance, IPFS; game-asset cards from reviewed templates | **mint** (`argus-mint serve`, or the CLI); a consumer supplies template variables, display text and 32-byte leaf hashes | Mint tokens a game reads stats from, or send free text to a model. |
 | Run the whole stack locally | **studio** `compose.yaml` | |
 | A new Python package, or CI | **argus-pkg-template**, **argus-ci** | Copy another repo's tooling by hand. |
+| A logo, favicon, README header or social preview for a repo, demo or UI | **cortex** `brand/` (suite mark, one mark per package, lockups, Panoptes font; `brand/README.md`) | Draw a new mark, recolour one, or set "argus" in another font. |
 
 ## Shared rules