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

argus_cortex-0.4.7/.cursor/rules/agent-coding-packs.mdc

@@ -0,0 +1,29 @@
+---
+description: Fetch ai-code-auditor coding packs for argus-cortex before changing code
+alwaysApply: true
+---
+
+<!-- ai-audit:agent-packs:start -->
+# Agent coding packs
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-cortex` yourself.
+
+The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in the local `.env`
+(see `.env.example`, placeholder `http://<AUDIT_HOST>:8765`); read it there, don't guess.
+
+1. **Bundle (one call):** `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/bundle?repo=argus-cortex`
+   (world model + ranked specialist packs + token-capped `briefs_markdown`;
+   optional `&token_budget=2500&q=<keyword>&limit_specialists=5`).
+   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`).
+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`.
+
+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.6 → argus_cortex-0.4.7}/.env.example

@@ -19,3 +19,8 @@ CORTEX_S3_ACCESS_KEY=
 CORTEX_S3_SECRET_KEY=
 CORTEX_S3_BUCKET=argus
 CORTEX_S3_REGION=us-east-1
+
+# ── Agent tooling (not read by this service) ──
+# ai-code-auditor audit API base that AGENTS.md tells coding agents to use.
+# Put the real host/IP in your local .env, never here.
+# AI_AUDIT_PUBLIC_BASE_URL=http://<AUDIT_HOST>:8765

{argus_cortex-0.4.6 → argus_cortex-0.4.7}/.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [dev, main]
   pull_request:
-    branches: [main]
+    branches: [dev, main]
 
 concurrency:
   group: ci-${{ github.ref }}

argus_cortex-0.4.7/AGENTS.md

@@ -0,0 +1,24 @@
+<!-- ai-audit:agent-packs:start -->
+## Agent coding packs (ai-code-auditor)
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-cortex` yourself.
+
+The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in the local `.env`
+(see `.env.example`, placeholder `http://<AUDIT_HOST>:8765`); read it there, don't guess.
+
+1. **Bundle (one call):** `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/bundle?repo=argus-cortex`
+   (world model + ranked specialist packs + token-capped `briefs_markdown`;
+   optional `&token_budget=2500&q=<keyword>&limit_specialists=5`).
+   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`).
+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`.
+
+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.6 → argus_cortex-0.4.7}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.7] - 2026-11-13
+
+### Added
+- **`concept` target category.** `TargetCategory` gains `concept`, a style or
+  visual-concept LoRA, matching argus-quarry's `concept` subjects. It is
+  additive, but a stage that keys tables by category (forge's heuristics, curator's
+  scanner) must add an entry before it accepts it.
+- **Committed `taxonomy-schema.json`.** Generated from `TargetProfile` by the new
+  `taxonomy_schema()` (`make schema`), with a test that fails when it drifts from
+  `taxonomy.py`, so non-Python clients such as studio generate their types instead
+  of copying the literals (#29).
+- **`SUITE.md`, the suite map for agents.** Every Argus repo, its port and purpose,
+  and a "Need it? Use it" index. Each repo's `CLAUDE.md` imports it (#33).
+
 ## [0.4.6] - 2026-11-06
 
 ### Changed
@@ -215,7 +229,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     (`LocalBackend`, `RemoteBackend`, `RemoteProvider`, `with_retries`
     retrying only transient errors, `resolve_device`).
 
-[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.6...HEAD
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.7...HEAD
+[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
 [0.4.4]: https://github.com/smk762/argus-cortex/compare/v0.4.3...v0.4.4

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

@@ -4,17 +4,25 @@ Guidance for AI agents working in this repo. Human-facing usage lives in [README
 
 ## What this is
 
-The **shared foundation library** of the Argus suite (quarry → curator → lens → forge → proof). It holds the code the stages *share* so it lives in one place instead of copy-pasted per repo: the target taxonomy, the wire-schema versioning discipline, the local/remote AI-backend contract, and the optional stateful-services layer.
+The **shared foundation library** of the Argus suite. It holds the code the stages *share* so it lives in one place instead of copy-pasted per repo: the target taxonomy, the wire-schema versioning discipline, the local/remote AI-backend contract, and the optional stateful-services layer.
 
 Naming: the working directory is `argus-core`, but the GitHub repo, the PyPI package, and the import name are all **`argus-cortex`** (`src/argus_cortex/`). Don't "fix" the mismatch.
 
 Because everything here is imported by the downstream stages, **a change ripples across the whole suite** — treat this repo as an API, not a leaf. Read [README.md](README.md) for the *why* and worked examples; it is the source of truth for behaviour.
 
+## Argus suite
+<!-- argus-suite: keep this block; argus-ci checks for it -->
+Cortex owns the suite map, [SUITE.md](SUITE.md), which every repo's CLAUDE.md imports. **Keep it accurate:** a cortex
+release that adds or changes a shared module updates its "Need it? Use it" row, and PRs from other repos that update
+their own rows land here. Keep it short, because it is loaded into every session in every repo.
+
+@SUITE.md
+
 ## Layout
 
 `src/argus_cortex/` (top level is pydantic-only; everything heavier is behind an extra and lazily imported):
 
-- `taxonomy.py` — the "moat" types every stage inherits verbatim: `TargetProfile`, `TargetStyle`/`TargetCategory` literals. Keep it dependency-light; a change here retrains everyone's expectations.
+- `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.
 - `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]`.
@@ -23,7 +31,7 @@ Because everything here is imported by the downstream stages, **a change ripples
 - `moderation/` — content-moderation clients over HTTP: `nudenet.py` (`NudeNetClient`, `NsfwResult`, `DEFAULT_EXPOSED_LABELS` — **the suite's one definition of nudity; don't widen it casually**, every stage's NSFW numbers move with it), `singguard.py` (`SingGuardClient` incl. text-only `check_text()`, `GuardResult`, `rule_matches`), `policies.py` (the named policy texts, the per-policy illegal-rule table and `mode()`: `default`/`sfw-*` are SFW — **a policy's text and its illegal letters change together**), `_http.py` (shared POST, proxy-free opener, `CheckFailed`/`ModerationConfigError`). Stdlib + pydantic; Pillow lazily, behind `[images]`. Never import NudeNet (AGPL) — HTTP only. URLs are passed in; stages own their env config.
 - `store/` — the optional stateful-services layer, opt-in per `CORTEX_*` env var: `lineage.py` (Phase 1 Postgres DAG, `open_lineage_store()`), `vector.py` (Phase 2 Qdrant, `open_vector_store()`), `blob.py` (Phase 3 MinIO/S3, `open_blob_store()`), over `config.py`/`models.py`/`errors.py`. Each `open_*()` returns a `Null*` no-op when its URL is unset. Drivers are behind `[postgres]`/`[qdrant]`/`[s3]`.
 
-There is **no CLI and no committed schema in this repo** — the `schema`/`schema --check` pattern is something `wire.py` *enables* for downstream repos, not something cortex runs on itself.
+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.
 
 ## Commands
 
@@ -45,6 +53,10 @@ Run one test: `uv run --no-sync pytest tests/test_wire.py::test_name -q`.
 - **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_cortex/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
 - Pydantic v2 everywhere; async tests via `asyncio_mode = auto`. Ruff pinned **0.15.16**, line-length 120, target py311.
 
+## 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.
+
 ## CI / release
 
 CI runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow (ruff + pytest with the `dev` extra — which installs the real psycopg/qdrant/minio/starlette clients so each store's live driver path is exercised, not just fakes). Release publishes to PyPI (OIDC trusted publishing) on `v*` tags — **no container image, this is a library**. Scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template); run `copier update` to pull tooling changes.

{argus_cortex-0.4.6 → argus_cortex-0.4.7}/Makefile

@@ -1,6 +1,6 @@
 UV ?= uv
 
-.PHONY: help install lint format test build clean
+.PHONY: help install lint format test schema build clean
 
 help:  ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
@@ -20,6 +20,9 @@ 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')"
+
 build:  ## Build sdist + wheel
 	$(UV) build
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.4.6
+Version: 0.4.7
 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
@@ -51,11 +51,11 @@ Description-Content-Type: text/markdown
 
 Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract.
 
-Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (quarry → curator → lens → forge → proof). This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
+Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/dev/SUITE.md) lists every repo, what it owns, and how they fit together. This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
 
 ## What's here
 
-- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim.
+- **`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.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.
@@ -75,7 +75,7 @@ from argus_cortex.backends import RemoteBackend, RemoteProvider
 _Versioned = make_versioned_base("proof_version", "1.0", ("1",))
 
 # reach a hosted scorer by IP/port, or a known provider
-scorer = RemoteBackend.from_host("192.168.1.20", 9000, api_key="…")
+scorer = RemoteBackend.from_host("<LAN_HOST>", 9000, api_key="…")  # real host/IP: local .env
 nim = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="…")
 ```
 

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

@@ -2,11 +2,11 @@
 
 Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract.
 
-Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (quarry → curator → lens → forge → proof). This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
+Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/dev/SUITE.md) lists every repo, what it owns, and how they fit together. This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
 
 ## What's here
 
-- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim.
+- **`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.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.
@@ -26,7 +26,7 @@ from argus_cortex.backends import RemoteBackend, RemoteProvider
 _Versioned = make_versioned_base("proof_version", "1.0", ("1",))
 
 # reach a hosted scorer by IP/port, or a known provider
-scorer = RemoteBackend.from_host("192.168.1.20", 9000, api_key="…")
+scorer = RemoteBackend.from_host("<LAN_HOST>", 9000, api_key="…")  # real host/IP: local .env
 nim = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="…")
 ```
 

argus_cortex-0.4.7/SUITE.md

@@ -0,0 +1,98 @@
+# The Argus suite: map for agents
+
+The canonical list of every Argus repo: what each one is for, and which one already does the thing you are about to build.
+Every repo's `CLAUDE.md` imports this file. **Before designing a feature, check the "Need it? Use it" index.** If a
+sibling already does it, call that sibling (HTTP, or its library) instead of rebuilding it.
+
+**Keep it current. Every release of any Argus repo checks its row here.** If a release adds, removes or renames a
+capability, endpoint, port, UI pairing or dependency, open a PR to `argus-cortex` that updates this file in the same
+release. A new repo adds a row and the import block (see the end of this file) before its first release.
+
+## Repos
+
+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, optional lineage/vector/blob stores. |
+| **argus-quarry** | service | 8102 | Acquire public-domain / CC0 images with provenance and licence into a category-sorted raw pool. 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. |
+| **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-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: QA, ground, DTM/DSM, contours, volumes, change, ASPRS accuracy. |
+| **argus-mint** | service | 8108 | Provenance tokens for game assets: renders reviewed templates through darkroom, pins to IPFS, mints ERC-721 cards and soulbound deeds, anchors Merkle roots (Base). |
+| **argus-mask** | service | 8109 | A talking face: audio in, facial-animation frames out, rendered in a browser on any LAN screen. |
+| **argus-studio** | UI + compose | 3000 | The suite web UI, and the compose stack that runs the services from GHCR images. No backend code. |
+| **argus-safelight** | UI | 3097 | Demo UI for darkroom: prompt, verdicts, generation over SSE, history. |
+| **argus-cull** | UI | 3000 | Demo UI for curator: which images make the set and why, plus the paths to act on. |
+| **argus-lightbox** | UI (static) | 3000 | Demo gallery navigated by lens captions; bakes from cortex stores, then runs with no server. |
+| **argus-sightline** | UI | 3107 | Workspace UI for survey. |
+| **argus-assay** | UI | 3108 | Review UI for mint: the moderator and owner approve every card, template and frame. |
+| **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-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,
+forge and proof carry the same `TargetProfile` from cortex. Darkroom is the suite's way to generate an image: mint
+renders through it, and anything new that needs a picture (mask backgrounds, game art) should too. Proof's sample grids
+and atlas's bakes predate it and still drive their own diffusion backend. Survey stands alone; its GeoTIFFs can feed
+atlas. Every Python service except quarry depends on cortex. UIs are thin clients: the service decides and the UI only
+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.
+
+## 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. |
+| 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. |
+| 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. |
+| Read or write XMP sidecars | `argus_cortex.xmp` | Overwrite another stage's properties. |
+| Record lineage, embeddings or blobs | `argus_cortex.store` (`open_lineage_store` / `open_vector_store` / `open_blob_store`) | Add a database to a single stage. |
+| The training target (style, category) | `argus_cortex.taxonomy`; non-Python clients use `taxonomy-schema.json` | Copy the literals. |
+| Acquire source photos with licence and provenance | **quarry** | Scrape inside another stage. |
+| Score, dedupe or select images; faces; content rating | **curator** | Re-score in a later stage. |
+| Caption or keyword images | **lens** | Write ad-hoc captions. |
+| Training configs, or evaluating a LoRA | **forge**, **proof** | |
+| Terrain, georeferencing, map tiles | **atlas** (stylised), **survey** (survey-grade) | |
+| A face that speaks | **mask** | |
+| On-chain provenance, IPFS | **mint** | |
+| 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. |
+
+## Shared rules
+
+- Shared code lives in cortex: import it, don't copy it. A cortex change ripples into every stage on its next bump.
+- Provenance first. Anything the suite serves or trains on carries its source and licence; unlicensed input is refused.
+- Optional heavy dependencies are lazy imports behind extras. A missing service config fails open to a no-op, never a crash.
+- Talk across repos over HTTP or a versioned wire schema, never by reading another repo's files.
+
+## Local checkouts
+
+The maintainer's siblings live under `~/`, so the paths are `../argus-<name>`, with two exceptions:
+- cortex is `../argus-core`;
+- studio is `../argus-vision-demo`.
+
+Directories named `argus-<repo>-<topic>` are worktrees of `<repo>`, not separate repos.
+
+## The import block (every repo's CLAUDE.md)
+
+```markdown
+## Argus suite
+<!-- argus-suite: keep this block; argus-ci checks for it -->
+This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
+building something a sibling may already do. **On every release, update this repo's row and capabilities in
+argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
+
+@../argus-core/SUITE.md
+
+Not checked out? Read https://github.com/smk762/argus-cortex/blob/dev/SUITE.md
+```

{argus_cortex-0.4.6 → argus_cortex-0.4.7}/src/argus_cortex/__init__.py

@@ -55,7 +55,7 @@ from argus_cortex.store import (
     open_lineage_store,
     open_vector_store,
 )
-from argus_cortex.taxonomy import TargetCategory, TargetProfile, TargetStyle
+from argus_cortex.taxonomy import TargetCategory, TargetProfile, TargetStyle, taxonomy_schema
 from argus_cortex.wire import (
     VersionError,
     check_version,
@@ -83,6 +83,7 @@ __all__ = [
     "TargetProfile",
     "TargetCategory",
     "TargetStyle",
+    "taxonomy_schema",
     # wire
     "VersionError",
     "check_version",

{argus_cortex-0.4.6 → argus_cortex-0.4.7}/src/argus_cortex/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.6'
-__version_tuple__ = version_tuple = (0, 4, 6)
+__version__ = version = '0.4.7'
+__version_tuple__ = version_tuple = (0, 4, 7)
 
 __commit_id__ = commit_id = None

{argus_cortex-0.4.6 → argus_cortex-0.4.7}/src/argus_cortex/taxonomy.py

@@ -16,15 +16,19 @@ from typing import Literal
 
 from pydantic import BaseModel
 
+from argus_cortex.wire import render_schema
+
 TargetStyle = Literal["photo", "anime"]
 
 # What the dataset is curated for. Note this is distinct from argus-lens's
 # caption *buckets* (identity/action/pose_composition/wardrobe/lighting/setting):
 # those describe caption fragments, this describes the training objective.
-TargetCategory = Literal["identity", "wardrobe", "pose_composition", "setting"]
+# ``concept`` is a style or visual-concept LoRA: what argus-quarry acquires
+# under its ``concept`` subjects.
+TargetCategory = Literal["identity", "wardrobe", "pose_composition", "setting", "concept"]
 
 TARGET_STYLES: tuple[TargetStyle, ...] = ("photo", "anime")
-TARGET_CATEGORIES: tuple[TargetCategory, ...] = ("identity", "wardrobe", "pose_composition", "setting")
+TARGET_CATEGORIES: tuple[TargetCategory, ...] = ("identity", "wardrobe", "pose_composition", "setting", "concept")
 
 
 class TargetProfile(BaseModel):
@@ -39,3 +43,16 @@ class TargetProfile(BaseModel):
     target_backend: str | None = "sdxl"
     checkpoint: str | None = None
     target_category: TargetCategory = "identity"
+
+
+TAXONOMY_SCHEMA_TITLE = "argus-cortex taxonomy"
+
+
+def taxonomy_schema() -> str:
+    """The canonical JSON Schema for the taxonomy, as committed in ``taxonomy-schema.json``.
+
+    Non-Python clients (argus-studio) generate their types from that file instead
+    of hand-copying the literals. ``tests/test_taxonomy.py`` fails if the
+    committed file and this module drift; regenerate it with ``make schema``.
+    """
+    return render_schema([TargetProfile], title=TAXONOMY_SCHEMA_TITLE)

argus_cortex-0.4.7/taxonomy-schema.json

@@ -0,0 +1,57 @@
+{
+  "$defs": {
+    "TargetProfile": {
+      "description": "What a dataset was curated for \u2014 shared verbatim across the suite.\n\nInherited unchanged from stage to stage (curator \u2192 lens \u2192 forge \u2192 proof) so\na decision made once at curation time is honoured everywhere downstream; no\nstage remaps the taxonomy.",
+      "properties": {
+        "checkpoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Checkpoint"
+        },
+        "target_backend": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": "sdxl",
+          "title": "Target Backend"
+        },
+        "target_category": {
+          "default": "identity",
+          "enum": [
+            "identity",
+            "wardrobe",
+            "pose_composition",
+            "setting",
+            "concept"
+          ],
+          "title": "Target Category",
+          "type": "string"
+        },
+        "target_style": {
+          "default": "photo",
+          "enum": [
+            "photo",
+            "anime"
+          ],
+          "title": "Target Style",
+          "type": "string"
+        }
+      },
+      "title": "TargetProfile",
+      "type": "object"
+    }
+  },
+  "title": "argus-cortex taxonomy"
+}

{argus_cortex-0.4.6 → argus_cortex-0.4.7}/tests/test_taxonomy.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+import json
+from pathlib import Path
+
 import pytest
 from pydantic import ValidationError
 
-from argus_cortex.taxonomy import TARGET_CATEGORIES, TARGET_STYLES, TargetProfile
+from argus_cortex.taxonomy import TARGET_CATEGORIES, TARGET_STYLES, TargetProfile, taxonomy_schema
 
 
 def test_defaults() -> None:
@@ -34,4 +37,17 @@ def test_round_trips() -> None:
 
 def test_tuples_match_literals() -> None:
     assert set(TARGET_STYLES) == {"photo", "anime"}
-    assert set(TARGET_CATEGORIES) == {"identity", "wardrobe", "pose_composition", "setting"}
+    assert set(TARGET_CATEGORIES) == {"identity", "wardrobe", "pose_composition", "setting", "concept"}
+
+
+SCHEMA_FILE = Path(__file__).resolve().parent.parent / "taxonomy-schema.json"
+
+
+def test_committed_schema_matches_taxonomy() -> None:
+    assert SCHEMA_FILE.read_text() == taxonomy_schema(), "taxonomy-schema.json is stale; run `make schema`"
+
+
+def test_schema_lists_every_literal() -> None:
+    defs = json.loads(taxonomy_schema())["$defs"]["TargetProfile"]["properties"]
+    assert defs["target_category"]["enum"] == list(TARGET_CATEGORIES)
+    assert defs["target_style"]["enum"] == list(TARGET_STYLES)