Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt

Use this file to discover all available pages before exploring further.

​
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?" }
        ]
      }
    ]
  }'