auroraomics 0.1.0.dev0__py3-none-any.whl

auroraomics/_contracts/public-api.tokens.json

@@ -0,0 +1,345 @@
+{
+  "_comment": "Public-API vocabularies — the SINGLE SOURCE OF TRUTH shared by packages/contracts/src/public-api.ts (validated in public-api.test.ts), the webapp backend (tests/test_public_api_contracts.py validates these bytes; the key and job services load them at import once they exist) and the SDK (vendored at build time, guarded to equal the repo's). Generated from PUBLIC_API_FIXTURES in the module — never hand-edit; run the contracts suite with UPDATE_PUBLIC_API_FIXTURES=1 to regenerate.",
+  "_visibility": "public",
+  "version": "v1",
+  "pathPrefix": "/v1",
+  "apiKey": {
+    "prefix": "aok_",
+    "prefixChars": 8,
+    "secretChars": 32,
+    "defaultTtlDays": 365,
+    "scopes": [
+      "submit",
+      "read",
+      "manage:keys"
+    ]
+  },
+  "idPrefixes": {
+    "job": "job_",
+    "upload": "upl_",
+    "key": "key_",
+    "model": "mdl_"
+  },
+  "headers": {
+    "idempotencyKey": "Idempotency-Key",
+    "requestId": "X-Request-Id",
+    "problemJson": "application/problem+json",
+    "rateLimit": [
+      "RateLimit-Limit",
+      "RateLimit-Remaining",
+      "RateLimit-Reset",
+      "Retry-After"
+    ]
+  },
+  "jobs": {
+    "states": [
+      "queued",
+      "validating",
+      "running",
+      "succeeded",
+      "failed",
+      "canceled",
+      "expired"
+    ],
+    "terminalStates": [
+      "succeeded",
+      "failed",
+      "canceled",
+      "expired"
+    ],
+    "lanes": [
+      "gpu",
+      "cpu"
+    ],
+    "events": [
+      "validated",
+      "qc",
+      "subsampled",
+      "model_loaded",
+      "predicted",
+      "written"
+    ],
+    "idempotencyScope": "per_key_while_job_lives",
+    "idempotencyKey": {
+      "header": "Idempotency-Key",
+      "scope": "per_key_while_job_lives",
+      "min_chars": 8,
+      "max_chars": 128,
+      "charset": "^[A-Za-z0-9_.:-]+$"
+    }
+  },
+  "errors": {
+    "validation_failed": {
+      "status": 422,
+      "anchor": "errors#validation_failed"
+    },
+    "unsupported_modality": {
+      "status": 422,
+      "anchor": "errors#unsupported_modality"
+    },
+    "input_spec_mismatch": {
+      "status": 422,
+      "anchor": "errors#input_spec_mismatch"
+    },
+    "calibration_failed": {
+      "status": 422,
+      "anchor": "errors#calibration_failed"
+    },
+    "gene_unknown": {
+      "status": 422,
+      "anchor": "errors#gene_unknown"
+    },
+    "gene_ambiguous": {
+      "status": 422,
+      "anchor": "errors#gene_ambiguous"
+    },
+    "bulk_rna_coverage_too_low": {
+      "status": 422,
+      "anchor": "errors#bulk_rna_coverage_too_low"
+    },
+    "checksum_mismatch": {
+      "status": 422,
+      "anchor": "errors#checksum_mismatch"
+    },
+    "model_does_not_accept": {
+      "status": 422,
+      "anchor": "errors#model_does_not_accept"
+    },
+    "model_not_found": {
+      "status": 404,
+      "anchor": "errors#model_not_found"
+    },
+    "not_found": {
+      "status": 404,
+      "anchor": "errors#not_found"
+    },
+    "upload_incomplete": {
+      "status": 409,
+      "anchor": "errors#upload_incomplete"
+    },
+    "idempotency_conflict": {
+      "status": 409,
+      "anchor": "errors#idempotency_conflict"
+    },
+    "result_not_ready": {
+      "status": 409,
+      "anchor": "errors#result_not_ready"
+    },
+    "job_not_cancelable": {
+      "status": 409,
+      "anchor": "errors#job_not_cancelable"
+    },
+    "result_expired": {
+      "status": 410,
+      "anchor": "errors#result_expired"
+    },
+    "payload_too_large": {
+      "status": 413,
+      "anchor": "errors#payload_too_large"
+    },
+    "quota_exceeded": {
+      "status": 429,
+      "anchor": "errors#quota_exceeded"
+    },
+    "rate_limited": {
+      "status": 429,
+      "anchor": "errors#rate_limited"
+    },
+    "unauthorized": {
+      "status": 401,
+      "anchor": "errors#unauthorized"
+    },
+    "forbidden": {
+      "status": 403,
+      "anchor": "errors#forbidden"
+    },
+    "not_approved": {
+      "status": 403,
+      "anchor": "errors#not_approved"
+    },
+    "terms_not_accepted": {
+      "status": 403,
+      "anchor": "errors#terms_not_accepted"
+    },
+    "queue_full": {
+      "status": 503,
+      "anchor": "errors#queue_full"
+    },
+    "lane_disabled": {
+      "status": 503,
+      "anchor": "errors#lane_disabled"
+    },
+    "internal": {
+      "status": 500,
+      "anchor": "errors#internal"
+    }
+  },
+  "containers": {
+    "patchArchive": {
+      "manifest": "tiles.csv",
+      "manifest_columns": [
+        "tile_id",
+        "file",
+        "x",
+        "y",
+        "width",
+        "height",
+        "mpp"
+      ],
+      "thumbnail": "thumbnail.jpg",
+      "tile_extensions": [
+        ".png",
+        ".jpg",
+        ".jpeg"
+      ],
+      "tile_name_pattern": "^tile_[0-9]{6}\\.(png|jpe?g)$",
+      "max_member_bytes": 4194304,
+      "geometry_sample": 3
+    },
+    "embeddingsNpz": {
+      "keys": [
+        "emb",
+        "px_col",
+        "px_row",
+        "passes",
+        "foreground_ratio",
+        "hsv_ratio",
+        "laplacian_var",
+        "calibration"
+      ],
+      "attrs": [
+        "encoder",
+        "revision",
+        "patch_px",
+        "pooling",
+        "commit"
+      ],
+      "dtypes": [
+        "float16",
+        "float32"
+      ]
+    },
+    "bulkRna": {
+      "units": [
+        "counts",
+        "tpm"
+      ],
+      "min_coverage_fraction": 0.6,
+      "layouts": [
+        "long",
+        "wide"
+      ]
+    },
+    "extensions": {
+      "zip": [
+        ".zip"
+      ],
+      "npz": [
+        ".npz",
+        ".npy"
+      ],
+      "table": [
+        ".csv",
+        ".tsv",
+        ".txt"
+      ],
+      "enum": []
+    },
+    "magic": {
+      ".zip": [
+        "504b0304"
+      ],
+      ".npz": [
+        "504b0304"
+      ],
+      ".npy": [
+        "934e554d5059"
+      ],
+      ".csv": [],
+      ".tsv": [],
+      ".txt": []
+    },
+    "tableDelimiters": [
+      ",",
+      "\t"
+    ]
+  },
+  "uploads": {
+    "chunk_size_bytes": 8388608,
+    "chunk_min_bytes": 524288,
+    "chunk_max_bytes": 94371840,
+    "chunk_digest_header": "Content-SHA256",
+    "offset_header": "X-Upload-Offset",
+    "complete_header": "X-Upload-Complete",
+    "tree_hash": {
+      "algorithm": "sha256",
+      "encoding": "lowercase-hex",
+      "leaf": "sha256(chunk bytes), the 32 RAW digest bytes, one leaf per Content-Range chunk in offset order",
+      "root": "sha256(leaf_0 || leaf_1 || ... || leaf_n-1)",
+      "single_chunk": "a whole-file PUT is ONE chunk, so the root is sha256(sha256(file)) — never sha256(file)"
+    }
+  },
+  "result": {
+    "format": "h5ad",
+    "var_index": "ensembl_gene_id",
+    "var_columns": [
+      "feature_name",
+      "hgnc_id",
+      "biotype",
+      "measured_in_training",
+      "n_train_datasets",
+      "model_token"
+    ],
+    "layers": [
+      "bulk_calibrated",
+      "image_only"
+    ],
+    "uns_keys": [
+      "model",
+      "input_spec",
+      "job"
+    ]
+  },
+  "rateBuckets": {
+    "read": {
+      "per_minute": 600
+    },
+    "write": {
+      "per_minute": 60
+    },
+    "submit": {
+      "per_minute": 10
+    }
+  },
+  "retention": {
+    "uploads_days_after_completion": 7,
+    "results_days": 90,
+    "embeddings_retain_default": false
+  },
+  "modelCards": {
+    "schemaVersion": 2,
+    "visibilities": [
+      "public",
+      "internal"
+    ],
+    "hostedRuntimes": [
+      "gpu",
+      "cpu"
+    ],
+    "encoderGates": [
+      "none",
+      "auto",
+      "manual"
+    ],
+    "poolings": [
+      "cls",
+      "mean_patch_tokens",
+      "cls_plus_mean",
+      "token_grid"
+    ]
+  },
+  "fixtureVisibilities": [
+    "public",
+    "internal"
+  ]
+}

auroraomics/_contracts/qc-thresholds.tokens.json

@@ -0,0 +1,10 @@
+{
+  "_comment": "Patch-QC threshold VALUES — the SINGLE SOURCE OF TRUTH for the three floors a tile must reach to be fed to a model, and the PRODUCTION numbers both pipelines run. patch-qc.vectors.json single-sources the per-pixel tissue RULE; these are the floors that rule is compared against, and they used to name four different things: 55/30/20 in both config.yaml files, 50/20/50 in the Python predicate defaults, and 20 for blur in filter_patches' own signature. Retuning one copy silently changes which tiles a model is fed relative to which tiles a reviewer approved. A model may override them on its card (input_spec.qc); absent that these are what everything uses. Loaded by the SDK (vendored) and validated against both pipeline configs by qc-thresholds.test.ts, which greps them because a container COPYs only its own tree. foregroundWhiteLevel is the OTHER half of the foreground rule: the grey level at or below which a pixel counts as tissue, which foreground_ratio is then measured against. It sits beside `thresholds` rather than inside it because that object is 1:1 with the QC_THRESHOLDS block in both config.yaml files and with the QcThresholds interface. It was hand-typed in three places — the SDK's qc.WHITE_LEVEL and a bare 210 in each pipeline's patch_qc.py — and was the last unpinned half of the QC rule: retune one and the SDK filters tiles the service would keep, which is exactly what the SDK exists not to do.",
+  "_visibility": "public",
+  "thresholds": {
+    "foreground_ratio": 55,
+    "hsv_tissue_ratio": 30,
+    "blur_laplacian_var": 20
+  },
+  "foregroundWhiteLevel": 210
+}

auroraomics/contracts.py

@@ -0,0 +1,155 @@
+"""The shared contract values, as data.
+
+Container layouts, input-kind caps and the result layout are agreed between
+this package and the service that runs the same models. Re-typing one of those
+numbers here would create a second source for it, and the copy that drifts is
+always the one nobody is looking at — so the agreed values ship *as the JSON
+they are defined in*, vendored into the wheel at ``_contracts/``.
+
+The vendored copies are byte-for-byte what the definition side holds, and each
+one carries its sha256 in ``_contracts/MANIFEST.json``. Only documents marked
+public are vendored; nothing else is readable from here, by construction.
+
+    >>> from auroraomics import contracts
+    >>> contracts.patch_archive()["manifest"]
+    'tiles.csv'
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+_DIR = Path(__file__).resolve().parent / "_contracts"
+_MANIFEST = "MANIFEST.json"
+
+#: The documents this package reads by name. Spelled here so a missing or
+#: renamed vendored file is an error at the call site rather than a KeyError
+#: deep inside a validator.
+PUBLIC_API = "public-api.tokens.json"
+#: The service's patch-QC floors. A model may override them on its card; absent
+#: that, these are what the service runs, and therefore what this package filters at.
+QC_THRESHOLDS = "qc-thresholds.tokens.json"
+INPUT_KINDS = "public-api-input-kinds.tokens.json"
+COUNTERS = "public-api-counters.tokens.json"
+
+
+class ContractError(RuntimeError):
+    """A vendored contract document is missing, unreadable or not itself."""
+
+
+@lru_cache(maxsize=1)
+def manifest() -> dict[str, Any]:
+    """The vendored index: every document's relative name and its sha256."""
+    path = _DIR / _MANIFEST
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:  # pragma: no cover - a broken install
+        raise ContractError(
+            f"{_MANIFEST} is missing from this installation, so no contract "
+            "value can be trusted; reinstall the package."
+        ) from exc
+
+
+def names() -> tuple[str, ...]:
+    """Every vendored document name, sorted."""
+    return tuple(sorted(manifest()["files"]))
+
+
+def path_of(name: str) -> Path:
+    """The absolute path of one vendored document.
+
+    ``name`` must be one the index lists. Resolving an arbitrary string here
+    would let a caller read any file the process can reach through a
+    ``../..`` name, so the index is the allow-list rather than a hint.
+    """
+    if name not in manifest()["files"]:
+        raise ContractError(
+            f"{name!r} is not a vendored contract document; the ones present "
+            f"are {', '.join(names())}"
+        )
+    return _DIR / name
+
+
+@lru_cache(maxsize=None)
+def load(name: str) -> dict[str, Any]:
+    """One vendored document, parsed. Cached: these are read-only constants."""
+    return json.loads(path_of(name).read_text(encoding="utf-8"))
+
+
+def verify() -> None:
+    """Re-hash every vendored document and compare with the index.
+
+    Raises :class:`ContractError` on the first mismatch. Not called on import —
+    hashing on every process start would tax every caller for a check that only
+    a damaged install can fail — but cheap enough to call from a diagnostic.
+    """
+    for name, expected in sorted(manifest()["files"].items()):
+        actual = hashlib.sha256(path_of(name).read_bytes()).hexdigest()
+        if actual != expected:
+            raise ContractError(
+                f"vendored contract {name} does not match its recorded "
+                f"sha256 ({actual} != {expected}) — the installation is damaged"
+            )
+
+
+# ── the values this package's own modules read ──────────────────────────────
+
+
+def qc_thresholds() -> dict[str, float]:
+    """The three patch-QC floors the service runs.
+
+    Read from the shipped contract rather than written here: a client that filters
+    tiles differently from the server it sends them to would drop tiles the
+    service would have kept, or keep tiles it will discard, and every number
+    downstream would still look plausible.
+    """
+    return {k: float(v) for k, v in load(QC_THRESHOLDS)["thresholds"].items()}
+
+
+def foreground_white_level() -> int:
+    """The grey level at or below which a pixel counts as foreground.
+
+    Read from the contract for the same reason :func:`qc_thresholds` is: this is
+    the other half of the foreground rule, and a client that cuts foreground at
+    a different grey level than the service does filters a different set of
+    tiles — while every number downstream still looks plausible.
+    """
+    return int(load(QC_THRESHOLDS)["foregroundWhiteLevel"])
+
+
+def patch_archive() -> dict[str, Any]:
+    """The ``patches`` container layout: manifest name, columns, tile names."""
+    return load(PUBLIC_API)["containers"]["patchArchive"]
+
+
+def result_layout() -> dict[str, Any]:
+    """The result file's agreed layout: format, ``var`` index, layer names."""
+    return load(PUBLIC_API)["result"]
+
+
+def input_kind(kind: str) -> dict[str, Any]:
+    """One input kind's registry row (container, cost unit, caps)."""
+    kinds = load(INPUT_KINDS)["kinds"]
+    if kind not in kinds:
+        raise ContractError(
+            f"{kind!r} is not an input kind; the registry declares "
+            f"{', '.join(sorted(kinds))}"
+        )
+    return kinds[kind]
+
+
+def max_bytes(kind: str) -> int:
+    """The largest an input of ``kind`` may be, uncompressed.
+
+    A cap is what makes it safe to look at an archive at all: the sizes a zip
+    declares are written by whoever produced it, so they are checked against
+    this number *before* anything is decompressed.
+    """
+    value = input_kind(kind)["max_bytes"]
+    if not isinstance(value, int) or value <= 0:
+        raise ContractError(f"input kind {kind!r} declares no byte cap")
+    return value