argus-cortex 0.1.0__tar.gz

argus_cortex-0.1.0/.copier-answers.yml

@@ -0,0 +1,20 @@
+# Managed by Copier — do not edit by hand.
+# Run `copier update` in this repo to pull template changes.
+_commit: be61abb
+_src_path: /home/smk/argus-pkg-template
+author: smk762
+description: 'Shared foundation for the Argus suite: taxonomy, versioned wire-schema
+    tooling, and the local/remote AI backend contract'
+dockerfile: Dockerfile
+github_owner: smk762
+has_cli: false
+has_server: false
+image_name: argus-cortex
+package_name: argus_cortex
+post_test: ''
+project_name: argus-cortex
+python_min: '3.11'
+ruff_pin: 0.15.16
+test_extras: dev
+version_build_arg: false
+

argus_cortex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    uses: smk762/argus-ci/.github/workflows/python-ci.yml@v1
+    with:
+      ruff-version: "0.15.16"
+      test-extras: "dev"
+

argus_cortex-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release to PyPI
+
+# Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
+# a reusable workflow. Keep this file in sync across the suite via `copier update`.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-install:
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install wheel and smoke-test import
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install dist/*.whl
+          uv run --no-sync python -c "import argus_cortex; print(f'argus-cortex {argus_cortex.__version__} OK')"
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: test-install
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: publish-testpypi
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

argus_cortex-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# hatch-vcs writes this at build time (version derived from git tags)
+src/argus_core/_version.py

argus_cortex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smk762
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argus_cortex-0.1.0/Makefile

@@ -0,0 +1,27 @@
+UV ?= uv
+
+.PHONY: help install lint format test build clean
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Create venv and install with test extras
+	$(UV) venv
+	$(UV) pip install -e ".[dev]"
+
+lint:  ## Ruff check + format check
+	$(UV)x ruff@0.15.16 check src/ tests/
+	$(UV)x ruff@0.15.16 format --check src/ tests/
+
+format:  ## Ruff autoformat + autofix
+	$(UV)x ruff@0.15.16 format src/ tests/
+	$(UV)x ruff@0.15.16 check --fix src/ tests/
+
+test:  ## Run the test suite
+	$(UV) run --no-sync pytest --tb=short -q
+
+build:  ## Build sdist + wheel
+	$(UV) build
+
+clean:  ## Remove build + cache artifacts
+	rm -rf dist build .venv *.egg-info .pytest_cache .ruff_cache src/argus_cortex/_version.py

argus_cortex-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: argus-cortex
+Version: 0.1.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: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.16; extra == 'dev'
+Provides-Extra: remote
+Requires-Dist: httpx>=0.27; extra == 'remote'
+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.
+
+```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="…")
+```
+
+## Install
+
+```bash
+uv pip install argus-cortex            # core (pydantic only)
+uv pip install "argus-cortex[remote]"  # + httpx for RemoteBackend
+```
+
+## 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/README.md

@@ -0,0 +1,47 @@
+# 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.
+
+```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="…")
+```
+
+## Install
+
+```bash
+uv pip install argus-cortex            # core (pydantic only)
+uv pip install "argus-cortex[remote]"  # + httpx for RemoteBackend
+```
+
+## 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/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argus-cortex"
+dynamic = ["version"]
+description = "Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "smk762" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+remote = ["httpx>=0.27"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff==0.15.16"]
+
+[project.urls]
+Repository = "https://github.com/smk762/argus-cortex"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/argus_cortex/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argus_cortex"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+extend-exclude = ["src/argus_cortex/_version.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501", "B008"]

argus_cortex-0.1.0/src/argus_cortex/__init__.py

@@ -0,0 +1,58 @@
+"""argus-cortex — Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract"""
+
+from __future__ import annotations
+
+try:
+    # Written by hatch-vcs at build time (see pyproject [tool.hatch.build.hooks.vcs]).
+    from argus_cortex._version import __version__
+except ImportError:  # running from a source checkout that hasn't been built
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("argus-cortex")
+    except PackageNotFoundError:
+        __version__ = "0.0.0+unknown"
+
+from argus_cortex.backends import (
+    Backend,
+    BackendError,
+    BackendKind,
+    LocalBackend,
+    RemoteBackend,
+    RemoteProvider,
+    resolve_device,
+    with_retries,
+)
+from argus_cortex.taxonomy import TargetCategory, TargetProfile, TargetStyle
+from argus_cortex.wire import (
+    VersionError,
+    check_version,
+    make_versioned_base,
+    render_schema,
+    schema_major,
+    wire_schema,
+)
+
+__all__ = [
+    "__version__",
+    # taxonomy
+    "TargetProfile",
+    "TargetCategory",
+    "TargetStyle",
+    # wire
+    "VersionError",
+    "check_version",
+    "make_versioned_base",
+    "render_schema",
+    "schema_major",
+    "wire_schema",
+    # backends
+    "Backend",
+    "BackendError",
+    "BackendKind",
+    "LocalBackend",
+    "RemoteBackend",
+    "RemoteProvider",
+    "resolve_device",
+    "with_retries",
+]

argus_cortex-0.1.0/src/argus_cortex/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+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)
+
+__commit_id__ = commit_id = None

argus_cortex-0.1.0/src/argus_cortex/backends.py

@@ -0,0 +1,286 @@
+"""The local / remote AI-backend contract, shared across the suite.
+
+Generalised from argus-lens's captioner backends (``CaptionBackend`` →
+``LocalBackend`` / ``CloudBackend``) so every stage that calls a model — lens
+captioning, proof scoring — shares one lifecycle, one retry policy, and one way
+to point at a **hosted service by IP/port** instead of loading weights locally.
+
+* :class:`Backend` — lifecycle + capability attributes (``load`` / ``unload`` /
+  ``is_available``); the domain call (caption an image, score an image) is added
+  by the subclass.
+* :class:`LocalBackend` — runs inference in-process on a resolved device.
+* :class:`RemoteBackend` — calls a hosted HTTP endpoint (``base_url`` or
+  ``host``/``port``, or a known :class:`RemoteProvider`); httpx lives behind the
+  ``argus-cortex[remote]`` extra and is imported lazily.
+
+Concrete, domain-specific adapters (a CLIP scorer, an OpenAI captioner) subclass
+these in the consuming package; this module stays domain-agnostic.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from enum import StrEnum
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+class BackendError(RuntimeError):
+    """A backend failure: model unavailable, remote endpoint unreachable."""
+
+
+class BackendKind(StrEnum):
+    """Where a backend runs — locally in-process, or a remote hosted service."""
+
+    LOCAL = "local"
+    REMOTE = "remote"
+
+
+def with_retries(
+    fn: Callable[[], T],
+    *,
+    attempts: int = 3,
+    base_delay: float = 0.5,
+    max_delay: float = 8.0,
+    retry_on: tuple[type[BaseException], ...] = (Exception,),
+    sleep: Callable[[float], None] = time.sleep,
+) -> T:
+    """Call *fn*, retrying on *retry_on* with exponential backoff.
+
+    Re-raises the last error after *attempts* tries. ``sleep`` is injectable so
+    tests exercise the backoff without wall-clock delay. Narrow ``retry_on`` to
+    the transient failures you actually want retried — the default of
+    ``Exception`` also retries deterministic programming errors.
+    """
+    if attempts < 1:
+        raise ValueError(f"attempts must be >= 1, got {attempts}")
+    last: BaseException | None = None
+    for attempt in range(attempts):
+        try:
+            return fn()
+        except retry_on as exc:
+            last = exc
+            if attempt == attempts - 1:
+                break
+            sleep(min(max_delay, base_delay * (2**attempt)))
+    raise last  # type: ignore[misc]  # attempts >= 1, so a caught error was assigned
+
+
+def resolve_device(device: str = "auto") -> str:
+    """Resolve ``"auto"`` to ``"cuda"``/``"mps"``/``"cpu"`` (or pass a fixed device through).
+
+    Uses torch only if it's importable; with no torch present, ``"auto"`` becomes
+    ``"cpu"`` so a device-free environment still works.
+    """
+    if device and device != "auto":
+        return device
+    try:
+        import torch
+    except ImportError:
+        return "cpu"  # no torch -> cpu; a real GPU-detection error below must surface
+    if torch.cuda.is_available():
+        return "cuda"
+    mps = getattr(torch.backends, "mps", None)
+    if mps is not None and mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+class Backend:
+    """Base for any model-backed backend: lifecycle + capability descriptor.
+
+    Subclasses set the class attributes and add the domain call. ``load`` /
+    ``unload`` default to no-ops so a trivial backend need not override them;
+    ``is_available`` / ``availability_reason`` let a registry skip a backend that
+    can't run right now (missing weights, unset API key) with a clear reason.
+    """
+
+    name: str = "base"
+    kind: BackendKind = BackendKind.LOCAL
+    requires_gpu: bool = False
+
+    def load(self, device: str = "auto") -> None:
+        """Load weights / init the client. Called lazily on first use."""
+
+    def unload(self) -> None:
+        """Release resources (GPU memory, HTTP connections)."""
+
+    def is_available(self) -> bool:
+        """Whether this backend can be used right now."""
+        return True
+
+    def availability_reason(self) -> str | None:
+        """Human-readable reason this backend is unavailable, or ``None``."""
+        return None
+
+
+class LocalBackend(Backend):
+    """Base for backends that run inference in-process on a device.
+
+    The target device is supplied once via :meth:`load` and remembered, so the
+    domain call stays device-free. Subclasses read ``self.device``.
+    """
+
+    kind = BackendKind.LOCAL
+    requires_gpu = True
+
+    def __init__(self) -> None:
+        self.device: str | None = None
+
+    def load(self, device: str = "auto") -> None:
+        self.device = resolve_device(device)
+
+
+class RemoteProvider(StrEnum):
+    """Known hosted inference providers (base URLs in :data:`REMOTE_PROVIDER_URLS`)."""
+
+    HF_INFERENCE = "hf_inference"
+    NVIDIA_NIM = "nvidia_nim"
+    OPENAI_COMPAT = "openai_compat"
+    REPLICATE = "replicate"
+
+
+# Default base URLs per provider. OPENAI_COMPAT has none — a local/self-hosted
+# OpenAI-compatible server is addressed by an explicit base_url / host+port.
+REMOTE_PROVIDER_URLS: dict[RemoteProvider, str | None] = {
+    RemoteProvider.HF_INFERENCE: "https://api-inference.huggingface.co",
+    RemoteProvider.NVIDIA_NIM: "https://integrate.api.nvidia.com/v1",
+    RemoteProvider.OPENAI_COMPAT: None,
+    RemoteProvider.REPLICATE: "https://api.replicate.com/v1",
+}
+
+
+class RemoteBackend(Backend):
+    """Base for backends that call a hosted HTTP endpoint.
+
+    Point it at a service by ``base_url``, by ``host``/``port`` via
+    :meth:`from_host`, or at a known provider via :meth:`from_provider`. An
+    ``api_key`` becomes a bearer ``Authorization`` header unless one is already
+    supplied. httpx is imported lazily (``argus-cortex[remote]``); an injected
+    ``_http`` client (tests) bypasses the import.
+    """
+
+    kind = BackendKind.REMOTE
+    requires_gpu = False
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        provider: RemoteProvider | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/") if base_url else None
+        self.api_key = api_key
+        self.timeout = timeout
+        self.provider = provider
+        self.headers = dict(headers or {})
+        if api_key and not any(k.lower() == "authorization" for k in self.headers):
+            self.headers["Authorization"] = f"Bearer {api_key}"
+        self._http = None  # lazily-created httpx.Client (or an injected fake)
+
+    @classmethod
+    def from_host(cls, host: str, port: int, *, scheme: str = "http", **kwargs: object) -> RemoteBackend:
+        """Address a service by host + port, e.g. a self-hosted model server."""
+        return cls(f"{scheme}://{host}:{port}", **kwargs)  # type: ignore[arg-type]
+
+    @classmethod
+    def from_provider(cls, provider: RemoteProvider | str, **kwargs: object) -> RemoteBackend:
+        """Address a known hosted provider by its default base URL.
+
+        This wires up only the URL (and auth) — it does NOT adapt to a provider's
+        request/response protocol. Replicate's poll-based predictions, an
+        OpenAI-compatible ``/chat/completions`` shape, etc. are the concrete
+        subclass's job; the plain :meth:`post_json` / :meth:`get_json` here assume
+        a single synchronous JSON round-trip.
+        """
+        provider = RemoteProvider(provider)
+        base = REMOTE_PROVIDER_URLS[provider]
+        if base is None and "base_url" not in kwargs:
+            raise BackendError(f"provider {provider.value} needs an explicit base_url (host+port of your server)")
+        return cls(kwargs.pop("base_url", base), provider=provider, **kwargs)  # type: ignore[arg-type]
+
+    def is_available(self) -> bool:
+        return bool(self.base_url)
+
+    def availability_reason(self) -> str | None:
+        return None if self.base_url else "no base_url configured (set base_url or host/port)"
+
+    def _client(self):  # noqa: ANN202  (httpx is optional; avoid importing at module load)
+        if self._http is None:
+            try:
+                import httpx
+            except ImportError as exc:  # pragma: no cover - exercised only without the extra
+                raise BackendError("remote backends need: pip install argus-cortex[remote]") from exc
+            if not self.base_url:
+                raise BackendError("remote backend has no base_url")
+            self._http = httpx.Client(base_url=self.base_url, timeout=self.timeout, headers=self.headers)
+        return self._http
+
+    @staticmethod
+    def _transient_errors() -> tuple[type[BaseException], ...]:
+        """Errors worth retrying: network/timeout blips, NOT 4xx/5xx responses.
+
+        ``httpx.TransportError`` covers connect/read/write/pool timeouts and
+        connection failures. A ``raise_for_status()`` 4xx/5xx (``HTTPStatusError``)
+        is deliberately excluded — a 401/404 never succeeds on retry, and a POST
+        that reached the server must not be blindly re-sent.
+        """
+        try:
+            import httpx
+
+            return (httpx.TransportError,)
+        except ImportError:  # pragma: no cover
+            return (OSError,)
+
+    @staticmethod
+    def _wrap_errors() -> tuple[type[BaseException], ...]:
+        """Exception types to wrap as :class:`BackendError` (bad status, bad JSON)."""
+        try:
+            import httpx
+
+            return (httpx.HTTPError, ValueError)
+        except ImportError:  # pragma: no cover
+            return (ValueError, OSError)
+
+    def _send(self, call: Callable[[], dict], *, label: str, attempts: int) -> dict:
+        """Retry *call* on transient failures; wrap any failure in BackendError.
+
+        So callers catch one error type whether the endpoint was unreachable,
+        returned a bad status, or sent a non-JSON body.
+        """
+        try:
+            return with_retries(call, attempts=attempts, retry_on=self._transient_errors())
+        except self._wrap_errors() as exc:
+            raise BackendError(f"{label} failed: {exc}") from exc
+
+    def post_json(self, path: str, payload: dict, *, attempts: int = 3) -> dict:
+        """POST JSON and return the JSON response; retries transient failures only."""
+        client = self._client()
+
+        def call() -> dict:
+            resp = client.post(path, json=payload)
+            resp.raise_for_status()
+            return resp.json()
+
+        return self._send(call, label=f"POST {path}", attempts=attempts)
+
+    def get_json(self, path: str, *, attempts: int = 3) -> dict:
+        """GET and return the JSON response; retries transient failures only."""
+        client = self._client()
+
+        def call() -> dict:
+            resp = client.get(path)
+            resp.raise_for_status()
+            return resp.json()
+
+        return self._send(call, label=f"GET {path}", attempts=attempts)
+
+    def unload(self) -> None:
+        if self._http is not None:
+            self._http.close()
+            self._http = None

argus_cortex-0.1.0/src/argus_cortex/py.typed

@@ -0,0 +1 @@
+

argus_cortex-0.1.0/src/argus_cortex/taxonomy.py

@@ -0,0 +1,41 @@
+"""The shared target taxonomy — what a dataset is curated *for*.
+
+This is the "moat" the whole Argus suite pivots on: the curator scores and
+labels exports against it, the captioner picks caption variants from it, the
+forge renders trainer configs for it, and proof evaluates a LoRA against it. It
+lived, copied verbatim, in argus-curator and argus-forge (whose comment noted it
+should "eventually hoist into a shared argus-cortex package") — this is that hoist.
+
+Keep this module dependency-light (pydantic only) and change it deliberately: a
+change here ripples through every stage of the suite.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+TargetStyle = Literal["photo", "anime"]
+
+# What the dataset is curated for. Note this is distinct from argus-lens's
+# caption *buckets* (identity/action/pose_composition/wardrobe/lighting/setting):
+# those describe caption fragments, this describes the training objective.
+TargetCategory = Literal["identity", "wardrobe", "pose_composition", "setting"]
+
+TARGET_STYLES: tuple[TargetStyle, ...] = ("photo", "anime")
+TARGET_CATEGORIES: tuple[TargetCategory, ...] = ("identity", "wardrobe", "pose_composition", "setting")
+
+
+class TargetProfile(BaseModel):
+    """What a dataset was curated for — shared verbatim across the suite.
+
+    Inherited unchanged from stage to stage (curator → lens → forge → proof) so
+    a decision made once at curation time is honoured everywhere downstream; no
+    stage remaps the taxonomy.
+    """
+
+    target_style: TargetStyle = "photo"
+    target_backend: str | None = "sdxl"
+    checkpoint: str | None = None
+    target_category: TargetCategory = "identity"

argus_cortex-0.1.0/src/argus_cortex/wire.py

@@ -0,0 +1,107 @@
+"""Versioned wire-schema tooling shared across the suite.
+
+Every Argus service defines a wire contract (Pydantic models exchanged over
+HTTP/CLI and codegen'd against by argus-studio) and stamps it with a version so
+a consumer can refuse an incompatible major instead of misreading it — the
+``MANIFEST_VERSION`` / ``PROOF_VERSION`` discipline. That machinery was
+re-implemented per repo; this module is the single copy.
+
+A package supplies its own version constant and field name (``proof_version``,
+``manifest_version`` — kept per-package for readable payloads) and gets:
+
+* :func:`check_version` — the major-compatibility gate;
+* :func:`make_versioned_base` — a Pydantic base that stamps + checks the field;
+* :func:`render_schema` — the canonical committed-schema string, so the
+  ``schema`` / ``schema --check`` CLI is identical everywhere.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, model_validator
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+
+class VersionError(RuntimeError):
+    """A wire payload's version is incompatible with this build."""
+
+
+def schema_major(version: str) -> str:
+    """The major component of a version string (``'2.7' -> '2'``)."""
+    return version.split(".", 1)[0]
+
+
+def check_version(
+    version: str,
+    supported_majors: Sequence[str],
+    *,
+    label: str = "wire schema",
+    error: type[Exception] = VersionError,
+) -> None:
+    """Raise if *version*'s major is not supported.
+
+    The single gate every deserialization path runs through, so an incompatible
+    payload is refused with a clear, consistent message across the suite. Pass
+    ``error`` to raise a package's own exception type (e.g. ``ProofError``) so
+    version failures fold into that package's error hierarchy.
+    """
+    if schema_major(version) not in tuple(supported_majors):
+        understood = ", ".join(f"{m}.x" for m in supported_majors)
+        raise error(f"{label} {version} is not supported (this build understands {understood}) — upgrade or regenerate")
+
+
+def make_versioned_base(
+    field_name: str,
+    current: str,
+    supported_majors: Sequence[str],
+    *,
+    label: str | None = None,
+    class_name: str = "VersionedBase",
+    error: type[Exception] = VersionError,
+) -> type[BaseModel]:
+    """Build a Pydantic base that stamps and version-checks *field_name*.
+
+    Subclasses of the returned base carry ``field_name`` (defaulting to
+    *current*) and, on construction or ``model_validate``, refuse a payload
+    whose major is not in *supported_majors*. Keeping the field name a parameter
+    lets each package keep its readable name (``proof_version``, …) while sharing
+    the logic; ``error`` selects the exception type raised on a mismatch.
+    """
+    majors = tuple(supported_majors)
+    lbl = label or field_name
+
+    def _check_wire_version(self: BaseModel) -> BaseModel:
+        check_version(getattr(self, field_name), majors, label=lbl, error=error)
+        return self
+
+    namespace = {
+        "__annotations__": {field_name: str},
+        field_name: current,
+        "_check_wire_version": model_validator(mode="after")(_check_wire_version),
+    }
+    return type(class_name, (BaseModel,), namespace)
+
+
+def wire_schema(models: Iterable[type[BaseModel]], *, title: str) -> dict:
+    """Combined JSON Schema for *models* (serialization view, ``$defs`` refs)."""
+    from pydantic.json_schema import models_json_schema
+
+    _, schema = models_json_schema(
+        [(m, "serialization") for m in models],
+        title=title,
+        ref_template="#/$defs/{model}",
+    )
+    return schema
+
+
+def render_schema(models: Iterable[type[BaseModel]], *, title: str) -> str:
+    """The canonical committed-schema string: sorted, indented, newline-terminated.
+
+    Used by both ``schema`` (write) and ``schema --check`` (compare) so the two
+    can never disagree about formatting.
+    """
+    return json.dumps(wire_schema(models, title=title), indent=2, sort_keys=True) + "\n"

argus_cortex-0.1.0/tests/test_backends.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import importlib.util
+
+import pytest
+
+from argus_cortex.backends import (
+    Backend,
+    BackendError,
+    BackendKind,
+    LocalBackend,
+    RemoteBackend,
+    RemoteProvider,
+    resolve_device,
+    with_retries,
+)
+
+_HAS_HTTPX = importlib.util.find_spec("httpx") is not None
+
+
+# --------------------------------------------------------------------------
+# retry
+# --------------------------------------------------------------------------
+
+
+def test_with_retries_returns_on_first_success() -> None:
+    assert with_retries(lambda: 42) == 42
+
+
+def test_with_retries_retries_then_succeeds_with_backoff() -> None:
+    calls = {"n": 0}
+    delays: list[float] = []
+
+    def flaky() -> str:
+        calls["n"] += 1
+        if calls["n"] < 3:
+            raise ValueError("boom")
+        return "ok"
+
+    result = with_retries(flaky, attempts=3, base_delay=1.0, retry_on=(ValueError,), sleep=delays.append)
+    assert result == "ok"
+    assert calls["n"] == 3
+    assert delays == [1.0, 2.0]  # exponential: base*2^0, base*2^1
+
+
+def test_with_retries_reraises_last_after_exhausting() -> None:
+    def always() -> None:
+        raise ValueError("nope")
+
+    with pytest.raises(ValueError, match="nope"):
+        with_retries(always, attempts=2, retry_on=(ValueError,), sleep=lambda _d: None)
+
+
+def test_with_retries_does_not_catch_unlisted_exception() -> None:
+    def boom() -> None:
+        raise KeyError("x")
+
+    with pytest.raises(KeyError):
+        with_retries(boom, attempts=3, retry_on=(ValueError,), sleep=lambda _d: None)
+
+
+def test_with_retries_rejects_non_positive_attempts() -> None:
+    # attempts<1 must fail loudly, never `raise None` (which the old assert did under -O)
+    with pytest.raises(ValueError, match="attempts must be >= 1"):
+        with_retries(lambda: 1, attempts=0)
+
+
+# --------------------------------------------------------------------------
+# device
+# --------------------------------------------------------------------------
+
+
+def test_resolve_device_passes_explicit_through() -> None:
+    assert resolve_device("cuda:1") == "cuda:1"
+    assert resolve_device("cpu") == "cpu"
+
+
+def test_resolve_device_auto_falls_back_to_cpu_without_torch() -> None:
+    # torch isn't a dependency of argus-cortex, so "auto" resolves to cpu here.
+    if importlib.util.find_spec("torch") is None:
+        assert resolve_device("auto") == "cpu"
+
+
+# --------------------------------------------------------------------------
+# Backend base + LocalBackend
+# --------------------------------------------------------------------------
+
+
+def test_backend_defaults() -> None:
+    b = Backend()
+    assert b.is_available() is True
+    assert b.availability_reason() is None
+    assert b.load() is None  # no-op
+    assert b.unload() is None
+
+
+def test_local_backend_load_sets_device() -> None:
+    b = LocalBackend()
+    assert b.kind == BackendKind.LOCAL
+    assert b.device is None
+    b.load("cpu")
+    assert b.device == "cpu"
+
+
+# --------------------------------------------------------------------------
+# RemoteBackend
+# --------------------------------------------------------------------------
+
+
+def test_remote_backend_normalizes_url_and_sets_auth() -> None:
+    b = RemoteBackend("http://10.0.0.5:9000/", api_key="secret")
+    assert b.base_url == "http://10.0.0.5:9000"
+    assert b.headers["Authorization"] == "Bearer secret"
+    assert b.kind == BackendKind.REMOTE
+    assert b.is_available() is True
+
+
+def test_remote_backend_from_host() -> None:
+    b = RemoteBackend.from_host("192.168.1.20", 8188)
+    assert b.base_url == "http://192.168.1.20:8188"
+
+
+def test_remote_backend_from_provider_uses_default_url() -> None:
+    b = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="k")
+    assert b.base_url == "https://integrate.api.nvidia.com/v1"
+    assert b.provider == RemoteProvider.NVIDIA_NIM
+
+
+def test_openai_compat_provider_requires_base_url() -> None:
+    with pytest.raises(BackendError, match="explicit base_url"):
+        RemoteBackend.from_provider(RemoteProvider.OPENAI_COMPAT)
+    # ...but works when you supply one (your self-hosted server)
+    b = RemoteBackend.from_provider(RemoteProvider.OPENAI_COMPAT, base_url="http://localhost:1234/v1")
+    assert b.base_url == "http://localhost:1234/v1"
+
+
+def test_remote_backend_unavailable_without_url() -> None:
+    b = RemoteBackend()
+    assert b.is_available() is False
+    assert "base_url" in (b.availability_reason() or "")
+
+
+class _FakeResp:
+    def __init__(self, data: dict) -> None:
+        self._data = data
+
+    def raise_for_status(self) -> None:
+        pass
+
+    def json(self) -> dict:
+        return self._data
+
+
+class _FakeClient:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, dict | None]] = []
+        self.closed = False
+
+    def post(self, path: str, json: dict) -> _FakeResp:
+        self.calls.append((path, json))
+        return _FakeResp({"echo": json})
+
+    def get(self, path: str) -> _FakeResp:
+        self.calls.append((path, None))
+        return _FakeResp({"path": path})
+
+    def close(self) -> None:
+        self.closed = True
+
+
+def test_remote_post_and_get_via_injected_client() -> None:
+    b = RemoteBackend("http://host:1")
+    fake = _FakeClient()
+    b._http = fake
+    assert b.post_json("/score", {"a": 1}) == {"echo": {"a": 1}}
+    assert b.get_json("/health") == {"path": "/health"}
+    assert fake.calls == [("/score", {"a": 1}), ("/health", None)]
+
+
+def test_remote_wraps_request_failures_in_backend_error() -> None:
+    class Failing(_FakeClient):
+        def post(self, path: str, json: dict) -> _FakeResp:
+            raise ValueError("bad json body")
+
+    b = RemoteBackend("http://host:1")
+    b._http = Failing()
+    with pytest.raises(BackendError, match="POST /score failed"):
+        b.post_json("/score", {"a": 1})
+
+
+def test_remote_unload_closes_client() -> None:
+    b = RemoteBackend("http://host:1")
+    fake = _FakeClient()
+    b._http = fake
+    b.unload()
+    assert fake.closed is True
+    assert b._http is None
+
+
+@pytest.mark.skipif(_HAS_HTTPX, reason="httpx installed; the missing-extra path can't be exercised")
+def test_client_without_httpx_raises_helpful_error() -> None:
+    with pytest.raises(BackendError, match=r"argus-cortex\[remote\]"):
+        RemoteBackend("http://host:1")._client()

argus_cortex-0.1.0/tests/test_smoke.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import argus_cortex
+
+
+def test_version_is_exposed() -> None:
+    assert isinstance(argus_cortex.__version__, str)
+    assert argus_cortex.__version__

argus_cortex-0.1.0/tests/test_taxonomy.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from argus_cortex.taxonomy import TARGET_CATEGORIES, TARGET_STYLES, TargetProfile
+
+
+def test_defaults() -> None:
+    p = TargetProfile()
+    assert p.target_style == "photo"
+    assert p.target_category == "identity"
+    assert p.target_backend == "sdxl"
+    assert p.checkpoint is None
+
+
+def test_accepts_valid_taxonomy() -> None:
+    p = TargetProfile(target_style="anime", target_category="wardrobe", checkpoint="ckpt.safetensors")
+    assert p.target_style == "anime"
+    assert p.target_category == "wardrobe"
+
+
+def test_rejects_invalid_style_and_category() -> None:
+    with pytest.raises(ValidationError):
+        TargetProfile(target_style="watercolor")
+    with pytest.raises(ValidationError):
+        TargetProfile(target_category="lighting")  # a caption bucket, not a target category
+
+
+def test_round_trips() -> None:
+    p = TargetProfile(target_style="anime", target_category="setting")
+    assert TargetProfile.model_validate_json(p.model_dump_json()) == p
+
+
+def test_tuples_match_literals() -> None:
+    assert set(TARGET_STYLES) == {"photo", "anime"}
+    assert set(TARGET_CATEGORIES) == {"identity", "wardrobe", "pose_composition", "setting"}

argus_cortex-0.1.0/tests/test_wire.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel
+
+from argus_cortex.wire import (
+    VersionError,
+    check_version,
+    make_versioned_base,
+    render_schema,
+    schema_major,
+    wire_schema,
+)
+
+
+def test_schema_major() -> None:
+    assert schema_major("1.0") == "1"
+    assert schema_major("2.7") == "2"
+    assert schema_major("10.3.1") == "10"
+
+
+def test_check_version_accepts_supported_major() -> None:
+    check_version("1.4", ("1",), label="proof_version")  # no raise
+
+
+def test_check_version_refuses_unsupported_major() -> None:
+    with pytest.raises(VersionError, match="proof_version 2.0 is not supported"):
+        check_version("2.0", ("1",), label="proof_version")
+
+
+def test_versioned_base_stamps_default() -> None:
+    Base = make_versioned_base("proof_version", "1.0", ("1",), label="proof_version")
+
+    class Model(Base):  # type: ignore[misc, valid-type]
+        x: int = 0
+
+    assert Model().proof_version == "1.0"
+    assert Model(x=5).x == 5
+
+
+def test_versioned_base_accepts_compatible_major() -> None:
+    Base = make_versioned_base("proof_version", "1.0", ("1",))
+
+    class Model(Base):  # type: ignore[misc, valid-type]
+        x: int = 0
+
+    assert Model.model_validate({"proof_version": "1.9", "x": 3}).x == 3
+
+
+def test_versioned_base_refuses_incompatible_major() -> None:
+    Base = make_versioned_base("proof_version", "1.0", ("1",))
+
+    class Model(Base):  # type: ignore[misc, valid-type]
+        x: int = 0
+
+    with pytest.raises(VersionError):
+        Model.model_validate({"proof_version": "2.0", "x": 3})
+
+
+def test_check_version_raises_custom_error_type() -> None:
+    class MyError(RuntimeError):
+        pass
+
+    with pytest.raises(MyError, match="not supported"):
+        check_version("2.0", ("1",), error=MyError)
+
+
+def test_versioned_base_raises_custom_error_type() -> None:
+    class MyError(RuntimeError):
+        pass
+
+    Base = make_versioned_base("proof_version", "1.0", ("1",), error=MyError)
+
+    class Model(Base):  # type: ignore[misc, valid-type]
+        x: int = 0
+
+    with pytest.raises(MyError):
+        Model.model_validate({"proof_version": "2.0"})
+
+
+def test_versioned_base_supports_custom_field_name() -> None:
+    Base = make_versioned_base("manifest_version", "2.0", ("1", "2"))
+
+    class Row(Base):  # type: ignore[misc, valid-type]
+        rel_path: str = ""
+
+    assert Row().manifest_version == "2.0"
+    Row.model_validate({"manifest_version": "1.3"})  # legacy major still supported
+    with pytest.raises(VersionError):
+        Row.model_validate({"manifest_version": "3.0"})
+
+
+class _A(BaseModel):
+    x: int
+    y: str = "hi"
+
+
+class _B(BaseModel):
+    a: _A
+    flag: bool = False
+
+
+def test_wire_schema_has_defs() -> None:
+    defs = wire_schema([_A, _B], title="test")["$defs"]
+    assert "_A" in defs and "_B" in defs
+
+
+def test_render_schema_is_canonical_and_deterministic() -> None:
+    a = render_schema([_A, _B], title="test")
+    b = render_schema([_A, _B], title="test")
+    assert a == b
+    assert a.endswith("\n")
+    # sorted keys: within a properties block, keys are alphabetical
+    assert a.index('"a"') < a.index('"flag"')