Metadata-Version: 2.4
Name: hypercache-kv
Version: 0.1.2
Summary: Official Python client for the HyperCache API.
Author-email: Hyper Cache <contact@hypercache.ai>
License: MIT
Project-URL: homepage, https://hypercache.ai
Project-URL: documentation, https://hypercache.ai/docs
Project-URL: repository, https://github.com/Hyper-Cache/hypercache-sdk
Project-URL: issues, https://github.com/Hyper-Cache/hypercache-sdk/issues
Keywords: ai,llm,cache,inference
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == "numpy"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: numpy>=1.20; extra == "test"
Dynamic: license-file

# hypercache (Python SDK)

Python client for the [HyperCache](https://hypercache.ai) API. Zero runtime dependencies (stdlib only).

## Install

```bash
pip install hypercache-kv
export HYPERCACHE_KEY=hck_...
```

Get a key at [hypercache.ai](https://hypercache.ai).

## Pipeline

Cache, records, and stats in one context:

```python
from hypercache.workflows import Pipeline

with Pipeline("my_pipeline") as p:
    answer, was_hit = p.cached(
        label="gpt_call",
        input_bytes=prompt.encode("utf-8"),
        compute=lambda: call_openai(prompt),
    )
    p.record("output", answer.encode("utf-8"))

print(f"{p.report.n_hits} hits / {p.report.n_misses} misses")
```

## Cache an expensive call

```python
import hypercache

result = hypercache.cache_lookup(b"some input bytes")
if result.hit:
    print(result.value)
else:
    hypercache.cache_put(result.fingerprint_hex, b"my expensive output", ttl=3600)

results = hypercache.cache_lookup_batch([b"in 1", b"in 2", b"in 3"])
```

## Wrap your LLM client

```python
from openai import OpenAI
from hypercache.workflows import wrap_openai

client = wrap_openai(OpenAI())
resp = client.chat.completions.create(model="gpt-4o-mini", messages=[...])
```

`wrap_anthropic` does the same for the Anthropic SDK.

## Records

```python
import hypercache

fp = hypercache.fingerprint(b"any bytes")
print(fp.record_hex)
```

Link records to a prior one:

```python
from hypercache.workflows import audit_chain

with audit_chain() as chain:
    r1 = chain.fingerprint(input_bytes)
    r2 = chain.fingerprint(model_output)
    r3 = chain.fingerprint(reviewer_note)
```

## License

MIT. See [LICENSE](./LICENSE).
