Caching and outages

curl https://app.reflections.ai/v1/checks \
  -H "Authorization: Bearer rk_test_…" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "talent": ["tal_9t0wxyhk5zba2q8v1m3n7p4r6s"],
    "facet": "fct_v1m3n7p4r6s9t0wxyhk5zba2q8",
    "inputs": [{ "role": "script", "text": "Welcome back to the Ridge Runners podcast." }],
    "use": {
      "modality": "speech", "kind": "impersonation", "purpose": "personal",
      "commercial": false, "channels": ["in_app"], "territories": ["US"]
    },
    "end_user": { "id": "usr_48213" },
    "execution": { "provider": "example-voice-provider", "model": "tts-2", "candidates": 1 },
    "on_escalate": "deny",
    "reuse": { "max_generations": 200, "ttl": "PT15M" }
  }'

const check = await fetch("https://app.reflections.ai/v1/checks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    talent: ["tal_9t0wxyhk5zba2q8v1m3n7p4r6s"],
    facet: "fct_v1m3n7p4r6s9t0wxyhk5zba2q8",
    inputs: [{ role: "script", text: "Welcome back to the Ridge Runners podcast." }],
    use: {
      modality: "speech", kind: "impersonation", purpose: "personal",
      commercial: false, channels: ["in_app"], territories: ["US"],
    },
    end_user: { id: "usr_48213" },
    execution: { provider: "example-voice-provider", model: "tts-2", candidates: 1 },
    on_escalate: "deny",
    reuse: { max_generations: 200, ttl: "PT15M" },
  }),
}).then((r) => r.json());

import os, uuid, requests

check = requests.post(
    "https://app.reflections.ai/v1/checks",
    headers={
        "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
        "Reflections-Version": "2026-10-15",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "talent": ["tal_9t0wxyhk5zba2q8v1m3n7p4r6s"],
        "facet": "fct_v1m3n7p4r6s9t0wxyhk5zba2q8",
        "inputs": [{"role": "script", "text": "Welcome back to the Ridge Runners podcast."}],
        "use": {
            "modality": "speech", "kind": "impersonation", "purpose": "personal",
            "commercial": False, "channels": ["in_app"], "territories": ["US"],
        },
        "end_user": {"id": "usr_48213"},
        "execution": {"provider": "example-voice-provider", "model": "tts-2", "candidates": 1},
        "on_escalate": "deny",
        "reuse": {"max_generations": 200, "ttl": "PT15M"},
    },
).json()

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

export async function post(path: string, body: unknown, key = crypto.randomUUID()) {
  for (let attempt = 0; attempt < 6; attempt++) {
    let wait = Math.min(1000 * 2 ** attempt, 30_000) * (0.5 + Math.random() / 2);
    let res: Response | undefined;
    try {
      res = await fetch(`https://app.reflections.ai/v1${path}`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
          "Reflections-Version": "2026-10-15",
          "Idempotency-Key": key, // the same key on every attempt
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(10_000),
      });
    } catch {
      // Timeout or network error: the outcome is unknown. Retry with the same key.
    }
    if (res?.ok) return res.json();
    if (res) {
      const problem = await res.json().catch(() => ({})); // a proxy's 502 may not be JSON
      const retryable =
        res.status >= 500 || res.status === 429 || problem.code === "idempotency_key_in_use";
      if (!retryable) throw new Error(`${res.status} ${problem.code}: ${problem.detail ?? problem.title}`);
      wait = retryAfterMs(res) ?? wait;
    }
    await sleep(wait);
  }
  throw new Error("Reflections unavailable: fail closed");
}

// Retry-After from Reflections is in seconds; a proxy in front of it may send an HTTP date.
function retryAfterMs(res: Response): number | undefined {
  const value = res.headers.get("Retry-After");
  if (!value) return undefined;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value);
  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
}

import os, random, time, uuid, requests
from email.utils import parsedate_to_datetime

def post(path, body, key=None):
    key = key or str(uuid.uuid4())  # the same key on every attempt
    for attempt in range(6):
        wait = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
        try:
            res = requests.post(
                f"https://app.reflections.ai/v1{path}",
                headers={
                    "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
                    "Reflections-Version": "2026-10-15",
                    "Idempotency-Key": key,
                },
                json=body,
                timeout=10,
            )
        except requests.RequestException:
            time.sleep(wait)  # unknown outcome: retry with the same key
            continue
        if res.ok:
            return res.json()
        try:
            problem = res.json()
        except ValueError:  # a proxy's 502 may not be JSON
            problem = {}
        retryable = res.status_code >= 500 or res.status_code == 429 or problem.get("code") == "idempotency_key_in_use"
        if not retryable:
            raise RuntimeError(f"{res.status_code} {problem.get('code')}: {problem.get('detail', problem.get('title'))}")
        delay = retry_after(res)
        time.sleep(wait if delay is None else delay)
    raise RuntimeError("Reflections unavailable: fail closed")

def retry_after(res):
    """Seconds to wait, or None. Reflections sends seconds; a proxy may send an HTTP date."""
    value = res.headers.get("Retry-After")
    if not value:
        return None
    try:
        return max(0.0, float(value))
    except ValueError:
        pass
    try:
        return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
    except (TypeError, ValueError):
        return None