singlepipe 0.0.1__tar.gz → 0.1.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/PKG-INFO +249 -0
- singlepipe-0.1.0/README.md +215 -0
- singlepipe-0.1.0/pyproject.toml +97 -0
- singlepipe-0.1.0/singlepipe/__init__.py +18 -0
- singlepipe-0.1.0/singlepipe/adapters/base.py +230 -0
- singlepipe-0.1.0/singlepipe/adapters/hf_adapter.py +185 -0
- singlepipe-0.1.0/singlepipe/schemas/__init__.py +24 -0
- singlepipe-0.1.0/singlepipe/schemas/containers.py +208 -0
- singlepipe-0.1.0/singlepipe/schemas/contract.py +116 -0
- singlepipe-0.1.0/singlepipe/schemas/image/base.py +42 -0
- singlepipe-0.1.0/singlepipe/schemas/image/classification.py +47 -0
- singlepipe-0.1.0/singlepipe/schemas/image/detection.py +71 -0
- singlepipe-0.1.0/singlepipe/schemas/modalities/__init__.py +3 -0
- singlepipe-0.1.0/singlepipe/schemas/modalities/image.py +236 -0
- singlepipe-0.1.0/singlepipe/schemas/primitives.py +127 -0
- singlepipe-0.1.0/singlepipe/tasks.py +117 -0
- singlepipe-0.1.0/singlepipe.egg-info/PKG-INFO +249 -0
- singlepipe-0.1.0/singlepipe.egg-info/SOURCES.txt +26 -0
- {singlepipe-0.0.1 → singlepipe-0.1.0}/singlepipe.egg-info/requires.txt +6 -4
- singlepipe-0.1.0/tests/test_package.py +42 -0
- singlepipe-0.1.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.1.0}/LICENSE +0 -0
- {singlepipe-0.0.1 → singlepipe-0.1.0}/setup.cfg +0 -0
- {singlepipe-0.0.1 → singlepipe-0.1.0}/singlepipe/adapters/__init__.py +0 -0
- /singlepipe-0.0.1/singlepipe/schemas/audio_schemas/__init__.py → /singlepipe-0.1.0/singlepipe/py.typed +0 -0
- {singlepipe-0.0.1/singlepipe/schemas/image_schemas → singlepipe-0.1.0/singlepipe/schemas/image}/__init__.py +0 -0
- {singlepipe-0.0.1 → singlepipe-0.1.0}/singlepipe.egg-info/dependency_links.txt +0 -0
- {singlepipe-0.0.1 → singlepipe-0.1.0}/singlepipe.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: singlepipe
|
|
3
|
+
Version: 0.1.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.1.0).** Image classification and object detection on
|
|
47
|
+
> HuggingFace models. The API will change before 1.0.
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install "singlepipe[hf]" # HuggingFace models (transformers + torch)
|
|
53
|
+
pip install "singlepipe[detr]" # + timm, for DETR detection models
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The core (`pip install singlepipe`) has no ML backend: schemas, tasks and image
|
|
57
|
+
handling only. Python 3.12+.
|
|
58
|
+
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import asyncio
|
|
63
|
+
|
|
64
|
+
import singlepipe as sp
|
|
65
|
+
from singlepipe.adapters.hf_adapter import HFAdapter
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
async def main() -> None:
|
|
69
|
+
classifier = HFAdapter("google/vit-base-patch16-224", sp.tasks.image_classification)
|
|
70
|
+
|
|
71
|
+
out = await classifier("cats.jpg") # path, URL, bytes, PIL, numpy, torch tensor
|
|
72
|
+
best = out.predictions.top1 # typed: Prediction | None
|
|
73
|
+
if best:
|
|
74
|
+
print(best.label, best.score)
|
|
75
|
+
print(out.predictions.top(3).labels)
|
|
76
|
+
|
|
77
|
+
classifier.close()
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
asyncio.run(main())
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`out` is an `ImageClassificationOutput`, not a dict: mypy knows it without a
|
|
84
|
+
`cast`. In Jupyter, `await` works directly in a cell.
|
|
85
|
+
|
|
86
|
+
## Object detection
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
|
|
90
|
+
|
|
91
|
+
out = await detector("http://images.cocodataset.org/val2017/000000039769.jpg")
|
|
92
|
+
for det in out.predictions.filter_by_label("cat").filter_by_score(0.9):
|
|
93
|
+
print(det.label, round(det.score, 3), det.box.as_tuple())
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Boxes are in pixels of the original image (`out.image_width`, `out.image_height`)
|
|
97
|
+
and are returned as the model gave them — `BBox.clip` is there if you need it.
|
|
98
|
+
|
|
99
|
+
## Batching: detect, crop, classify
|
|
100
|
+
|
|
101
|
+
Calls are written one at a time; concurrent calls are grouped into batches by
|
|
102
|
+
the adapter.
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from singlepipe.schemas.modalities import Image
|
|
106
|
+
|
|
107
|
+
detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
|
|
108
|
+
classifier = HFAdapter(
|
|
109
|
+
"my-org/sku-vit",
|
|
110
|
+
sp.tasks.image_classification,
|
|
111
|
+
max_batch_size=16,
|
|
112
|
+
max_wait_ms=5, # dynamic batching
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
async def shelf(path: str) -> list[str]:
|
|
117
|
+
image = Image(path)
|
|
118
|
+
detections = await detector(image)
|
|
119
|
+
bottles = detections.predictions.filter_by_label("bottle").filter_by_score(0.5)
|
|
120
|
+
|
|
121
|
+
crops = [image.pil.crop(tuple(round(v) for v in d.box.as_tuple())) for d in bottles]
|
|
122
|
+
results = await asyncio.gather(*(classifier(crop) for crop in crops)) # one forward pass
|
|
123
|
+
return [r.predictions.top1.label for r in results if r.predictions.top1]
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- Each adapter has its own worker thread: independent models run in parallel,
|
|
127
|
+
and the event loop stays free (a server keeps answering while a model computes).
|
|
128
|
+
- The worker collects up to `max_batch_size` calls, waiting at most `max_wait_ms`
|
|
129
|
+
for the first one's company. Calls that arrive while the model is busy join the
|
|
130
|
+
next batch on their own.
|
|
131
|
+
- Defaults are `max_batch_size=1, max_wait_ms=0`: no batching until you ask for it.
|
|
132
|
+
- A bad input is rejected before the queue; a failing batch fails all its calls;
|
|
133
|
+
a bad output fails only its own call.
|
|
134
|
+
|
|
135
|
+
## Your own task on a HuggingFace model
|
|
136
|
+
|
|
137
|
+
A task is a pair of schemas. Built-in tasks are ready objects; a custom one is a
|
|
138
|
+
line of code.
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from typing import Any, Self
|
|
142
|
+
|
|
143
|
+
from singlepipe.schemas.contract import OutputSchema
|
|
144
|
+
from singlepipe.schemas.image.base import ImageTaskInput
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
class IsCat(OutputSchema):
|
|
148
|
+
is_cat: bool
|
|
149
|
+
confidence: float
|
|
150
|
+
|
|
151
|
+
@classmethod
|
|
152
|
+
def from_pipeline_output(cls, raw: Any, **context: Any) -> Self:
|
|
153
|
+
cat = next((p for p in raw if "cat" in p["label"]), None)
|
|
154
|
+
return cls(is_cat=cat is not None, confidence=cat["score"] if cat else 0.0)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
is_cat = sp.Task("is-cat", ImageTaskInput, IsCat)
|
|
158
|
+
adapter = HFAdapter("google/vit-base-patch16-224", is_cat, hf_task="image-classification")
|
|
159
|
+
|
|
160
|
+
answer = await adapter("cats.jpg")
|
|
161
|
+
answer.is_cat # typed: bool
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Your own adapter, any library
|
|
165
|
+
|
|
166
|
+
Everything except the backend call lives in `Adapter`: async calls, validation,
|
|
167
|
+
the worker thread, batching, `close()`. A backend implements one method.
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
from collections.abc import Sequence
|
|
171
|
+
from typing import Any
|
|
172
|
+
|
|
173
|
+
import numpy as np
|
|
174
|
+
import onnxruntime
|
|
175
|
+
|
|
176
|
+
from singlepipe.adapters.base import Adapter
|
|
177
|
+
from singlepipe.schemas import ImageClassificationOutput
|
|
178
|
+
from singlepipe.schemas.image.classification import ImageClassificationInput
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
class OnnxClassifier(Adapter[ImageClassificationInput, ImageClassificationOutput]):
|
|
182
|
+
def __init__(self, path: str, labels: list[str], **batching: Any) -> None:
|
|
183
|
+
self.session = onnxruntime.InferenceSession(path) # load the model first,
|
|
184
|
+
self.labels = labels
|
|
185
|
+
super().__init__(sp.tasks.image_classification, **batching) # then start the worker
|
|
186
|
+
|
|
187
|
+
def run_batch(self, inputs: Sequence[Any]) -> Sequence[Any]:
|
|
188
|
+
x = np.stack([preprocess(image) for image in inputs]) # your resize + normalise
|
|
189
|
+
probabilities = self.session.run(None, {"input": x})[0]
|
|
190
|
+
return [
|
|
191
|
+
[{"label": label, "score": float(p)} for label, p in zip(self.labels, row)]
|
|
192
|
+
for row in probabilities
|
|
193
|
+
]
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
`run_batch` receives what the input schema produces (here RGB PIL images) and
|
|
197
|
+
returns one raw output per input, in the format the output schema reads.
|
|
198
|
+
|
|
199
|
+
## FastAPI
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
from contextlib import asynccontextmanager
|
|
203
|
+
|
|
204
|
+
from fastapi import FastAPI
|
|
205
|
+
|
|
206
|
+
from singlepipe.schemas import ImageClassificationOutput
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
@asynccontextmanager
|
|
210
|
+
async def lifespan(app: FastAPI):
|
|
211
|
+
app.state.classifier = HFAdapter(
|
|
212
|
+
"google/vit-base-patch16-224",
|
|
213
|
+
sp.tasks.image_classification,
|
|
214
|
+
max_batch_size=32,
|
|
215
|
+
max_wait_ms=10, # concurrent requests share batches
|
|
216
|
+
)
|
|
217
|
+
yield
|
|
218
|
+
app.state.classifier.close()
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
app = FastAPI(lifespan=lifespan)
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@app.post("/classify")
|
|
225
|
+
async def classify(url: str) -> ImageClassificationOutput:
|
|
226
|
+
return await app.state.classifier(url)
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## What is there today
|
|
230
|
+
|
|
231
|
+
| | |
|
|
232
|
+
|---|---|
|
|
233
|
+
| Tasks | `image_classification`, `object_detection` |
|
|
234
|
+
| Backends | HuggingFace `transformers` pipelines; anything else via `Adapter` |
|
|
235
|
+
| Inputs | file path, URL, data URI, bytes, PIL image, numpy array, torch tensor |
|
|
236
|
+
| Execution | async calls, a worker thread per model, dynamic batching |
|
|
237
|
+
| Typing | outputs typed for mypy without `cast` (`py.typed` included) |
|
|
238
|
+
|
|
239
|
+
## Roadmap
|
|
240
|
+
|
|
241
|
+
- `Image.crop`, `sp.each(adapter)(items)` and other glue for multi-model code
|
|
242
|
+
- `@sp.graph`: a graph is an async function, with a run log and FastAPI endpoints
|
|
243
|
+
- `Connector`: picks the adapter from the model object
|
|
244
|
+
- PyTorch and scikit-learn / XGBoost adapters, tabular tasks
|
|
245
|
+
- Text and audio tasks
|
|
246
|
+
|
|
247
|
+
## License
|
|
248
|
+
|
|
249
|
+
MIT
|
|
@@ -0,0 +1,215 @@
|
|
|
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.1.0).** Image classification and object detection on
|
|
13
|
+
> HuggingFace models. The API will change before 1.0.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install "singlepipe[hf]" # HuggingFace models (transformers + torch)
|
|
19
|
+
pip install "singlepipe[detr]" # + timm, for DETR detection models
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The core (`pip install singlepipe`) has no ML backend: schemas, tasks and image
|
|
23
|
+
handling only. Python 3.12+.
|
|
24
|
+
|
|
25
|
+
## Quick start
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import asyncio
|
|
29
|
+
|
|
30
|
+
import singlepipe as sp
|
|
31
|
+
from singlepipe.adapters.hf_adapter import HFAdapter
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
async def main() -> None:
|
|
35
|
+
classifier = HFAdapter("google/vit-base-patch16-224", sp.tasks.image_classification)
|
|
36
|
+
|
|
37
|
+
out = await classifier("cats.jpg") # path, URL, bytes, PIL, numpy, torch tensor
|
|
38
|
+
best = out.predictions.top1 # typed: Prediction | None
|
|
39
|
+
if best:
|
|
40
|
+
print(best.label, best.score)
|
|
41
|
+
print(out.predictions.top(3).labels)
|
|
42
|
+
|
|
43
|
+
classifier.close()
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
asyncio.run(main())
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`out` is an `ImageClassificationOutput`, not a dict: mypy knows it without a
|
|
50
|
+
`cast`. In Jupyter, `await` works directly in a cell.
|
|
51
|
+
|
|
52
|
+
## Object detection
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
|
|
56
|
+
|
|
57
|
+
out = await detector("http://images.cocodataset.org/val2017/000000039769.jpg")
|
|
58
|
+
for det in out.predictions.filter_by_label("cat").filter_by_score(0.9):
|
|
59
|
+
print(det.label, round(det.score, 3), det.box.as_tuple())
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Boxes are in pixels of the original image (`out.image_width`, `out.image_height`)
|
|
63
|
+
and are returned as the model gave them — `BBox.clip` is there if you need it.
|
|
64
|
+
|
|
65
|
+
## Batching: detect, crop, classify
|
|
66
|
+
|
|
67
|
+
Calls are written one at a time; concurrent calls are grouped into batches by
|
|
68
|
+
the adapter.
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
from singlepipe.schemas.modalities import Image
|
|
72
|
+
|
|
73
|
+
detector = HFAdapter("facebook/detr-resnet-50", sp.tasks.object_detection)
|
|
74
|
+
classifier = HFAdapter(
|
|
75
|
+
"my-org/sku-vit",
|
|
76
|
+
sp.tasks.image_classification,
|
|
77
|
+
max_batch_size=16,
|
|
78
|
+
max_wait_ms=5, # dynamic batching
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
async def shelf(path: str) -> list[str]:
|
|
83
|
+
image = Image(path)
|
|
84
|
+
detections = await detector(image)
|
|
85
|
+
bottles = detections.predictions.filter_by_label("bottle").filter_by_score(0.5)
|
|
86
|
+
|
|
87
|
+
crops = [image.pil.crop(tuple(round(v) for v in d.box.as_tuple())) for d in bottles]
|
|
88
|
+
results = await asyncio.gather(*(classifier(crop) for crop in crops)) # one forward pass
|
|
89
|
+
return [r.predictions.top1.label for r in results if r.predictions.top1]
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
- Each adapter has its own worker thread: independent models run in parallel,
|
|
93
|
+
and the event loop stays free (a server keeps answering while a model computes).
|
|
94
|
+
- The worker collects up to `max_batch_size` calls, waiting at most `max_wait_ms`
|
|
95
|
+
for the first one's company. Calls that arrive while the model is busy join the
|
|
96
|
+
next batch on their own.
|
|
97
|
+
- Defaults are `max_batch_size=1, max_wait_ms=0`: no batching until you ask for it.
|
|
98
|
+
- A bad input is rejected before the queue; a failing batch fails all its calls;
|
|
99
|
+
a bad output fails only its own call.
|
|
100
|
+
|
|
101
|
+
## Your own task on a HuggingFace model
|
|
102
|
+
|
|
103
|
+
A task is a pair of schemas. Built-in tasks are ready objects; a custom one is a
|
|
104
|
+
line of code.
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
from typing import Any, Self
|
|
108
|
+
|
|
109
|
+
from singlepipe.schemas.contract import OutputSchema
|
|
110
|
+
from singlepipe.schemas.image.base import ImageTaskInput
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
class IsCat(OutputSchema):
|
|
114
|
+
is_cat: bool
|
|
115
|
+
confidence: float
|
|
116
|
+
|
|
117
|
+
@classmethod
|
|
118
|
+
def from_pipeline_output(cls, raw: Any, **context: Any) -> Self:
|
|
119
|
+
cat = next((p for p in raw if "cat" in p["label"]), None)
|
|
120
|
+
return cls(is_cat=cat is not None, confidence=cat["score"] if cat else 0.0)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
is_cat = sp.Task("is-cat", ImageTaskInput, IsCat)
|
|
124
|
+
adapter = HFAdapter("google/vit-base-patch16-224", is_cat, hf_task="image-classification")
|
|
125
|
+
|
|
126
|
+
answer = await adapter("cats.jpg")
|
|
127
|
+
answer.is_cat # typed: bool
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Your own adapter, any library
|
|
131
|
+
|
|
132
|
+
Everything except the backend call lives in `Adapter`: async calls, validation,
|
|
133
|
+
the worker thread, batching, `close()`. A backend implements one method.
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from collections.abc import Sequence
|
|
137
|
+
from typing import Any
|
|
138
|
+
|
|
139
|
+
import numpy as np
|
|
140
|
+
import onnxruntime
|
|
141
|
+
|
|
142
|
+
from singlepipe.adapters.base import Adapter
|
|
143
|
+
from singlepipe.schemas import ImageClassificationOutput
|
|
144
|
+
from singlepipe.schemas.image.classification import ImageClassificationInput
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
class OnnxClassifier(Adapter[ImageClassificationInput, ImageClassificationOutput]):
|
|
148
|
+
def __init__(self, path: str, labels: list[str], **batching: Any) -> None:
|
|
149
|
+
self.session = onnxruntime.InferenceSession(path) # load the model first,
|
|
150
|
+
self.labels = labels
|
|
151
|
+
super().__init__(sp.tasks.image_classification, **batching) # then start the worker
|
|
152
|
+
|
|
153
|
+
def run_batch(self, inputs: Sequence[Any]) -> Sequence[Any]:
|
|
154
|
+
x = np.stack([preprocess(image) for image in inputs]) # your resize + normalise
|
|
155
|
+
probabilities = self.session.run(None, {"input": x})[0]
|
|
156
|
+
return [
|
|
157
|
+
[{"label": label, "score": float(p)} for label, p in zip(self.labels, row)]
|
|
158
|
+
for row in probabilities
|
|
159
|
+
]
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`run_batch` receives what the input schema produces (here RGB PIL images) and
|
|
163
|
+
returns one raw output per input, in the format the output schema reads.
|
|
164
|
+
|
|
165
|
+
## FastAPI
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from contextlib import asynccontextmanager
|
|
169
|
+
|
|
170
|
+
from fastapi import FastAPI
|
|
171
|
+
|
|
172
|
+
from singlepipe.schemas import ImageClassificationOutput
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
@asynccontextmanager
|
|
176
|
+
async def lifespan(app: FastAPI):
|
|
177
|
+
app.state.classifier = HFAdapter(
|
|
178
|
+
"google/vit-base-patch16-224",
|
|
179
|
+
sp.tasks.image_classification,
|
|
180
|
+
max_batch_size=32,
|
|
181
|
+
max_wait_ms=10, # concurrent requests share batches
|
|
182
|
+
)
|
|
183
|
+
yield
|
|
184
|
+
app.state.classifier.close()
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
app = FastAPI(lifespan=lifespan)
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
@app.post("/classify")
|
|
191
|
+
async def classify(url: str) -> ImageClassificationOutput:
|
|
192
|
+
return await app.state.classifier(url)
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## What is there today
|
|
196
|
+
|
|
197
|
+
| | |
|
|
198
|
+
|---|---|
|
|
199
|
+
| Tasks | `image_classification`, `object_detection` |
|
|
200
|
+
| Backends | HuggingFace `transformers` pipelines; anything else via `Adapter` |
|
|
201
|
+
| Inputs | file path, URL, data URI, bytes, PIL image, numpy array, torch tensor |
|
|
202
|
+
| Execution | async calls, a worker thread per model, dynamic batching |
|
|
203
|
+
| Typing | outputs typed for mypy without `cast` (`py.typed` included) |
|
|
204
|
+
|
|
205
|
+
## Roadmap
|
|
206
|
+
|
|
207
|
+
- `Image.crop`, `sp.each(adapter)(items)` and other glue for multi-model code
|
|
208
|
+
- `@sp.graph`: a graph is an async function, with a run log and FastAPI endpoints
|
|
209
|
+
- `Connector`: picks the adapter from the model object
|
|
210
|
+
- PyTorch and scikit-learn / XGBoost adapters, tabular tasks
|
|
211
|
+
- Text and audio tasks
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
MIT
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "singlepipe"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Typed, async, batching inference for ML models: pydantic schemas in and out, any backend"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.12"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
authors = [
|
|
10
|
+
{ name = "Gleb", email = "glebov274@gmail.com" },
|
|
11
|
+
]
|
|
12
|
+
keywords = ["ml", "inference", "huggingface", "pytorch", "pydantic", "typed", "async", "batching"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 3 - Alpha",
|
|
15
|
+
"Intended Audience :: Developers",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Programming Language :: Python :: 3.14",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
21
|
+
"Typing :: Typed",
|
|
22
|
+
]
|
|
23
|
+
# The core: schemas, validation, images. No ML backend here — each backend is an
|
|
24
|
+
# extra, so a user who only needs one backend does not download the others.
|
|
25
|
+
dependencies = [
|
|
26
|
+
"httpx>=0.28.1",
|
|
27
|
+
"pillow>=12.3.0",
|
|
28
|
+
"pydantic>=2.13.4",
|
|
29
|
+
"numpy>=2.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
# HFAdapter. torch is included: without it transformers cannot load models.
|
|
34
|
+
# For a specific CUDA build, install torch from its own index on top.
|
|
35
|
+
hf = [
|
|
36
|
+
"transformers>=5.14.1",
|
|
37
|
+
"torch>=2.13.0",
|
|
38
|
+
]
|
|
39
|
+
# DETR models in transformers use a timm backbone.
|
|
40
|
+
detr = [
|
|
41
|
+
"singlepipe[hf]",
|
|
42
|
+
"timm>=1.0.28",
|
|
43
|
+
]
|
|
44
|
+
# Bare torch, for the planned torch adapter.
|
|
45
|
+
torch = [
|
|
46
|
+
"torch>=2.13.0",
|
|
47
|
+
]
|
|
48
|
+
all = [
|
|
49
|
+
"singlepipe[hf,detr,torch]",
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
[dependency-groups]
|
|
53
|
+
dev = [
|
|
54
|
+
"singlepipe[all]",
|
|
55
|
+
"anyio>=4",
|
|
56
|
+
"pytest>=8",
|
|
57
|
+
"ruff>=0.16.1",
|
|
58
|
+
"mypy>=2.3.0",
|
|
59
|
+
]
|
|
60
|
+
|
|
61
|
+
[build-system]
|
|
62
|
+
requires = ["setuptools>=77"]
|
|
63
|
+
build-backend = "setuptools.build_meta"
|
|
64
|
+
|
|
65
|
+
[tool.setuptools.packages.find]
|
|
66
|
+
where = ["."]
|
|
67
|
+
include = ["singlepipe*"]
|
|
68
|
+
|
|
69
|
+
# PEP 561 marker: without it, mypy in users' projects treats singlepipe as untyped
|
|
70
|
+
# and every adapter output becomes Any.
|
|
71
|
+
[tool.setuptools.package-data]
|
|
72
|
+
singlepipe = ["py.typed"]
|
|
73
|
+
|
|
74
|
+
[tool.ruff]
|
|
75
|
+
line-length = 100
|
|
76
|
+
target-version = "py312"
|
|
77
|
+
|
|
78
|
+
[tool.ruff.lint]
|
|
79
|
+
select = ["E", "F", "I", "UP", "B", "SIM", "A"]
|
|
80
|
+
# PEP 695 generics (class X[T]) — отдельное решение: вариантность и поддержка pydantic
|
|
81
|
+
ignore = ["UP046", "UP047"]
|
|
82
|
+
|
|
83
|
+
[tool.mypy]
|
|
84
|
+
python_version = "3.12"
|
|
85
|
+
strict = false
|
|
86
|
+
warn_return_any = true
|
|
87
|
+
warn_unused_ignores = true
|
|
88
|
+
|
|
89
|
+
[[tool.mypy.overrides]]
|
|
90
|
+
module = ["torch", "torch.*"]
|
|
91
|
+
ignore_missing_imports = true
|
|
92
|
+
|
|
93
|
+
[tool.pytest.ini_options]
|
|
94
|
+
pythonpath = ["."]
|
|
95
|
+
markers = [
|
|
96
|
+
"slow: downloads or runs large pretrained models (deselect with -m \"not slow\")",
|
|
97
|
+
]
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""SinglePipe: typed multi-model inference orchestrator.
|
|
2
|
+
|
|
3
|
+
Importing the package loads only the core (schemas, tasks). ML backends are
|
|
4
|
+
extras and are imported by their adapters, not here: a user of one backend
|
|
5
|
+
never pays for the others, and ``import singlepipe`` stays fast. Adapters are
|
|
6
|
+
imported from their modules, e.g. ``from singlepipe.adapters.hf_adapter import
|
|
7
|
+
HFAdapter``.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from importlib.metadata import version
|
|
11
|
+
|
|
12
|
+
from singlepipe import tasks
|
|
13
|
+
from singlepipe.tasks import Task
|
|
14
|
+
|
|
15
|
+
# One source of truth: the version in pyproject.toml, read from the installed metadata.
|
|
16
|
+
__version__ = version("singlepipe")
|
|
17
|
+
|
|
18
|
+
__all__ = ["Task", "tasks"]
|