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

argus_cortex-0.2.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.2.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.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: argus-cortex
+Version: 0.2.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: 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: qdrant-client>=1.10; extra == 'qdrant'
+Provides-Extra: remote
+Requires-Dist: httpx>=0.27; extra == 'remote'
+Provides-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.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.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.2.0/README.md

@@ -0,0 +1,104 @@
+# 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.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.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.2.0}/pyproject.toml

@@ -25,7 +25,26 @@ dependencies = [
 
 [project.optional-dependencies]
 remote = ["httpx>=0.27"]
-dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff==0.15.16"]
+postgres = ["psycopg[binary,pool]>=3.1"]
+qdrant = ["qdrant-client>=1.10"]
+s3 = ["minio>=7.2"]
+# 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",
+]
 
 [project.urls]
 Repository = "https://github.com/smk762/argus-cortex"

{argus_cortex-0.1.0 → argus_cortex-0.2.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,
@@ -55,4 +79,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.2.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.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

argus_cortex-0.2.0/src/argus_cortex/server.py

@@ -0,0 +1,155 @@
+"""Shared ASGI write-guard + env-flag scaffolding for the suite's micro-servers.
+
+Every Argus micro-server (proof, curator, forge, lens) is a small FastAPI app
+that must fence off state-changing requests in some deployment mode:
+
+* **read-only / replay** (argus-proof #45) — a GPU-less public demo keeps serving
+  stored reports but refuses every write and every live-eval trigger.
+* **cross-site protection** (argus-curator #3) — CORS is not a write boundary, so
+  unsafe methods carrying an untrusted ``Origin`` are refused before the routes.
+
+Both are the same shape: gate the *unsafe* HTTP methods, refuse with a ``403``
+JSON ``{"detail": ...}``, let reads through. :class:`WriteGuard` is that one
+gate, parameterised by a *refuse* predicate; :func:`constant_refuse` and
+:func:`cross_site_refuse` are the two predicates the suite needs today.
+
+The guard is deliberately **pure ASGI**, not Starlette's ``BaseHTTPMiddleware``:
+``BaseHTTPMiddleware`` runs the response through an anyio memory stream, which
+buffers the SSE / NDJSON streams these servers return and adds a hop to every
+read on a read-heavy demo host. A pure-ASGI guard forwards the untouched ``send``
+channel, so streaming endpoints stream and reads pay nothing.
+
+Starlette ships with FastAPI, so this module lives behind the ``argus-cortex``
+``[server]`` extra and is never imported at ``import argus_cortex`` time.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable, Iterable
+
+try:
+    from starlette.datastructures import Headers
+    from starlette.responses import JSONResponse
+    from starlette.types import ASGIApp, Receive, Scope, Send
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("argus_cortex.server requires Starlette: pip install argus-cortex[server]") from exc
+
+__all__ = [
+    "FALSY",
+    "TRUTHY",
+    "UNSAFE_METHODS",
+    "Refuse",
+    "WriteGuard",
+    "constant_refuse",
+    "cross_site_refuse",
+    "env_flag",
+]
+
+# HTTP methods that change server state (or trigger compute). Idempotent reads
+# (GET/HEAD/OPTIONS) are never gated — they stay CORS's business.
+UNSAFE_METHODS: frozenset[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+# Recognised env-flag spellings. A *set* value in neither set is a
+# misconfiguration (a typo like ``...=enabled``), surfaced by :func:`env_flag`.
+TRUTHY: frozenset[str] = frozenset({"1", "true", "yes", "on"})
+FALSY: frozenset[str] = frozenset({"0", "false", "no", "off", ""})
+
+_log = logging.getLogger(__name__)
+
+
+def env_flag(name: str) -> bool:
+    """Whether env var *name* is set to a truthy string (``1``/``true``/``yes``/``on``).
+
+    A set-but-unrecognised value (a typo like ``ARGUS_PROOF_READ_ONLY=enabled``)
+    logs a warning and is treated as **off**, so a mistyped protection flag is
+    visible in the logs rather than silently leaving the guard disabled.
+    """
+    raw = os.environ.get(name, "").strip().lower()
+    if raw in TRUTHY:
+        return True
+    if raw not in FALSY:
+        _log.warning("env flag %s set to an unrecognised value %r; treating as off", name, raw)
+    return False
+
+
+# A refusal predicate: given the scope + headers of an *unsafe* request, return a
+# ``403`` detail message to refuse it, or ``None`` to let it through.
+Refuse = Callable[[Scope, Headers], "str | None"]
+
+
+class WriteGuard:
+    """Pure-ASGI gate on state-changing HTTP methods.
+
+    For every request whose method is in :data:`UNSAFE_METHODS`, consult
+    ``refuse(scope, headers)``: a returned string becomes a ``403`` JSON
+    ``{"detail": ...}`` and the wrapped app is never called; ``None`` lets the
+    request through. Reads (and every non-``http`` scope) are forwarded untouched.
+
+    Register it *before* ``CORSMiddleware`` (``add_middleware`` inserts at the top
+    of the stack, so the last added is outermost) — that keeps CORS the outer
+    layer and lets it still annotate a refused cross-origin write with its
+    headers, so the caller sees a readable ``403`` rather than an opaque CORS
+    error.
+    """
+
+    def __init__(self, app: ASGIApp, refuse: Refuse) -> None:
+        self.app = app
+        self.refuse = refuse
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http" and scope["method"] in UNSAFE_METHODS:
+            detail = self.refuse(scope, Headers(scope=scope))
+            if detail is not None:
+                await JSONResponse({"detail": detail}, status_code=403)(scope, receive, send)
+                return
+        await self.app(scope, receive, send)
+
+
+def constant_refuse(message: str) -> Refuse:
+    """A :class:`WriteGuard` predicate refusing *every* unsafe request with the
+    same *message* — read-only / replay mode, where no write is ever allowed.
+
+    Method-based, so it covers every write route — current and future — without
+    per-route guards to forget.
+    """
+
+    def _refuse(scope: Scope, headers: Headers) -> str | None:
+        return message
+
+    return _refuse
+
+
+def cross_site_refuse(trusted_origins: Iterable[str]) -> Refuse:
+    """A :class:`WriteGuard` predicate refusing untrusted cross-origin writes.
+
+    CORS is not a write boundary: a ``multipart/form-data`` POST is a
+    CORS-safelisted content type, so a browser sends it with **no preflight** and
+    any page the user visits can drive it — the same-origin policy only stops
+    that page from *reading* the reply. For an unauthenticated server commonly
+    bound on localhost or a LAN address the attacker's own server cannot reach,
+    that is enough to poison data (or move files about). So unsafe methods are
+    gated on ``Origin``:
+
+    * absent -> allowed. Non-browser clients (curl, the CLI, server-to-server)
+      never send it, and browsers always do for cross-origin state changes.
+    * same host:port as the request -> allowed, so a UI proxied onto this host
+      keeps working un-allow-listed. Compared host:port (not full origin) because
+      behind a TLS-terminating proxy the app sees ``http://`` while the browser
+      reports ``https://`` — same host either way.
+    * in *trusted_origins* -> allowed. That is the operator's own allow-list.
+    * anything else -> refused.
+    """
+    trusted = set(trusted_origins)
+
+    def _refuse(scope: Scope, headers: Headers) -> str | None:
+        origin = headers.get("origin")
+        if origin is None or origin in trusted:
+            return None
+        host = headers.get("host")
+        if host and origin.partition("://")[2] == host:
+            return None
+        return f"cross-site {scope['method']} from origin {origin} is not allowed"
+
+    return _refuse

argus_cortex-0.2.0/src/argus_cortex/store/__init__.py

@@ -0,0 +1,72 @@
+"""Optional stateful services layer — the suite's persistent "memory".
+
+External and opt-in: each store is addressed by a ``CORTEX_*`` URL in the
+environment and no-ops when unset (see :class:`~argus_cortex.store.config.StoreConfig`).
+Phase 1 ships the Postgres lineage store, phase 2 the Qdrant vector store, and
+phase 3 the MinIO/S3 blob store.
+
+The dependency direction is ``cortex → lens``: cortex defines the lineage
+entities in :mod:`~argus_cortex.store.models` and the embedding model is the
+caller's concern, so lens never imports cortex and stays DB-free.
+"""
+
+from __future__ import annotations
+
+from argus_cortex.store.blob import (
+    BlobStore,
+    NullBlobStore,
+    S3BlobStore,
+    content_key,
+    open_blob_store,
+)
+from argus_cortex.store.config import StoreConfig
+from argus_cortex.store.errors import StoreError
+from argus_cortex.store.lineage import (
+    LineageStore,
+    NullLineageStore,
+    PostgresLineageStore,
+    open_lineage_store,
+)
+from argus_cortex.store.models import (
+    Caption,
+    HumanEdit,
+    SourceAsset,
+    TrainingRun,
+)
+from argus_cortex.store.vector import (
+    IMAGE_COLLECTION,
+    TAGSET_COLLECTION,
+    NullVectorStore,
+    QdrantVectorStore,
+    VectorHit,
+    VectorStore,
+    open_vector_store,
+)
+
+__all__ = [
+    "StoreConfig",
+    "StoreError",
+    # lineage (phase 1: Postgres)
+    "LineageStore",
+    "NullLineageStore",
+    "PostgresLineageStore",
+    "open_lineage_store",
+    "Caption",
+    "HumanEdit",
+    "SourceAsset",
+    "TrainingRun",
+    # vector (phase 2: Qdrant)
+    "VectorStore",
+    "NullVectorStore",
+    "QdrantVectorStore",
+    "VectorHit",
+    "open_vector_store",
+    "IMAGE_COLLECTION",
+    "TAGSET_COLLECTION",
+    # blob (phase 3: MinIO/S3)
+    "BlobStore",
+    "NullBlobStore",
+    "S3BlobStore",
+    "open_blob_store",
+    "content_key",
+]