Skip to content

Instructor: using the VIDAI Control Plane as the backend

Instructor patches your OpenAI (or Anthropic) client to add structured output. The base_url and api_key on the client you patch are what Instructor uses — point them at the control plane and every client.chat.completions.create(..., response_model=...) call routes through it.

TL;DR

import instructor
from openai import OpenAI
from pydantic import BaseModel

client = instructor.from_openai(
    OpenAI(
        base_url="https://your-vidai-server.example.com/v1",
        api_key="your-vidai-key",
    )
)

class Ticket(BaseModel):
    priority: str
    reason: str

result = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Ticket,
    messages=[{"role": "user", "content": "printer is on fire"}],
)
print(result)

Prerequisites

  • pip install instructor openai (or anthropic).
  • Control plane base URL and an API key from API Keys.
  • A model registered on the Models page.

Anthropic client

For Claude-family models registered on the control plane, patch the Anthropic client instead. Note the Anthropic base URL is the root (no /v1):

import instructor
from anthropic import Anthropic
from pydantic import BaseModel

client = instructor.from_anthropic(
    Anthropic(
        base_url="https://your-vidai-server.example.com",
        api_key="your-vidai-key",
    )
)

class Extraction(BaseModel):
    name: str
    email: str

result = client.messages.create(
    model="claude-haiku-4-5",
    response_model=Extraction,
    max_tokens=200,
    messages=[{"role": "user", "content": "Alice ([email protected])"}],
)

Validators and retries

Instructor's built-in retries fire when validation fails. Each retry is a fresh control-plane request that shows up in Request Logs, so you can see when the model is struggling to produce valid output.

from pydantic import BaseModel, field_validator

class Answer(BaseModel):
    value: int

    @field_validator("value")
    def positive(cls, v):
        if v < 0:
            raise ValueError("must be positive")
        return v

result = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Answer,
    max_retries=3,
    messages=[{"role": "user", "content": "Return a random positive integer."}],
)

Streaming partial

create_partial streams the object as it builds:

from instructor import Partial

for partial in client.chat.completions.create_partial(
    model="gpt-4o-mini",
    response_model=Partial[Ticket],
    messages=[{"role": "user", "content": "printer is on fire"}],
):
    print(partial)

Verify it works

import instructor
from openai import OpenAI
from pydantic import BaseModel

class Probe(BaseModel):
    reply: str

client = instructor.from_openai(
    OpenAI(
        base_url="https://your-vidai-server.example.com/v1",
        api_key="your-vidai-key",
    )
)

result = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Probe,
    messages=[{"role": "user", "content": "Return reply exactly: ok"}],
)
print(result.reply)

If something's off

Raise an issue at github.com/vidaiUK/vidai-quickstart/issues with your patched client and the response_model that reproduces the issue. We'll get it sorted.

Where to go next