Metadata-Version: 2.4
Name: mm-cache-client
Version: 0.0.2
Summary: Tiny aiohttp client for the mm-cache distributed cache service
Author-email: Michael Feil <no-reply@baseten.co>
License: Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Framework :: AsyncIO
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25; extra == "dev"

# mm-cache-client

`mm-cache-client` is a tiny async Python client for the `mm-cache` service.

## Install

```bash
pip install mm-cache-client==0.0.2
```

## Usage

```python
from mm_cache_client import MMCacheClient, MMCacheConfig

async with MMCacheClient(MMCacheConfig(base_url="http://mm-cache:8080")) as cache:
    hit = await cache.resolve(
        model="moonshotai/Kimi-K2.5",
        content_type="image_url",
        url="https://example.com/cat.png",
    )
    if hit is not None:
        mm_hash = hit.mm_hash
        mm_kwargs = hit.mm_kwargs
```

Plugin fast path:

```python
sha = MMCacheClient.alias_sha(
    model=model_id,
    content_type="image_url",
    url=url,
)
hit = await cache.resolve_sha(model=model_id, sha=sha)
if hit is not None:
    return hit.mm_hash, hit.mm_kwargs
```

Presigned URL churn:

```python
hit = await cache.get_payload(model=model_name, mm_hash=mm_hash)
if hit is not None:
    mm_kwargs = hit.mm_kwargs
```

## API

- `alias_sha(model, content_type, url)`
- `BASETEN_MM_HASH_HEADER`
- `MMCacheClient.alias_sha(model=..., content_type=..., url=...)`
- `MMCacheClient.resolve(...)`
- `MMCacheClient.resolve_sha(...)`
- `MMCacheClient.resolve_alias(...)`
- `MMCacheClient.get_payload(...)`
- `MMCacheClient.put_resolve(...)`
- `MMCacheClient.put_sha(...)`
- `MMCacheClient.put_payload(...)`

## Integration patterns

`image_encoder_plugin`:

```python
sha = MMCacheClient.alias_sha(model=model_id, content_type="image_url", url=url)
hit = await cache.resolve_sha(model=model_id, sha=sha)
if hit is not None:
    return hit.mm_hash, hit.mm_kwargs
```

Encoder backend:

```python
hit = await cache.resolve(model=model_id, content_type="image_url", url=url)
if hit is not None:
    return hit.mm_hash, hit.mm_kwargs

hit = await cache.get_payload(model=model_id, mm_hash=mm_hash)
if hit is not None:
    return hit.mm_hash, hit.mm_kwargs
```

See:

- `examples/plugin_integration.py`
- `examples/encoder_integration.py`
