Instructor
Integrate nRouter with Instructor for structured LLM outputs, automated retry logic, streaming responses, and strict Pydantic model validation in Python.
Integrate Instructor with nRouter for structured LLM outputs, automated retry cycles, and strict Pydantic validation backed by enterprise gateway controls. Point Instructor's patched OpenAI client to https://api.nrouter.ai/v1 to enforce schemas alongside server-side prompt injection defense, exact-match caching, and real-time cost tracking.
For framework details, see the official Instructor documentation.
Installation & Setup
Install Instructor with Pydantic and the nRouter SDK:
pip install instructor openai pydantic nrouter-sdk
export NROUTER_API_KEY="sk-nrouter-xxxxxxxxxxxx"Configure Instructor with the nRouter gateway endpoint:
import os
import instructor
from openai import OpenAI
client = instructor.from_openai(
OpenAI(
base_url="https://api.nrouter.ai/v1",
api_key=os.environ["NROUTER_API_KEY"],
timeout=30.0,
max_retries=2,
)
)Structured Output & Validation
Extract typed Pydantic models with automated retry on validation failures:
from pydantic import BaseModel, Field
class UserProfile(BaseModel):
name: str = Field(description="Full name")
skills: list[str] = Field(description="Verified technical skills")
years_of_experience: int = Field(description="Years of professional experience")
user_data = client.chat.completions.create(
model="gpt-5.4-mini",
response_model=UserProfile,
max_retries=3,
messages=[
{"role": "user", "content": "Jason has 8 years of experience building distributed systems in Rust."}
],
)
print(f"{user_data.name} ({user_data.years_of_experience} yrs): {', '.join(user_data.skills)}")Routing & Observability
Configure model selection, caching, and cost tracking:
- Routing & fallbacks: Target specific models or use
nrouter/auto(see Router Settings). For per-call fallbacks, passnrouter_fallbacksinextra_body(see Per-Request Options). - Exact-match caching: Set
"nrouter_cache": Trueinextra_bodyto answer repeated extractions from cache. - FinOps telemetry: Headers include
x-nr-request-id,x-nr-model,x-nr-cost-status, andx-nr-request-cost. - Error handling: Gateway errors map to HTTP status codes (see Errors & Rate Limits):
import openai
try:
product = client.chat.completions.create(
model="gpt-5.4-mini",
response_model=UserProfile,
messages=[{"role": "user", "content": "Extract profile for Alice"}],
)
except openai.BadRequestError as e:
print(f"Blocked by guardrail or invalid parameters: {e}")
except openai.RateLimitError:
print("Rate limit reached. Backing off before retry.")Next Steps
- Python SDK Guide — Official nRouter Python SDK documentation
- LangChain Integration — Orchestrating chains and RAG workflows
- Chat Completions API — Complete HTTP wire specifications