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.
- {singlepipe-0.1.0/singlepipe.egg-info → singlepipe-0.2.0}/PKG-INFO +119 -38
- singlepipe-0.2.0/README.md +296 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/pyproject.toml +1 -1
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/__init__.py +2 -2
- singlepipe-0.2.0/singlepipe/_fanout.py +111 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/adapters/base.py +42 -2
- singlepipe-0.2.0/singlepipe/ops.py +49 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/modalities/image.py +140 -16
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/primitives.py +42 -8
- {singlepipe-0.1.0 → singlepipe-0.2.0/singlepipe.egg-info}/PKG-INFO +119 -38
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/SOURCES.txt +4 -0
- singlepipe-0.2.0/tests/test_fanout.py +167 -0
- singlepipe-0.2.0/tests/test_ops.py +72 -0
- singlepipe-0.1.0/README.md +0 -215
- {singlepipe-0.1.0 → singlepipe-0.2.0}/LICENSE +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/setup.cfg +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/adapters/__init__.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/adapters/hf_adapter.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/py.typed +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/__init__.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/containers.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/contract.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/__init__.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/base.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/classification.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/image/detection.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/schemas/modalities/__init__.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe/tasks.py +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/dependency_links.txt +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/requires.txt +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/singlepipe.egg-info/top_level.txt +0 -0
- {singlepipe-0.1.0 → singlepipe-0.2.0}/tests/test_package.py +0 -0
- {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.
|
|
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.
|
|
47
|
-
> HuggingFace models
|
|
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
|
|
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 —
|
|
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
|
-
##
|
|
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) ->
|
|
119
|
+
async def shelf(path: str) -> Counter[str]:
|
|
117
120
|
image = Image(path)
|
|
118
|
-
|
|
119
|
-
bottles =
|
|
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
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
|
178
|
-
|
|
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
|
|
234
|
-
| Backends
|
|
235
|
-
| Inputs
|
|
236
|
-
| Execution | async calls, a worker thread per model, dynamic batching |
|
|
237
|
-
|
|
|
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
|
-
-
|
|
242
|
-
|
|
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
|
|
@@ -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}")
|