Thinking - Perceptron Docs

Overview

Thinking exposes the model’s chain-of-thought. The SDK extracts <think>...</think> spans and returns them under reasoning while keeping the final text clean. Reasoning is opt-in unless the model is marked as “thinking”.

When reasoning runs

Set reasoning=True to turn on reasoning for any perceive call or CLI run.
Models that disable reasoning drop the flag and warn instead of erroring.
Without reasoning=True, calls return answers with no <think> trace.

How to request reasoning

Reasoning flag: @perceive(..., reasoning=True) or for streaming, perceive(..., reasoning=True, stream=True) (defaults to text outputs).
High-level helpers: pass the same flag, e.g. caption(..., reasoning=True), detect(..., reasoning=True), or question(..., reasoning=True).

Streaming usage (Python)

import perceptron
from perceptron import perceive, image, text

perceptron.configure(provider="perceptron", api_key="YOUR_API_KEY")

@perceive(model="isaac-0.2-2b-preview", stream=True, reasoning=True)
def check_safety(img):
  return image(img) + text("Are all workers wearing proper safety equipment?")

for event in check_safety("https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/main/cookbook/_shared/assets/capabilities/detection/ppe_line.webp"):
  if event["type"] == "text.delta":
    print(event["chunk"], end="")
  if event["type"] == "final":
    res = event["result"]
    print()  # newline after streamed deltas
    print("Reasoning trace:")
    print((res.get("reasoning") or "").strip())
    print()
    print("Answer:")
    print((res.get("text") or "").strip())

Non-streaming usage (Python)

import perceptron
from perceptron import perceive, image, text

perceptron.configure(provider="perceptron", api_key="YOUR_API_KEY")

@perceive(model="isaac-0.2-2b-preview", reasoning=True)
def check_safety(img):
  return image(img) + text("Are all workers wearing proper safety equipment?")

result = check_safety("https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/main/cookbook/_shared/assets/capabilities/detection/ppe_line.webp")
print("Reasoning trace:")
print((result.reasoning or "").strip())
print()
print("Answer:")
print((result.text or "").strip())

Event and result shape

Streaming emits text.delta chunks; reasoning appears first wrapped in <think>...</think>, followed by answer text. There is no separate reasoning.delta channel.
The final payload is { "type": "final", "result": { ... } } where result["reasoning"] is a list of extracted reasoning strings and result["text"] omits the <think> tags.
Structured helpers (detect, ocr, caption, question, etc.) pass through the same reasoning flag and include traces in their final results.

Tips

Use low temperature for repeatable traces.
Request reasoning only when you need it; thinking models already enable it automatically.
Capture the final reasoning list for logging instead of scraping <think> tags yourself.

When to enable thinking

On for text Q&A, captioning, OCR, and video clipping (annotation_format: "clip").
Combining <hint>THINK</hint> with <hint>BOX</hint> or <hint>POINT</hint> is helpful for counting and multi-step spatial reasoning, but not for pure detection.

See the full request/response schema in the Chat Completions API.

API usage

curl https://api.perceptron.inc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "isaac-0.2-2b-preview",
    "messages": [
      { "role": "system", "content": "<hint>THINK</hint>" },
      { "role": "user",
        "content": [
          { "type": "image_url", "image_url": { "url": "<image-url>" } },
          { "type": "text", "text": "Are all workers wearing proper safety equipment?" }
        ]
      }
    ]
  }'

​Overview

​When reasoning runs

​How to request reasoning

​Streaming usage (Python)

​Non-streaming usage (Python)

​Event and result shape

​Tips

​When to enable thinking

​API usage