nRouter SDKs

OpenAI-compatible SDKs for the nRouter LLM gateway. One key, one bill, the live multi-provider catalog, built-in guardrails, and prompt management. The exact current models are published at nrouter.ai/api/public/models.

SDKs

⚠️ Status corrected 2026-08-02. This table used to mark six branded SDKs "Ready" with copy-pasteable install commands. Only Python exists on disk (sdks/ contains exactly one directory) and only Python is published. Every other install line 404s. Verified against the registries on 2026-08-02: pypi.org/pypi/nroutersdk → 200 (v0.1.0, uploaded 2026-03-31); registry.npmjs.org/@nrouter/sdk → 404. Do not restore a "Ready" status without a registry check.

Until a branded SDK ships for your language, use the stock OpenAI SDK pointed at https://api.nrouter.ai/v1 — that is the supported path and it is what every file under examples/ demonstrates.

Architecture

Every SDK is a thin wrapper around the language's OpenAI SDK. The magic happens server-side.

spec/nrouter-sdk-spec.json          ← Single source of truth
    ↓
sdks/
└── python/                       ← pip install nroutersdk   (the ONLY one that exists)

(planned, not built: node/ go/ java/ ruby/ php/ — see the status table above)

What Every SDK Does (Same Features, Every Language)

1. Pre-configured — base_url and api_key (from NROUTER_API_KEY) set automatically
2. Auto-captures metadata — last_response populated from the gateway's canonical x-nr-* cost, model, token, request, and limit headers
3. Typed errors — GuardrailBlockedError, CreditError, RateLimitError (not generic 400/402/429)
4. Blocks unsupported endpoints — audio, files, fine_tuning, etc. give clear errors, not confusing 404s
5. nRouter APIs — credits.balance(), guardrails.list(), prompts.list(), nrouterModels.pricing()
6. Prompt template override — nrouter_prompt_template_id + nrouter_prompt_variables per request

Keeping SDKs in Sync

All SDKs are driven by spec/nrouter-sdk-spec.json:

{
  "version": "2.0.0",
  "response_headers": { "x-nr-request-cost": { "type": "float" }, ... },
  "errors": { "guardrail_blocked": { "http": 400, "class": "GuardrailBlockedError" }, ... },
  "unsupported_endpoints": { "audio": "...", "files": "...", ... },
  "nrouter_apis": { "credits": { "balance": "/api/credits/balance" }, ... }
}

When the backend changes:

1. Update spec/nrouter-sdk-spec.json
2. Re-publish the Python SDK

(There is no CI that "regenerates + publishes all SDKs" — only the Python package exists, and its release is manual. Do not describe an automated multi-language pipeline that isn't wired.)

Quick Start

Only the Python snippet below is runnable today. The rest show the intended shape of branded SDKs that have not been built — do not paste them into a customer doc.

Python

from nroutersdk import nRouter
client = nRouter()
response = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Hello!"}])
print(f"Cost: ${client.last_response.cost}")

Anthropic Messages (first provider-complete slice)

message = client.messages.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=256,
)
print(message["content"][0]["text"])
print(f"Cost: ${client.last_response.cost}")

Buffered Messages calls are supported in both nRouter and AsyncnRouter. stream=True refuses explicitly until the branded SDK has a tested SSE parser; use the official Anthropic-compatible HTTP endpoint directly if you need streaming today.

Node.js

import { nRouter } from "@nrouter/sdk";
const client = new nRouter();
const res = await client.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "Hello!" }] });

Go

client := nrouter.New()
resp, _ := client.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{...})
fmt.Println(client.LastResponse.Cost)

Ruby

client = nRouter::Client.new
response = client.chat(parameters: { model: "gpt-4o", messages: [{ role: "user", content: "Hello!" }] })

PHP

$client = new \nRouter\nRouter();
$response = $client->chat()->create([...]);

Java

nRouter nrouter = new nRouter();
ChatCompletion resp = nrouter.openai().chat().completions().create(...);

cURL

curl https://api.nrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello!"}]}'

How We Keep SDKs Updated

Industry Standard (What OpenAI, Stripe, Anthropic Do)

The pattern is universal: one spec file → code generation → publish.

Our Approach

┌─────────────────────────────────────────┐
│  spec/nrouter-sdk-spec.json                │   ← YOU EDIT THIS
│  (headers, errors, APIs, version)       │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  scripts/generate-sdks.py               │   ← READS SPEC
│  (validates + generates SDK code)       │
│                                         │
│  For each language:                     │
│    1. Read spec                         │
│    2. Generate response meta class      │
│    3. Generate error classes            │
│    4. Generate unsupported blockers     │
│    5. Generate nRouter API helpers         │
│    6. Write to sdks/{lang}/             │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  CI Pipeline (GitHub Actions)           │
│                                         │
│  On spec change:                        │
│    1. Regenerate all SDKs               │
│    2. Run tests per language            │
│    3. Version bump (from spec.version)  │
│    4. Publish:                          │
│       PyPI, npm, Maven, RubyGems,      │
│       Packagist, Go module tag          │
└─────────────────────────────────────────┘

What Triggers an Update

What DOESN'T Need an Update

This is the key advantage of the thin-wrapper approach: 90% of product changes need zero SDK updates.