Model settings

iztro-ziwei-v3 and iztro-qimen-v3 use the same supported subset of the standard OpenAI Agents SDK ModelSettings. Settings belong to the Agent request, not to one astrology model. An SDK field is not automatically a supported hosted-model control.

Complete example

The examples below separate deep reasoning from non-thinking sampling because DeepSeek does not allow those controls in the same request.

Python

from agents import ModelSettings
from openai.types.shared import Reasoning
from iztro_agents import iztro_qimen_agent, iztro_ziwei_agent

deep_settings = ModelSettings(
    reasoning=Reasoning(effort="high"),
    max_tokens=384000,
    tool_choice="auto",
    parallel_tool_calls=True,
    metadata={
        "current_datetime": "2026-07-20T14:30:00+08:00",
    },
    extra_body={
        "language": "vi",
    },
)

fast_settings = ModelSettings(
    reasoning=Reasoning(effort="none"),
    temperature=0.4,  # Or top_p=0.9; never set both.
    extra_body={"language": "vi"},
)

ziwei = iztro_ziwei_agent(model_settings=deep_settings)
qimen = iztro_qimen_agent(model_settings=fast_settings)

TypeScript

import type {ModelSettings} from '@openai/agents';
import {iztroQimenAgent, iztroZiweiAgent} from 'openai-iztro-agents';

const deepSettings: ModelSettings = {
  reasoning: {effort: 'high'},
  maxTokens: 384000,
  toolChoice: 'auto',
  parallelToolCalls: true,
  providerData: {
    language: 'vi',
    metadata: {
      current_datetime: '2026-07-20T14:30:00+08:00',
    },
  },
};

const fastSettings: ModelSettings = {
  reasoning: {effort: 'none'},
  temperature: 0.4, // Or topP: 0.9; never set both.
  providerData: {language: 'vi'},
};

const ziwei = iztroZiweiAgent({modelSettings: deepSettings});
const qimen = iztroQimenAgent({modelSettings: fastSettings});

For production Qimen requests, create the timestamp from the user's local clock on each turn. A fixed current_datetime is appropriate only for tests, replays, or reproducible examples.

Support matrix

Control	Python	TypeScript	Raw Chat API	Iztro behavior
Reasoning effort	reasoning=Reasoning(effort=...)	reasoning: {effort: ...}	reasoning_effort	Selects the fast or deep execution path
Output ceiling	max_tokens	maxTokens	max_tokens	Limits generated output tokens
Temperature	temperature	temperature	temperature	Non-thinking only, range 0 to 2; cannot be combined with top-p
Nucleus sampling	top_p	topP	top_p	Non-thinking only, range 0 to 1; cannot be combined with temperature
Frequency penalty	frequency_penalty	frequencyPenalty	frequency_penalty	Unsupported by DeepSeek; the hosted API rejects it
Presence penalty	presence_penalty	presencePenalty	presence_penalty	Unsupported by DeepSeek; the hosted API rejects it
Developer tool mode	tool_choice	toolChoice	tool_choice	Controls developer-supplied tools only
Parallel developer tools	parallel_tool_calls	parallelToolCalls	parallel_tool_calls	Allows multiple developer tool calls in one turn
Question time	metadata.current_datetime	providerData.metadata.current_datetime	metadata.current_datetime	Sets the user's local question time
Response language	extra_body.language	providerData.language	language	Forces one unmixed response language
Hosted Iztro tools	extra_body.enable_iztro_call	providerData.enable_iztro_call	enable_iztro_call	Enables or disables hosted chart calculations

reasoning, token, sampling, and developer tool controls are standard SDK fields, but only the behaviors marked supported above are hosted-model controls. language, current_datetime, and enable_iztro_call are Iztro request extensions carried through the SDK's standard provider-extension fields.

Reasoning effort

Iztro maps standard effort values onto two execution paths:

Reasoning effort	Iztro execution path	Use it for
omitted / none / minimal / low	Faster non-thinking model	Chat, follow-up questions, and straightforward readings
medium / high / xhigh / raw HTTP max	Deep-reasoning model at high effort	Comprehensive Ziwei reports, difficult chart synthesis, and multi-evidence Qimen decisions

Use high when depth matters. Current Python and TypeScript Agents SDK types accept through xhigh. Raw HTTP also accepts max; Iztro intentionally maps every deep value to the same provider high effort. Do not send a custom thinking field or an Iztro-specific value such as "deep".

Accuracy on complex charts

Non-thinking mode prioritizes latency and can miss or mis-associate details in a complex chart. Use high for cross-palace Ziwei synthesis, multiple fortune layers, or Qimen decisions that combine chart and timing evidence. Deep reasoning is generally more reliable for these readings, but it does not guarantee correctness; conclusions should remain grounded in the chart facts returned by the hosted tools.

Reasoning effort does not control answer length. Use max_tokens or maxTokens separately.

Output limit

When omitted, both public models use the current configured DeepSeek maximum of 384,000 output tokens. This is the recommended setting for comprehensive Ziwei reports and Qimen questions that may require chart calculation followed by timing analysis.

Set a lower ceiling only when the application needs a hard cost or latency bound:

ModelSettings(max_tokens=12000)

const modelSettings = {maxTokens: 12000};

A small limit can end a multi-step answer before all chart evidence and timing conclusions are written. The API returns finish_reason: "length" when the configured ceiling is reached.

Sampling

temperature and top_p / topP work only on the non-thinking path. Set exactly one of them, or omit both to use the model default:

ModelSettings(
    reasoning=Reasoning(effort="none"),
    temperature=0.4,
)

Deep reasoning ignores both controls, so Iztro rejects that combination instead of accepting a setting that cannot take effect. DeepSeek has deprecated and no longer supports frequency_penalty / frequencyPenalty and presence_penalty / presencePenalty; Iztro rejects them in every mode.

Response language

Supported values are zh, en, ko, ja, and vi. When set, all user-facing headings, prose, lists, conclusions, caveats, tool-progress narration, and translated domain terms use only that language. The model does not mix source-language terms or append them in parentheses.

Code, URLs, model names, API/tool/event identifiers, and JSON keys remain canonical. Omit language when the answer should follow the conversation language automatically.

Time and application instructions

Use metadata.current_datetime for the user's local ISO 8601 time, including the UTC offset. It is especially important for Qimen because the question time determines the chart.

Raw Chat API metadata also supports system_prompt_override for application instructions up to 8,000 characters:

{
  "metadata": {
    "current_datetime": "2026-07-20T14:30:00+08:00",
    "system_prompt_override": "Put the conclusion first and distinguish evidence from practical advice."
  }
}

Tool controls

tool_choice and parallel_tool_calls apply only to function or MCP tools supplied by your application. Hosted Ziwei and Qimen calculations remain hidden and are reported through Iztro tool events. Use enable_iztro_call: false only when the answer must rely entirely on context your application already supplied.

SDK fields outside the hosted model contract

The Agents SDK exposes more ModelSettings fields because it supports multiple providers and both Chat Completions and Responses APIs. The following are not currently Iztro hosted-model controls:

• reasoning summaries and verbosity / text.verbosity;
• frequency_penalty and presence_penalty, which DeepSeek no longer supports;
• store, prompt-cache retention, truncation, response includes, and top log probabilities;
• arbitrary provider fields other than the documented Iztro extensions.

SDK runtime or transport options such as retry policy and extra headers remain SDK concerns. Usage is returned automatically by Iztro; developers do not need to enable it.

Raw HTTP example

{
  "model": "iztro-qimen-v3",
  "reasoning_effort": "high",
  "max_tokens": 384000,
  "language": "vi",
  "messages": [
    {
      "role": "user",
      "content": "Tôi nên thúc đẩy quan hệ hợp tác này ngay hay tiếp tục đàm phán? Hãy giải thích căn cứ và thời điểm hành động."
    }
  ],
  "metadata": {
    "current_datetime": "2026-07-20T14:30:00+08:00"
  }
}