> ## 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.

# Thinking

> Use reasoning traces to inspect how the model reached an answer.

## 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)

```python theme={null}
import perceptron
from perceptron import perceive, image, text

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

@perceive(model="perceptron-mk1", 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)

```python theme={null}
import perceptron
from perceptron import perceive, image, text

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

@perceive(model="perceptron-mk1", 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"`).
* **Off** for spatial detection (`point`, `box`, `polygon`).

See the full request/response schema in the [Chat Completions API](/perceptron-mk1/api-reference/endpoint/chat-completions).

## API usage

```bash theme={null}
curl https://api.perceptron.inc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "perceptron-mk1",
    "messages": [
      { "role": "user",
        "content": [
          { "type": "image_url", "image_url": { "url": "<image-url>" } },
          { "type": "text", "text": "Are all workers wearing proper safety equipment?" }
        ]
      }
    ],
    "vision_config": { "enable_thinking": true }
  }'
```