auroraomics 0.1.0.dev3__tar.gz → 0.1.0.dev4__tar.gz

{auroraomics-0.1.0.dev3/src/auroraomics.egg-info → auroraomics-0.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auroraomics
-Version: 0.1.0.dev3
+Version: 0.1.0.dev4
 Summary: Prepare H&E slides on your own machine, submit them to Aurora, and read the spatial gene expression it predicts.
 Author: Kalin Nonchev
 License-Expression: PolyForm-Noncommercial-1.0.0
@@ -23,15 +23,20 @@ Requires-Dist: pydantic>=2
 Requires-Dist: anndata>=0.10
 Requires-Dist: tifffile>=2023.7.10
 Requires-Dist: imagecodecs>=2023.3.16
+Requires-Dist: scipy>1.8
 Provides-Extra: embed
 Requires-Dist: torch>=2.0; extra == "embed"
 Requires-Dist: timm>=1.0; extra == "embed"
 Requires-Dist: transformers>=4.40; extra == "embed"
 Requires-Dist: huggingface-hub>=0.23; extra == "embed"
+Provides-Extra: spatialdata
+Requires-Dist: spatialdata>=0.2; extra == "spatialdata"
+Requires-Dist: setuptools<81; python_version < "3.12" and extra == "spatialdata"
 Provides-Extra: mcp
 Requires-Dist: mcp<3,>=2; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: auroraomics[mcp]; extra == "dev"
+Requires-Dist: auroraomics[spatialdata]; extra == "dev"
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: packaging>=22; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
@@ -73,6 +78,9 @@ same code runs on your machine and on the service:
 - **`auroraomics.contracts`** — the shared contract values (container layout,
   input-kind caps, result layout) as data, so nothing here re-types a number
   the service also reads.
+- **`auroraomics.export`** — write a result as a SpatialData Zarr store
+  *(extra)* or as a folder Seurat loads, with the same matrix, coordinates and
+  gene names as the `.h5ad`.
 - **`auroraomics.embed`** *(extra)* — run a pinned image encoder over your
   tiles locally and write the embeddings container, so a prediction can be made
   from numbers instead of pixels.
@@ -93,8 +101,9 @@ pip install auroraomics
 
 That is the whole documented path: open a slide, judge and pack its tiles,
 submit, and read the result. One extra adds local embedding extraction
-(`embed`). No extra brings the model: predicting gene expression runs on the
-service, not here.
+(`embed`), and one writes a result as a SpatialData store (`spatialdata`). No
+extra brings the model: predicting gene expression runs on the service, not
+here.
 
 ## Pack tiles, then look at the report
 
@@ -248,6 +257,26 @@ measured. Such a gene becomes `nan` in `X` and in every layer, not zero: zero
 is a measurement, and an unmeasured gene left as one averages, correlates and
 colours a heat map exactly like a prediction.
 
+## Read a result in SpatialData or Seurat
+
+Every result is an `.h5ad`, which is an HDF5 file: `anndata` reads it, and so
+does any HDF5 library. For tools that read other formats, write it again:
+
+```
+auroraomics export result.h5ad --format seurat    # result_seurat/, for Read10X
+auroraomics export result.h5ad --format zarr      # result.zarr, a SpatialData store
+```
+
+```python
+from auroraomics.export import write_seurat_dir, write_zarr
+
+write_seurat_dir("result.h5ad", "result_seurat")
+write_zarr("result.h5ad", "result.zarr")    # pip install "auroraomics[spatialdata]"
+```
+
+Both keep the result's own values: a gene the model never measured stays blank
+(`nan`) in either format, never zero.
+
 ## Prepare a bulk RNA profile
 
 ```python

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/README.md

@@ -29,6 +29,9 @@ same code runs on your machine and on the service:
 - **`auroraomics.contracts`** — the shared contract values (container layout,
   input-kind caps, result layout) as data, so nothing here re-types a number
   the service also reads.
+- **`auroraomics.export`** — write a result as a SpatialData Zarr store
+  *(extra)* or as a folder Seurat loads, with the same matrix, coordinates and
+  gene names as the `.h5ad`.
 - **`auroraomics.embed`** *(extra)* — run a pinned image encoder over your
   tiles locally and write the embeddings container, so a prediction can be made
   from numbers instead of pixels.
@@ -49,8 +52,9 @@ pip install auroraomics
 
 That is the whole documented path: open a slide, judge and pack its tiles,
 submit, and read the result. One extra adds local embedding extraction
-(`embed`). No extra brings the model: predicting gene expression runs on the
-service, not here.
+(`embed`), and one writes a result as a SpatialData store (`spatialdata`). No
+extra brings the model: predicting gene expression runs on the service, not
+here.
 
 ## Pack tiles, then look at the report
 
@@ -204,6 +208,26 @@ measured. Such a gene becomes `nan` in `X` and in every layer, not zero: zero
 is a measurement, and an unmeasured gene left as one averages, correlates and
 colours a heat map exactly like a prediction.
 
+## Read a result in SpatialData or Seurat
+
+Every result is an `.h5ad`, which is an HDF5 file: `anndata` reads it, and so
+does any HDF5 library. For tools that read other formats, write it again:
+
+```
+auroraomics export result.h5ad --format seurat    # result_seurat/, for Read10X
+auroraomics export result.h5ad --format zarr      # result.zarr, a SpatialData store
+```
+
+```python
+from auroraomics.export import write_seurat_dir, write_zarr
+
+write_seurat_dir("result.h5ad", "result_seurat")
+write_zarr("result.h5ad", "result.zarr")    # pip install "auroraomics[spatialdata]"
+```
+
+Both keep the result's own values: a gene the model never measured stays blank
+(`nan`) in either format, never zero.
+
 ## Prepare a bulk RNA profile
 
 ```python

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auroraomics"
-version = "0.1.0.dev3"
+version = "0.1.0.dev4"
 description = "Prepare H&E slides on your own machine, submit them to Aurora, and read the spatial gene expression it predicts."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -64,12 +64,18 @@ dependencies = [
   # rather than being handed tiles they cut themselves.
   "tifffile>=2023.7.10",
   "imagecodecs>=2023.3.16",
+  # Writing a result as the folder Seurat loads (`auroraomics.export`): the
+  # matrix is written by scipy's Matrix Market writer. scipy already arrives
+  # behind anndata, so a plain install resolves nothing new for it; it is named
+  # because that module imports it directly, at anndata's own lower bound.
+  "scipy>1.8",
 ]
 
 [project.optional-dependencies]
-# TWO extras, and only one of them is a runtime: `embed` is the single opt-in
-# the documented path can need, and `mcp` is a protocol adapter for an agent.
-# Where that line is drawn is the whole of this comment.
+# THREE extras, and only one of them is a model runtime: `embed` is the single
+# opt-in the documented path can need, `mcp` is a protocol adapter for an agent,
+# and `spatialdata` writes a result in one more format. Where the first line is
+# drawn is the rest of this comment.
 #
 # There is no model-runtime extra, and that is the boundary rather than an
 # omission. Predicting gene expression runs on the service: the model definition
@@ -109,6 +115,21 @@ embed = [
   "transformers>=4.40",
   "huggingface-hub>=0.23",
 ]
+# Writing a result as a SpatialData Zarr store (`auroraomics.export.write_zarr`,
+# `auroraomics export --format zarr`). An extra because it is large — some
+# seventy distributions and 700 MB on top of the core, measured on Python 3.10 —
+# and only someone who wants SpatialData's own format needs it; the Seurat
+# folder and the .h5ad need nothing from it.
+#
+# The setuptools bound is not a preference. Every SpatialData release before
+# 0.8 imports a schema library that reads `pkg_resources`, which setuptools 81
+# removed, so on a fresh environment the import fails with ModuleNotFoundError
+# however the rest resolves. 0.8 dropped that library and requires Python 3.12,
+# so the bound applies exactly where an older release is what pip can choose.
+spatialdata = [
+  "spatialdata>=0.2",
+  "setuptools<81; python_version < '3.12'",
+]
 # The MCP server: `auroraomics mcp` over stdio, so an agent reaches the same
 # client the CLI does. Only the protocol adapter is here; the tool table and
 # every handler are in the client, which is in the core now, so this extra names
@@ -135,6 +156,10 @@ dev = [
   # that spelled its own bound would be testing a dependency set no user can
   # install. The client needs no reference any more — it is the core.
   "auroraomics[mcp]",
+  # The SpatialData extra by reference, for the same reason: the export tests
+  # read every store back with SpatialData's own reader, so the environment
+  # that runs them installs what a user who asks for the format installs.
+  "auroraomics[spatialdata]",
   "pytest>=7",
   # The release guard parses version strings with `packaging.version`, at module
   # scope. It has always resolved, because more than one dependency in this list

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/src/auroraomics/__init__.py

@@ -7,10 +7,11 @@ embeddings computed from them; everything either side of that word is the same:
 import auroraomics as ao
 
 client = ao.Client()
+card = next(m for m in client.models() if "patches" in m["accepts"]["observations"])
 slide  = ao.open_slide("slide.svs")
-report = ao.pack_tiles(slide, "sample.zip", mpp=slide.mpp, patch_um=55,
+report = ao.pack_tiles(slide, "sample.zip", mpp=slide.mpp, patch_um=card["input_spec"]["patch_um"],
                        thresholds=client.qc_thresholds())
-job    = client.predict(model=model_id, observations={"patches": report.path})
+job    = client.predict(model=model_id, observation=report)
 job.wait().download("result.h5ad")
 ```
 

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/src/auroraomics/cli.py

@@ -30,6 +30,7 @@ from typing import Any, Sequence
 
 from auroraomics import __version__, contracts
 from auroraomics._text import bounded_repr
+from auroraomics.contracts import COVARIATE_SLOT, OBSERVATION_SLOT, kinds_in
 
 from .client import credentials, errors
 from ._text import EMBEDDING_COMPONENT
@@ -194,12 +195,6 @@ def _ask(prompt: str, *, stdin=None, out: Out | None = None) -> str:
 # ── commands ────────────────────────────────────────────────────────────────
 
 
-OBSERVATION_SLOT = "observations"
-"""The registry slot the sample itself is filed under."""
-
-COVARIATE_SLOT = "covariates"
-"""The registry slot for what is known about the sample besides."""
-
 OBSERVATION_SHAPE = "KIND=PATH"
 """How ``--observation`` is written. Named once: it is the flag's metavar in the
 help AND the shape the refusal tells a reader to use, and the two disagreed."""
@@ -774,11 +769,22 @@ def cmd_submit(args: argparse.Namespace, out: Out) -> int:
             f"{', '.join(kinds_in(OBSERVATION_SLOT))}; `auroraomics models` says "
             "which of them a model takes."
         )
+    if len(observations) > 1:
+        # Refused here, before anything is uploaded: the service runs one
+        # observation per job, and the flag stays repeatable only so that this
+        # sentence, rather than argparse's, is what a second one meets.
+        raise errors.ClientError(
+            f"a submission carries exactly one observation, and this one names "
+            f"{', '.join(observations)}: pass --observation once. A cohort is one "
+            "submission per sample."
+        )
+    ((kind, path),) = observations.items()
     refuse_flags_that_need_wait(args)
     with _client(args) as client:
         job = client.predict(
             model=args.model,
-            observations=observations,
+            observation=path,
+            kind=kind,
             covariates=_pairs(args.covariate, "--covariate", COVARIATE_SHAPE, COVARIATE_SLOT),
             land_in_workspace=args.land_in_workspace,
             idempotency_key=args.idempotency_key,
@@ -824,6 +830,32 @@ def cmd_download(args: argparse.Namespace, out: Out) -> int:
     return EXIT_OK
 
 
+EXPORT_FORMATS: dict[str, str] = {"zarr": ".zarr", "seurat": "_seurat"}
+"""What ``export --format`` takes, and the ending of the name it writes beside
+the result when no ``--output`` is given."""
+
+
+def cmd_export(args: argparse.Namespace, out: Out) -> int:
+    """Write a result file as a SpatialData store or as a folder Seurat loads."""
+    from .export import ExportError, ExportUnavailable, write_seurat_dir, write_zarr
+
+    source = Path(args.result)
+    target = (
+        Path(args.output)
+        if args.output
+        else source.with_name(source.stem + EXPORT_FORMATS[args.format])
+    )
+    writer = write_zarr if args.format == "zarr" else write_seurat_dir
+    try:
+        written = writer(source, target)
+    except (ExportError, ExportUnavailable) as exc:
+        # A refusal about this machine or this command line, never the
+        # service's, so it exits with the code those refusals carry.
+        raise errors.ClientError(str(exc)) from exc
+    out.emit({"format": args.format, "path": str(written)}, str(written))
+    return EXIT_OK
+
+
 def cmd_mcp(args: argparse.Namespace, out: Out) -> int:
     """Serve the tool surface over stdio, for an agent."""
     try:
@@ -856,18 +888,6 @@ def _job_line(job) -> str:
     return "  ".join(parts)
 
 
-def kinds_in(slot: str) -> tuple[str, ...]:
-    """The input kinds the registry files under one slot, in its own order.
-
-    Read from the shipped registry rather than listed here, so a kind the
-    service adds is named by the refusals below without an edit. The two slots
-    are ``observations`` (the sample itself) and ``covariates`` (what is known
-    about it besides).
-    """
-    rows = contracts.load(contracts.INPUT_KINDS)["kinds"]
-    return tuple(name for name, row in rows.items() if row.get("slot") == slot)
-
-
 TILE_COST_UNIT = "tiles"
 """What the registry charges the route that sends pixels by."""
 
@@ -1433,7 +1453,7 @@ def build_parser() -> argparse.ArgumentParser:
         metavar=OBSERVATION_SHAPE,
         help=(
             "the sample, as KIND=PATH — a file is uploaded, an upload id is used "
-            "as it stands. Repeatable. Required."
+            "as it stands. Required, once: a job reads one sample."
         ),
     )
     submit.add_argument(
@@ -1557,6 +1577,38 @@ def build_parser() -> argparse.ArgumentParser:
     )
     download.set_defaults(handler=cmd_download)
 
+    export = commands.add_parser(
+        "export",
+        parents=[common],
+        help="write a result for SpatialData or Seurat",
+        description=_described(
+            "Write a result file in another format, beside it or at --output.\n\n"
+            "--format zarr writes a SpatialData Zarr store: the result is its "
+            "table, and each spot is a circle at its coordinates. It needs the "
+            "spatialdata extra: pip install 'auroraomics[spatialdata]'.\n\n"
+            "--format seurat writes a folder Seurat loads: the matrix in the "
+            "layout Read10X reads, with each spot's coordinates and metadata as "
+            "CSV. A plain install writes it.\n\n"
+            "Nothing that already exists is replaced."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    export.add_argument("result", metavar="RESULT", help="the .h5ad result file to read")
+    export.add_argument(
+        "--format",
+        required=True,
+        choices=sorted(EXPORT_FORMATS),
+        help="zarr for a SpatialData store, seurat for a folder Seurat loads",
+    )
+    export.add_argument(
+        "--output",
+        "-o",
+        default=None,
+        metavar="PATH",
+        help="where to write it (default: beside RESULT, as NAME.zarr or NAME_seurat)",
+    )
+    export.set_defaults(handler=cmd_export)
+
     mcp = commands.add_parser(
         "mcp",
         parents=[common],

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/src/auroraomics/client/__init__.py

@@ -4,7 +4,7 @@
 import auroraomics as ao
 
 client = ao.Client()                       # env, then ~/.config
-job    = client.predict(model=model_id, observations={"patches": "sample.zip"})
+job    = client.predict(model=model_id, observation="sample.zip", kind="patches")
 adata  = job.wait().download()
 ```
 

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/src/auroraomics/client/_generated.py

@@ -11,6 +11,10 @@ a contract that ages: the service may add a field in a release this package
 predates, and a client that raised on it would break every caller for an
 addition that breaks nothing. Drift in the other direction — a field this
 package expects and the service stopped sending — still fails, at the model.
+
+A field the schema marks deprecated is optional here even when the schema lists
+it as required: the service has said it will stop sending it, and the release
+that stops must not break this one.
 """
 
 from __future__ import annotations
@@ -289,7 +293,8 @@ class Job(_Model):
     landed: bool
     lane: str
     model: str
-    observation: str
+    observation: str | None = None
+    observation_kind: str
     queue_position: int | None
     started_at: str | None
     state: str
@@ -317,7 +322,8 @@ class PredictionBody(_Model):
 
     covariates: dict[str, str] = Field(default_factory=lambda: {})
     model: str
-    observations: dict[str, str]
+    observation: str | None = None
+    observations: dict[str, str] | None = None
     options: PredictionOptions = Field(default_factory=lambda: {'land_in_workspace': False})
 
 

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/src/auroraomics/client/api.py

@@ -14,6 +14,7 @@ instead of a 404.
 
 from __future__ import annotations
 
+import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Iterable, Iterator, Mapping
 
@@ -51,6 +52,8 @@ from . import uploads as uploads_module
 from .jobs import Job
 
 if TYPE_CHECKING:  # pragma: no cover - for the type checker, never at run time
+    from auroraomics.embed import EmbedReport
+    from auroraomics.pack import PackReport
     from auroraomics.qc import QcThresholds
 
 JOBS_PAGE = 50
@@ -512,22 +515,44 @@ class Client:
         self,
         *,
         model: str,
-        observations: Mapping[str, Any],
+        observation: PackReport | EmbedReport | str | Path | Any = None,
+        kind: str | None = None,
         covariates: Mapping[str, Any] | None = None,
         land_in_workspace: bool = False,
         idempotency_key: str | None = None,
+        observations: Mapping[str, Any] | None = None,
     ) -> Job:
         """Submit a prediction and return the job it created.
 
-        ``observations`` and ``covariates`` map an input KIND to an upload id or,
-        for a covariate the registry declares inline, to its value. A path is
-        uploaded first: passing one is the ordinary case, and making the caller
-        upload by hand to submit would be a second way to do one thing.
+        ``observation`` is the one sample the model reads, given in one of three
+        ways:
+
+        * the report [pack_tiles][auroraomics.pack.pack_tiles] or
+          [embed_tiles][auroraomics.embed.embed_tiles] returned. It carries the
+          file and its kind, so nothing else is needed:
+          ``predict(model=card["id"], observation=report)``;
+        * a path or an open file, with ``kind`` naming which observation kind it
+          is: ``observation="sample.zip", kind="patches"``. A path alone is
+          refused, because a file name does not say how the file was made;
+        * an upload id, from [upload][auroraomics.client.api.Client.upload] or
+          ``start_upload``. The service reads its kind off the upload, so
+          ``kind`` may be left out.
+
+        A report or a path is uploaded first: passing one is the ordinary case,
+        and making the caller upload by hand to submit would be a second way to
+        do one thing. ``covariates`` maps a covariate KIND to an upload id, a
+        path, or, for a kind declared inline, its value.
+
+        ``observations``, a one-entry ``{kind: value}`` mapping, is the earlier
+        spelling of ``observation`` and ``kind`` together. It still submits the
+        same request, and warns.
         """
-        self._refuse_what_the_card_refuses(model, observations, covariates)
+        kind, value = self._the_observation(observation, kind, observations)
+        given = {kind: value} if kind else {}
+        self._refuse_what_the_card_refuses(model, given, covariates)
         body: dict[str, Any] = {
             "model": model,
-            "observations": self._resolve_inputs(observations),
+            "observation": self._resolve_one(kind, value),
             "options": {"land_in_workspace": land_in_workspace},
         }
         if covariates:
@@ -544,6 +569,79 @@ class Client:
             retry_after=errors._retry_after(response.headers.get(errors.RETRY_AFTER_HEADER)),
         )
 
+    def _the_observation(
+        self,
+        observation: Any,
+        kind: str | None,
+        observations: Mapping[str, Any] | None,
+    ) -> tuple[str | None, Any]:
+        """``(kind, value)`` for the one observation, or a refusal naming the fix.
+
+        Every refusal here is made before anything is uploaded or sent. The kind
+        is ``None`` only for an upload id given without one: the service reads
+        it off the upload, and nothing here needs it.
+        """
+        kinds = list(contracts.kinds_in(contracts.OBSERVATION_SLOT))
+        if observations is not None:
+            if observation is not None or kind is not None:
+                raise errors.ClientError(
+                    "pass the observation once: observation= (with kind= for a path), or "
+                    "the earlier observations={kind: value}, not both"
+                )
+            warnings.warn(
+                "observations={kind: value} is the earlier spelling; pass observation= "
+                "instead, with the report pack_tiles or embed_tiles returned, or a path "
+                "and kind=",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            if len(observations) != 1:
+                raise errors.ClientError(
+                    "a submission carries exactly one observation, and this one names "
+                    f"{len(observations)}. Pass one, as observation=; a cohort is one "
+                    "submission per sample."
+                )
+            ((named, value),) = observations.items()
+            return str(named), value
+        if observation is None:
+            raise errors.ClientError(
+                "predict needs the observation: pass observation= the report pack_tiles or "
+                f"embed_tiles returned, an upload id, or a path with kind= one of "
+                f"{_text.listed(kinds)}"
+            )
+        carried = _report_kind(observation)
+        if carried is not None:
+            if kind is not None and kind != carried:
+                raise errors.ClientError(
+                    f"the report carries the kind {carried}, and kind= says "
+                    f"{_text.bounded(kind)}; a report carries its own kind, so leave kind= out"
+                )
+            return carried, observation.path
+        if kind is not None and kind not in kinds:
+            raise errors.ClientError(
+                f"kind= takes an observation kind, {_text.listed(kinds)}, and was "
+                f"given {_text.bounded(kind)}"
+            )
+        # Asked only without a kind: with one, a file is what kind= says it is.
+        source = _upload_source(observation) if kind is None else None
+        if source is not None:
+            name = getattr(source, "name", None) or "this file"
+            raise errors.ClientError(
+                f"{_text.bounded(str(Path(str(name)).name))} is a file, and a file does not say "
+                f"which kind of observation it is: pass kind= one of {_text.listed(kinds)}, "
+                "or pass the report pack_tiles or embed_tiles returned, which carries it"
+            )
+        return kind, observation
+
+    def _resolve_one(self, kind: str | None, value: Any) -> str:
+        """One value as the upload id the body sends, uploading it first when it
+        is a file. The one upload-or-pass-through rule: the observation goes
+        through it, and ``_resolve_inputs`` maps it over the covariates."""
+        source = _upload_source(value)
+        if source is None:
+            return str(value)
+        return self.upload(source, kind=str(kind)).upload_id
+
     def _refuse_what_the_card_refuses(
         self,
         model: str,
@@ -566,9 +664,10 @@ class Client:
         be read is not a reason to refuse a valid submission, so a failure here
         falls through to the service's own answer.
 
-        The slot names are the ones ``predict`` writes into the body above, not
-        a second vocabulary: what a card accepts is keyed the way a submission
-        is.
+        The slot names are the registry's, the keys of a card's ``accepts``:
+        ``observations`` holds the kinds a card reads, which is why it is
+        plural, and the one observation ``predict`` sends is checked against
+        it by its kind.
 
         And it is skipped when nothing WILL be uploaded. The whole argument for
         reading a catalogue before the submission is the upload it saves, so a
@@ -633,9 +732,8 @@ class Client:
         )
         if not isinstance(reference, Mapping) or not reference.get("reference"):
             return
-        upload_prefix = contracts.id_prefixes()["upload"]
         for kind, value in observations.items():
-            source = _upload_source(value, upload_prefix)
+            source = _upload_source(value)
             if not isinstance(source, Path):
                 continue
             try:
@@ -662,18 +760,12 @@ class Client:
     def _resolve_inputs(self, given: Mapping[str, Any]) -> dict[str, str]:
         """Upload ids as given; a path or a file object uploaded first.
 
-        Which of the two a value is, is ``_upload_source``'s question and only
-        its question — the pre-flight gate above asks the same one, and a second
-        copy of the answer here is how the two would come to disagree.
+        ``_resolve_one`` per kind. Which of the two a value is, is
+        ``_upload_source``'s question and only its question — the pre-flight
+        gate above asks the same one, and a second copy of the answer here is
+        how the two would come to disagree.
         """
-        upload_prefix = contracts.id_prefixes()["upload"]
-        resolved: dict[str, str] = {}
-        for kind, value in given.items():
-            source = _upload_source(value, upload_prefix)
-            resolved[kind] = (
-                str(value) if source is None else self.upload(source, kind=kind).upload_id
-            )
-        return resolved
+        return {kind: self._resolve_one(kind, value) for kind, value in given.items()}
 
     def _would_upload(self, *slots: Mapping[str, Any] | None) -> bool:
         """Whether ``_resolve_inputs`` would send bytes for any of these.
@@ -687,9 +779,8 @@ class Client:
         No I/O: the id prefix is the vendored contract's, and
         ``_looks_like_a_path`` is a string test with at most a ``stat``.
         """
-        upload_prefix = contracts.id_prefixes()["upload"]
         return any(
-            _upload_source(value, upload_prefix) is not None
+            _upload_source(value) is not None
             for slot in slots
             for value in (slot or {}).values()
         )
@@ -755,12 +846,28 @@ def _bearer(token: str) -> dict[str, str]:
     return {"Authorization": f"Bearer {token}"}
 
 
-def _upload_source(value: Any, upload_prefix: str) -> Any | None:
+def _report_kind(value: Any) -> str | None:
+    """The kind a packer's report carries, or ``None`` for anything else.
+
+    Read by shape, not by class: both reports have a ``path`` and a ``kind``,
+    and importing their modules here to ask ``isinstance`` would make the
+    client load the image stack it otherwise never needs. A path, a string, an
+    upload id and a file object have no ``kind``, so none of them is mistaken
+    for a report.
+    """
+    kind = getattr(value, "kind", None)
+    if isinstance(kind, str) and isinstance(getattr(value, "path", None), Path):
+        return kind
+    return None
+
+
+def _upload_source(value: Any) -> Any | None:
     """What a submission would UPLOAD for this value, or ``None`` if it is an id.
 
-    The one place the question is answered. ``_resolve_inputs`` uploads what
-    comes back and passes the value through when it is ``None``; the pre-flight
-    gate asks only whether anything comes back at all.
+    The one place the question is answered, and the one place the upload id's
+    prefix is read for it. ``_resolve_one`` uploads what comes back and passes
+    the value through when it is ``None``; the pre-flight gate asks only whether
+    anything comes back at all.
 
     A file object is recognised by having ``read``, not by descending from
     ``io.IOBase``: a ``BytesIO``, a ``gzip`` reader and a member of an open
@@ -773,7 +880,7 @@ def _upload_source(value: Any, upload_prefix: str) -> Any | None:
     if isinstance(value, Path) or hasattr(value, "read"):
         return value
     text = str(value)
-    if text.startswith(upload_prefix) or not _looks_like_a_path(text):
+    if text.startswith(contracts.id_prefixes()["upload"]) or not _looks_like_a_path(text):
         return None
     return Path(text)
 

{auroraomics-0.1.0.dev3 → auroraomics-0.1.0.dev4}/src/auroraomics/client/errors.py

@@ -12,7 +12,7 @@ Catching is by class, at whichever width the caller wants:
 
 ```python
 try:
-    job = client.predict(model=model_id, observations={"patches": "sample.zip"})
+    job = client.predict(model=model_id, observation="sample.zip", kind="patches")
 except QuotaExceededError as exc:      # one code
     wait_until_tomorrow(exc.retry_after)
 except LimitExceededError:             # every 413/429 code