singlepipe 0.1.0__tar.gz → 0.2.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 (33) hide show
  1. {singlepipe-0.1.0/singlepipe.egg-info → singlepipe-0.2.0}/PKG-INFO +119 -38
  2. singlepipe-0.2.0/README.md +296 -0
  3. {singlepipe-0.1.0 → singlepipe-0.2.0}/pyproject.toml +1 -1
  4. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/__init__.py +2 -2
  5. singlepipe-0.2.0/singlepipe/_fanout.py +111 -0
  6. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/adapters/base.py +42 -2
  7. singlepipe-0.2.0/singlepipe/ops.py +49 -0
  8. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/modalities/image.py +140 -16
  9. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/primitives.py +42 -8
  10. {singlepipe-0.1.0 → singlepipe-0.2.0/singlepipe.egg-info}/PKG-INFO +119 -38
  11. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/SOURCES.txt +4 -0
  12. singlepipe-0.2.0/tests/test_fanout.py +167 -0
  13. singlepipe-0.2.0/tests/test_ops.py +72 -0
  14. singlepipe-0.1.0/README.md +0 -215
  15. {singlepipe-0.1.0 → singlepipe-0.2.0}/LICENSE +0 -0
  16. {singlepipe-0.1.0 → singlepipe-0.2.0}/setup.cfg +0 -0
  17. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/adapters/__init__.py +0 -0
  18. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/adapters/hf_adapter.py +0 -0
  19. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/py.typed +0 -0
  20. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/__init__.py +0 -0
  21. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/containers.py +0 -0
  22. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/contract.py +0 -0
  23. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/__init__.py +0 -0
  24. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/base.py +0 -0
  25. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/classification.py +0 -0
  26. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/detection.py +0 -0
  27. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/modalities/__init__.py +0 -0
  28. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/tasks.py +0 -0
  29. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/dependency_links.txt +0 -0
  30. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/requires.txt +0 -0
  31. {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/top_level.txt +0 -0
  32. {singlepipe-0.1.0 → singlepipe-0.2.0}/tests/test_package.py +0 -0
  33. {singlepipe-0.1.0 → singlepipe-0.2.0}/tests/test_tasks.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: singlepipe
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Typed, async, batching inference for ML models: pydantic schemas in and out, any backend
5
5
  Author-email: Gleb <glebov274@gmail.com>
6
6
  License-Expression: MIT
@@ -43,8 +43,10 @@ typed objects your editor and mypy understand, and the model runs off the event
43
43
  loop with dynamic batching — so several models can work together in one
44
44
  program or one FastAPI service.
45
45
 
46
- > **Status: alpha (0.1.0).** Image classification and object detection on
47
- > HuggingFace models. The API will change before 1.0.
46
+ > **Status: alpha (0.2.0).** Image classification and object detection on
47
+ > HuggingFace models, plus the glue between models: crops, coordinates and
48
+ > fan-out. The API will change before 1.0; breaking changes are listed in
49
+ > `CHANGELOG.md`.
48
50
 
49
51
  ## Install
50
52
 
@@ -53,8 +55,8 @@ pip install "singlepipe[hf]" # HuggingFace models (transformers + torch)
53
55
  pip install "singlepipe[detr]" # + timm, for DETR detection models
54
56
  ```
55
57
 
56
- The core (`pip install singlepipe`) has no ML backend: schemas, tasks and image
57
- handling only. Python 3.12+.
58
+ The core (`pip install singlepipe`) has no ML backend: schemas, tasks, image
59
+ handling and glue only. Python 3.12+.
58
60
 
59
61
  ## Quick start
60
62
 
@@ -68,7 +70,7 @@ from singlepipe.adapters.hf_adapter import HFAdapter
68
70
  async def main() -> None:
69
71
  classifier = HFAdapter("google/vit-base-patch16-224", sp.tasks.image_classification)
70
72
 
71
- out = await classifier("cats.jpg") # path, URL, bytes, PIL, numpy, torch tensor
73
+ out = await classifier("cats.jpg") # path, URL, data URI, bytes, PIL, numpy, torch tensor
72
74
  best = out.predictions.top1 # typed: Prediction | None
73
75
  if best:
74
76
  print(best.label, best.score)
@@ -94,14 +96,15 @@ for det in out.predictions.filter_by_label("cat").filter_by_score(0.9):
94
96
  ```
95
97
 
96
98
  Boxes are in pixels of the original image (`out.image_width`, `out.image_height`)
97
- and are returned as the model gave them — `BBox.clip` is there if you need it.
99
+ and are returned as the model gave them — even partly outside the image, on any
100
+ side, as detectors do for objects at the edge. `box.clip(w, h)` cuts a box to
101
+ the image; `image.crop(box)` does that by itself.
98
102
 
99
- ## Batching: detect, crop, classify
100
-
101
- Calls are written one at a time; concurrent calls are grouped into batches by
102
- the adapter.
103
+ ## Many models: detect, crop, classify
103
104
 
104
105
  ```python
106
+ from collections import Counter
107
+
105
108
  from singlepipe.schemas.modalities import Image
106
109
 
107
110
  detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
@@ -113,24 +116,88 @@ classifier = HFAdapter(
113
116
  )
114
117
 
115
118
 
116
- async def shelf(path: str) -> list[str]:
119
+ async def shelf(path: str) -> Counter[str]:
117
120
  image = Image(path)
118
- detections = await detector(image)
119
- bottles = detections.predictions.filter_by_label("bottle").filter_by_score(0.5)
121
+ dets = await detector(image)
122
+ bottles = dets.predictions.filter_by_label("bottle").filter_by_score(0.5)
123
+
124
+ crops = sp.ops.crops(image, bottles, scale=1.1) # one crop per box, a little context
125
+ results = await classifier.map(crops) # batched: up to 16 crops per forward pass
126
+ return Counter(r.predictions.top1.label for r in results if r.predictions.top1)
127
+ ```
120
128
 
121
- crops = [image.pil.crop(tuple(round(v) for v in d.box.as_tuple())) for d in bottles]
122
- results = await asyncio.gather(*(classifier(crop) for crop in crops)) # one forward pass
123
- return [r.predictions.top1.label for r in results if r.predictions.top1]
129
+ - **`classifier.map(items)`** sends every item at once, so the adapter batches
130
+ them. A loop of `await classifier(c)` would send them one at a time and
131
+ batching would never kick in. Results come back in input order.
132
+ - **`sp.ops.crops`** cuts one crop per detection (or bare `BBox`). `scale=1.1`
133
+ makes every box 1.1× wider and taller about its center; at the image edge the
134
+ crop simply stops there. For anything per box, write the list comprehension:
135
+ `[image.crop(d.box.scale(k)) for d in dets if ...]`.
136
+ - A crop is clipped to the image and widened to whole pixels; nothing is padded.
137
+
138
+ ### When one item fails
139
+
140
+ By default the first failure cancels the remaining calls and is raised as is —
141
+ a bad input is still a `pydantic.ValidationError` — with a note naming the item:
142
+
143
+ ```
144
+ pydantic_core._pydantic_core.ValidationError: 1 validation error for ...
145
+ HFAdapter(task='image-classification').map: item at index 6 of 14
124
146
  ```
125
147
 
126
- - Each adapter has its own worker thread: independent models run in parallel,
127
- and the event loop stays free (a server keeps answering while a model computes).
128
- - The worker collects up to `max_batch_size` calls, waiting at most `max_wait_ms`
129
- for the first one's company. Calls that arrive while the model is busy join the
130
- next batch on their own.
131
- - Defaults are `max_batch_size=1, max_wait_ms=0`: no batching until you ask for it.
132
- - A bad input is rejected before the queue; a failing batch fails all its calls;
133
- a bad output fails only its own call.
148
+ To keep going, ask for it explicitly; the result type says that an item may be
149
+ an error, so mypy makes you handle it:
150
+
151
+ ```python
152
+ results = await classifier.map(crops, errors="collect")
153
+ # list[ImageClassificationOutput | Exception], same length and order as crops
154
+
155
+ for crop, result in zip(crops, results):
156
+ if isinstance(result, Exception):
157
+ print("failed:", crop.origin, result)
158
+ elif result.predictions.top1:
159
+ print(result.predictions.top1.label)
160
+ ```
161
+
162
+ Which one is right depends on the task: a content filter must not pass an image
163
+ it failed to check; a catalogue search can return 49 results out of 50.
164
+
165
+ ## Cascades: back to the original frame
166
+
167
+ A crop remembers where it was cut (`crop.origin`), so a box found inside it maps
168
+ back to the original image:
169
+
170
+ ```python
171
+ from singlepipe.schemas.primitives import BBox
172
+
173
+
174
+ async def find_plate(frame: Image) -> BBox | None:
175
+ car = (await car_detector(frame)).predictions.filter_by_label("car").top1
176
+ if car is None:
177
+ return None
178
+ car_crop = frame.crop(car.box)
179
+
180
+ plate = (await plate_detector(car_crop)).predictions.top1
181
+ if plate is None:
182
+ return None
183
+ return car_crop.to_frame(plate.box) # in pixels of `frame`
184
+ ```
185
+
186
+ The offset is the region actually cut — after clipping to the image and
187
+ rounding to whole pixels — not the requested box, so the mapped box is exact.
188
+ A crop of a crop maps straight to the first image.
189
+
190
+ ## Images
191
+
192
+ `Image` accepts a file path, an `http(s)://` URL, a base64 data URI, raw bytes,
193
+ a PIL image, a numpy array (HWC or HW) or a torch tensor (CHW), and normalises
194
+ it to RGB. It never guesses silently:
195
+
196
+ - pixel arrays must be `uint8` or float in `[0, 1]`; a float array in `0..255`,
197
+ an `int16` array, NaN or an empty array raise `ValueError` with a hint, instead
198
+ of turning into a white or wrapped-around picture;
199
+ - EXIF orientation is applied, as HuggingFace does: a phone photo reaches the
200
+ model upright, and boxes are in the frame people see.
134
201
 
135
202
  ## Your own task on a HuggingFace model
136
203
 
@@ -140,6 +207,8 @@ line of code.
140
207
  ```python
141
208
  from typing import Any, Self
142
209
 
210
+ import singlepipe as sp
211
+ from singlepipe.adapters.hf_adapter import HFAdapter
143
212
  from singlepipe.schemas.contract import OutputSchema
144
213
  from singlepipe.schemas.image.base import ImageTaskInput
145
214
 
@@ -164,7 +233,7 @@ answer.is_cat # typed: bool
164
233
  ## Your own adapter, any library
165
234
 
166
235
  Everything except the backend call lives in `Adapter`: async calls, validation,
167
- the worker thread, batching, `close()`. A backend implements one method.
236
+ the worker thread, batching, `map`, `close()`. A backend implements one method.
168
237
 
169
238
  ```python
170
239
  from collections.abc import Sequence
@@ -173,9 +242,12 @@ from typing import Any
173
242
  import numpy as np
174
243
  import onnxruntime
175
244
 
245
+ import singlepipe as sp
176
246
  from singlepipe.adapters.base import Adapter
177
- from singlepipe.schemas import ImageClassificationOutput
178
- from singlepipe.schemas.image.classification import ImageClassificationInput
247
+ from singlepipe.schemas.image.classification import (
248
+ ImageClassificationInput,
249
+ ImageClassificationOutput,
250
+ )
179
251
 
180
252
 
181
253
  class OnnxClassifier(Adapter[ImageClassificationInput, ImageClassificationOutput]):
@@ -203,7 +275,7 @@ from contextlib import asynccontextmanager
203
275
 
204
276
  from fastapi import FastAPI
205
277
 
206
- from singlepipe.schemas import ImageClassificationOutput
278
+ from singlepipe.schemas.image.classification import ImageClassificationOutput
207
279
 
208
280
 
209
281
  @asynccontextmanager
@@ -226,23 +298,32 @@ async def classify(url: str) -> ImageClassificationOutput:
226
298
  return await app.state.classifier(url)
227
299
  ```
228
300
 
301
+ > **Do not expose this to untrusted clients yet.** A string given to `Image` may
302
+ > be a local file path or any URL, so a public endpoint like this one can read
303
+ > server files or reach internal hosts. A mode for untrusted input is planned;
304
+ > until then, accept only data URIs or bytes and check them yourself.
305
+
229
306
  ## What is there today
230
307
 
231
- | | |
232
- |---|---|
233
- | Tasks | `image_classification`, `object_detection` |
234
- | Backends | HuggingFace `transformers` pipelines; anything else via `Adapter` |
235
- | Inputs | file path, URL, data URI, bytes, PIL image, numpy array, torch tensor |
236
- | Execution | async calls, a worker thread per model, dynamic batching |
237
- | Typing | outputs typed for mypy without `cast` (`py.typed` included) |
308
+ | | |
309
+ | --------- | --------------------------------------------------------------------- |
310
+ | Tasks | `image_classification`, `object_detection` |
311
+ | Backends | HuggingFace `transformers` pipelines; anything else via `Adapter` |
312
+ | Inputs | file path, URL, data URI, bytes, PIL image, numpy array, torch tensor |
313
+ | Execution | async calls, a worker thread per model, dynamic batching, `map` |
314
+ | Glue | `Image.crop`, `origin`, `to_frame`; `BBox.scale`, `clip`, `iou`; `sp.ops.crops` |
315
+ | Typing | outputs typed for mypy without `cast` (`py.typed` included) |
238
316
 
239
317
  ## Roadmap
240
318
 
241
- - `Image.crop`, `sp.each(adapter)(items)` and other glue for multi-model code
242
- - `@sp.graph`: a graph is an async function, with a run log and FastAPI endpoints
319
+ - `@sp.node` and `@sp.graph`: a graph is an async function — loops, fallbacks and
320
+ parallel branches are plain Python — with a run log, node paths in errors,
321
+ `.map` on any node and FastAPI endpoints
322
+ - Safe mode for untrusted input in FastAPI
243
323
  - `Connector`: picks the adapter from the model object
244
324
  - PyTorch and scikit-learn / XGBoost adapters, tabular tasks
245
325
  - Text and audio tasks
326
+ - Later: a node as a remote service (`sp.serve`, `RemoteAdapter`)
246
327
 
247
328
  ## License
248
329
 
@@ -0,0 +1,296 @@
1
+ # SinglePipe
2
+
3
+ **Typed, async, batching inference for ML models.** Pydantic schemas in and out,
4
+ any backend underneath.
5
+
6
+ SinglePipe does not reimplement HuggingFace, PyTorch or scikit-learn. It puts a
7
+ typed boundary around them: inputs are validated and normalised, outputs are
8
+ typed objects your editor and mypy understand, and the model runs off the event
9
+ loop with dynamic batching — so several models can work together in one
10
+ program or one FastAPI service.
11
+
12
+ > **Status: alpha (0.2.0).** Image classification and object detection on
13
+ > HuggingFace models, plus the glue between models: crops, coordinates and
14
+ > fan-out. The API will change before 1.0; breaking changes are listed in
15
+ > `CHANGELOG.md`.
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ pip install "singlepipe[hf]" # HuggingFace models (transformers + torch)
21
+ pip install "singlepipe[detr]" # + timm, for DETR detection models
22
+ ```
23
+
24
+ The core (`pip install singlepipe`) has no ML backend: schemas, tasks, image
25
+ handling and glue only. Python 3.12+.
26
+
27
+ ## Quick start
28
+
29
+ ```python
30
+ import asyncio
31
+
32
+ import singlepipe as sp
33
+ from singlepipe.adapters.hf_adapter import HFAdapter
34
+
35
+
36
+ async def main() -> None:
37
+ classifier = HFAdapter("google/vit-base-patch16-224", sp.tasks.image_classification)
38
+
39
+ out = await classifier("cats.jpg") # path, URL, data URI, bytes, PIL, numpy, torch tensor
40
+ best = out.predictions.top1 # typed: Prediction | None
41
+ if best:
42
+ print(best.label, best.score)
43
+ print(out.predictions.top(3).labels)
44
+
45
+ classifier.close()
46
+
47
+
48
+ asyncio.run(main())
49
+ ```
50
+
51
+ `out` is an `ImageClassificationOutput`, not a dict: mypy knows it without a
52
+ `cast`. In Jupyter, `await` works directly in a cell.
53
+
54
+ ## Object detection
55
+
56
+ ```python
57
+ detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
58
+
59
+ out = await detector("http://images.cocodataset.org/val2017/000000039769.jpg")
60
+ for det in out.predictions.filter_by_label("cat").filter_by_score(0.9):
61
+ print(det.label, round(det.score, 3), det.box.as_tuple())
62
+ ```
63
+
64
+ Boxes are in pixels of the original image (`out.image_width`, `out.image_height`)
65
+ and are returned as the model gave them — even partly outside the image, on any
66
+ side, as detectors do for objects at the edge. `box.clip(w, h)` cuts a box to
67
+ the image; `image.crop(box)` does that by itself.
68
+
69
+ ## Many models: detect, crop, classify
70
+
71
+ ```python
72
+ from collections import Counter
73
+
74
+ from singlepipe.schemas.modalities import Image
75
+
76
+ detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
77
+ classifier = HFAdapter(
78
+ "my-org/sku-vit",
79
+ sp.tasks.image_classification,
80
+ max_batch_size=16,
81
+ max_wait_ms=5, # dynamic batching
82
+ )
83
+
84
+
85
+ async def shelf(path: str) -> Counter[str]:
86
+ image = Image(path)
87
+ dets = await detector(image)
88
+ bottles = dets.predictions.filter_by_label("bottle").filter_by_score(0.5)
89
+
90
+ crops = sp.ops.crops(image, bottles, scale=1.1) # one crop per box, a little context
91
+ results = await classifier.map(crops) # batched: up to 16 crops per forward pass
92
+ return Counter(r.predictions.top1.label for r in results if r.predictions.top1)
93
+ ```
94
+
95
+ - **`classifier.map(items)`** sends every item at once, so the adapter batches
96
+ them. A loop of `await classifier(c)` would send them one at a time and
97
+ batching would never kick in. Results come back in input order.
98
+ - **`sp.ops.crops`** cuts one crop per detection (or bare `BBox`). `scale=1.1`
99
+ makes every box 1.1× wider and taller about its center; at the image edge the
100
+ crop simply stops there. For anything per box, write the list comprehension:
101
+ `[image.crop(d.box.scale(k)) for d in dets if ...]`.
102
+ - A crop is clipped to the image and widened to whole pixels; nothing is padded.
103
+
104
+ ### When one item fails
105
+
106
+ By default the first failure cancels the remaining calls and is raised as is —
107
+ a bad input is still a `pydantic.ValidationError` — with a note naming the item:
108
+
109
+ ```
110
+ pydantic_core._pydantic_core.ValidationError: 1 validation error for ...
111
+ HFAdapter(task='image-classification').map: item at index 6 of 14
112
+ ```
113
+
114
+ To keep going, ask for it explicitly; the result type says that an item may be
115
+ an error, so mypy makes you handle it:
116
+
117
+ ```python
118
+ results = await classifier.map(crops, errors="collect")
119
+ # list[ImageClassificationOutput | Exception], same length and order as crops
120
+
121
+ for crop, result in zip(crops, results):
122
+ if isinstance(result, Exception):
123
+ print("failed:", crop.origin, result)
124
+ elif result.predictions.top1:
125
+ print(result.predictions.top1.label)
126
+ ```
127
+
128
+ Which one is right depends on the task: a content filter must not pass an image
129
+ it failed to check; a catalogue search can return 49 results out of 50.
130
+
131
+ ## Cascades: back to the original frame
132
+
133
+ A crop remembers where it was cut (`crop.origin`), so a box found inside it maps
134
+ back to the original image:
135
+
136
+ ```python
137
+ from singlepipe.schemas.primitives import BBox
138
+
139
+
140
+ async def find_plate(frame: Image) -> BBox | None:
141
+ car = (await car_detector(frame)).predictions.filter_by_label("car").top1
142
+ if car is None:
143
+ return None
144
+ car_crop = frame.crop(car.box)
145
+
146
+ plate = (await plate_detector(car_crop)).predictions.top1
147
+ if plate is None:
148
+ return None
149
+ return car_crop.to_frame(plate.box) # in pixels of `frame`
150
+ ```
151
+
152
+ The offset is the region actually cut — after clipping to the image and
153
+ rounding to whole pixels — not the requested box, so the mapped box is exact.
154
+ A crop of a crop maps straight to the first image.
155
+
156
+ ## Images
157
+
158
+ `Image` accepts a file path, an `http(s)://` URL, a base64 data URI, raw bytes,
159
+ a PIL image, a numpy array (HWC or HW) or a torch tensor (CHW), and normalises
160
+ it to RGB. It never guesses silently:
161
+
162
+ - pixel arrays must be `uint8` or float in `[0, 1]`; a float array in `0..255`,
163
+ an `int16` array, NaN or an empty array raise `ValueError` with a hint, instead
164
+ of turning into a white or wrapped-around picture;
165
+ - EXIF orientation is applied, as HuggingFace does: a phone photo reaches the
166
+ model upright, and boxes are in the frame people see.
167
+
168
+ ## Your own task on a HuggingFace model
169
+
170
+ A task is a pair of schemas. Built-in tasks are ready objects; a custom one is a
171
+ line of code.
172
+
173
+ ```python
174
+ from typing import Any, Self
175
+
176
+ import singlepipe as sp
177
+ from singlepipe.adapters.hf_adapter import HFAdapter
178
+ from singlepipe.schemas.contract import OutputSchema
179
+ from singlepipe.schemas.image.base import ImageTaskInput
180
+
181
+
182
+ class IsCat(OutputSchema):
183
+ is_cat: bool
184
+ confidence: float
185
+
186
+ @classmethod
187
+ def from_pipeline_output(cls, raw: Any, **context: Any) -> Self:
188
+ cat = next((p for p in raw if "cat" in p["label"]), None)
189
+ return cls(is_cat=cat is not None, confidence=cat["score"] if cat else 0.0)
190
+
191
+
192
+ is_cat = sp.Task("is-cat", ImageTaskInput, IsCat)
193
+ adapter = HFAdapter("google/vit-base-patch16-224", is_cat, hf_task="image-classification")
194
+
195
+ answer = await adapter("cats.jpg")
196
+ answer.is_cat # typed: bool
197
+ ```
198
+
199
+ ## Your own adapter, any library
200
+
201
+ Everything except the backend call lives in `Adapter`: async calls, validation,
202
+ the worker thread, batching, `map`, `close()`. A backend implements one method.
203
+
204
+ ```python
205
+ from collections.abc import Sequence
206
+ from typing import Any
207
+
208
+ import numpy as np
209
+ import onnxruntime
210
+
211
+ import singlepipe as sp
212
+ from singlepipe.adapters.base import Adapter
213
+ from singlepipe.schemas.image.classification import (
214
+ ImageClassificationInput,
215
+ ImageClassificationOutput,
216
+ )
217
+
218
+
219
+ class OnnxClassifier(Adapter[ImageClassificationInput, ImageClassificationOutput]):
220
+ def __init__(self, path: str, labels: list[str], **batching: Any) -> None:
221
+ self.session = onnxruntime.InferenceSession(path) # load the model first,
222
+ self.labels = labels
223
+ super().__init__(sp.tasks.image_classification, **batching) # then start the worker
224
+
225
+ def run_batch(self, inputs: Sequence[Any]) -> Sequence[Any]:
226
+ x = np.stack([preprocess(image) for image in inputs]) # your resize + normalise
227
+ probabilities = self.session.run(None, {"input": x})[0]
228
+ return [
229
+ [{"label": label, "score": float(p)} for label, p in zip(self.labels, row)]
230
+ for row in probabilities
231
+ ]
232
+ ```
233
+
234
+ `run_batch` receives what the input schema produces (here RGB PIL images) and
235
+ returns one raw output per input, in the format the output schema reads.
236
+
237
+ ## FastAPI
238
+
239
+ ```python
240
+ from contextlib import asynccontextmanager
241
+
242
+ from fastapi import FastAPI
243
+
244
+ from singlepipe.schemas.image.classification import ImageClassificationOutput
245
+
246
+
247
+ @asynccontextmanager
248
+ async def lifespan(app: FastAPI):
249
+ app.state.classifier = HFAdapter(
250
+ "google/vit-base-patch16-224",
251
+ sp.tasks.image_classification,
252
+ max_batch_size=32,
253
+ max_wait_ms=10, # concurrent requests share batches
254
+ )
255
+ yield
256
+ app.state.classifier.close()
257
+
258
+
259
+ app = FastAPI(lifespan=lifespan)
260
+
261
+
262
+ @app.post("/classify")
263
+ async def classify(url: str) -> ImageClassificationOutput:
264
+ return await app.state.classifier(url)
265
+ ```
266
+
267
+ > **Do not expose this to untrusted clients yet.** A string given to `Image` may
268
+ > be a local file path or any URL, so a public endpoint like this one can read
269
+ > server files or reach internal hosts. A mode for untrusted input is planned;
270
+ > until then, accept only data URIs or bytes and check them yourself.
271
+
272
+ ## What is there today
273
+
274
+ | | |
275
+ | --------- | --------------------------------------------------------------------- |
276
+ | Tasks | `image_classification`, `object_detection` |
277
+ | Backends | HuggingFace `transformers` pipelines; anything else via `Adapter` |
278
+ | Inputs | file path, URL, data URI, bytes, PIL image, numpy array, torch tensor |
279
+ | Execution | async calls, a worker thread per model, dynamic batching, `map` |
280
+ | Glue | `Image.crop`, `origin`, `to_frame`; `BBox.scale`, `clip`, `iou`; `sp.ops.crops` |
281
+ | Typing | outputs typed for mypy without `cast` (`py.typed` included) |
282
+
283
+ ## Roadmap
284
+
285
+ - `@sp.node` and `@sp.graph`: a graph is an async function — loops, fallbacks and
286
+ parallel branches are plain Python — with a run log, node paths in errors,
287
+ `.map` on any node and FastAPI endpoints
288
+ - Safe mode for untrusted input in FastAPI
289
+ - `Connector`: picks the adapter from the model object
290
+ - PyTorch and scikit-learn / XGBoost adapters, tabular tasks
291
+ - Text and audio tasks
292
+ - Later: a node as a remote service (`sp.serve`, `RemoteAdapter`)
293
+
294
+ ## License
295
+
296
+ MIT
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "singlepipe"
3
- version = "0.1.0"
3
+ version = "0.2.0"
4
4
  description = "Typed, async, batching inference for ML models: pydantic schemas in and out, any backend"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -9,10 +9,10 @@ HFAdapter``.
9
9
 
10
10
  from importlib.metadata import version
11
11
 
12
- from singlepipe import tasks
12
+ from singlepipe import ops, tasks
13
13
  from singlepipe.tasks import Task
14
14
 
15
15
  # One source of truth: the version in pyproject.toml, read from the installed metadata.
16
16
  __version__ = version("singlepipe")
17
17
 
18
- __all__ = ["Task", "tasks"]
18
+ __all__ = ["Task", "__version__", "ops", "tasks"]
@@ -0,0 +1,111 @@
1
+ """Fan-out: run one async call on every item concurrently, results in input order.
2
+
3
+ This is the engine behind ``Adapter.map`` (and later ``.map`` of ``@sp.node``
4
+ and ``@sp.graph`` objects). It is written against "an async callable" only, so
5
+ every kind of node shares one behaviour.
6
+
7
+ Why not a loop or plain ``asyncio.gather``:
8
+
9
+ - a loop of ``await`` calls runs one item at a time, so an adapter's queue never
10
+ holds more than one call and dynamic batching silently does nothing; here all
11
+ calls are started at once;
12
+ - when one call of a ``gather`` fails, the others keep running and keep the
13
+ model busy for results nobody will read; here they are cancelled (an adapter
14
+ drops a cancelled call from its batch before the backend runs);
15
+ - ``TaskGroup`` cancels, but raises an ``ExceptionGroup``; here the original
16
+ exception is raised, so ``except ValueError`` and FastAPI handlers keep
17
+ working, with a note saying which item failed.
18
+
19
+ Notes. An exception gets one note per fan-out, listing every index it failed
20
+ at: an adapter whose whole batch fails sets the *same* exception object on each
21
+ call of the batch, and a note per item would pile them all onto that one object.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import asyncio
27
+ from collections import defaultdict
28
+ from collections.abc import Callable, Coroutine, Iterable, Sequence
29
+ from typing import Any
30
+
31
+
32
+ async def gather_all[T, R](
33
+ call: Callable[[T], Coroutine[Any, Any, R]], items: Iterable[T], *, name: str
34
+ ) -> list[R]:
35
+ """Run ``call`` on every item; on the first failure cancel the rest and raise it.
36
+
37
+ If several items failed before the rest were cancelled, the one with the
38
+ lowest index is raised. Cancellation of the fan-out itself propagates as is.
39
+ """
40
+ batch = list(items)
41
+ tasks: list[asyncio.Task[R]] = []
42
+ failed: BaseException | None = None
43
+ try:
44
+ async with asyncio.TaskGroup() as group:
45
+ tasks = [group.create_task(call(item)) for item in batch]
46
+ except ExceptionGroup as errors:
47
+ failed = _first_failure(tasks, len(batch), name) or errors
48
+ if failed is not None:
49
+ # Raised outside the except block: the ExceptionGroup must not become
50
+ # the context of the original error in the traceback.
51
+ raise failed
52
+ return [task.result() for task in tasks]
53
+
54
+
55
+ async def gather_settled[T, R](
56
+ call: Callable[[T], Coroutine[Any, Any, R]], items: Iterable[T], *, name: str
57
+ ) -> list[R | Exception]:
58
+ """Run ``call`` on every item; a failed item's exception takes its place.
59
+
60
+ Only ``Exception`` is collected: cancellation, ``KeyboardInterrupt`` and
61
+ other ``BaseException`` still propagate.
62
+ """
63
+ batch = list(items)
64
+
65
+ async def settle(item: T) -> R | Exception:
66
+ try:
67
+ return await call(item)
68
+ except Exception as error:
69
+ return error
70
+
71
+ async with asyncio.TaskGroup() as group:
72
+ tasks = [group.create_task(settle(item)) for item in batch]
73
+ results = [task.result() for task in tasks]
74
+
75
+ _note_failures(
76
+ {i: r for i, r in enumerate(results) if isinstance(r, Exception)}, len(batch), name
77
+ )
78
+ return results
79
+
80
+
81
+ # ----------------------------------------------------------------- notes
82
+
83
+
84
+ def _first_failure[R](tasks: Sequence[asyncio.Task[R]], total: int, name: str) -> Exception | None:
85
+ """The exception of the lowest failed index, annotated; None if no task failed."""
86
+ failures: dict[int, Exception] = {}
87
+ for index, task in enumerate(tasks):
88
+ if task.done() and not task.cancelled():
89
+ error = task.exception()
90
+ if isinstance(error, Exception):
91
+ failures[index] = error
92
+ if not failures:
93
+ return None
94
+ _note_failures(failures, total, name)
95
+ return failures[min(failures)]
96
+
97
+
98
+ def _note_failures(failures: dict[int, Exception], total: int, name: str) -> None:
99
+ """Add one note per distinct exception, listing every index it failed at."""
100
+ indices_of: defaultdict[int, list[int]] = defaultdict(list)
101
+ error_of: dict[int, Exception] = {}
102
+ for index, error in failures.items():
103
+ indices_of[id(error)].append(index)
104
+ error_of[id(error)] = error
105
+ for key, indices in indices_of.items():
106
+ where = (
107
+ f"item at index {indices[0]}"
108
+ if len(indices) == 1
109
+ else f"items at indices {', '.join(map(str, indices))}"
110
+ )
111
+ error_of[key].add_note(f"{name}: {where} of {total}")