Oracle SDK

Install

Quick start (TypeScript)

import { OracleClient } from "@inferenceflow/oracle-sdk";

// Maintains a background WebSocket connection.
// Health states update in < 1ms from local cache.
const oracle = new OracleClient({ apiKey: process.env.ORACLE_API_KEY });

await oracle.connect();

// Before calling a model:
const health = oracle.check("openai-gpt4o");

if (health.state === "green") {
  const result = await callGPT4o(prompt);
} else if (health.state === "yellow") {
  // Route to fallback
  const result = await callClaude(prompt);
} else {
  // RED — skip spend, use cached response
  throw new Error("Primary provider down, skipping transaction");
}

Quick start (Python)

from inferenceflow import OracleClient

oracle = OracleClient(api_key=os.environ["ORACLE_API_KEY"])
oracle.connect()  # starts background WebSocket listener

# Inside your agent loop:
health = oracle.check("anthropic-claude35")

if health.state == "green":
    response = call_claude(prompt)
elif health.state == "yellow":
    response = call_fallback(prompt)
else:
    raise RuntimeError(f"Provider down: {health.provider_id}")

REST API

Health object

{
  "provider_id": "openai-gpt4o",
  "name": "GPT-4o",
  "state": "green",           // "green" | "yellow" | "red"
  "uptime_24h": 99.87,        // percent
  "latency": {
    "p50": 312,               // milliseconds
    "p95": 720,
    "p99": 1240
  },
  "ttft": 187,                // time to first token, ms
  "error_rate": 0.12,         // percent
  "cost_per_1k": 0.005,       // USD per 1 000 input tokens
  "cost_drift": 1.2,          // percent change vs 7-day average
  "checked_at": "2025-01-01T12:00:00Z"
}