Use cases and models

Choose a feature below to find a recommended model, the reason for that choice, and a prompt. Replace the [placeholders] with customer details. Every scenario includes Python and TypeScript code.

Feature	Recommended model	Reason	Prompt and code
Generate a complete Ziwei life report in one request	`iztro-ziwei-v3-fast`	Combines chart, decade, and annual data to produce a report in the requested structure	Birth chart, every decade, and five years
Ongoing Ziwei consultation or report follow-ups	`iztro-ziwei-v3`	Adds period-specific interpretations as each new question requires	Conversation
Generate a detailed Qimen analysis in one request	`iztro-qimen-v3-fast`	Uses the collected situation details to deliver a complete analysis in one response	Situation analysis
Ongoing Qimen consultation	`iztro-qimen-v3`	Continues the analysis as the customer adds information and questions	Follow-up questions

Use fast for one-off reports and v3 for ongoing consultations. Specify the report's scope and level of detail in the prompt.

All four models support complete reports and ongoing conversations. Thinking can be configured separately: v3 enables it by default, while fast disables it. See Model settings to change it.

Before running the code, follow SDK quickstart to install the SDK and set ZIWEI_API_KEY. The customer details in the code are illustrative. To switch models, change model_name in Python or modelName in TypeScript.

Generate a complete life report

Fill in the customer's Gregorian birth date, birth time, and gender, plus the years the report should cover:

Generate a complete Ziwei Doushu life report for the following customer.
Customer details: Gregorian birth date [birth date], birth time [birth time], gender [gender].

Include:
1. Birth chart: list the major stars and transformations across all twelve palaces. Interpret the overall chart, career, wealth, relationships, and family.
2. Every decade cycle: analyze each decade shown in the chart, with its age range and main themes. Cover all cycles.
3. Five years: analyze each year from [start year] through [end year], relating it to its decade cycle.

Return the complete report in one response, using Markdown headings and tables. Identify missing customer details before proceeding.

For example, a five-year period starting in 2026 covers 2026 through 2030.

For an interactive chart graphic, integrate the iztro chart library separately. This prompt produces a report with text and tables.

View complete Python / TypeScript code

Python
TypeScript

import asyncio
from agents import Runner
from iztro_agents import iztro_ziwei_fast_agent

PROMPT = """Generate a complete Ziwei Doushu life report for this customer.
Customer details: Gregorian birth date 1990-06-15, birth time 10:00, male.
1. Birth chart: list major stars and transformations in all twelve palaces; interpret the overall chart, career, wealth, relationships, and family.
2. Every decade cycle: interpret all decades in the chart, with age ranges and main themes.
3. Five years: analyze 2026 through 2030 individually, relating each year to its decade cycle.
Return the complete report in one response with headings and tables."""

async def main():
    agent = iztro_ziwei_fast_agent(model_name="iztro-ziwei-v3-fast")
    result = await Runner.run(agent, PROMPT)
    print(result.final_output)

asyncio.run(main())

import {run} from '@openai/agents';
import {iztroZiweiFastAgent} from 'openai-iztro-agents';

const prompt = `Generate a complete Ziwei Doushu life report for this customer.
Customer details: Gregorian birth date 1990-06-15, birth time 10:00, male.
1. Birth chart: list major stars and transformations in all twelve palaces; interpret the overall chart, career, wealth, relationships, and family.
2. Every decade cycle: interpret all decades in the chart, with age ranges and main themes.
3. Five years: analyze 2026 through 2030 individually, relating each year to its decade cycle.
Return the complete report in one response with headings and tables.`;

const agent = iztroZiweiFastAgent({modelName: 'iztro-ziwei-v3-fast'});
const result = await run(agent, prompt);
console.log(result.finalOutput);

Ongoing Ziwei consultation

Include customer details with the first question:

Use the following details to answer the customer's Ziwei Doushu question.
Customer details: Gregorian birth date [birth date], birth time [birth time], gender [gender].
Current question: [question submitted by the customer]

Send follow-up questions in the same conversation:

Customer follow-up: [new question from the customer]

For example, ask “Analyze this customer's career in 2027,” then “Expand on the first half of the year.”

Customers can also ask follow-up questions in the conversation that produced their report. If the report came from another conversation, include the customer's details and report first.

The code prints the conversation ID. Save it, then resume with ChatSession(conversation_id=saved_id) in Python or new ChatSession({conversationId: savedId}) in TypeScript.

View complete Python / TypeScript code

Python
TypeScript

import asyncio
from agents import Runner
from iztro_agents import ChatSession, iztro_ziwei_agent

QUESTIONS = [
    "Customer details: Gregorian birth date 1990-06-15, birth time 10:00, male. Analyze this customer's career in 2027.",
    "Customer follow-up: using the previous analysis, compare career changes in 2028 and 2027."
]

async def main():
    # Use your product's customer ID and reuse the session for this consultation.
    session = ChatSession(external_user_id="customer_123")
    try:
        for question in QUESTIONS:
            agent = iztro_ziwei_agent(model_name="iztro-ziwei-v3")
            result = await Runner.run(agent, question, session=session)
            print(result.final_output)
        print("session_id:", session.session_id)
    finally:
        await session.close()

asyncio.run(main())

import {run} from '@openai/agents';
import {ChatSession, iztroZiweiAgent} from 'openai-iztro-agents';

const questions = [
  "Customer details: Gregorian birth date 1990-06-15, birth time 10:00, male. Analyze this customer's career in 2027.",
  "Customer follow-up: using the previous analysis, compare career changes in 2028 and 2027."
];

// Use your product's customer ID and reuse the session for this consultation.
const session = new ChatSession({externalUserId: 'customer_123'});
try {
  for (const question of questions) {
    const agent = iztroZiweiAgent({modelName: 'iztro-ziwei-v3'});
    const result = await run(agent, question, {session});
    console.log(result.finalOutput);
  }
  console.log("sessionId:", session.sessionId);
} finally {
  await session.close();
}

Generate a detailed Qimen analysis

Fill in the matter, current situation, and customer's question:

Generate a Qimen analysis for the customer.
Matter: [what the customer wants analyzed]
Current situation: [what has happened and the available options]
Customer question: [the outcome or action timing they want to understand]
Question time: [the customer's local date, time, and timezone]

Provide an assessment, supporting chart evidence, and next steps. Include timing analysis when the customer asks about timing.

For example: matter, “Signing a distribution partnership”; situation, “Two discussions completed, revenue split unresolved”; question, “How should the process move forward, and when should the next discussion take place?”

Use the customer's local date, time, and timezone when they ask the question. Put any planned signing date in the matter details.

The code uses UTC+08:00 as an example and supplies the current question time on each turn. Use the actual customer's timezone in your product.

View complete Python / TypeScript code

Python
TypeScript

import asyncio
from datetime import datetime, timedelta, timezone
from agents import ModelSettings, Runner
from iztro_agents import iztro_qimen_fast_agent

# Example customer timezone: UTC+08:00. Use the actual customer's timezone.
CUSTOMER_TIMEZONE = timezone(timedelta(hours=8))

PROMPT = """Generate a detailed Qimen analysis for the customer.
Matter: signing a distribution partnership.
Current situation: two discussions completed; revenue split and launch date unresolved.
Customer question: how should the process move forward, and when should the next discussion happen?
Provide an assessment, supporting chart evidence, next steps, and the basis for timing."""

async def main():
    agent = iztro_qimen_fast_agent(model_name="iztro-qimen-v3-fast",
        model_settings=ModelSettings(metadata={
            "current_datetime": datetime.now(CUSTOMER_TIMEZONE).isoformat(),
        }),
    )
    result = await Runner.run(agent, PROMPT)
    print(result.final_output)

asyncio.run(main())

import {run} from '@openai/agents';
import {iztroQimenFastAgent} from 'openai-iztro-agents';

// Example customer timezone: UTC+08:00. Use the actual customer's timezone.
const questionTime = () =>
  new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString().replace('Z', '+08:00');

const prompt = `Generate a detailed Qimen analysis for the customer.
Matter: signing a distribution partnership.
Current situation: two discussions completed; revenue split and launch date unresolved.
Customer question: how should the process move forward, and when should the next discussion happen?
Provide an assessment, supporting chart evidence, next steps, and the basis for timing.`;

const agent = iztroQimenFastAgent({modelName: 'iztro-qimen-v3-fast',
  modelSettings: {providerData: {metadata: {current_datetime: questionTime()}}},
});
const result = await run(agent, prompt);
console.log(result.finalOutput);

Ongoing Qimen consultation

Use the situation template above for the first question, then add updates and follow-ups in the same conversation:

Continue analyzing the matter in this conversation.
Latest development: [new information; leave blank if none]
Customer follow-up: [new question from the customer]

The code prints the conversation ID. Save it, then resume with ChatSession(conversation_id=saved_id) in Python or new ChatSession({conversationId: savedId}) in TypeScript.

The code uses UTC+08:00 as an example and supplies the current question time on each turn. Use the actual customer's timezone in your product.

View complete Python / TypeScript code

Python
TypeScript

import asyncio
from datetime import datetime, timedelta, timezone
from agents import ModelSettings, Runner
from iztro_agents import ChatSession, iztro_qimen_agent

# Example customer timezone: UTC+08:00. Use the actual customer's timezone.
CUSTOMER_TIMEZONE = timezone(timedelta(hours=8))

QUESTIONS = [
    "The customer is negotiating a distribution partnership. Two discussions are complete; the revenue split is unresolved. Analyze how to move forward.",
    "Customer update: the other party proposed a one-month trial. How does this affect the previous assessment?"
]

async def main():
    # Use your product's customer ID and reuse the session for this consultation.
    session = ChatSession(external_user_id="customer_123")
    try:
        for question in QUESTIONS:
            agent = iztro_qimen_agent(model_name="iztro-qimen-v3",
                model_settings=ModelSettings(metadata={
                    "current_datetime": datetime.now(CUSTOMER_TIMEZONE).isoformat(),
                }),
            )
            result = await Runner.run(agent, question, session=session)
            print(result.final_output)
        print("session_id:", session.session_id)
    finally:
        await session.close()

asyncio.run(main())

import {run} from '@openai/agents';
import {ChatSession, iztroQimenAgent} from 'openai-iztro-agents';

// Example customer timezone: UTC+08:00. Use the actual customer's timezone.
const questionTime = () =>
  new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString().replace('Z', '+08:00');

const questions = [
  "The customer is negotiating a distribution partnership. Two discussions are complete; the revenue split is unresolved. Analyze how to move forward.",
  "Customer update: the other party proposed a one-month trial. How does this affect the previous assessment?"
];

// Use your product's customer ID and reuse the session for this consultation.
const session = new ChatSession({externalUserId: 'customer_123'});
try {
  for (const question of questions) {
    const agent = iztroQimenAgent({modelName: 'iztro-qimen-v3',
      modelSettings: {providerData: {metadata: {current_datetime: questionTime()}}},
    });
    const result = await run(agent, question, {session});
    console.log(result.finalOutput);
  }
  console.log("sessionId:", session.sessionId);
} finally {
  await session.close();
}

Code examples: send a request or save and continue a conversation.

Generate a complete life report​

Ongoing Ziwei consultation​

Generate a detailed Qimen analysis​

Ongoing Qimen consultation​

Generate a complete life report

Ongoing Ziwei consultation

Generate a detailed Qimen analysis

Ongoing Qimen consultation