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

pip install recall-relay

For local development:

pip install -e sdk/python

Configure

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

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

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:

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.

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.