Metadata-Version: 2.4
Name: paperclip-llm-cache
Version: 0.1.0a1
Summary: Semantic cache for LLM API calls — pay once, answer many paraphrases.
Author-email: Paperclip <noreply@paperclip.ing>
License: MIT
License-File: LICENSE
Keywords: cache,embeddings,llm,openai,semantic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# llm-cache

Semantic **inference cache** for LLM API calls: intercept prompts, embed them, and reuse prior completions when a new prompt is semantically similar enough.

This is intentionally **not** a durable “agent memory” product. It optimizes **cost and latency** by avoiding repeat work for paraphrased prompts.

## Install

The **PyPI distribution name** is `paperclip-llm-cache` (PyPI rejected the shorter `llm-cache` as too similar to an existing project). The **import package** is still `llm_cache`.

**PyPI:**

```bash
pip install paperclip-llm-cache
```

**From source:**

```bash
pip install -e .
```

## Quickstart

Wire a SQLite backend and use `LLMCache` for `store` / `lookup`. You supply embeddings from your own model; dimensions must stay consistent for cosine similarity.

```python
from llm_cache import LLMCache, SQLiteBackend

with SQLiteBackend("/path/to/cache.sqlite") as backend:
    cache = LLMCache(similarity_threshold=0.95, backend=backend)
    cache.store(
        prompt_fingerprint="sha256-or-id-of-prompt",
        embedding=[...],  # sequence of floats from your embedder
        response="plain or JSON string of the completion",
    )
    hit = cache.lookup([...])  # embedding of the new prompt
```

See [examples/basic_sqlite_cache.py](examples/basic_sqlite_cache.py) for a small runnable script.

`LLMCache.wrap` is reserved for the OpenAI adapter path (not implemented in this scaffold).

## Docs and releasing

- **GitHub:** https://github.com/j-srodka/llm-cache
- [CHANGELOG.md](CHANGELOG.md) — version history (repo root in this workspace).
- [docs/RELEASING.md](docs/RELEASING.md) — release checklist, tagging, PyPI upload, and board-owned CI secrets.

## Status

v0.1.0a1 is an alpha scaffold. See the parent tracking issue on Paperclip for scope and task breakdown.

## Dev

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
mypy
```

## License

MIT
