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

argus_cortex-0.3.0/.env.example

@@ -0,0 +1,21 @@
+# Optional stateful services layer (argus_cortex.store).
+# Every value is optional: unset a URL and that feature no-ops (graceful degrade).
+# Copy to .env and fill in only the services you actually run.
+
+# Postgres — lineage DAG + human-edit capture (Phase 1).
+# Unset -> open_lineage_store() returns a no-op NullLineageStore.
+CORTEX_PG_URL=postgresql://user:pass@localhost:5432/argus
+# Connection-pool bounds (optional; defaults 0 / 8 — min 0 holds no idle conn).
+CORTEX_PG_POOL_MIN_SIZE=0
+CORTEX_PG_POOL_MAX_SIZE=8
+
+# Qdrant — image + tag-set embeddings (Phase 2).
+CORTEX_QDRANT_URL=http://localhost:6333
+
+# MinIO / S3 — owned image bytes (Phase 3). Scheme-less endpoint defaults to TLS;
+# write http:// explicitly for a plaintext endpoint. Region matters on AWS S3.
+CORTEX_S3_ENDPOINT=http://localhost:9000
+CORTEX_S3_ACCESS_KEY=
+CORTEX_S3_SECRET_KEY=
+CORTEX_S3_BUCKET=argus
+CORTEX_S3_REGION=us-east-1

{argus_cortex-0.1.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.1.0 → argus_cortex-0.3.0}/.gitignore

@@ -6,5 +6,7 @@ build/
 *.egg-info/
 .pytest_cache/
 .ruff_cache/
+# local service config for the optional stores (.env.example stays tracked)
+.env
 # hatch-vcs writes this at build time (version derived from git tags)
-src/argus_core/_version.py
+src/argus_cortex/_version.py

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.3.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: argus-cortex
+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
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: qdrant-client>=1.10; extra == 'dev'
+Requires-Dist: ruff==0.15.16; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
+Provides-Extra: 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'
+Description-Content-Type: text/markdown
+
+# argus-cortex
+
+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.
+
+## What's here
+
+- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim.
+- **`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.
+  - **Phase 3 — MinIO/S3 blob store.** Owns image bytes when cortex can't rely on the filesystem/Immich (exported/selected training images). Blobs are content-addressed on sha256 (`content_key()` == `source_asset.sha256`), so storage, dedup, and lineage join share one identity. `open_blob_store()` no-ops when `CORTEX_S3_ENDPOINT`/`CORTEX_S3_BUCKET` are unset; the `minio` client lives behind the `[s3]` extra.
+
+```python
+from argus_cortex.wire import make_versioned_base, render_schema
+from argus_cortex.backends import RemoteBackend, RemoteProvider
+
+# per-package versioned base (readable field name kept local, logic shared)
+_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="…")
+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
+
+# no-op if CORTEX_PG_URL is unset; PostgresLineageStore if it's set
+store = open_lineage_store()          # reads CORTEX_* from the environment
+store.ensure_schema()                 # idempotent bootstrap of the lineage tables
+
+# one atomic unit — the asset + caption + edit commit together or not at all
+with store.transaction():
+    asset_id = store.record_asset(SourceAsset(uri="immich://…", sha256="…"))
+    # lens emits a CaptionResult; cortex ingests it (cortex never imports lens)
+    cap_id = store.record_caption(asset_id, Caption.from_caption_result(result, profile={...}))
+    store.record_edit(cap_id, HumanEdit(edited_caption="…", editor="alice"))
+
+# the (model_caption, edited_caption) pairs the summariser feedback loop trains on
+pairs = store.caption_edit_pairs()
+```
+
+```python
+from argus_cortex.store import open_vector_store, IMAGE_COLLECTION
+
+# no-op if CORTEX_QDRANT_URL is unset; QdrantVectorStore if it's set
+vec = open_vector_store()
+vec.ensure_collection(IMAGE_COLLECTION, dim=512)   # idempotent
+
+# store an embedding you computed, tagged with its lineage id
+vec.upsert(IMAGE_COLLECTION, point_id=cap_id, vector=embedding, payload={"caption_id": cap_id})
+
+# retrieve similar past captions to steer the summariser (few-shot)
+hits = vec.search(IMAGE_COLLECTION, vector=query_embedding, top_k=5)
+similar_caption_ids = [h.payload["caption_id"] for h in hits]   # join back to Postgres
+```
+
+```python
+from argus_cortex.store import open_blob_store
+
+# no-op if CORTEX_S3_ENDPOINT / CORTEX_S3_BUCKET are unset; S3BlobStore if set
+blobs = open_blob_store()
+blobs.ensure_bucket()
+
+# content-addressed: the returned key IS the sha256 (== source_asset.sha256)
+sha = blobs.put_content_addressed(image_bytes, content_type="image/jpeg")
+data = blobs.get(sha)                    # bytes, or None if absent
+link = blobs.url(sha, expires=3600)      # presigned GET URL
+```
+
+## Install
+
+```bash
+uv pip install argus-cortex              # core (pydantic only)
+uv pip install "argus-cortex[remote]"    # + httpx for RemoteBackend
+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
+```
+
+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.
+
+## Develop
+
+```bash
+make install   # venv + editable install with the "dev" extras
+make test
+make lint
+```
+
+## CI / Release
+
+- **CI** runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow.
+- **Release** publishes to PyPI (OIDC trusted publishing) on `v*` tags. No container image — this is a library.
+- Versioning is derived from git tags via `hatch-vcs` — tag `vX.Y.Z` to cut a release.
+
+This repo was scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template).
+Run `copier update` to pull template changes (CI, release, tooling).

argus_cortex-0.3.0/README.md

@@ -0,0 +1,121 @@
+# argus-cortex
+
+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.
+
+## What's here
+
+- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim.
+- **`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.
+  - **Phase 3 — MinIO/S3 blob store.** Owns image bytes when cortex can't rely on the filesystem/Immich (exported/selected training images). Blobs are content-addressed on sha256 (`content_key()` == `source_asset.sha256`), so storage, dedup, and lineage join share one identity. `open_blob_store()` no-ops when `CORTEX_S3_ENDPOINT`/`CORTEX_S3_BUCKET` are unset; the `minio` client lives behind the `[s3]` extra.
+
+```python
+from argus_cortex.wire import make_versioned_base, render_schema
+from argus_cortex.backends import RemoteBackend, RemoteProvider
+
+# per-package versioned base (readable field name kept local, logic shared)
+_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="…")
+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
+
+# no-op if CORTEX_PG_URL is unset; PostgresLineageStore if it's set
+store = open_lineage_store()          # reads CORTEX_* from the environment
+store.ensure_schema()                 # idempotent bootstrap of the lineage tables
+
+# one atomic unit — the asset + caption + edit commit together or not at all
+with store.transaction():
+    asset_id = store.record_asset(SourceAsset(uri="immich://…", sha256="…"))
+    # lens emits a CaptionResult; cortex ingests it (cortex never imports lens)
+    cap_id = store.record_caption(asset_id, Caption.from_caption_result(result, profile={...}))
+    store.record_edit(cap_id, HumanEdit(edited_caption="…", editor="alice"))
+
+# the (model_caption, edited_caption) pairs the summariser feedback loop trains on
+pairs = store.caption_edit_pairs()
+```
+
+```python
+from argus_cortex.store import open_vector_store, IMAGE_COLLECTION
+
+# no-op if CORTEX_QDRANT_URL is unset; QdrantVectorStore if it's set
+vec = open_vector_store()
+vec.ensure_collection(IMAGE_COLLECTION, dim=512)   # idempotent
+
+# store an embedding you computed, tagged with its lineage id
+vec.upsert(IMAGE_COLLECTION, point_id=cap_id, vector=embedding, payload={"caption_id": cap_id})
+
+# retrieve similar past captions to steer the summariser (few-shot)
+hits = vec.search(IMAGE_COLLECTION, vector=query_embedding, top_k=5)
+similar_caption_ids = [h.payload["caption_id"] for h in hits]   # join back to Postgres
+```
+
+```python
+from argus_cortex.store import open_blob_store
+
+# no-op if CORTEX_S3_ENDPOINT / CORTEX_S3_BUCKET are unset; S3BlobStore if set
+blobs = open_blob_store()
+blobs.ensure_bucket()
+
+# content-addressed: the returned key IS the sha256 (== source_asset.sha256)
+sha = blobs.put_content_addressed(image_bytes, content_type="image/jpeg")
+data = blobs.get(sha)                    # bytes, or None if absent
+link = blobs.url(sha, expires=3600)      # presigned GET URL
+```
+
+## Install
+
+```bash
+uv pip install argus-cortex              # core (pydantic only)
+uv pip install "argus-cortex[remote]"    # + httpx for RemoteBackend
+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
+```
+
+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.
+
+## Develop
+
+```bash
+make install   # venv + editable install with the "dev" extras
+make test
+make lint
+```
+
+## CI / Release
+
+- **CI** runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow.
+- **Release** publishes to PyPI (OIDC trusted publishing) on `v*` tags. No container image — this is a library.
+- Versioning is derived from git tags via `hatch-vcs` — tag `vX.Y.Z` to cut a release.
+
+This repo was scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template).
+Run `copier update` to pull template changes (CI, release, tooling).

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

@@ -24,8 +24,29 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-remote = ["httpx>=0.27"]
-dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff==0.15.16"]
+remote = ["httpx>=0.27", "certifi>=2026.10.19"]
+postgres = ["psycopg[binary,pool]>=3.1"]
+qdrant = ["qdrant-client>=1.10", "certifi>=2026.10.19"]
+s3 = ["minio>=7.2", "certifi>=2026.10.19"]
+# The shared ASGI write-guard + env-flag scaffolding for the suite's servers
+# (argus_cortex.server). Starlette ships with FastAPI, so consumers already have
+# it via their own [server] extra.
+server = ["starlette>=0.37"]
+# The store drivers are in dev so each store's real client path (pool/enum/client
+# construction, error wrapping) is exercised in CI, not just via fakes.
+# starlette + httpx power the pure-ASGI guard tests (Starlette TestClient).
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff==0.15.16",
+    "psycopg[binary,pool]>=3.1",
+    "qdrant-client>=1.10",
+    "minio>=7.2",
+    "starlette>=0.37",
+    "httpx>=0.27",
+    "httpx2>=2.7",
+    "certifi>=2026.10.19",
+]
 
 [project.urls]
 Repository = "https://github.com/smk762/argus-cortex"

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

@@ -23,6 +23,30 @@ from argus_cortex.backends import (
     resolve_device,
     with_retries,
 )
+from argus_cortex.store import (
+    IMAGE_COLLECTION,
+    TAGSET_COLLECTION,
+    BlobStore,
+    Caption,
+    HumanEdit,
+    LineageStore,
+    NullBlobStore,
+    NullLineageStore,
+    NullVectorStore,
+    PostgresLineageStore,
+    QdrantVectorStore,
+    S3BlobStore,
+    SourceAsset,
+    StoreConfig,
+    StoreError,
+    TrainingRun,
+    VectorHit,
+    VectorStore,
+    content_key,
+    open_blob_store,
+    open_lineage_store,
+    open_vector_store,
+)
 from argus_cortex.taxonomy import TargetCategory, TargetProfile, TargetStyle
 from argus_cortex.wire import (
     VersionError,
@@ -32,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__",
@@ -46,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",
@@ -55,4 +102,27 @@ __all__ = [
     "RemoteProvider",
     "resolve_device",
     "with_retries",
+    # store (optional stateful services layer)
+    "StoreConfig",
+    "StoreError",
+    "LineageStore",
+    "NullLineageStore",
+    "PostgresLineageStore",
+    "open_lineage_store",
+    "Caption",
+    "HumanEdit",
+    "SourceAsset",
+    "TrainingRun",
+    "VectorStore",
+    "NullVectorStore",
+    "QdrantVectorStore",
+    "VectorHit",
+    "open_vector_store",
+    "IMAGE_COLLECTION",
+    "TAGSET_COLLECTION",
+    "BlobStore",
+    "NullBlobStore",
+    "S3BlobStore",
+    "open_blob_store",
+    "content_key",
 ]

{argus_cortex-0.1.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.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None