Metadata-Version: 2.3
Name: cooksafe
Version: 0.2.0
Summary: Shared helpers for the TypeSafe cookbooks
Requires-Dist: lzstring
Requires-Dist: typesafe-sdk>=0.7.0,<0.8.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# CookSafe

Small Python utilities for reproducible LLM experiments and shareable
[TypeSafe](https://console.typesafe.ai) playground links.

- `JsonCache` saves function results to a JSON file and reuses them on subsequent calls.
- `make_playground_link` creates a link containing your input and TypeSafe questions.

## Installation

Requires Python 3.10 or newer. Install from [PyPI](https://pypi.org/project/cooksafe/):

```bash
pip install cooksafe
```

## `JsonCache`

Decorate a synchronous function to persist its results between runs. This is useful for
replaying expensive API calls while developing notebooks or experiments.

```python
from cooksafe import JsonCache

cache = JsonCache("results.json")


@cache
def analyze(text: str) -> dict:
    print("Computing result")
    return {"characters": len(text)}  # Replace with your API call or computation.


print(analyze("hello"))  # Computes and saves {"characters": 5} on the first call.
print(analyze("hello"))  # Returns the saved result without running analyze again.
```

Results must be JSON-serializable. Cache keys use the function name and string representations
of its arguments. Changing the function body does not invalidate existing entries: delete the
cache file before starting a new run to recompute them. Use `JsonCache("results.json", indent=None)`
for compact files.

Cached results are stored in plaintext. Do not commit cache files containing sensitive data.

## `make_playground_link`

Create a link that opens your input and questions in the TypeSafe playground. Inputs can be
text or JSON-compatible data; questions can be `typesafe-sdk` objects or their dictionary forms.

```python
from typesafe_sdk import Noul, NoulCriteria

from cooksafe import make_playground_link

questions = {
    "is_greeting": Noul(
        instructions="Is this a greeting?",
        criteria=NoulCriteria(true="it greets the reader", false="it does not"),
    )
}
print(make_playground_link({"doc": "hello there"}, questions, models=["speed_latest"]))
```

Link generation works offline and needs no API key. The URL contains the input and questions,
so anyone with the link can read them; avoid including sensitive data.

See the [CookSafe cookbooks](https://github.com/typesafe-ai/CookSafe/tree/main/cookbooks)
for complete examples.
