Instructor 1.17.0: our test log

Instructor 1.17.0 returned a validated Pydantic object from a local 3B model in 3 of 3 trials (structured extraction, not a tool call); cold uv install 1.4 s.

Result at a glance

What we found

• 3 of 3 task trials passed: the model's tool call reached the framework, the function ran with 17 and 25, and the final answer contained 42.
• Cold install took 1.4 s with uv and 7.3 s with pip, and left 49 MB in 41 packages (uv).
• Different task from the others: structured extraction, not a tool call. We asked for an Order model (order int, city str, date str) from the sentence 'Order 8841 shipped to Austin on 2026-03-02' with JSON mode and max_retries=2.
• Pass here means the validated object equaled order 8841, city Austin, date 2026-03-02.

What we ran, step by step

# Install with uv (cold, no cache)
uv venv -q -p 3.13 work/py/instructor && VIRTUAL_ENV=work/py/instructor uv pip install --no-cache -q instructor

# Install with pip (cold, no cache)
uv venv -q --seed -p 3.13 work/pip/instructor && work/pip/instructor/bin/pip install --no-cache-dir -q instructor

# Task command (all trials)
OTEL_SDK_DISABLED=true work/py/instructor/bin/python tasks/instructor_task.py

Raw output (excerpts)

import json, instructor
from openai import OpenAI
from pydantic import BaseModel
class Order(BaseModel):
    order: int
    city: str
    date: str
c = instructor.from_openai(OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama"), mode=instructor.Mode.JSON)
o = c.chat.completions.create(model="qwen2.5-3b", response_model=Order, max_retries=2, temperature=0, messages=[{"role":"user","content":"Extract the fields from: Order 8841 shipped to Austin on 2026-03-02"}])
ok = o.order == 8841 and o.city == "Austin" and o.date == "2026-03-02"
print("RESULT_JSON " + json.dumps({"calls": [], "final": o.model_dump_json(), "ok": ok}))

import json, os
BASE = "http://127.0.0.1:11434/v1"
MODEL = os.environ.get("MODEL", "qwen2.5-3b")
KEY = "ollama"
TASK = "Use the add_numbers tool to compute 17 + 25, then tell me the result."
CALLS = []
def add_numbers(a: int, b: int) -> int:
    """Add two integers and return the sum."""
    CALLS.append((a, b))
    return int(a) + int(b)
def report(final):
    ok = any({int(x), int(y)} == {17, 25} for x, y in CALLS) and "42" in str(final)
    print("RESULT_JSON " + json.dumps({"calls": CALLS, "final": str(final)[:300], "ok": ok}))

RESULT_JSON {"calls": [], "final": "{\"order\":8841,\"city\":\"Austin\",\"date\":\"2026-03-02\"}", "ok": true}

What we did not test

• Any vendor-hosted model: everything ran on a local 3B model, so tool-call reliability with frontier models is not measured here.
• Multi-agent flows, memory, long conversations, streaming, tracing and cloud deployment.
• Anything beyond one tool and one question; three trials is a smoke test, not a benchmark.

Reproduce it

Versions change. These commands install whatever is latest on the day you run them unless a version is pinned, so expect different results later. The version we measured is in the table above.

# 1. Serve any local model that supports tool calling behind an OpenAI-compatible endpoint, registered as qwen2.5-3b:
#    http://127.0.0.1:11434/v1  (we used Ollama with a Qwen2.5-3B-Instruct Q4_K_M GGUF)
uv venv -p 3.13 .venv && VIRTUAL_ENV=.venv uv pip install instructor
# 2. Save common.py (above) and the task script next to each other, then:
.venv/bin/python instructor_task.py

How to read this test

Every number on this page was measured on this one machine, which also ran other jobs, so timings are indicative and vary run to run. A pass means our small task worked once or as stated, a fail means it did not work as we ran it; neither says how the tool behaves with a vendor's frontier model, on a GPU, or at scale. Where a tool could not run without an account or a GPU, we say so instead of guessing.

See the testing rig for the hardware, the local model and the rules we follow, and the test hub for every other test.

Related tests: agent frameworks and sdks

• LangChain: LangChain 1.4.7 passed our one-tool task on a local 3B model: 3 of 3 trials; cold uv install 0.8 s.
• LangChain.js: LangChain.js 1.5.19 passed our one-tool task 3 of 3 on Node 20 and 3 of 3 on Node 24; about 101 MB in 36 packages.
• LangGraph: LangGraph 1.2.17 passed our one-tool task on a local 3B model: 3 of 3 trials; cold uv install 2.5 s.
• LiteLLM: LiteLLM 1.106.4 passed our one-tool task on a local 3B model: 3 of 3 trials; cold uv install 2.3 s.
• LlamaIndex: LlamaIndex 0.14.25 passed our one-tool task on a local 3B model: 3 of 3 trials; cold uv install 3.4 s.
• Mastra: Mastra passed 5 of 5 on Node 20 (0.24.9) and 5 of 5 on Node 24 (1.79.0) with temperature pinned to 0, after failing 5 of 6 earlier trials at default sampling.

All test logs · How we test

FAQ

Sources

• Instructor repository (fetched 2026-10-25)
• Instructor documentation (fetched 2026-10-25)

Related

• All test logs
• Methodology and testing rig
• Study: install size and first-task results across 16 frameworks