Metadata-Version: 2.3
Name: embedders-litserve
Version: 0.0.1
Summary: LitServe embedding server and typed asynchronous client
Requires-Dist: httpx>=0.28.0
Requires-Dist: litserve>=0.2.19
Requires-Dist: open-clip-torch>=3.3.0
Requires-Dist: pydantic>=2.14.1
Requires-Dist: pydantic-settings>=2.16.1
Requires-Dist: torch>=2.14.1
Requires-Dist: transformers>=5.21.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Embedders LitServe

## Installation

```sh
pip install embedders-litserve
```

For running the server from a checkout, configure `.env` and use:

```sh
uv run embedders-litserve
```

## Client

```python
import asyncio

from embedders_litserve import EmbedderClient


async def main() -> None:
    async with EmbedderClient("siglip2", "http://localhost:8000") as client:
        await client.verify_model()
        response = await client.embed_texts(["a red fox"])
        print(response.embeddings)


asyncio.run(main())
```

## Benchmark

Run a local HTTP throughput benchmark against a running server:

```sh
embedders-litserve-bench http://localhost:8000
embedders-litserve-bench http://localhost:8000 --batch-size 64 --requests 100 --concurrency 8
```

The CLI sends bundled `test_images` as base64 to `/predict`. A full endpoint URL
and a custom `--images-dir` are also supported. Images are reused when needed.
The reported `images/sec` includes HTTP transfer and response decoding, excludes
local image loading and the warmup requests (`--warmup`, default 2), and counts
only runs where every response contains the expected number of embeddings.
Use `--help` for all options.

Each successful run saves a dated UTC JSON file in `benchmark_history/` (gitignored).
It contains the server's `GET /info` response (model, devices, workers and server
configuration), benchmark parameters, timestamps, elapsed time and images/sec.
The server must expose `/info`; metadata is fetched before warmup, outside the
measurement. Use `--history-dir` to change the output directory.

## Publishing

Create a GitHub release with a tag such as `v1.2.3`. The publish workflow sets
the package version to `1.2.3`, builds distributions, and publishes them via
PyPI Trusted Publishing. Configure the PyPI project as a trusted publisher for
this repository, workflow `publish.yml`, and environment `pypi` before the
first release.
