> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning

> Use chain-of-thought and extended thinking with a single, provider-agnostic API.

## Overview

**Reasoning** lets the model spend more compute on internal chain-of-thought or extended thinking before producing the final answer. Maitai exposes one **`reasoning`** object on chat requests. The platform maps it to each provider’s native interface (for example reasoning controls on OpenAI reasoning models, thinking blocks on Anthropic, or extracted reasoning content where the model exposes it). You do not need to branch your integration by vendor.

## Request parameters

Pass **`reasoning`** inside the same argument list as your chat completion (SDK) or inside the request body’s **`params`** object (REST). It has two fields:

<ParamField path="reasoning.effort" type="string" optional>
  How much the model should think before answering. Typical values: `"low"`, `"medium"`, `"high"`. Exact behavior depends on the model; Maitai forwards this through the unified config.
</ParamField>

<ParamField path="reasoning.summary" type="boolean" default="false">
  When `true`, the response can include the model’s reasoning text in the top-level **`reasoning`** field (see [Response fields](#response-fields)).
</ParamField>

## SDK examples

### Basic usage (effort only)

<RequestExample>
  ```python Python (async) theme={null}
  import maitai

  client = maitai.MaitaiAsync()

  messages = [
      {"role": "user", "content": "Explain briefly how you would solve 17 * 24."},
  ]

  response = await client.chat.completions.create(
      messages=messages,
      application="demo_app",
      intent="REASONING_DEMO",
      session_id="YOUR_SESSION_ID",
      model="gpt-5",
      reasoning={"effort": "high"},
  )
  print(response.choices[0].message.content)
  ```

  ```python Python (sync) theme={null}
  import maitai

  client = maitai.Maitai()

  messages = [
      {"role": "user", "content": "Explain briefly how you would solve 17 * 24."},
  ]

  response = client.chat.completions.create(
      messages=messages,
      application="demo_app",
      intent="REASONING_DEMO",
      session_id="YOUR_SESSION_ID",
      model="gpt-5",
      reasoning={"effort": "high"},
  )
  print(response.choices[0].message.content)
  ```

  ```javascript Node theme={null}
  import Maitai from "maitai";

  const maitai = new Maitai();

  const messages = [
    { role: "user", content: "Explain briefly how you would solve 17 * 24." },
  ];

  const response = await maitai.chat.completions.create({
    messages,
    application: "demo_app",
    intent: "REASONING_DEMO",
    session_id: "YOUR_SESSION_ID",
    model: "gpt-5",
    reasoning: { effort: "high" },
  });

  console.log(response.choices[0].message.content);
  ```
</RequestExample>

### Returning reasoning in the response

Set **`summary: true`** (Python: `True`) so the completion may include the model’s reasoning text on the response object.

<RequestExample>
  ```python Python (async) theme={null}
  response = await client.chat.completions.create(
      messages=messages,
      application="demo_app",
      intent="REASONING_DEMO",
      session_id="YOUR_SESSION_ID",
      model="gpt-5",
      reasoning={"effort": "high", "summary": True},
  )
  print(response.reasoning)
  print(response.choices[0].message.content)
  ```

  ```python Python (sync) theme={null}
  response = client.chat.completions.create(
      messages=messages,
      application="demo_app",
      intent="REASONING_DEMO",
      session_id="YOUR_SESSION_ID",
      model="gpt-5",
      reasoning={"effort": "high", "summary": True},
  )
  print(response.reasoning)
  print(response.choices[0].message.content)
  ```

  ```javascript Node theme={null}
  const response = await maitai.chat.completions.create({
    messages,
    application: "demo_app",
    intent: "REASONING_DEMO",
    session_id: "YOUR_SESSION_ID",
    model: "gpt-5",
    reasoning: { effort: "high", summary: true },
  });

  console.log(response.reasoning);
  console.log(response.choices[0].message.content);
  ```
</RequestExample>

## API example

Server-side chat completions are sent to Maitai with `application_ref_name`, `session_id`, `action_type` (intent), and a `params` object that mirrors SDK parameters. Include **`reasoning`** inside **`params`**:

```bash theme={null}
curl -sS -X POST "https://api.trymaitai.ai/api/v1/chat/completions/serialized" \
  -H "Content-Type: application/json" \
  -H "X-Maitai-Api-Key: $MAITAI_API_KEY" \
  -d '{
    "application_ref_name": "demo_app",
    "session_id": "YOUR_SESSION_ID",
    "action_type": "REASONING_DEMO",
    "evaluation_enabled": true,
    "params": {
      "messages": [
        { "role": "user", "content": "Short plan to boil an egg." }
      ],
      "model": "gpt-5",
      "stream": false,
      "reasoning": { "effort": "high", "summary": true }
    },
    "auth_keys": {}
  }'
```

Adjust `model` and message content to match your environment.

## Response fields

When **`reasoning.summary`** is enabled and the model returns thinking content, the completion may include:

<ResponseField name="reasoning" type="string | null">
  The model’s chain-of-thought or thinking text. Omitted or `null` when summaries are off or the model does not expose reasoning in the response.
</ResponseField>

Usage may break out reasoning token counts:

<ResponseField name="usage.completion_tokens_details.reasoning_tokens" type="number | null">
  Number of completion tokens attributed to reasoning, when the provider supplies this breakdown.
</ResponseField>

Standard `choices[0].message.content` still holds the final assistant message.

## Portal configuration

In the Maitai Portal, you can set a default **reasoning effort** at the **intent** or **intent group** level as part of model / request configuration (the UI uses the legacy **`reasoning_effort`** field for that default). Per-request **`reasoning`** from the SDK or API overrides those defaults when both are present.

## Related

* [Model Request](/sdk/chat), full chat parameters and Maitai-specific fields