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

{argus_cortex-0.2.0 → argus_cortex-0.3.0}/.github/workflows/release.yml

@@ -62,7 +62,15 @@ jobs:
 
   publish-pypi:
     runs-on: ubuntu-latest
-    needs: publish-testpypi
+    # Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
+    # deliberately not gated on it. A TestPyPI-only fault — a missing trusted
+    # publisher, an index outage — must not silently withhold the real release:
+    # that failure mode shipped argus-proof images for two tags with no wheel on
+    # PyPI, and nothing surfaced it because publish-image is independent.
+    # Only the build + install gate is required; a TestPyPI failure still marks
+    # the whole run failed, so the problem stays loud.
+    needs: [test-install, publish-testpypi]
+    if: "!cancelled() && needs.test-install.result == 'success'"
     environment: pypi
     steps:
       - uses: actions/download-artifact@v4

argus_cortex-0.3.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-25
+
+### Added
+- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation, hoisted
+  from argus-lens so lens (keywords/caption) and argus-curator (face regions,
+  content rating) share a writer. `write_xmp()` / `read_xmp()` /
+  `merge_xmp()` / `parse_xmp()` / `render_xmp()` / `sidecar_path()` over an
+  `XmpData` model, all exported from the top-level package.
+  - Namespaces: `dc` (subject, description), `xmp` (Rating, Label), `lr`
+    (hierarchicalSubject), `Iptc4xmpExt` (PersonInImage), `mwg-rs` regions
+    (`XmpRegions` / `XmpRegion`, MWG centre-based normalised coordinates), and a
+    new `argus` namespace for `ContentRating`. The `argus` namespace URI
+    (`https://github.com/smk762/argus-cortex/ns/xmp/1.0/`) is now a wire
+    contract.
+  - **Writes merge**: each property set in `XmpData` replaces that property
+    (latest write wins, element or attribute form, across every
+    `rdf:Description`); everything else in the sidecar — Lightroom develop
+    settings, GPS, another stage's fields, foreign namespace prefixes — is
+    preserved. `None` leaves a property untouched, an empty value removes it;
+    `replace=True` discards the existing sidecar.
+  - Writes are atomic (temp file + rename) and keep the existing file mode
+    (`0644` for a new sidecar). An unparseable existing sidecar raises
+    `XmpError` and is never clobbered; a DTD / entity declaration is refused.
+  - Stdlib `xml.etree` + pydantic only, so the top-level import stays
+    pydantic-only.
+- `CLAUDE.md` agent guide.
+
+### Security
+- **eMudhra/emSign CA incident.** The extras that make outbound TLS
+  connections (`[remote]` httpx, `[qdrant]`, `[s3]`) now require
+  `certifi>=2026.10.19`, which no longer trusts the compromised emSign
+  intermediates. See https://discuss.python.org/t/109576.
+
+## [0.2.0] - 2026-07-21
+
+### Added
+- **Optional stateful-services layer** (`argus_cortex.store`), each store opt-in
+  via `CORTEX_*` env vars and a `Null*` no-op when unset:
+  - Phase 1 — Postgres lineage store (`source_asset → caption → human_edit →
+    dataset_membership → training_run`), backed by a psycopg connection pool
+    with an atomic `transaction()` boundary (`[postgres]` extra).
+  - Phase 2 — Qdrant vector store for image / tag-set embeddings
+    (`[qdrant]` extra).
+  - Phase 3 — MinIO/S3 content-addressed blob store, keyed on sha256
+    (`content_key()` == `source_asset.sha256`) (`[s3]` extra).
+- **`argus_cortex.server`** — shared pure-ASGI `WriteGuard`, the
+  `constant_refuse()` / `cross_site_refuse()` predicates, `env_flag()` and the
+  `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants (`[server]` extra).
+
+### Fixed
+- Release: a TestPyPI failure no longer gates the real PyPI release.
+
+## [0.1.0] - 2026-07-08
+
+### Added
+- Initial release (renamed from `argus-core`; that PyPI name was taken):
+  - `argus_cortex.taxonomy` — `TargetProfile`, `TargetStyle`, `TargetCategory`.
+  - `argus_cortex.wire` — versioned wire-schema toolkit (`make_versioned_base`,
+    `check_version` with an injectable error type, `render_schema` /
+    `wire_schema`, `VersionError`).
+  - `argus_cortex.backends` — the local/remote AI-backend contract
+    (`LocalBackend`, `RemoteBackend`, `RemoteProvider`, `with_retries`
+    retrying only transient errors, `resolve_device`).
+
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/smk762/argus-cortex/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/smk762/argus-cortex/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/smk762/argus-cortex/releases/tag/v0.1.0

argus_cortex-0.3.0/CLAUDE.md

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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.2.0
+Version: 0.3.0
 Summary: Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract
 Project-URL: Repository, https://github.com/smk762/argus-cortex
 Author: smk762
@@ -16,6 +16,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: pydantic>=2.7
 Provides-Extra: dev
+Requires-Dist: certifi>=2026.10.19; extra == 'dev'
+Requires-Dist: httpx2>=2.7; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: minio>=7.2; extra == 'dev'
 Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'dev'
@@ -27,10 +29,13 @@ Requires-Dist: starlette>=0.37; extra == 'dev'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'postgres'
 Provides-Extra: qdrant
+Requires-Dist: certifi>=2026.10.19; extra == 'qdrant'
 Requires-Dist: qdrant-client>=1.10; extra == 'qdrant'
 Provides-Extra: remote
+Requires-Dist: certifi>=2026.10.19; extra == 'remote'
 Requires-Dist: httpx>=0.27; extra == 'remote'
 Provides-Extra: s3
+Requires-Dist: certifi>=2026.10.19; extra == 's3'
 Requires-Dist: minio>=7.2; extra == 's3'
 Provides-Extra: server
 Requires-Dist: starlette>=0.37; extra == 'server'
@@ -48,6 +53,7 @@ Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (q
 - **`argus_cortex.wire`** — the versioned wire-schema toolkit: `check_version()` (major-compatibility gate), `make_versioned_base()` (a Pydantic base that stamps + checks a version field like `proof_version` / `manifest_version`), and `wire_schema()` / `render_schema()` for the committed-schema `schema --check` CLI pattern.
 - **`argus_cortex.backends`** — the AI-backend contract generalised from argus-lens: `Backend` / `LocalBackend` / `RemoteBackend` (point at a hosted service by `base_url`, `host`/`port`, or a known `RemoteProvider`), plus `with_retries()` and `resolve_device()`. httpx lives behind the `[remote]` extra.
 - **`argus_cortex.server`** — shared write-guard + env-flag scaffolding for the suite's FastAPI micro-servers: `WriteGuard` (a pure-ASGI method-gate that never buffers streaming responses), the `constant_refuse()` / `cross_site_refuse()` predicates (read-only/replay mode and cross-site-write protection are two configs of the one guard), the `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants, and `env_flag()` (warns on a mistyped protection flag rather than silently disabling it). Starlette lives behind the `[server]` extra.
+- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib only.
 - **`argus_cortex.store`** — the optional **stateful services layer** (the suite's persistent "memory"). External and opt-in — every store is configured by `CORTEX_*` env vars and no-ops when its URL is unset.
   - **Phase 1 — Postgres lineage store.** Persists the `source_asset → caption → human_edit → dataset_membership → training_run` DAG for LoRA reproducibility, edit capture, and the feedback loop. Backed by a psycopg connection **pool** (concurrent `asyncio.to_thread` calls are safe; a dropped connection is replaced), with a `transaction()` boundary for atomic multi-step writes. `open_lineage_store()` returns a no-op store when `CORTEX_PG_URL` is unset; psycopg lives behind the `[postgres]` extra.
   - **Phase 2 — Qdrant vector store.** Stores image + tag-set embeddings for retrieval-augmented few-shot and near-duplicate curation; put a `caption_id`/`asset_id` in a point's payload and a search hit joins straight back to the lineage. `open_vector_store()` no-ops when `CORTEX_QDRANT_URL` is unset; qdrant-client lives behind the `[qdrant]` extra. cortex stores vectors it's *handed* — computing embeddings is the caller's job.
@@ -65,6 +71,22 @@ scorer = RemoteBackend.from_host("192.168.1.20", 9000, api_key="…")
 nim = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="…")
 ```
 
+```python
+from argus_cortex.xmp import XmpData, XmpRegion, XmpRegions, write_xmp
+
+# lens writes captions/keywords …
+write_xmp("pics/beach.jpg", XmpData(keywords=["beach", "sunset"], description="a beach at sunset"))
+# … curator later adds faces + a content rating to the same sidecar; lens's fields survive
+write_xmp(
+    "pics/beach.jpg",
+    XmpData(
+        persons=["Ada"],
+        regions=XmpRegions(width=4000, height=3000, regions=[XmpRegion(x=0.52, y=0.4, w=0.1, h=0.18, name="Ada")]),
+        content_rating="safe",
+    ),
+)
+```
+
 ```python
 from argus_cortex.store import open_lineage_store, SourceAsset, Caption, HumanEdit
 

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

@@ -10,6 +10,7 @@ Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (q
 - **`argus_cortex.wire`** — the versioned wire-schema toolkit: `check_version()` (major-compatibility gate), `make_versioned_base()` (a Pydantic base that stamps + checks a version field like `proof_version` / `manifest_version`), and `wire_schema()` / `render_schema()` for the committed-schema `schema --check` CLI pattern.
 - **`argus_cortex.backends`** — the AI-backend contract generalised from argus-lens: `Backend` / `LocalBackend` / `RemoteBackend` (point at a hosted service by `base_url`, `host`/`port`, or a known `RemoteProvider`), plus `with_retries()` and `resolve_device()`. httpx lives behind the `[remote]` extra.
 - **`argus_cortex.server`** — shared write-guard + env-flag scaffolding for the suite's FastAPI micro-servers: `WriteGuard` (a pure-ASGI method-gate that never buffers streaming responses), the `constant_refuse()` / `cross_site_refuse()` predicates (read-only/replay mode and cross-site-write protection are two configs of the one guard), the `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants, and `env_flag()` (warns on a mistyped protection flag rather than silently disabling it). Starlette lives behind the `[server]` extra.
+- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib only.
 - **`argus_cortex.store`** — the optional **stateful services layer** (the suite's persistent "memory"). External and opt-in — every store is configured by `CORTEX_*` env vars and no-ops when its URL is unset.
   - **Phase 1 — Postgres lineage store.** Persists the `source_asset → caption → human_edit → dataset_membership → training_run` DAG for LoRA reproducibility, edit capture, and the feedback loop. Backed by a psycopg connection **pool** (concurrent `asyncio.to_thread` calls are safe; a dropped connection is replaced), with a `transaction()` boundary for atomic multi-step writes. `open_lineage_store()` returns a no-op store when `CORTEX_PG_URL` is unset; psycopg lives behind the `[postgres]` extra.
   - **Phase 2 — Qdrant vector store.** Stores image + tag-set embeddings for retrieval-augmented few-shot and near-duplicate curation; put a `caption_id`/`asset_id` in a point's payload and a search hit joins straight back to the lineage. `open_vector_store()` no-ops when `CORTEX_QDRANT_URL` is unset; qdrant-client lives behind the `[qdrant]` extra. cortex stores vectors it's *handed* — computing embeddings is the caller's job.
@@ -27,6 +28,22 @@ scorer = RemoteBackend.from_host("192.168.1.20", 9000, api_key="…")
 nim = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="…")
 ```
 
+```python
+from argus_cortex.xmp import XmpData, XmpRegion, XmpRegions, write_xmp
+
+# lens writes captions/keywords …
+write_xmp("pics/beach.jpg", XmpData(keywords=["beach", "sunset"], description="a beach at sunset"))
+# … curator later adds faces + a content rating to the same sidecar; lens's fields survive
+write_xmp(
+    "pics/beach.jpg",
+    XmpData(
+        persons=["Ada"],
+        regions=XmpRegions(width=4000, height=3000, regions=[XmpRegion(x=0.52, y=0.4, w=0.1, h=0.18, name="Ada")]),
+        content_rating="safe",
+    ),
+)
+```
+
 ```python
 from argus_cortex.store import open_lineage_store, SourceAsset, Caption, HumanEdit
 

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

@@ -24,10 +24,10 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-remote = ["httpx>=0.27"]
+remote = ["httpx>=0.27", "certifi>=2026.10.19"]
 postgres = ["psycopg[binary,pool]>=3.1"]
-qdrant = ["qdrant-client>=1.10"]
-s3 = ["minio>=7.2"]
+qdrant = ["qdrant-client>=1.10", "certifi>=2026.10.19"]
+s3 = ["minio>=7.2", "certifi>=2026.10.19"]
 # The shared ASGI write-guard + env-flag scaffolding for the suite's servers
 # (argus_cortex.server). Starlette ships with FastAPI, so consumers already have
 # it via their own [server] extra.
@@ -44,6 +44,8 @@ dev = [
     "minio>=7.2",
     "starlette>=0.37",
     "httpx>=0.27",
+    "httpx2>=2.7",
+    "certifi>=2026.10.19",
 ]
 
 [project.urls]

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

@@ -56,6 +56,18 @@ from argus_cortex.wire import (
     schema_major,
     wire_schema,
 )
+from argus_cortex.xmp import (
+    XmpData,
+    XmpError,
+    XmpRegion,
+    XmpRegions,
+    merge_xmp,
+    parse_xmp,
+    read_xmp,
+    render_xmp,
+    sidecar_path,
+    write_xmp,
+)
 
 __all__ = [
     "__version__",
@@ -70,6 +82,17 @@ __all__ = [
     "render_schema",
     "schema_major",
     "wire_schema",
+    # xmp sidecars
+    "XmpData",
+    "XmpError",
+    "XmpRegion",
+    "XmpRegions",
+    "merge_xmp",
+    "parse_xmp",
+    "read_xmp",
+    "render_xmp",
+    "sidecar_path",
+    "write_xmp",
     # backends
     "Backend",
     "BackendError",

{argus_cortex-0.2.0 → argus_cortex-0.3.0}/src/argus_cortex/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

argus_cortex-0.3.0/src/argus_cortex/xmp.py

@@ -0,0 +1,409 @@
+"""XMP sidecar read / merge / write — the suite's one XMP implementation.
+
+XMP sidecars (``<image>.<ext>.xmp``) are the zero-coupling interop surface:
+Lightroom, digiKam and Immich all ingest them, so metadata any stage writes
+here shows up in the user's own photo tools. Hoisted from
+``argus_lens.connectors.xmp`` so lens (captions/keywords) and curator (face
+regions, content rating) share one writer instead of each growing their own.
+
+Writes **merge**: the existing sidecar is parsed, each property being written
+replaces that property wholesale (the latest write wins on a conflicting key),
+and every other property — ratings, GPS, develop settings, another stage's
+fields — is preserved untouched. A field left as ``None`` in :class:`XmpData`
+is not touched; an empty list/string removes the property.
+
+Stdlib + pydantic only (``xml.etree``), so it is safe for the top-level import.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import os
+import re
+import tempfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+NS: dict[str, str] = {
+    "x": "adobe:ns:meta/",
+    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "xmp": "http://ns.adobe.com/xap/1.0/",
+    "lr": "http://ns.adobe.com/lightroom/1.0/",
+    "Iptc4xmpExt": "http://iptc.org/std/Iptc4xmpExt/2008-02-29/",
+    "mwg-rs": "http://www.metadataworkinggroup.com/schemas/regions/",
+    "stArea": "http://ns.adobe.com/xmp/sType/Area#",
+    "stDim": "http://ns.adobe.com/xap/1.0/sType/Dimensions#",
+    # Suite-specific properties with no standard home (e.g. a content rating —
+    # deliberately not xmp:Rating, which is the user's star rating).
+    "argus": "https://github.com/smk762/argus-cortex/ns/xmp/1.0/",
+}
+
+for _prefix, _uri in NS.items():
+    ET.register_namespace(_prefix, _uri)
+
+_XPACKET_BEGIN = '<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>\n'
+_XPACKET_END = '\n<?xpacket end="w"?>\n'
+
+# Characters that are illegal in XML 1.0 even when escaped. Stripped so a value
+# can never produce a sidecar Lightroom/digiKam/Immich would refuse to parse.
+_ILLEGAL_XML_CHARS = re.compile("[^\u0009\u000a\u000d -퟿-�\U00010000-\U0010ffff]")
+_XML_LANG = "{http://www.w3.org/XML/1998/namespace}lang"
+
+
+class XmpError(ValueError):
+    """An existing sidecar could not be parsed; it is left untouched rather than clobbered."""
+
+
+class XmpRegion(BaseModel):
+    """One MWG region (``mwg-rs:RegionList`` item), e.g. a detected face.
+
+    Coordinates are normalised to ``[0, 1]`` and, per the MWG spec, ``x``/``y``
+    are the region's **centre**, not its top-left corner.
+    """
+
+    x: float = Field(ge=0, le=1)
+    y: float = Field(ge=0, le=1)
+    w: float = Field(ge=0, le=1)
+    h: float = Field(ge=0, le=1)
+    name: str | None = None
+    type: Literal["Face", "Pet", "Focus", "BarCode"] = "Face"
+
+
+class XmpRegions(BaseModel):
+    """The ``mwg-rs:Regions`` struct: regions plus the image dimensions they apply to."""
+
+    width: int = Field(gt=0)
+    height: int = Field(gt=0)
+    regions: list[XmpRegion] = Field(default_factory=list)
+
+
+class XmpData(BaseModel):
+    """The XMP properties the suite reads and writes.
+
+    ``None`` means "leave this property alone" on a merge; an empty list or
+    string removes it.
+    """
+
+    keywords: list[str] | None = None  # dc:subject
+    description: str | None = None  # dc:description (x-default)
+    hierarchical_keywords: list[str] | None = None  # lr:hierarchicalSubject, "a|b|c"
+    rating: int | None = Field(default=None, ge=-1, le=5)  # xmp:Rating (user stars; -1 = rejected)
+    label: str | None = None  # xmp:Label (colour label)
+    persons: list[str] | None = None  # Iptc4xmpExt:PersonInImage
+    regions: XmpRegions | None = None  # mwg-rs:Regions
+    content_rating: str | None = None  # argus:ContentRating (e.g. safe / suggestive / explicit)
+
+
+def _q(qname: str) -> str:
+    """``"dc:subject"`` → ``"{http://purl.org/dc/elements/1.1/}subject"``."""
+    prefix, local = qname.split(":", 1)
+    return f"{{{NS[prefix]}}}{local}"
+
+
+def _text(value: str) -> str:
+    return _ILLEGAL_XML_CHARS.sub("", value)
+
+
+def _num(value: float) -> str:
+    return f"{value:.6g}"
+
+
+def _container(tag: str, kind: str, items: list[str]) -> ET.Element:
+    prop = ET.Element(_q(tag))
+    container = ET.SubElement(prop, _q(f"rdf:{kind}"))
+    for item in items:
+        ET.SubElement(container, _q("rdf:li")).text = _text(item)
+    return prop
+
+
+def _lang_alt(tag: str, value: str) -> ET.Element:
+    prop = ET.Element(_q(tag))
+    li = ET.SubElement(ET.SubElement(prop, _q("rdf:Alt")), _q("rdf:li"), {_XML_LANG: "x-default"})
+    li.text = _text(value)
+    return prop
+
+
+def _simple(tag: str, value: str) -> ET.Element:
+    prop = ET.Element(_q(tag))
+    prop.text = _text(value)
+    return prop
+
+
+def _regions(value: XmpRegions) -> ET.Element:
+    prop = ET.Element(_q("mwg-rs:Regions"), {_q("rdf:parseType"): "Resource"})
+    ET.SubElement(
+        prop,
+        _q("mwg-rs:AppliedToDimensions"),
+        {
+            _q("rdf:parseType"): "Resource",
+            _q("stDim:w"): str(value.width),
+            _q("stDim:h"): str(value.height),
+            _q("stDim:unit"): "pixel",
+        },
+    )
+    bag = ET.SubElement(ET.SubElement(prop, _q("mwg-rs:RegionList")), _q("rdf:Bag"))
+    for region in value.regions:
+        li = ET.SubElement(bag, _q("rdf:li"), {_q("rdf:parseType"): "Resource"})
+        if region.name:
+            ET.SubElement(li, _q("mwg-rs:Name")).text = _text(region.name)
+        ET.SubElement(li, _q("mwg-rs:Type")).text = region.type
+        ET.SubElement(
+            li,
+            _q("mwg-rs:Area"),
+            {
+                _q("rdf:parseType"): "Resource",
+                _q("stArea:x"): _num(region.x),
+                _q("stArea:y"): _num(region.y),
+                _q("stArea:w"): _num(region.w),
+                _q("stArea:h"): _num(region.h),
+                _q("stArea:unit"): "normalized",
+            },
+        )
+    return prop
+
+
+def _properties(data: XmpData) -> list[tuple[str, ET.Element | None]]:
+    """``(qname, element)`` for every field that is set; ``element`` is None to remove it."""
+    out: list[tuple[str, ET.Element | None]] = []
+
+    def add(qname: str, value: object, build) -> None:
+        if value is None:
+            return
+        out.append((qname, build(value) if value != [] and value != "" else None))
+
+    add("dc:subject", data.keywords, lambda v: _container("dc:subject", "Bag", v))
+    add("dc:description", data.description, lambda v: _lang_alt("dc:description", v))
+    add("lr:hierarchicalSubject", data.hierarchical_keywords, lambda v: _container("lr:hierarchicalSubject", "Bag", v))
+    add("xmp:Rating", data.rating, lambda v: _simple("xmp:Rating", str(v)))
+    add("xmp:Label", data.label, lambda v: _simple("xmp:Label", v))
+    add("Iptc4xmpExt:PersonInImage", data.persons, lambda v: _container("Iptc4xmpExt:PersonInImage", "Bag", v))
+    add("mwg-rs:Regions", data.regions, _regions)
+    add("argus:ContentRating", data.content_rating, lambda v: _simple("argus:ContentRating", v))
+    return out
+
+
+def _parse(raw: bytes) -> ET.Element:
+    """Parse a sidecar into its ``x:xmpmeta`` root (wrapping a bare ``rdf:RDF``)."""
+    # XMP never carries a DTD; refusing one outright rules out entity-expansion tricks.
+    if b"<!DOCTYPE" in raw or b"<!ENTITY" in raw:
+        raise XmpError("XMP sidecar contains a DTD/entity declaration; refusing to parse it")
+    for prefix, uri in _declared_namespaces(raw):
+        # Keep a foreign schema's own prefix on re-serialisation (cosmetic, but
+        # Lightroom-written sidecars stay recognisable). Ours always win.
+        if prefix and prefix not in NS:
+            with contextlib.suppress(ValueError):
+                ET.register_namespace(prefix, uri)
+    try:
+        root = ET.fromstring(raw)
+    except ET.ParseError as exc:
+        raise XmpError(f"malformed XMP sidecar: {exc}") from exc
+    if root.tag == _q("x:xmpmeta"):
+        return root
+    if root.tag == _q("rdf:RDF"):
+        meta = ET.Element(_q("x:xmpmeta"))
+        meta.append(root)
+        return meta
+    raise XmpError(f"not an XMP document (root element {root.tag!r})")
+
+
+def _declared_namespaces(raw: bytes) -> list[tuple[str, str]]:
+    try:
+        return [ns for _, ns in ET.iterparse(io.BytesIO(raw), events=("start-ns",))]
+    except ET.ParseError:
+        return []  # surfaced properly by ET.fromstring in _parse
+
+
+def _fresh() -> ET.Element:
+    meta = ET.Element(_q("x:xmpmeta"))
+    rdf = ET.SubElement(meta, _q("rdf:RDF"))
+    ET.SubElement(rdf, _q("rdf:Description"), {_q("rdf:about"): ""})
+    return meta
+
+
+def _descriptions(meta: ET.Element) -> list[ET.Element]:
+    rdf = meta.find(_q("rdf:RDF"))
+    if rdf is None:
+        rdf = ET.SubElement(meta, _q("rdf:RDF"))
+    descs = rdf.findall(_q("rdf:Description"))
+    if not descs:
+        descs = [ET.SubElement(rdf, _q("rdf:Description"), {_q("rdf:about"): ""})]
+    return descs
+
+
+def merge_xmp(existing: bytes | str | None, data: XmpData) -> str:
+    """Merge *data* into an existing XMP document and return the new document.
+
+    Each property set in *data* replaces that property wherever it appears
+    (element or attribute form, in any ``rdf:Description``); everything else is
+    kept. ``existing=None`` renders a fresh document.
+
+    Raises:
+        XmpError: if *existing* is not a parseable XMP document.
+    """
+    if isinstance(existing, str):
+        existing = existing.encode("utf-8")
+    meta = _parse(existing) if existing else _fresh()
+    descs = _descriptions(meta)
+    for qname, element in _properties(data):
+        tag = _q(qname)
+        for desc in descs:
+            desc.attrib.pop(tag, None)
+            for child in desc.findall(tag):
+                desc.remove(child)
+        if element is not None:
+            descs[0].append(element)
+    ET.indent(meta, space=" ")
+    return _XPACKET_BEGIN + ET.tostring(meta, encoding="unicode") + _XPACKET_END
+
+
+def render_xmp(data: XmpData) -> str:
+    """Render a fresh XMP document holding only *data* (pure; useful for tests)."""
+    return merge_xmp(None, data)
+
+
+def _prop_values(desc: ET.Element, qname: str) -> list[str] | None:
+    tag = _q(qname)
+    if tag in desc.attrib:
+        return [desc.attrib[tag]]
+    prop = desc.find(tag)
+    if prop is None:
+        return None
+    items = prop.findall(f"./*/{_q('rdf:li')}")
+    if items:
+        return [li.text or "" for li in items]
+    return [prop.text or ""]
+
+
+def _read_regions(desc: ET.Element) -> XmpRegions | None:
+    prop = desc.find(_q("mwg-rs:Regions"))
+    if prop is None:
+        return None
+
+    def field(el: ET.Element | None, qname: str) -> str | None:
+        if el is None:
+            return None
+        if _q(qname) in el.attrib:
+            return el.attrib[_q(qname)]
+        child = el.find(_q(qname))
+        return child.text if child is not None else None
+
+    dims = prop.find(_q("mwg-rs:AppliedToDimensions"))
+    regions: list[XmpRegion] = []
+    for li in prop.findall(f"./{_q('mwg-rs:RegionList')}/*/{_q('rdf:li')}"):
+        area = li.find(_q("mwg-rs:Area"))
+        try:
+            regions.append(
+                XmpRegion(
+                    x=float(field(area, "stArea:x") or 0),
+                    y=float(field(area, "stArea:y") or 0),
+                    w=float(field(area, "stArea:w") or 0),
+                    h=float(field(area, "stArea:h") or 0),
+                    name=field(li, "mwg-rs:Name"),
+                    type=field(li, "mwg-rs:Type") or "Face",
+                )
+            )
+        except ValueError:
+            continue  # a foreign region we can't represent; it is still preserved on disk
+    try:
+        return XmpRegions(
+            width=int(float(field(dims, "stDim:w") or 0)),
+            height=int(float(field(dims, "stDim:h") or 0)),
+            regions=regions,
+        )
+    except ValueError:
+        return None
+
+
+def parse_xmp(raw: bytes | str) -> XmpData:
+    """Read the suite's known properties out of an XMP document.
+
+    Raises:
+        XmpError: if *raw* is not a parseable XMP document.
+    """
+    if isinstance(raw, str):
+        raw = raw.encode("utf-8")
+    descs = _descriptions(_parse(raw))
+    found: dict[str, object] = {}
+
+    def first(qname: str) -> list[str] | None:
+        for desc in descs:
+            values = _prop_values(desc, qname)
+            if values is not None:
+                return values
+        return None
+
+    for field_name, qname in (
+        ("keywords", "dc:subject"),
+        ("hierarchical_keywords", "lr:hierarchicalSubject"),
+        ("persons", "Iptc4xmpExt:PersonInImage"),
+    ):
+        if (values := first(qname)) is not None:
+            found[field_name] = values
+    for field_name, qname in (
+        ("description", "dc:description"),
+        ("label", "xmp:Label"),
+        ("content_rating", "argus:ContentRating"),
+    ):
+        if (values := first(qname)) is not None:
+            found[field_name] = values[0] if values else ""
+    if (values := first("xmp:Rating")) and values[0].strip().lstrip("-").isdigit():
+        found["rating"] = int(values[0])
+    for desc in descs:
+        if (regions := _read_regions(desc)) is not None:
+            found["regions"] = regions
+            break
+    return XmpData.model_validate(found)
+
+
+def sidecar_path(image_path: str | os.PathLike[str]) -> Path:
+    """Return the sidecar path for an image: ``photo.jpg`` → ``photo.jpg.xmp``."""
+    path = Path(image_path)
+    return path.with_suffix(path.suffix + ".xmp")
+
+
+def read_xmp(image_path: str | os.PathLike[str]) -> XmpData | None:
+    """Read the sidecar next to *image_path*, or ``None`` if there is none.
+
+    Raises:
+        XmpError: if the sidecar exists but cannot be parsed.
+    """
+    sidecar = sidecar_path(image_path)
+    if not sidecar.exists():
+        return None
+    return parse_xmp(sidecar.read_bytes())
+
+
+def write_xmp(image_path: str | os.PathLike[str], data: XmpData, *, replace: bool = False) -> Path:
+    """Merge *data* into the sidecar next to *image_path* and return its path.
+
+    By default the existing sidecar is merged (latest write wins per property,
+    everything else preserved). ``replace=True`` discards the existing sidecar
+    and writes a document holding only *data*. The write is atomic (temp file +
+    rename), so a crash never leaves a half-written sidecar.
+
+    Raises:
+        XmpError: if merging and the existing sidecar cannot be parsed — it is
+            left untouched rather than clobbered.
+    """
+    sidecar = sidecar_path(image_path)
+    exists = sidecar.exists()
+    existing = sidecar.read_bytes() if exists and not replace else None
+    doc = merge_xmp(existing, data)
+    # mkstemp creates 0600; keep the old sidecar's mode (or a world-readable
+    # default) so other tools — e.g. an Immich container user — can still read it.
+    mode = sidecar.stat().st_mode & 0o777 if exists else 0o644
+    fd, tmp = tempfile.mkstemp(dir=sidecar.parent, prefix=f".{sidecar.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(doc)
+        os.chmod(tmp, mode)
+        os.replace(tmp, sidecar)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+    return sidecar

argus_cortex-0.3.0/tests/test_xmp.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import stat
+
+import pytest
+from pydantic import ValidationError
+
+from argus_cortex.xmp import (
+    XmpData,
+    XmpError,
+    XmpRegion,
+    XmpRegions,
+    merge_xmp,
+    parse_xmp,
+    read_xmp,
+    render_xmp,
+    sidecar_path,
+    write_xmp,
+)
+
+# A Lightroom-style sidecar: attribute-form simple properties, a foreign schema
+# (crs = Camera Raw develop settings), GPS, and two rdf:Description blocks.
+LIGHTROOM_SIDECAR = """<?xml version="1.0" encoding="UTF-8"?>
+<x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="Adobe XMP Core 7.0">
+ <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+  <rdf:Description rdf:about=""
+    xmlns:xmp="http://ns.adobe.com/xap/1.0/"
+    xmlns:exif="http://ns.adobe.com/exif/1.0/"
+    xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
+    xmp:Rating="4"
+    exif:GPSLatitude="51,30.0N"
+    crs:Exposure2012="+0.35">
+   <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <rdf:Bag><rdf:li>holiday</rdf:li></rdf:Bag>
+   </dc:subject>
+  </rdf:Description>
+  <rdf:Description rdf:about="" xmlns:xmp="http://ns.adobe.com/xap/1.0/" xmp:Label="Red"/>
+ </rdf:RDF>
+</x:xmpmeta>
+"""
+
+
+def test_render_round_trips_every_field() -> None:
+    data = XmpData(
+        keywords=["mountain", "lake & sky"],
+        description="a <scenic> view",
+        hierarchical_keywords=["places|alps"],
+        rating=3,
+        label="Green",
+        persons=["Ada"],
+        regions=XmpRegions(width=4000, height=3000, regions=[XmpRegion(x=0.5, y=0.4, w=0.1, h=0.2, name="Ada")]),
+        content_rating="safe",
+    )
+    doc = render_xmp(data)
+    assert doc.startswith("<?xpacket begin=")
+    assert doc.rstrip().endswith('<?xpacket end="w"?>')
+    assert "lake &amp; sky" in doc and "&lt;scenic&gt;" in doc
+    assert "mwg-rs:Regions" in doc and "argus:ContentRating" in doc
+    assert parse_xmp(doc) == data
+
+
+def test_illegal_xml_chars_are_stripped() -> None:
+    doc = render_xmp(XmpData(keywords=["cat\x00\x07dog"], description="line\x0bbreak"))
+    assert parse_xmp(doc) == XmpData(keywords=["catdog"], description="linebreak")
+
+
+def test_merge_preserves_foreign_properties_and_latest_wins() -> None:
+    merged = merge_xmp(LIGHTROOM_SIDECAR, XmpData(keywords=["cat"], description="a cat", rating=1))
+    # Foreign schemas and untouched properties survive, with their prefixes.
+    assert 'crs:Exposure2012="+0.35"' in merged
+    assert 'exif:GPSLatitude="51,30.0N"' in merged
+    data = parse_xmp(merged)
+    assert data.label == "Red"  # untouched, still in the second Description
+    # Conflicting keys: the latest write replaces the old value wholesale.
+    assert data.keywords == ["cat"]
+    assert data.rating == 1  # was an attribute on the first Description
+    assert merged.count("<xmp:Rating>") == 1 and 'xmp:Rating="' not in merged
+    assert data.description == "a cat"
+
+
+def test_none_leaves_property_and_empty_removes_it() -> None:
+    base = render_xmp(XmpData(keywords=["a"], description="d", persons=["Ada"]))
+    merged = parse_xmp(merge_xmp(base, XmpData(keywords=[], content_rating="explicit")))
+    assert merged.keywords is None  # [] removed it
+    assert merged.description == "d"  # None left it alone
+    assert merged.persons == ["Ada"]
+    assert merged.content_rating == "explicit"
+
+
+def test_successive_writers_merge(tmp_path) -> None:
+    """Lens then curator writing the same sidecar: neither clobbers the other."""
+    img = tmp_path / "photo.jpg"
+    write_xmp(img, XmpData(keywords=["beach"], description="a beach"))
+    write_xmp(img, XmpData(persons=["Ada"], content_rating="safe"))
+    write_xmp(img, XmpData(description="a sunny beach"))
+    data = read_xmp(img)
+    assert data == XmpData(keywords=["beach"], description="a sunny beach", persons=["Ada"], content_rating="safe")
+
+
+def test_replace_discards_existing(tmp_path) -> None:
+    img = tmp_path / "photo.jpg"
+    sidecar_path(img).write_text(LIGHTROOM_SIDECAR, encoding="utf-8")
+    write_xmp(img, XmpData(keywords=["cat"]), replace=True)
+    assert read_xmp(img) == XmpData(keywords=["cat"])
+    assert "crs:" not in sidecar_path(img).read_text(encoding="utf-8")
+
+
+def test_malformed_sidecar_is_refused_not_clobbered(tmp_path) -> None:
+    img = tmp_path / "photo.jpg"
+    sidecar = sidecar_path(img)
+    sidecar.write_text("<x:xmpmeta not xml", encoding="utf-8")
+    with pytest.raises(XmpError):
+        write_xmp(img, XmpData(keywords=["cat"]))
+    assert sidecar.read_text(encoding="utf-8") == "<x:xmpmeta not xml"
+    assert list(tmp_path.iterdir()) == [sidecar]  # no temp file left behind
+
+
+def test_dtd_is_refused() -> None:
+    evil = '<?xml version="1.0"?><!DOCTYPE x [<!ENTITY a "aaaa">]><x:xmpmeta xmlns:x="adobe:ns:meta/"/>'
+    with pytest.raises(XmpError, match="DTD"):
+        parse_xmp(evil)
+
+
+def test_non_xmp_root_is_refused() -> None:
+    with pytest.raises(XmpError, match="not an XMP document"):
+        parse_xmp("<html/>")
+
+
+def test_bare_rdf_root_is_wrapped() -> None:
+    bare = (
+        '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">'
+        '<rdf:Description xmlns:xmp="http://ns.adobe.com/xap/1.0/" xmp:Rating="2"/></rdf:RDF>'
+    )
+    merged = merge_xmp(bare, XmpData(label="Blue"))
+    assert "x:xmpmeta" in merged
+    assert parse_xmp(merged) == XmpData(rating=2, label="Blue")
+
+
+def test_write_keeps_existing_file_mode(tmp_path) -> None:
+    img = tmp_path / "photo.jpg"
+    first = write_xmp(img, XmpData(keywords=["a"]))
+    assert stat.S_IMODE(first.stat().st_mode) == 0o644
+    first.chmod(0o664)
+    write_xmp(img, XmpData(keywords=["b"]))
+    assert stat.S_IMODE(first.stat().st_mode) == 0o664
+
+
+def test_sidecar_path_and_missing_read(tmp_path) -> None:
+    assert str(sidecar_path("/pics/photo.jpg")) == "/pics/photo.jpg.xmp"
+    assert read_xmp(tmp_path / "none.jpg") is None
+
+
+def test_validation() -> None:
+    with pytest.raises(ValidationError):
+        XmpData(rating=6)
+    with pytest.raises(ValidationError):
+        XmpRegion(x=1.5, y=0, w=0, h=0)