Metadata-Version: 2.4
Name: recall-relay
Version: 0.1.1
Summary: Bring-your-own-key generation relay and private memory client for Recall
Author: Recall contributors
License-Expression: MIT
Project-URL: Homepage, https://recall-production-production.up.railway.app/
Project-URL: Repository, https://github.com/usv240/recall-generation-memory
Project-URL: Documentation, https://github.com/usv240/recall-generation-memory/tree/main/sdk/python
Keywords: generative-media,gemini,backblaze,b2,genblaze,semantic-cache
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# recall-relay

`recall-relay` is a dependency-free, provider-neutral Python client. It checks a private Recall memory before an image, video, or audio provider runs; on a safe hit it returns the stored asset, and on a miss it captures the caller-generated bytes for future reuse.

## Install

```bash
pip install recall-relay
```

For local development:

```bash
pip install -e sdk/python
```

## Configure

Use either a private workspace pair or a scoped Recall integration key:

```bash
export RECALL_URL=https://recall-production-production.up.railway.app
export RECALL_WORKSPACE_ID=ws-...
export RECALL_WORKSPACE_KEY=save-the-one-time-key
# Alternative to the workspace pair:
# export RECALL_API_KEY=your-scoped-integration-key
export GEMINI_API_KEY=your-google-key
```
`n## Use

```bash
recall-relay doctor
recall-relay gemini "Editorial cobalt glass product image" --tag launch --intent brand=Recall --intent format=1:1 --output hero.png --cost-usd 0.067
```

The CLI never prints credentials. `gemini` calls Google only after Recall's private workspace returns a safe miss.

## OpenAI image generation

Set `OPENAI_API_KEY` locally and run:

```bash
recall-relay openai "Editorial cobalt glass product image" --model gpt-image-1 --output hero.png --cost-usd 0.067
```

## Secure releases

PyPI releases use GitHub Trusted Publishing from `.github/workflows/release.yml` and the protected `pypi` environment. No long-lived PyPI token is stored in GitHub.

## Any provider: the adoption API

Use `generate_with()` to add Recall in front of any image, video, or audio provider. The provider call and its credentials stay in your application; Recall only receives completed media after a safe miss.

```python
from recall_relay import RecallRelay

relay = RecallRelay("https://your-recall.example", workspace_id="ws-...", workspace_key="...")

result = relay.generate_with(
    "A launch visual for our cobalt collection",
    generator=lambda prompt: call_your_provider(prompt),  # returns bytes
    provider="your-provider",
    model="your-model",
    media_type="image/png",
    tags=["launch", "cobalt"],
    intent={"brand": "Acme", "format": "1:1"},
    cost_usd=0.42,  # effective cost for this completed output
)
```

On `reused`, `call_your_provider` is never invoked; Relay performs the explicit free retrieval so Recall records the avoided cost. On `generated_and_captured`, Recall stores the output, byte hash, provider/model record, caller-reported cost, and reuse receipt for the next request.

Capture requires a private workspace or `RECALL_API_KEY`; the public demo lane cannot be used for arbitrary uploads. `cost_usd` is optional, but savings remain unpriced until a trustworthy effective cost is supplied. Completed media is limited to 18 MB per capture by default. `RecallRelay(..., max_media_bytes=...)` can lower the client-side ceiling, while the server remains authoritative. Existing output files are never silently overwritten; the CLI selects a numbered filename.
