Reasoning

Use the top-level reasoning_effort field to control reasoning in new integrations. Accepted values are none, minimal, low, medium, and high. These guides use high when enabling reasoning and none when disabling it. Evaluate answer quality and latency on your task. none requests an answer without reasoning; any other tier enables reasoning without an additional flag. minimal currently maps to low. Send the exact lowercase values: an unsupported tier is rejected by the SDK before sending. A raw API request with an unsupported tier returns HTTP 400 with invalid_request_error and a message naming reasoning_effort.

{
  "model": "perceptron-mk1.5",
  "messages": [{"role": "user", "content": "Explain how to check whether two observations are consistent."}],
  "reasoning_effort": "high",
  "max_completion_tokens": 2048
}

The final answer is in message.content. When returned, reasoning is in the separate message.reasoning_content extension. In the Perceptron SDK, read the final answer from response.text and optional reasoning from response.reasoning. Streaming chunks use delta.reasoning_content separately from delta.content. The field location depends on the endpoint:

Endpoint	Control	Scope
`/v1/chat/completions`	`reasoning_effort`	The completion request, including tool-calling turns.
`/v1/chat/completions/multilook`	`reasoning_effort`	One tier shared by every prompt and completion in the request.
`/v1/detect`	`config.reasoning_effort`	Detection-mode-specific behavior; see Detect.

Choose effort for your task

Use none for a baseline without reasoning, including straightforward captions, direct questions, or transcription.
Set reasoning_effort="high" when enabling reasoning for comparisons, counting with ambiguous overlaps, or questions that combine several observations. Evaluate the answer against examples with known results.
Measure the added token and latency cost. Higher effort does not guarantee a more accurate answer.

Higher tiers can spend more of max_completion_tokens on reasoning. A budget of only a few hundred tokens may leave an empty final answer with finish_reason: "length". Start with a larger budget, such as 2,048 tokens in the example below, and adjust to your task within the model’s context and output limits. Evaluate spatial and temporal tasks with the same approach: check the returned geometry, labels, timestamps, and asset references. Do not assume that every task benefits from the same effort level.

Read a completed answer

Install perceptron>=0.4.0 and set PERCEPTRON_API_KEY. This example keeps reasoning separate from the answer and checks that generation completed:

import os

from perceptron import Client, image


client = Client(
    provider="perceptron",
    api_key=os.environ["PERCEPTRON_API_KEY"],
)
messages = [{
    "role": "user",
    "content": [
        image(
            "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/"
            "main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
        ),
        {"type": "text", "text": (
            "Compare the terrain along the coast and farther inland. Support your answer with visible evidence."
        )},
    ],
}]
response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=messages,
    reasoning_effort="high",
    max_completion_tokens=2048,
)
choice = response.choices[0]
if choice.finish_reason != "stop" or choice.message.tool_calls:
    raise RuntimeError(f"Expected a completed answer, got: {choice.finish_reason}")

reasoning = response.reasoning or ""
answer = response.text
print("Reasoning:", reasoning)
print("Answer:", answer)
if response.usage is not None:
    print("Usage:", response.usage.to_dict())

Reasoning may be absent, in which case response.reasoning is None. Use response.text as the final answer instead of joining the two fields.

Consume reasoning in a stream

Run this after defining client and messages above. It collects the two fields independently and consumes the entire stream, including a possible final usage chunk with no choices:

reasoning_parts = []
answer_parts = []

with client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=messages,
    reasoning_effort="high",
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
) as stream:
    for chunk in stream:
        for choice in chunk.choices:
            delta = choice.delta
            if delta is not None:
                if delta.tool_calls:
                    raise RuntimeError("Expected an answer, but received a tool call")
                reasoning_parts.append(delta.reasoning_content or "")
                answer_parts.append(delta.content or "")
    response = stream.get_final_completion()

if not response.complete or response.finish_reason != "stop" or response.tool_calls:
    raise RuntimeError(f"Incomplete answer: {response.finish_reason}")

print("Reasoning:", "".join(reasoning_parts))
print("Answer:", "".join(answer_parts))
if response.usage is not None:
    print("Usage:", response.usage.to_dict())

The SDK assembles reasoning, text, and usage in get_final_completion(). It raises on streamed API errors or a stream that ends before its completion marker. If iteration raises or the final completion is unsuccessful, treat the accumulated text as incomplete. A length finish reason can mean reasoning used the available budget before the answer was finished.

Retain reasoning in conversation history

For tool conversations, preserve reasoning_content on assistant messages when sending the history back. Append response.message or response.message.to_dict() to history after checking that a message was returned; both retain the reasoning and tool-call fields. The tool-calling guide demonstrates this alongside call IDs and tool results.

Migrating the older flag

For chat completions and Multilook, vision_config.enable_thinking is a deprecated compatibility control. If present, it overrides whether reasoning is enabled, even when you also send reasoning_effort:

false keeps reasoning off, including with reasoning_effort: "high".
true enables reasoning. An enabled tier still sets the effort; reasoning_effort: "none" does not turn reasoning off in this combination and leaves the tier unpinned.

Omit the deprecated flag when using reasoning_effort so there is one source of control. Detect has different precedence: its explicit config.reasoning_effort wins over config.enable_thinking. Reasoning text consumes output budget. Leave room for the final answer or tool arguments, and check finish_reason before using the result. Increasing effort does not replace validation of annotations, extracted facts, or function arguments. See the tokenization guide for output budgeting and usage accounting.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Choose effort for your task

Read a completed answer

Consume reasoning in a stream

Retain reasoning in conversation history

Migrating the older flag

​Choose effort for your task

​Read a completed answer

​Consume reasoning in a stream

​Retain reasoning in conversation history

​Migrating the older flag

Choose effort for your task

Read a completed answer

Consume reasoning in a stream

Retain reasoning in conversation history

Migrating the older flag