singlepipe 0.0.1__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 (78) hide show
  1. singlepipe-0.2.0/PKG-INFO +330 -0
  2. singlepipe-0.2.0/README.md +296 -0
  3. singlepipe-0.2.0/pyproject.toml +97 -0
  4. singlepipe-0.2.0/singlepipe/__init__.py +18 -0
  5. singlepipe-0.2.0/singlepipe/_fanout.py +111 -0
  6. singlepipe-0.2.0/singlepipe/adapters/base.py +270 -0
  7. singlepipe-0.2.0/singlepipe/adapters/hf_adapter.py +185 -0
  8. singlepipe-0.2.0/singlepipe/ops.py +49 -0
  9. singlepipe-0.2.0/singlepipe/schemas/__init__.py +24 -0
  10. singlepipe-0.2.0/singlepipe/schemas/containers.py +208 -0
  11. singlepipe-0.2.0/singlepipe/schemas/contract.py +116 -0
  12. singlepipe-0.2.0/singlepipe/schemas/image/base.py +42 -0
  13. singlepipe-0.2.0/singlepipe/schemas/image/classification.py +47 -0
  14. singlepipe-0.2.0/singlepipe/schemas/image/detection.py +71 -0
  15. singlepipe-0.2.0/singlepipe/schemas/modalities/__init__.py +3 -0
  16. singlepipe-0.2.0/singlepipe/schemas/modalities/image.py +360 -0
  17. singlepipe-0.2.0/singlepipe/schemas/primitives.py +161 -0
  18. singlepipe-0.2.0/singlepipe/tasks.py +117 -0
  19. singlepipe-0.2.0/singlepipe.egg-info/PKG-INFO +330 -0
  20. singlepipe-0.2.0/singlepipe.egg-info/SOURCES.txt +30 -0
  21. {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe.egg-info/requires.txt +6 -4
  22. singlepipe-0.2.0/tests/test_fanout.py +167 -0
  23. singlepipe-0.2.0/tests/test_ops.py +72 -0
  24. singlepipe-0.2.0/tests/test_package.py +42 -0
  25. singlepipe-0.2.0/tests/test_tasks.py +141 -0
  26. singlepipe-0.0.1/PKG-INFO +0 -135
  27. singlepipe-0.0.1/README.md +0 -102
  28. singlepipe-0.0.1/pyproject.toml +0 -70
  29. singlepipe-0.0.1/singlepipe/__init__.py +0 -8
  30. singlepipe-0.0.1/singlepipe/adapters/hf_adapter.py +0 -119
  31. singlepipe-0.0.1/singlepipe/model_types/__init__.py +0 -3
  32. singlepipe-0.0.1/singlepipe/model_types/types.py +0 -79
  33. singlepipe-0.0.1/singlepipe/schemas/__init__.py +0 -25
  34. singlepipe-0.0.1/singlepipe/schemas/audio_schemas/audio_classification.py +0 -40
  35. singlepipe-0.0.1/singlepipe/schemas/audio_schemas/speech_to_text.py +0 -40
  36. singlepipe-0.0.1/singlepipe/schemas/audio_schemas/text_to_audio.py +0 -40
  37. singlepipe-0.0.1/singlepipe/schemas/audio_schemas/zero_shot_audio_classification.py +0 -40
  38. singlepipe-0.0.1/singlepipe/schemas/image_schemas/depth_estimation.py +0 -40
  39. singlepipe-0.0.1/singlepipe/schemas/image_schemas/image_classification.py +0 -40
  40. singlepipe-0.0.1/singlepipe/schemas/image_schemas/image_embedding.py +0 -40
  41. singlepipe-0.0.1/singlepipe/schemas/image_schemas/image_segmentation.py +0 -40
  42. singlepipe-0.0.1/singlepipe/schemas/image_schemas/keypoint_matching.py +0 -40
  43. singlepipe-0.0.1/singlepipe/schemas/image_schemas/mask_generation.py +0 -40
  44. singlepipe-0.0.1/singlepipe/schemas/image_schemas/object_detection.py +0 -290
  45. singlepipe-0.0.1/singlepipe/schemas/image_schemas/zero_shot_image_classification.py +0 -40
  46. singlepipe-0.0.1/singlepipe/schemas/image_schemas/zero_shot_object_detection.py +0 -40
  47. singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/__init__.py +0 -0
  48. singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/document_question_answering.py +0 -40
  49. singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/image_text_to_text.py +0 -40
  50. singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/table_question_answering.py +0 -40
  51. singlepipe-0.0.1/singlepipe/schemas/ocr_schemas/__init__.py +0 -0
  52. singlepipe-0.0.1/singlepipe/schemas/ocr_schemas/ocr.py +0 -40
  53. singlepipe-0.0.1/singlepipe/schemas/registry.py +0 -97
  54. singlepipe-0.0.1/singlepipe/schemas/table_schemas/__init__.py +0 -0
  55. singlepipe-0.0.1/singlepipe/schemas/table_schemas/tabular_classification.py +0 -40
  56. singlepipe-0.0.1/singlepipe/schemas/table_schemas/tabular_regression.py +0 -40
  57. singlepipe-0.0.1/singlepipe/schemas/text_schemas/__init__.py +0 -0
  58. singlepipe-0.0.1/singlepipe/schemas/text_schemas/fill_mask.py +0 -40
  59. singlepipe-0.0.1/singlepipe/schemas/text_schemas/question_answering.py +0 -40
  60. singlepipe-0.0.1/singlepipe/schemas/text_schemas/summarization.py +0 -40
  61. singlepipe-0.0.1/singlepipe/schemas/text_schemas/text2text_generation.py +0 -40
  62. singlepipe-0.0.1/singlepipe/schemas/text_schemas/text_classification.py +0 -40
  63. singlepipe-0.0.1/singlepipe/schemas/text_schemas/text_embedding.py +0 -40
  64. singlepipe-0.0.1/singlepipe/schemas/text_schemas/text_generation.py +0 -40
  65. singlepipe-0.0.1/singlepipe/schemas/text_schemas/token_classification.py +0 -40
  66. singlepipe-0.0.1/singlepipe/schemas/text_schemas/translation.py +0 -40
  67. singlepipe-0.0.1/singlepipe/schemas/text_schemas/zero_shot_text_classification.py +0 -40
  68. singlepipe-0.0.1/singlepipe/schemas/video_schemas/__init__.py +0 -0
  69. singlepipe-0.0.1/singlepipe/schemas/video_schemas/video_classification.py +0 -40
  70. singlepipe-0.0.1/singlepipe.egg-info/PKG-INFO +0 -135
  71. singlepipe-0.0.1/singlepipe.egg-info/SOURCES.txt +0 -52
  72. {singlepipe-0.0.1 → singlepipe-0.2.0}/LICENSE +0 -0
  73. {singlepipe-0.0.1 → singlepipe-0.2.0}/setup.cfg +0 -0
  74. {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe/adapters/__init__.py +0 -0
  75. /singlepipe-0.0.1/singlepipe/schemas/audio_schemas/__init__.py → /singlepipe-0.2.0/singlepipe/py.typed +0 -0
  76. {singlepipe-0.0.1/singlepipe/schemas/image_schemas → singlepipe-0.2.0/singlepipe/schemas/image}/__init__.py +0 -0
  77. {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe.egg-info/dependency_links.txt +0 -0
  78. {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe.egg-info/top_level.txt +0 -0
@@ -0,0 +1,330 @@
1
+ Metadata-Version: 2.4
2
+ Name: singlepipe
3
+ Version: 0.2.0
4
+ Summary: Typed, async, batching inference for ML models: pydantic schemas in and out, any backend
5
+ Author-email: Gleb <glebov274@gmail.com>
6
+ License-Expression: MIT
7
+ Keywords: ml,inference,huggingface,pytorch,pydantic,typed,async,batching
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Classifier: Typing :: Typed
16
+ Requires-Python: >=3.12
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: httpx>=0.28.1
20
+ Requires-Dist: pillow>=12.3.0
21
+ Requires-Dist: pydantic>=2.13.4
22
+ Requires-Dist: numpy>=2.0
23
+ Provides-Extra: hf
24
+ Requires-Dist: transformers>=5.14.1; extra == "hf"
25
+ Requires-Dist: torch>=2.13.0; extra == "hf"
26
+ Provides-Extra: detr
27
+ Requires-Dist: singlepipe[hf]; extra == "detr"
28
+ Requires-Dist: timm>=1.0.28; extra == "detr"
29
+ Provides-Extra: torch
30
+ Requires-Dist: torch>=2.13.0; extra == "torch"
31
+ Provides-Extra: all
32
+ Requires-Dist: singlepipe[detr,hf,torch]; extra == "all"
33
+ Dynamic: license-file
34
+
35
+ # SinglePipe
36
+
37
+ **Typed, async, batching inference for ML models.** Pydantic schemas in and out,
38
+ any backend underneath.
39
+
40
+ SinglePipe does not reimplement HuggingFace, PyTorch or scikit-learn. It puts a
41
+ typed boundary around them: inputs are validated and normalised, outputs are
42
+ typed objects your editor and mypy understand, and the model runs off the event
43
+ loop with dynamic batching — so several models can work together in one
44
+ program or one FastAPI service.
45
+
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`.
50
+
51
+ ## Install
52
+
53
+ ```bash
54
+ pip install "singlepipe[hf]" # HuggingFace models (transformers + torch)
55
+ pip install "singlepipe[detr]" # + timm, for DETR detection models
56
+ ```
57
+
58
+ The core (`pip install singlepipe`) has no ML backend: schemas, tasks, image
59
+ handling and glue only. Python 3.12+.
60
+
61
+ ## Quick start
62
+
63
+ ```python
64
+ import asyncio
65
+
66
+ import singlepipe as sp
67
+ from singlepipe.adapters.hf_adapter import HFAdapter
68
+
69
+
70
+ async def main() -> None:
71
+ classifier = HFAdapter("google/vit-base-patch16-224", sp.tasks.image_classification)
72
+
73
+ out = await classifier("cats.jpg") # path, URL, data URI, bytes, PIL, numpy, torch tensor
74
+ best = out.predictions.top1 # typed: Prediction | None
75
+ if best:
76
+ print(best.label, best.score)
77
+ print(out.predictions.top(3).labels)
78
+
79
+ classifier.close()
80
+
81
+
82
+ asyncio.run(main())
83
+ ```
84
+
85
+ `out` is an `ImageClassificationOutput`, not a dict: mypy knows it without a
86
+ `cast`. In Jupyter, `await` works directly in a cell.
87
+
88
+ ## Object detection
89
+
90
+ ```python
91
+ detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
92
+
93
+ out = await detector("http://images.cocodataset.org/val2017/000000039769.jpg")
94
+ for det in out.predictions.filter_by_label("cat").filter_by_score(0.9):
95
+ print(det.label, round(det.score, 3), det.box.as_tuple())
96
+ ```
97
+
98
+ Boxes are in pixels of the original image (`out.image_width`, `out.image_height`)
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.
102
+
103
+ ## Many models: detect, crop, classify
104
+
105
+ ```python
106
+ from collections import Counter
107
+
108
+ from singlepipe.schemas.modalities import Image
109
+
110
+ detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
111
+ classifier = HFAdapter(
112
+ "my-org/sku-vit",
113
+ sp.tasks.image_classification,
114
+ max_batch_size=16,
115
+ max_wait_ms=5, # dynamic batching
116
+ )
117
+
118
+
119
+ async def shelf(path: str) -> Counter[str]:
120
+ image = Image(path)
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
+ ```
128
+
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
146
+ ```
147
+
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.
201
+
202
+ ## Your own task on a HuggingFace model
203
+
204
+ A task is a pair of schemas. Built-in tasks are ready objects; a custom one is a
205
+ line of code.
206
+
207
+ ```python
208
+ from typing import Any, Self
209
+
210
+ import singlepipe as sp
211
+ from singlepipe.adapters.hf_adapter import HFAdapter
212
+ from singlepipe.schemas.contract import OutputSchema
213
+ from singlepipe.schemas.image.base import ImageTaskInput
214
+
215
+
216
+ class IsCat(OutputSchema):
217
+ is_cat: bool
218
+ confidence: float
219
+
220
+ @classmethod
221
+ def from_pipeline_output(cls, raw: Any, **context: Any) -> Self:
222
+ cat = next((p for p in raw if "cat" in p["label"]), None)
223
+ return cls(is_cat=cat is not None, confidence=cat["score"] if cat else 0.0)
224
+
225
+
226
+ is_cat = sp.Task("is-cat", ImageTaskInput, IsCat)
227
+ adapter = HFAdapter("google/vit-base-patch16-224", is_cat, hf_task="image-classification")
228
+
229
+ answer = await adapter("cats.jpg")
230
+ answer.is_cat # typed: bool
231
+ ```
232
+
233
+ ## Your own adapter, any library
234
+
235
+ Everything except the backend call lives in `Adapter`: async calls, validation,
236
+ the worker thread, batching, `map`, `close()`. A backend implements one method.
237
+
238
+ ```python
239
+ from collections.abc import Sequence
240
+ from typing import Any
241
+
242
+ import numpy as np
243
+ import onnxruntime
244
+
245
+ import singlepipe as sp
246
+ from singlepipe.adapters.base import Adapter
247
+ from singlepipe.schemas.image.classification import (
248
+ ImageClassificationInput,
249
+ ImageClassificationOutput,
250
+ )
251
+
252
+
253
+ class OnnxClassifier(Adapter[ImageClassificationInput, ImageClassificationOutput]):
254
+ def __init__(self, path: str, labels: list[str], **batching: Any) -> None:
255
+ self.session = onnxruntime.InferenceSession(path) # load the model first,
256
+ self.labels = labels
257
+ super().__init__(sp.tasks.image_classification, **batching) # then start the worker
258
+
259
+ def run_batch(self, inputs: Sequence[Any]) -> Sequence[Any]:
260
+ x = np.stack([preprocess(image) for image in inputs]) # your resize + normalise
261
+ probabilities = self.session.run(None, {"input": x})[0]
262
+ return [
263
+ [{"label": label, "score": float(p)} for label, p in zip(self.labels, row)]
264
+ for row in probabilities
265
+ ]
266
+ ```
267
+
268
+ `run_batch` receives what the input schema produces (here RGB PIL images) and
269
+ returns one raw output per input, in the format the output schema reads.
270
+
271
+ ## FastAPI
272
+
273
+ ```python
274
+ from contextlib import asynccontextmanager
275
+
276
+ from fastapi import FastAPI
277
+
278
+ from singlepipe.schemas.image.classification import ImageClassificationOutput
279
+
280
+
281
+ @asynccontextmanager
282
+ async def lifespan(app: FastAPI):
283
+ app.state.classifier = HFAdapter(
284
+ "google/vit-base-patch16-224",
285
+ sp.tasks.image_classification,
286
+ max_batch_size=32,
287
+ max_wait_ms=10, # concurrent requests share batches
288
+ )
289
+ yield
290
+ app.state.classifier.close()
291
+
292
+
293
+ app = FastAPI(lifespan=lifespan)
294
+
295
+
296
+ @app.post("/classify")
297
+ async def classify(url: str) -> ImageClassificationOutput:
298
+ return await app.state.classifier(url)
299
+ ```
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
+
306
+ ## What is there today
307
+
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) |
316
+
317
+ ## Roadmap
318
+
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
323
+ - `Connector`: picks the adapter from the model object
324
+ - PyTorch and scikit-learn / XGBoost adapters, tabular tasks
325
+ - Text and audio tasks
326
+ - Later: a node as a remote service (`sp.serve`, `RemoteAdapter`)
327
+
328
+ ## License
329
+
330
+ MIT
@@ -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