OpenAI Python SDK

The official openai package. It works with plugboard on both Chat Completions and the Responses API.

Connect

import os
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:4010/v1", api_key=os.environ["PLUGBOARD_KEY"])

model is an alias from your aliases option, such as "fast", or any allowed provider/model[#variant].

Chat

response = client.chat.completions.create(model=model, messages=[{"role": "user", "content": "Reply with exactly: pong"}])

Tool calls

Plugboard returns the call. Your code runs the tool and sends the result back. TOOL is a function schema and TOOL_RESULT the tool's output.

first = client.chat.completions.create(model=model, messages=messages, tools=[TOOL])
call = first.choices[0].message.tool_calls[0]
# Send the assistant turn back as the SDK typed it, then the result under the same call id.
messages.append(first.choices[0].message.model_dump(exclude_none=True))
messages.append({"role": "tool", "tool_call_id": call.id, "content": TOOL_RESULT})
second = client.chat.completions.create(model=model, messages=messages, tools=[TOOL])

Structured output

client.chat.completions.parse(model=..., messages=..., response_format=Meal) with a Pydantic model returns message.parsed. The full example is structured.py.

Responses API

Text:

response = client.responses.create(model=model, input="Reply with exactly: pong", max_output_tokens=1024)

Tool calls. RESPONSES_TOOL is the tool in the Responses shape (name at the top level, no function wrapper). With store=False you send the whole history in input; with the default store=True you can pass previous_response_id instead.

first = client.responses.create(model=model, input=PROMPT, tools=[RESPONSES_TOOL], store=False, max_output_tokens=1024)
call = next(item for item in first.output if item.type == "function_call")
# Store is off, so the whole conversation goes back in input: the answer's items as the SDK typed them, then the result.
items = [{"role": "user", "content": PROMPT}, *(item.model_dump(exclude_none=True) for item in first.output)]
items.append({"type": "function_call_output", "call_id": call.call_id, "output": TOOL_RESULT})
second = client.responses.create(model=model, input=items, tools=[RESPONSES_TOOL], store=False, max_output_tokens=1024)

Streaming, reading response.output_text.delta events:

with client.responses.stream(model=model, input="Reply with exactly: pong", max_output_tokens=1024) as stream:
    text = ""
    for event in stream:  # the SDK stops here when the server sends response.completed
        if event.type == "response.output_text.delta":
            text += event.delta
    final = stream.get_final_response()

Images, as a data URL:

response = client.responses.create(
    model=model,
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What color is this image? One word."},
                {"type": "input_image", "image_url": RED, "detail": "auto"},
            ],
        }
    ],
    max_output_tokens=1024,
)

Structured output with responses.parse, or the raw text.format json_schema form:

parsed = client.responses.parse(model=model, input=PROMPT, text_format=Meal, max_output_tokens=1024)
meal = parsed.output_parsed  # a Meal, or the SDK raises

client.responses.retrieve, input_items.list and delete work on stored responses. See Responses API.

Files

client.files.create(file=open("doc.pdf", "rb"), purpose="user_data") returns an id you can use in a file part (Chat) or an input_file part (Responses). See Files.

Limits

• Tool call ids differ by model (call_..., toolu_..., a bare UUID). Don't parse them.
• Streaming usage needs stream_options={"include_usage": True}. A streamed tool call arrives as one delta with the whole arguments string.
• The schema in structured output is not enforced by the provider. Validate the answer.
• A wrong key raises AuthenticationError (401). An unknown model raises NotFoundError (404).