API Reference

const url = "https://nexuscompute.app/api/v1/chat/completions";
const maxAttempts = 3;

class CapacityUnavailableError extends Error {}
class OutcomeUnknownError extends Error {}

export async function createChatCompletion(apiKey: string) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    let response: Response;
    try {
      response = await fetch(url, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          model: "llama-3-70b",
          messages: [{ role: "user", content: "Summarize this task." }],
          max_tokens: 128,
        }),
        signal: AbortSignal.timeout(30_000),
      });
    } catch (error) {
      // The POST may have reached the server. Retrying or falling back could
      // duplicate a job and charge, so surface the ambiguous outcome instead.
      throw new OutcomeUnknownError(
        "Request timed out or disconnected; verify the job before resubmitting",
        { cause: error },
      );
    }

    if (response.ok) return response.json();

    // Funding and spend controls require operator action; do not retry.
    if (response.status === 402 || response.status === 429) {
      throw new Error(`Operator action required (HTTP ${response.status})`);
    }

    // Retry temporary capacity failures only, with a strict attempt limit.
    if (response.status !== 503) {
      throw new Error(`Chat completion failed (HTTP ${response.status})`);
    }
    if (attempt === maxAttempts) {
      throw new CapacityUnavailableError("Capacity unavailable after 3 attempts");
    }

    const retryAfterHeader = response.headers.get("retry-after");
    const retryAfter = retryAfterHeader === null ? NaN : Number(retryAfterHeader);
    const backoffMs = Number.isFinite(retryAfter) && retryAfter >= 0
      ? Math.min(retryAfter * 1000, 10_000)
      : Math.min(500 * 2 ** (attempt - 1) + Math.random() * 250, 10_000);
    await new Promise((resolve) => setTimeout(resolve, backoffMs));
  }
}

// The operator supplies this policy for definitive 503 responses: call another
// provider, enqueue the task, notify a human, or rethrow. NexusCompute does not
// choose it automatically. Ambiguous network failures are never caught here.
export async function runWithFallback(
  apiKey: string,
  operatorFallback: () => Promise<unknown>,
) {
  try {
    return await createChatCompletion(apiKey);
  } catch (error) {
    if (error instanceof CapacityUnavailableError) {
      return operatorFallback();
    }
    throw error; // 402/429 still require operator action.
  }
}

import random
import math
import time
import requests

URL = "https://nexuscompute.app/api/v1/chat/completions"
MAX_ATTEMPTS = 3

class CapacityUnavailableError(RuntimeError):
    pass

class OutcomeUnknownError(RuntimeError):
    pass

def create_chat_completion(api_key: str):
    for attempt in range(MAX_ATTEMPTS):
        try:
            response = requests.post(
                URL,
                headers={"Authorization": f"Bearer {api_key}"},
                json={
                    "model": "llama-3-70b",
                    "messages": [
                        {"role": "user", "content": "Summarize this task."}
                    ],
                    "max_tokens": 128,
                },
                timeout=30,
            )
        except requests.RequestException as error:
            # The POST may have reached the server. Retrying or falling back
            # could duplicate a job and charge, so surface the ambiguity.
            raise OutcomeUnknownError(
                "Request timed out or disconnected; "
                "verify the job before resubmitting"
            ) from error

        if response.ok:
            return response.json()

        # Funding and spend controls require operator action; do not retry.
        if response.status_code in (402, 429):
            raise RuntimeError(
                f"Operator action required (HTTP {response.status_code})"
            )

        # Retry temporary capacity failures only, with a strict attempt limit.
        if response.status_code != 503:
            raise RuntimeError(
                f"Chat completion failed (HTTP {response.status_code})"
            )
        if attempt == MAX_ATTEMPTS - 1:
            raise CapacityUnavailableError(
                "Capacity unavailable after 3 attempts"
            )

        retry_after = response.headers.get("Retry-After")
        try:
            delay = min(float(retry_after), 10.0)
            if not math.isfinite(delay) or delay < 0:
                raise ValueError
        except (TypeError, ValueError):
            delay = min(0.5 * (2 ** attempt) + random.uniform(0, 0.25), 10.0)
        time.sleep(delay)

# The operator supplies this policy for definitive 503 responses: call another
# provider, enqueue the task, notify a human, or re-raise. NexusCompute does not
# choose it automatically. Ambiguous network failures are never caught here.
def run_with_fallback(api_key: str, operator_fallback):
    try:
        return create_chat_completion(api_key)
    except CapacityUnavailableError:
        return operator_fallback()
    # 402/429 are not caught here; they still require operator action.