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.
- singlepipe-0.2.0/PKG-INFO +330 -0
- singlepipe-0.2.0/README.md +296 -0
- singlepipe-0.2.0/pyproject.toml +97 -0
- singlepipe-0.2.0/singlepipe/__init__.py +18 -0
- singlepipe-0.2.0/singlepipe/_fanout.py +111 -0
- singlepipe-0.2.0/singlepipe/adapters/base.py +270 -0
- singlepipe-0.2.0/singlepipe/adapters/hf_adapter.py +185 -0
- singlepipe-0.2.0/singlepipe/ops.py +49 -0
- singlepipe-0.2.0/singlepipe/schemas/__init__.py +24 -0
- singlepipe-0.2.0/singlepipe/schemas/containers.py +208 -0
- singlepipe-0.2.0/singlepipe/schemas/contract.py +116 -0
- singlepipe-0.2.0/singlepipe/schemas/image/base.py +42 -0
- singlepipe-0.2.0/singlepipe/schemas/image/classification.py +47 -0
- singlepipe-0.2.0/singlepipe/schemas/image/detection.py +71 -0
- singlepipe-0.2.0/singlepipe/schemas/modalities/__init__.py +3 -0
- singlepipe-0.2.0/singlepipe/schemas/modalities/image.py +360 -0
- singlepipe-0.2.0/singlepipe/schemas/primitives.py +161 -0
- singlepipe-0.2.0/singlepipe/tasks.py +117 -0
- singlepipe-0.2.0/singlepipe.egg-info/PKG-INFO +330 -0
- singlepipe-0.2.0/singlepipe.egg-info/SOURCES.txt +30 -0
- {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe.egg-info/requires.txt +6 -4
- singlepipe-0.2.0/tests/test_fanout.py +167 -0
- singlepipe-0.2.0/tests/test_ops.py +72 -0
- singlepipe-0.2.0/tests/test_package.py +42 -0
- singlepipe-0.2.0/tests/test_tasks.py +141 -0
- singlepipe-0.0.1/PKG-INFO +0 -135
- singlepipe-0.0.1/README.md +0 -102
- singlepipe-0.0.1/pyproject.toml +0 -70
- singlepipe-0.0.1/singlepipe/__init__.py +0 -8
- singlepipe-0.0.1/singlepipe/adapters/hf_adapter.py +0 -119
- singlepipe-0.0.1/singlepipe/model_types/__init__.py +0 -3
- singlepipe-0.0.1/singlepipe/model_types/types.py +0 -79
- singlepipe-0.0.1/singlepipe/schemas/__init__.py +0 -25
- singlepipe-0.0.1/singlepipe/schemas/audio_schemas/audio_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/audio_schemas/speech_to_text.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/audio_schemas/text_to_audio.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/audio_schemas/zero_shot_audio_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/depth_estimation.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/image_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/image_embedding.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/image_segmentation.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/keypoint_matching.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/mask_generation.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/object_detection.py +0 -290
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/zero_shot_image_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/image_schemas/zero_shot_object_detection.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/__init__.py +0 -0
- singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/document_question_answering.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/image_text_to_text.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/multimodal_schemas/table_question_answering.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/ocr_schemas/__init__.py +0 -0
- singlepipe-0.0.1/singlepipe/schemas/ocr_schemas/ocr.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/registry.py +0 -97
- singlepipe-0.0.1/singlepipe/schemas/table_schemas/__init__.py +0 -0
- singlepipe-0.0.1/singlepipe/schemas/table_schemas/tabular_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/table_schemas/tabular_regression.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/__init__.py +0 -0
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/fill_mask.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/question_answering.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/summarization.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/text2text_generation.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/text_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/text_embedding.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/text_generation.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/token_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/translation.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/text_schemas/zero_shot_text_classification.py +0 -40
- singlepipe-0.0.1/singlepipe/schemas/video_schemas/__init__.py +0 -0
- singlepipe-0.0.1/singlepipe/schemas/video_schemas/video_classification.py +0 -40
- singlepipe-0.0.1/singlepipe.egg-info/PKG-INFO +0 -135
- singlepipe-0.0.1/singlepipe.egg-info/SOURCES.txt +0 -52
- {singlepipe-0.0.1 → singlepipe-0.2.0}/LICENSE +0 -0
- {singlepipe-0.0.1 → singlepipe-0.2.0}/setup.cfg +0 -0
- {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe/adapters/__init__.py +0 -0
- /singlepipe-0.0.1/singlepipe/schemas/audio_schemas/__init__.py → /singlepipe-0.2.0/singlepipe/py.typed +0 -0
- {singlepipe-0.0.1/singlepipe/schemas/image_schemas → singlepipe-0.2.0/singlepipe/schemas/image}/__init__.py +0 -0
- {singlepipe-0.0.1 → singlepipe-0.2.0}/singlepipe.egg-info/dependency_links.txt +0 -0
- {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
|