euler-inference 2.7.0__tar.gz → 2.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. euler_inference-2.9.0/PKG-INFO +361 -0
  2. euler_inference-2.9.0/README.md +342 -0
  3. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/_outputs.py +215 -4
  4. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/api.py +11 -4
  5. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/config.py +118 -15
  6. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/inference.py +95 -27
  7. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/model_card.py +24 -8
  8. euler_inference-2.9.0/euler_inference.egg-info/PKG-INFO +361 -0
  9. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/SOURCES.txt +2 -0
  10. {euler_inference-2.7.0 → euler_inference-2.9.0}/pyproject.toml +16 -1
  11. {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_intrinsics_resolution.py +19 -11
  12. {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_model_card.py +3 -5
  13. {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_model_metadata.py +5 -5
  14. euler_inference-2.9.0/tests/test_sampling.py +141 -0
  15. {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_save_path.py +0 -88
  16. euler_inference-2.9.0/tests/test_source_grid.py +178 -0
  17. {euler_inference-2.7.0 → euler_inference-2.9.0}/tests/test_writer_integration.py +49 -4
  18. euler_inference-2.7.0/PKG-INFO +0 -13
  19. euler_inference-2.7.0/README.md +0 -613
  20. euler_inference-2.7.0/euler_inference.egg-info/PKG-INFO +0 -13
  21. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/__init__.py +0 -0
  22. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/__main__.py +0 -0
  23. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/models/__init__.py +0 -0
  24. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference/models/external_model.py +0 -0
  25. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/dependency_links.txt +0 -0
  26. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/entry_points.txt +0 -0
  27. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/requires.txt +0 -0
  28. {euler_inference-2.7.0 → euler_inference-2.9.0}/euler_inference.egg-info/top_level.txt +0 -0
  29. {euler_inference-2.7.0 → euler_inference-2.9.0}/setup.cfg +0 -0
@@ -0,0 +1,361 @@
1
+ Metadata-Version: 2.4
2
+ Name: euler-inference
3
+ Version: 2.9.0
4
+ Summary: Modality-agnostic inference pipeline using euler-loading
5
+ Author-email: Daniel Rothenpieler <rothenpielerdaniel@gmail.com>
6
+ Project-URL: Homepage, https://github.com/d-rothen/euler-inference
7
+ Project-URL: Repository, https://github.com/d-rothen/euler-inference
8
+ Project-URL: Issues, https://github.com/d-rothen/euler-inference/issues
9
+ Keywords: machine-learning,inference,multimodal,datasets
10
+ Requires-Python: >=3.10
11
+ Description-Content-Type: text/markdown
12
+ Requires-Dist: torch>=2.0.0
13
+ Requires-Dist: numpy
14
+ Requires-Dist: Pillow
15
+ Requires-Dist: euler-loading
16
+ Requires-Dist: tqdm
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest; extra == "dev"
19
+
20
+ <!-- euler header — shared across the euler packages.
21
+ Per package, change only: the <h1>, the tagline, and the badge URLs. -->
22
+ <p align="center">
23
+ <img src="https://files.chronodle.com/icons/euler.svg" alt="euler" width="96" height="96">
24
+ </p>
25
+
26
+ <h1 align="center">euler-inference</h1>
27
+
28
+ <p align="center">
29
+ <em>A small, modality-agnostic runner for applying Python models to indexed datasets.</em>
30
+ </p>
31
+
32
+ <p align="center">
33
+ <a href="https://pypi.org/project/euler-inference/"><img alt="PyPI" src="https://img.shields.io/pypi/v/euler-inference?color=0A7BBB"></a>
34
+ <a href="https://www.python.org/"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
35
+ </p>
36
+
37
+ ---
38
+
39
+ `euler-inference` connects an in-process model to one or more
40
+ [`euler-loading`](https://github.com/d-rothen/euler-loading) modalities. It
41
+ intersects their dataset IDs, loads synchronized samples, runs `predict()`, and
42
+ writes indexed outputs while preserving source paths when possible.
43
+
44
+ ```text
45
+ indexed modalities → euler-loading → Model.predict(inputs) → indexed outputs
46
+ ```
47
+
48
+ ## Quick start
49
+
50
+ Install the package:
51
+
52
+ ```bash
53
+ pip install euler-inference
54
+ ```
55
+
56
+ Create a model file. The pipeline deliberately keeps the contract tiny:
57
+
58
+ ```python
59
+ # /absolute/path/to/model.py
60
+ import numpy as np
61
+
62
+
63
+ class Model:
64
+ OUTPUTS = [{"key": "depth", "type": "npy"}]
65
+
66
+ def __init__(self, config: dict, device: str | None = None):
67
+ self.scale = config.get("scale", 1.0)
68
+
69
+ def predict(self, inputs: dict) -> dict:
70
+ height, width = inputs["rgb"].shape[-2:]
71
+ depth = np.ones((height, width), dtype=np.float32) * self.scale
72
+ return {"depth": depth}
73
+ ```
74
+
75
+ Point a config at the model and an indexed modality:
76
+
77
+ ```json
78
+ {
79
+ "external_model": {
80
+ "model_path": "/absolute/path/to/model.py",
81
+ "model_config": {"scale": 2.0}
82
+ },
83
+ "dataset": {
84
+ "modalities": {"rgb": "/data/vkitti2/rgb"}
85
+ },
86
+ "output_base_path": "/data/predictions",
87
+ "sample": 0.1,
88
+ "sample_mode": "random"
89
+ }
90
+ ```
91
+
92
+ Run it:
93
+
94
+ ```bash
95
+ euler-inference --config config.json
96
+ ```
97
+
98
+ The dataset directories or zip archives must contain `ds-crawler` metadata.
99
+ `euler-loading` resolves each loader from that metadata, so the model receives
100
+ the native loaded value: for example a NumPy array or torch tensor.
101
+
102
+ ## Sampling
103
+
104
+ `sample` limits work before any files are loaded:
105
+
106
+ | Value | Meaning |
107
+ | --- | --- |
108
+ | omitted | Process every synchronized dataset ID |
109
+ | integer greater than `1` | Process at most that many IDs |
110
+ | float between `0` and `1` | Process that fraction of all IDs |
111
+
112
+ Fractional counts round down, with a minimum of one sample for a non-empty
113
+ dataset. Counts larger than the dataset are capped at its size.
114
+
115
+ `sample_mode` controls which IDs are chosen:
116
+
117
+ - `sequential` (default) selects the first IDs in dataset order.
118
+ - `random` selects uniformly without replacement from the complete set of
119
+ synchronized IDs.
120
+
121
+ ```bash
122
+ euler-inference -c config.json --sample 250 --sample-mode sequential
123
+ euler-inference -c config.json --sample 0.05 --sample-mode random
124
+ ```
125
+
126
+ ## Model contract
127
+
128
+ The external file must define `Model` with these methods:
129
+
130
+ ```python
131
+ class Model:
132
+ def __init__(self, config: dict, device: str | None = None): ...
133
+ def predict(self, inputs: dict) -> dict: ...
134
+ ```
135
+
136
+ - `config` is `external_model.model_config`, or `{}` when omitted.
137
+ - `inputs` contains every regular and hierarchical modality by its configured
138
+ name. Loader metadata determines each value's type.
139
+ - `predict()` runs once per sample and returns a dict keyed by configured
140
+ output names.
141
+ - The model runs in the current process, so its dependencies must be installed
142
+ in the active environment.
143
+
144
+ Models may declare two optional class attributes:
145
+
146
+ ```python
147
+ class Model:
148
+ OUTPUTS = [{"key": "depth", "type": "npy"}]
149
+ DEFAULT_CONFIG = {"backbone": "resnet50"}
150
+ ```
151
+
152
+ User-provided model config takes precedence over `DEFAULT_CONFIG`. Explicit
153
+ config `outputs` take precedence over `OUTPUTS`.
154
+
155
+ ## Configuration
156
+
157
+ The complete monolithic example lives at
158
+ [`configs/example_external_model.json`](configs/example_external_model.json).
159
+
160
+ | Key | Required | Description |
161
+ | --- | --- | --- |
162
+ | `external_model.model_path` | yes | Absolute path to the Python model file |
163
+ | `external_model.model_config` | no | Dict or path to a JSON object passed to `Model` |
164
+ | `dataset.modalities` | yes | Named regular modality paths; IDs are intersected |
165
+ | `dataset.hierarchical_modalities` | no | Named values inherited down a dataset hierarchy |
166
+ | `output_base_path` | yes | Root for prediction datasets |
167
+ | `outputs` | no | Output keys, formats, and writer settings |
168
+ | `device` | no | `cpu`, `cuda`, or `mps`; passed through to the model |
169
+ | `sample` | no | Integer count or fractional dataset size |
170
+ | `sample_mode` | no | `sequential` or `random` |
171
+ | `zip` | no | Write each output as a zip dataset |
172
+ | `strict` | no | Require known modality metadata; default `true` |
173
+
174
+ A modality can be a path string or a structured entry:
175
+
176
+ ```json
177
+ {
178
+ "dataset": {
179
+ "modalities": {
180
+ "rgb": "/data/rgb",
181
+ "depth": {"path": "/data/depth", "split": "test"},
182
+ "image": {
183
+ "path": "/data/multi-modal.zip",
184
+ "metadata_scope": "rgb",
185
+ "modality_key": "rgb"
186
+ }
187
+ }
188
+ }
189
+ }
190
+ ```
191
+
192
+ `split` selects an inline ds-crawler split. `metadata_scope` disambiguates
193
+ multiple indexed modalities at the same physical path; in deterministic cases
194
+ it is inferred from the input name or `modality_key`.
195
+
196
+ ### Outputs
197
+
198
+ Each output accepts `key`, `type`, optional `suffix`, optional writer metadata,
199
+ optional `source_modality`, and optional `source_grid`:
200
+
201
+ ```json
202
+ {
203
+ "outputs": [
204
+ {"key": "rgb", "type": "png"},
205
+ {
206
+ "key": "depth",
207
+ "type": "npy",
208
+ "writer": {
209
+ "euler_loading": {
210
+ "loader": "generic_dense_depth",
211
+ "function": "depth"
212
+ },
213
+ "meta": {"radial_depth": false, "scale_to_meters": 1.0}
214
+ }
215
+ }
216
+ ]
217
+ }
218
+ ```
219
+
220
+ When an output key matches an input modality—or `source_modality` names
221
+ one—the source writer and relative filename are mirrored. Otherwise the legacy
222
+ serializer writes `{sample_id}{suffix}.{type}` beneath the sample hierarchy.
223
+ Supported legacy formats are `npy`, `npz`, `png`, `jpg`, `jpeg`, and `exr`.
224
+
225
+ ### How an output relates to its input (`source_grid`)
226
+
227
+ A model that crops or resizes its input returns an output on another pixel
228
+ grid than the image it came from. The shapes alone cannot tell whether a
229
+ 400×872 depth map is the top-left of a 400×879 input or a squeezed copy of
230
+ it, so declare it per output:
231
+
232
+ ```python
233
+ class Model:
234
+ OUTPUTS = [{"key": "depth", "type": "npy", "source_grid": "crop_top_left"}]
235
+ ```
236
+
237
+ | `source_grid` | The output is |
238
+ |---|---|
239
+ | `"identity"` | on the input's grid (sizes must match) |
240
+ | `"resize"` | the whole input stretched to the output size |
241
+ | `"crop_top_left"` | the top-left part of the input, e.g. a latent model that floors each side to a multiple of 8 |
242
+ | `"crop_center"` | the centred part of the input |
243
+
244
+ The input defaults to `source_modality`, else the only regular modality, else
245
+ the only RGB one; name it with `{"rule": "resize", "source": "rgb"}`
246
+ otherwise. For every sample, euler-inference turns the rule and the actual
247
+ input and output sizes into euler-dataset-contract's exact `source_grid`
248
+ (source size plus affine pixel mapping) and writes it to that file's
249
+ attributes. When every sample gets the same one, it also goes into the
250
+ output's dataset head (`modality.meta.source_grid`). euler-eval reads it to
251
+ score the prediction on the right pixels. An output whose size differs from
252
+ its input's without a declared rule logs a warning, and evaluation falls back
253
+ to guessing. Recording needs euler-dataset-contract with `source_grid`
254
+ support.
255
+
256
+ #### Known limitation: mappings the sizes do not determine
257
+
258
+ A rule turns into an exact mapping only because the input and output sizes
259
+ pin it down. Some preprocessing does not leave enough in the sizes:
260
+
261
+ - a resize to an intermediate size followed by a crop, such as
262
+ Depth-Anything-3's `upper_bound_crop` / `lower_bound_crop` (resize the long
263
+ or short side to `process_res`, then centre-crop each side down to a
264
+ multiple of 14); the intermediate size cannot be recovered from the input
265
+ and output sizes in general;
266
+ - letterboxing or padding to a fixed size;
267
+ - crops whose position depends on the content or on randomness.
268
+
269
+ None of the four rules describes these, and declaring the nearest one
270
+ records a wrong mapping. Until models can report it themselves, either make
271
+ such an output land on a rule-describable grid (resize or pad it back onto
272
+ the input grid and declare `identity`, or pick a preprocessing mode that is
273
+ a plain resize, like Depth-Anything-3's default `upper_bound_resize`), or
274
+ declare no `source_grid` and set euler-eval's `spatial_alignment` by hand.
275
+
276
+ **Open design question (deferred):** let a model return the exact
277
+ `source_grid` matrix per sample, which euler-dataset-contract can already
278
+ store. That needs a channel in the model contract, for example an optional
279
+ reserved `"source_grid"` key in `predict()`'s result mapping output keys to
280
+ matrices, or an optional `Model.source_grid(inputs, outputs)` method.
281
+ Either way euler-inference would validate the matrix
282
+ (`euler_dataset_contract.validate_source_grid`) and record it exactly as it
283
+ records rule-derived ones.
284
+
285
+ ## Model cards
286
+
287
+ A model card keeps model-owned metadata beside the model and leaves paths to
288
+ the operator. Placeholders use `{{type:name}}` syntax:
289
+
290
+ ```json
291
+ {
292
+ "model": "./model.py",
293
+ "checkpoint": "{{checkpoint:weights}}",
294
+ "inputs": {"rgb": "{{modality:rgb}}"},
295
+ "outputs": [{"key": "depth", "type": "npy"}],
296
+ "sample": 100,
297
+ "sample_mode": "random"
298
+ }
299
+ ```
300
+
301
+ ```bash
302
+ euler-inference \
303
+ --model-card model_card.json \
304
+ --set weights=/models/weights.pt \
305
+ --data rgb=/data/rgb \
306
+ --output-base-path /data/predictions
307
+ ```
308
+
309
+ Use `--hierarchical-data name=/path` for hierarchical placeholders. See
310
+ [`examples/model_card.json`](examples/model_card.json) and
311
+ [`examples/model_template.py`](examples/model_template.py) for a complete pair.
312
+
313
+ ## Python API
314
+
315
+ ```python
316
+ from euler_inference.api import infer
317
+
318
+ infer(
319
+ model_path="/absolute/path/to/model.py",
320
+ dataset_modalities={"rgb": "/data/rgb"},
321
+ output_base_path="/data/predictions",
322
+ sample=0.1,
323
+ sample_mode="random",
324
+ )
325
+ ```
326
+
327
+ `infer()` also accepts `model_card=`, `bindings=`, `data=`, and
328
+ `hierarchical_data=`. For scheduler-managed output targets, construct an
329
+ `InferenceConfig` with `PipelineRuntimeConfig` and call `run_inference()`.
330
+
331
+ ## Development
332
+
333
+ ```bash
334
+ git clone https://github.com/d-rothen/euler-inference.git
335
+ cd euler-inference
336
+ uv sync --extra dev
337
+ uv run pytest -q
338
+ ```
339
+
340
+ The unit suite uses synthetic datasets and does not require model weights or a
341
+ GPU. Contributions should keep the model boundary modality-agnostic and add a
342
+ focused regression test for behavior changes.
343
+
344
+ The VKITTI2 integration checks are opt-in:
345
+
346
+ ```bash
347
+ VKITTI2_RGB_PATH=/data/vkitti2/rgb \
348
+ VKITTI2_TEXTGT_PATH=/data/vkitti2/textgt \
349
+ uv run pytest -m real
350
+ ```
351
+
352
+ ## Common integration mistakes
353
+
354
+ - `model_path` in a monolithic config must be absolute.
355
+ - Output keys returned by `predict()` must match configured `outputs[].key`.
356
+ - Relative imports in dynamically loaded model files are fragile; add the
357
+ model directory to `sys.path` or package the model code.
358
+ - Explicit `source_modality` values must name a regular input with a resolvable
359
+ euler-loading writer.
360
+ - A model that crops or resizes its input without declaring `source_grid`
361
+ leaves evaluation to guess which one it did.
@@ -0,0 +1,342 @@
1
+ <!-- euler header — shared across the euler packages.
2
+ Per package, change only: the <h1>, the tagline, and the badge URLs. -->
3
+ <p align="center">
4
+ <img src="https://files.chronodle.com/icons/euler.svg" alt="euler" width="96" height="96">
5
+ </p>
6
+
7
+ <h1 align="center">euler-inference</h1>
8
+
9
+ <p align="center">
10
+ <em>A small, modality-agnostic runner for applying Python models to indexed datasets.</em>
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://pypi.org/project/euler-inference/"><img alt="PyPI" src="https://img.shields.io/pypi/v/euler-inference?color=0A7BBB"></a>
15
+ <a href="https://www.python.org/"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
16
+ </p>
17
+
18
+ ---
19
+
20
+ `euler-inference` connects an in-process model to one or more
21
+ [`euler-loading`](https://github.com/d-rothen/euler-loading) modalities. It
22
+ intersects their dataset IDs, loads synchronized samples, runs `predict()`, and
23
+ writes indexed outputs while preserving source paths when possible.
24
+
25
+ ```text
26
+ indexed modalities → euler-loading → Model.predict(inputs) → indexed outputs
27
+ ```
28
+
29
+ ## Quick start
30
+
31
+ Install the package:
32
+
33
+ ```bash
34
+ pip install euler-inference
35
+ ```
36
+
37
+ Create a model file. The pipeline deliberately keeps the contract tiny:
38
+
39
+ ```python
40
+ # /absolute/path/to/model.py
41
+ import numpy as np
42
+
43
+
44
+ class Model:
45
+ OUTPUTS = [{"key": "depth", "type": "npy"}]
46
+
47
+ def __init__(self, config: dict, device: str | None = None):
48
+ self.scale = config.get("scale", 1.0)
49
+
50
+ def predict(self, inputs: dict) -> dict:
51
+ height, width = inputs["rgb"].shape[-2:]
52
+ depth = np.ones((height, width), dtype=np.float32) * self.scale
53
+ return {"depth": depth}
54
+ ```
55
+
56
+ Point a config at the model and an indexed modality:
57
+
58
+ ```json
59
+ {
60
+ "external_model": {
61
+ "model_path": "/absolute/path/to/model.py",
62
+ "model_config": {"scale": 2.0}
63
+ },
64
+ "dataset": {
65
+ "modalities": {"rgb": "/data/vkitti2/rgb"}
66
+ },
67
+ "output_base_path": "/data/predictions",
68
+ "sample": 0.1,
69
+ "sample_mode": "random"
70
+ }
71
+ ```
72
+
73
+ Run it:
74
+
75
+ ```bash
76
+ euler-inference --config config.json
77
+ ```
78
+
79
+ The dataset directories or zip archives must contain `ds-crawler` metadata.
80
+ `euler-loading` resolves each loader from that metadata, so the model receives
81
+ the native loaded value: for example a NumPy array or torch tensor.
82
+
83
+ ## Sampling
84
+
85
+ `sample` limits work before any files are loaded:
86
+
87
+ | Value | Meaning |
88
+ | --- | --- |
89
+ | omitted | Process every synchronized dataset ID |
90
+ | integer greater than `1` | Process at most that many IDs |
91
+ | float between `0` and `1` | Process that fraction of all IDs |
92
+
93
+ Fractional counts round down, with a minimum of one sample for a non-empty
94
+ dataset. Counts larger than the dataset are capped at its size.
95
+
96
+ `sample_mode` controls which IDs are chosen:
97
+
98
+ - `sequential` (default) selects the first IDs in dataset order.
99
+ - `random` selects uniformly without replacement from the complete set of
100
+ synchronized IDs.
101
+
102
+ ```bash
103
+ euler-inference -c config.json --sample 250 --sample-mode sequential
104
+ euler-inference -c config.json --sample 0.05 --sample-mode random
105
+ ```
106
+
107
+ ## Model contract
108
+
109
+ The external file must define `Model` with these methods:
110
+
111
+ ```python
112
+ class Model:
113
+ def __init__(self, config: dict, device: str | None = None): ...
114
+ def predict(self, inputs: dict) -> dict: ...
115
+ ```
116
+
117
+ - `config` is `external_model.model_config`, or `{}` when omitted.
118
+ - `inputs` contains every regular and hierarchical modality by its configured
119
+ name. Loader metadata determines each value's type.
120
+ - `predict()` runs once per sample and returns a dict keyed by configured
121
+ output names.
122
+ - The model runs in the current process, so its dependencies must be installed
123
+ in the active environment.
124
+
125
+ Models may declare two optional class attributes:
126
+
127
+ ```python
128
+ class Model:
129
+ OUTPUTS = [{"key": "depth", "type": "npy"}]
130
+ DEFAULT_CONFIG = {"backbone": "resnet50"}
131
+ ```
132
+
133
+ User-provided model config takes precedence over `DEFAULT_CONFIG`. Explicit
134
+ config `outputs` take precedence over `OUTPUTS`.
135
+
136
+ ## Configuration
137
+
138
+ The complete monolithic example lives at
139
+ [`configs/example_external_model.json`](configs/example_external_model.json).
140
+
141
+ | Key | Required | Description |
142
+ | --- | --- | --- |
143
+ | `external_model.model_path` | yes | Absolute path to the Python model file |
144
+ | `external_model.model_config` | no | Dict or path to a JSON object passed to `Model` |
145
+ | `dataset.modalities` | yes | Named regular modality paths; IDs are intersected |
146
+ | `dataset.hierarchical_modalities` | no | Named values inherited down a dataset hierarchy |
147
+ | `output_base_path` | yes | Root for prediction datasets |
148
+ | `outputs` | no | Output keys, formats, and writer settings |
149
+ | `device` | no | `cpu`, `cuda`, or `mps`; passed through to the model |
150
+ | `sample` | no | Integer count or fractional dataset size |
151
+ | `sample_mode` | no | `sequential` or `random` |
152
+ | `zip` | no | Write each output as a zip dataset |
153
+ | `strict` | no | Require known modality metadata; default `true` |
154
+
155
+ A modality can be a path string or a structured entry:
156
+
157
+ ```json
158
+ {
159
+ "dataset": {
160
+ "modalities": {
161
+ "rgb": "/data/rgb",
162
+ "depth": {"path": "/data/depth", "split": "test"},
163
+ "image": {
164
+ "path": "/data/multi-modal.zip",
165
+ "metadata_scope": "rgb",
166
+ "modality_key": "rgb"
167
+ }
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ `split` selects an inline ds-crawler split. `metadata_scope` disambiguates
174
+ multiple indexed modalities at the same physical path; in deterministic cases
175
+ it is inferred from the input name or `modality_key`.
176
+
177
+ ### Outputs
178
+
179
+ Each output accepts `key`, `type`, optional `suffix`, optional writer metadata,
180
+ optional `source_modality`, and optional `source_grid`:
181
+
182
+ ```json
183
+ {
184
+ "outputs": [
185
+ {"key": "rgb", "type": "png"},
186
+ {
187
+ "key": "depth",
188
+ "type": "npy",
189
+ "writer": {
190
+ "euler_loading": {
191
+ "loader": "generic_dense_depth",
192
+ "function": "depth"
193
+ },
194
+ "meta": {"radial_depth": false, "scale_to_meters": 1.0}
195
+ }
196
+ }
197
+ ]
198
+ }
199
+ ```
200
+
201
+ When an output key matches an input modality—or `source_modality` names
202
+ one—the source writer and relative filename are mirrored. Otherwise the legacy
203
+ serializer writes `{sample_id}{suffix}.{type}` beneath the sample hierarchy.
204
+ Supported legacy formats are `npy`, `npz`, `png`, `jpg`, `jpeg`, and `exr`.
205
+
206
+ ### How an output relates to its input (`source_grid`)
207
+
208
+ A model that crops or resizes its input returns an output on another pixel
209
+ grid than the image it came from. The shapes alone cannot tell whether a
210
+ 400×872 depth map is the top-left of a 400×879 input or a squeezed copy of
211
+ it, so declare it per output:
212
+
213
+ ```python
214
+ class Model:
215
+ OUTPUTS = [{"key": "depth", "type": "npy", "source_grid": "crop_top_left"}]
216
+ ```
217
+
218
+ | `source_grid` | The output is |
219
+ |---|---|
220
+ | `"identity"` | on the input's grid (sizes must match) |
221
+ | `"resize"` | the whole input stretched to the output size |
222
+ | `"crop_top_left"` | the top-left part of the input, e.g. a latent model that floors each side to a multiple of 8 |
223
+ | `"crop_center"` | the centred part of the input |
224
+
225
+ The input defaults to `source_modality`, else the only regular modality, else
226
+ the only RGB one; name it with `{"rule": "resize", "source": "rgb"}`
227
+ otherwise. For every sample, euler-inference turns the rule and the actual
228
+ input and output sizes into euler-dataset-contract's exact `source_grid`
229
+ (source size plus affine pixel mapping) and writes it to that file's
230
+ attributes. When every sample gets the same one, it also goes into the
231
+ output's dataset head (`modality.meta.source_grid`). euler-eval reads it to
232
+ score the prediction on the right pixels. An output whose size differs from
233
+ its input's without a declared rule logs a warning, and evaluation falls back
234
+ to guessing. Recording needs euler-dataset-contract with `source_grid`
235
+ support.
236
+
237
+ #### Known limitation: mappings the sizes do not determine
238
+
239
+ A rule turns into an exact mapping only because the input and output sizes
240
+ pin it down. Some preprocessing does not leave enough in the sizes:
241
+
242
+ - a resize to an intermediate size followed by a crop, such as
243
+ Depth-Anything-3's `upper_bound_crop` / `lower_bound_crop` (resize the long
244
+ or short side to `process_res`, then centre-crop each side down to a
245
+ multiple of 14); the intermediate size cannot be recovered from the input
246
+ and output sizes in general;
247
+ - letterboxing or padding to a fixed size;
248
+ - crops whose position depends on the content or on randomness.
249
+
250
+ None of the four rules describes these, and declaring the nearest one
251
+ records a wrong mapping. Until models can report it themselves, either make
252
+ such an output land on a rule-describable grid (resize or pad it back onto
253
+ the input grid and declare `identity`, or pick a preprocessing mode that is
254
+ a plain resize, like Depth-Anything-3's default `upper_bound_resize`), or
255
+ declare no `source_grid` and set euler-eval's `spatial_alignment` by hand.
256
+
257
+ **Open design question (deferred):** let a model return the exact
258
+ `source_grid` matrix per sample, which euler-dataset-contract can already
259
+ store. That needs a channel in the model contract, for example an optional
260
+ reserved `"source_grid"` key in `predict()`'s result mapping output keys to
261
+ matrices, or an optional `Model.source_grid(inputs, outputs)` method.
262
+ Either way euler-inference would validate the matrix
263
+ (`euler_dataset_contract.validate_source_grid`) and record it exactly as it
264
+ records rule-derived ones.
265
+
266
+ ## Model cards
267
+
268
+ A model card keeps model-owned metadata beside the model and leaves paths to
269
+ the operator. Placeholders use `{{type:name}}` syntax:
270
+
271
+ ```json
272
+ {
273
+ "model": "./model.py",
274
+ "checkpoint": "{{checkpoint:weights}}",
275
+ "inputs": {"rgb": "{{modality:rgb}}"},
276
+ "outputs": [{"key": "depth", "type": "npy"}],
277
+ "sample": 100,
278
+ "sample_mode": "random"
279
+ }
280
+ ```
281
+
282
+ ```bash
283
+ euler-inference \
284
+ --model-card model_card.json \
285
+ --set weights=/models/weights.pt \
286
+ --data rgb=/data/rgb \
287
+ --output-base-path /data/predictions
288
+ ```
289
+
290
+ Use `--hierarchical-data name=/path` for hierarchical placeholders. See
291
+ [`examples/model_card.json`](examples/model_card.json) and
292
+ [`examples/model_template.py`](examples/model_template.py) for a complete pair.
293
+
294
+ ## Python API
295
+
296
+ ```python
297
+ from euler_inference.api import infer
298
+
299
+ infer(
300
+ model_path="/absolute/path/to/model.py",
301
+ dataset_modalities={"rgb": "/data/rgb"},
302
+ output_base_path="/data/predictions",
303
+ sample=0.1,
304
+ sample_mode="random",
305
+ )
306
+ ```
307
+
308
+ `infer()` also accepts `model_card=`, `bindings=`, `data=`, and
309
+ `hierarchical_data=`. For scheduler-managed output targets, construct an
310
+ `InferenceConfig` with `PipelineRuntimeConfig` and call `run_inference()`.
311
+
312
+ ## Development
313
+
314
+ ```bash
315
+ git clone https://github.com/d-rothen/euler-inference.git
316
+ cd euler-inference
317
+ uv sync --extra dev
318
+ uv run pytest -q
319
+ ```
320
+
321
+ The unit suite uses synthetic datasets and does not require model weights or a
322
+ GPU. Contributions should keep the model boundary modality-agnostic and add a
323
+ focused regression test for behavior changes.
324
+
325
+ The VKITTI2 integration checks are opt-in:
326
+
327
+ ```bash
328
+ VKITTI2_RGB_PATH=/data/vkitti2/rgb \
329
+ VKITTI2_TEXTGT_PATH=/data/vkitti2/textgt \
330
+ uv run pytest -m real
331
+ ```
332
+
333
+ ## Common integration mistakes
334
+
335
+ - `model_path` in a monolithic config must be absolute.
336
+ - Output keys returned by `predict()` must match configured `outputs[].key`.
337
+ - Relative imports in dynamically loaded model files are fragile; add the
338
+ model directory to `sys.path` or package the model code.
339
+ - Explicit `source_modality` values must name a regular input with a resolvable
340
+ euler-loading writer.
341
+ - A model that crops or resizes its input without declaring `source_grid`
342
+ leaves evaluation to guess which one it did.