### Install KinQiMen and Dependencies

Source: https://github.com/kentang2017/kinqimen/blob/master/README.md

Install the kinqimen library and its primary dependency sxtwl using pip. Ensure you have Python installed.

```bash
pip install sxtwl
pip install kinqimen
```

--------------------------------

### Install Required Dependencies

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Installs the core dependencies required for the Kinqimen library using pip. This command ensures all necessary packages are available.

```bash
pip install sxtwl kinliuren streamlit pendulum bidict
```

--------------------------------

### Install Optional AI Dependencies

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Installs optional dependencies for AI features, specifically the cerebras package. This is needed for AI-powered analysis.

```bash
pip install cerebras
```

--------------------------------

### Get Initial Yin Configuration

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Retrieves the initial yin configuration based on the year's 60-year cycle. This method is part of the Qimen class.

```python
def ypan(self) -> str:
```

--------------------------------

### Integration with Qimen Application

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/cerebras_client.md

Example of using CerebrasClient within a Streamlit application for AI-powered divination analysis. Requires API key from environment variable.

```python
from kinqimen.cerebras_client import CerebrasClient

# In Streamlit app
client = CerebrasClient(api_key=os.getenv("CEREBRAS_API_KEY"))

# Prepare chart data
chart_text = format_qimen_results_for_prompt(q_data, ...)

# Get AI analysis
response = client.get_chat_completion(
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": chart_text}
    ],
    model=selected_model,
    max_tokens=8192
)

# Display results
analysis = response.choices[0].message.content
```

--------------------------------

### Example Yang Configuration Entry in Angan

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/angan.md

Presents a sample entry for a Yang configuration ('陽一甲子') within the Angan dictionary. The structure is similar to Yin configurations, mapping to hidden stems and a trigram descriptor.

```python
Angan['陽一甲子'] = [
    '戊辰', '己巳', '庚午', '辛未', '壬申', '癸酉', '丁卯', '丙寅', '乙丑', '壬坤'
]
```

--------------------------------

### get_before_jieqi_start_date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Retrieves the start date and time of the previous solar term before the given date and time. It returns a dictionary with the same structure as `get_jieqi_start_date`, but for the preceding solar term.

```APIDOC
## get_before_jieqi_start_date(year, month, day, hour, minute)

### Description
Get the start date and time of the previous solar term before the given date and time.

### Method
```python
def get_before_jieqi_start_date(year: int, month: int, day: int, hour: int, minute: int) -> dict
```

### Parameters
#### Path Parameters
- **year** (int) - Required - Gregorian year
- **month** (int) - Required - Month (1-12)
- **day** (int) - Required - Day (1-31)
- **hour** (int) - Required - Hour (0-23)
- **minute** (int) - Required - Minute (0-59)

### Response
#### Success Response
- **年** (int) - Year of solar term occurrence
- **月** (int) - Month of solar term occurrence
- **日** (int) - Day of solar term occurrence
- **時** (int) - Hour of solar term occurrence
- **分** (int) - Minute of solar term occurrence
- **節氣** (str) - Solar term name (e.g., "冬至", "小寒", "立春")
- **時間** (datetime) - Python datetime object of solar term

### Request Example
```python
from kinqimen import jieqi

result = jieqi.get_before_jieqi_start_date(2024, 6, 15, 14, 30)
# Returns the previous solar term before June 15
```
```

--------------------------------

### Get Previous Solar Term Start Date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Retrieves the start date and time of the solar term immediately preceding the given Gregorian date and time. Returns a dictionary with the previous solar term's information.

```python
from kinqimen import jieqi

result = jieqi.get_before_jieqi_start_date(2024, 6, 15, 14, 30)
# Returns the previous solar term before June 15
```

--------------------------------

### Get Solar Term Start Date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Determines the start date and time of the current solar term for a given Gregorian date and time.

```APIDOC
## get_jieqi_start_date

### Description
Retrieves the start date and time of the solar term for a specific Gregorian date and time.

### Method
`jieqi.get_jieqi_start_date(year, month, day, hour, minute)`

### Parameters
- **year** (int) - The Gregorian year.
- **month** (int) - The Gregorian month.
- **day** (int) - The Gregorian day.
- **hour** (int) - The hour of the day (0-23).
- **minute** (int) - The minute of the hour (0-59).

### Response
- **節氣** (string) - The name of the solar term.
- **時間** (string) - The precise start time of the solar term in 'YYYY-MM-DD HH:MM:SS' format.

### Request Example
```python
from kinqimen import jieqi

result = jieqi.get_jieqi_start_date(2024, 6, 15, 14, 30)
print(result)
```

### Response Example
```json
{
  "節氣": "夏至",
  "時間": "2024-06-21 09:57:00"
}
```
```

--------------------------------

### Get Solar Term Start Date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Retrieves the start date and time of the current solar term for a given Gregorian date and time. Returns a dictionary containing details of the solar term, including its name and a Python datetime object.

```python
from kinqimen import jieqi

# Get the solar term for June 15, 2024
result = jieqi.get_jieqi_start_date(2024, 6, 15, 14, 30)
print(result['節氣'])      # e.g., "夏至"
print(result['時間'])       # datetime.datetime(2024, 6, 20, 10, 50)
```

--------------------------------

### Example Yin Configuration Entry in Angan

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/angan.md

Shows a sample entry for a Yin configuration ('陰三甲子') within the Angan dictionary. The value is a list containing hidden stems for the 8 palaces and the trigram association.

```python
Angan['陰三甲子'] = [
    '庚午', '己巳', '戊辰', '乙丑', '丙寅', '丁卯', '癸酉', '壬申', '辛未', '丙坤'
]
```

--------------------------------

### Get Previous Solar Term Start Date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Retrieves the start date and time of the solar term immediately preceding a given Gregorian date and time.

```APIDOC
## get_before_jieqi_start_date

### Description
Retrieves the start date and time of the solar term that occurred before the specified Gregorian date and time.

### Method
`jieqi.get_before_jieqi_start_date(year, month, day, hour, minute)`

### Parameters
- **year** (int) - The Gregorian year.
- **month** (int) - The Gregorian month.
- **day** (int) - The Gregorian day.
- **hour** (int) - The hour of the day (0-23).
- **minute** (int) - The minute of the hour (0-59).

### Response
- **節氣** (string) - The name of the previous solar term.
- **時間** (string) - The precise start time of the previous solar term in 'YYYY-MM-DD HH:MM:SS' format.

### Request Example
```python
from kinqimen import jieqi

previous = jieqi.get_before_jieqi_start_date(2024, 6, 15, 14, 30)
print(previous)
```

### Response Example
```json
{
  "節氣": "芒種",
  "時間": "2024-06-05 12:09:00"
}
```
```

--------------------------------

### Get Year Cycle Information

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Determines the 60-year cycle (upper, middle, or lower) for the current year. Returns the cycle name and its starting year, or None if not applicable.

```python
yuen = q.year_yuen()
if yuen:
    print(f"Cycle: {yuen[0]}, Started: {yuen[1]}")
```

--------------------------------

### Track Seasonal Progression with Solar Terms

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Retrieves the start dates for the previous and current solar terms relative to a given Gregorian date and time. Useful for seasonal analysis and understanding progression.

```python
from kinqimen import jieqi

# Get consecutive solar terms for seasonal analysis
current = jieqi.get_jieqi_start_date(2024, 6, 15, 14, 30)
previous = jieqi.get_before_jieqi_start_date(2024, 6, 15, 14, 30)

print(f"Previous term: {previous['節氣']} on {previous['時間']}")
print(f"Current term: {current['節氣']} on {current['時間']}")
```

--------------------------------

### year_yuen()

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Determines the 60-year cycle (upper, middle, lower) for the current year, returning the cycle name and its start year.

```APIDOC
## year_yuen()

### Description
Determine which 60-year cycle (upper, middle, lower) the current year belongs to.

### Method
`year_yuen(self) -> list | None`

### Returns
List with two elements: `[cycle_name (str), start_year (int)]` or `None`

### Example
```python
q = kinqimen.Qimen(2024, 6, 15, 14, 30)
yuen = q.year_yuen()
if yuen:
    print(f"Cycle: {yuen[0]}, Started: {yuen[1]}")
```
```

--------------------------------

### get_jieqi_start_date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Retrieves the start date and time of the current solar term (jieqi) for a given Gregorian date and time. It returns a dictionary containing details of the solar term, including its name and precise occurrence time.

```APIDOC
## get_jieqi_start_date(year, month, day, hour, minute)

### Description
Get the start date and time of the current solar term (jieqi) for the given date and time.

### Method
```python
def get_jieqi_start_date(year: int, month: int, day: int, hour: int, minute: int) -> dict
```

### Parameters
#### Path Parameters
- **year** (int) - Required - Gregorian year
- **month** (int) - Required - Month (1-12)
- **day** (int) - Required - Day (1-31)
- **hour** (int) - Required - Hour (0-23)
- **minute** (int) - Required - Minute (0-59)

### Response
#### Success Response
- **年** (int) - Year of solar term occurrence
- **月** (int) - Month of solar term occurrence
- **日** (int) - Day of solar term occurrence
- **時** (int) - Hour of solar term occurrence
- **分** (int) - Minute of solar term occurrence
- **節氣** (str) - Solar term name (e.g., "冬至", "小寒", "立春")
- **時間** (datetime) - Python datetime object of solar term

### Request Example
```python
from kinqimen import jieqi

# Get the solar term for June 15, 2024
result = jieqi.get_jieqi_start_date(2024, 6, 15, 14, 30)
print(result['節氣'])      # e.g., "夏至"
print(result['時間'])       # datetime.datetime(2024, 6, 20, 10, 50)
```
```

--------------------------------

### Get Eight Deities Configuration for Daily Divination

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the Eight Deities configuration used for daily (golden mirror) divination. It provides mappings from Heavenly Stems to deity-temple locations.

```python
def getgtw() -> dict
```

--------------------------------

### Get Minute-Based Qimen Configuration

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the Qimen divination configuration using the minute-based (刻家) method. This provides minute-level precision for the configuration string, like '陽一局上元'.

```python
def qimen_ju_name_ke(year: int, month: int, day: int, hour: int, minute: int) -> str
```

--------------------------------

### Get Master Star and Gate Master Positions (Hour-Based)

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the Master Star (值符) and Gate Master (值使) positions for hour-based divination. It returns detailed mappings including stem, star, and palace information.

```python
def zhifu_n_zhishi(year: int, month: int, day: int, hour: int, minute: int, option: int) -> dict
```

```python
from kinqimen import config
zfzs = config.zhifu_n_zhishi(2024, 6, 15, 14, 30, 1)
print(zfzs['值符星宮'])  # [Star name, Palace]
```

--------------------------------

### Get Current Solar Term Start Date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Determines the start date and time of the current solar term for a given Gregorian date and time. Useful for validating solar term dates or analyzing seasonal patterns.

```python
from kinqimen import jieqi

# Determine what solar term we're in
result = jieqi.get_jieqi_start_date(2024, 6, 15, 14, 30)
if result['節氣'] == '冬至':
    print("Winter solstice calculations apply")
```

--------------------------------

### KinQiMen Class Initialization and Chart Generation

Source: https://github.com/kentang2017/kinqimen/blob/master/README.md

Demonstrates how to initialize the Qimen class with date and time, and generate different types of Qimen Dunjia charts using various methods.

```APIDOC
## kinqimen.Qimen Class Usage

### Description
This section details how to use the `kinqimen.Qimen` class to generate various Qimen Dunjia charts. It covers initialization with specific date and time parameters and the different methods available for chart generation, including hour-based, minute-based, and daily charts.

### Methods

- **`__init__(self, year, month, day, hour, minute)`**
  Initializes the Qimen object with the specified year, month, day, hour, and minute.

- **`pan(self, method)`**
  Generates an hour-based Qimen chart. Supports two calculation methods: `1` for Chabu (拆補) and `2` for Zhirun (置閏).

- **`pan_minute(self, method)`**
  Generates a minute-based Qimen chart for high-precision divination. Also supports `method` parameter for Chabu or Zhirun.

- **`gpan(self)`**
  Generates a daily Qimen chart in the style of the Golden Letter Jade Mirror (金函玉鏡).

- **`overall(self)`**
  Generates a combined chart, typically including both hour-based and Golden Mirror daily charts.

### Parameters

- **`year`** (int) - Required - The year for the divination.
- **`month`** (int) - Required - The month for the divination.
- **`day`** (int) - Required - The day for the divination.
- **`hour`** (int) - Required - The hour for the divination.
- **`minute`** (int) - Required - The minute for the divination.
- **`method`** (int) - Required - The calculation method for `pan` and `pan_minute` methods (1 for Chabu, 2 for Zhirun).

### Request Example
```python
from kinqimen import kinqimen

year, month, day, hour, minute = 2024, 6, 15, 14, 30

# Hour-based Qimen (Chabu method)
result_chabu = kinqimen.Qimen(year, month, day, hour, minute).pan(1)

# Minute-based Qimen (Zhirun method)
result_minute = kinqimen.Qimen(year, month, day, hour, minute).pan_minute(2)

# Golden Mirror daily chart
result_daily = kinqimen.Qimen(year, month, day, hour, minute).gpan()

# Combined chart
result_combined = kinqimen.Qimen(year, month, day, hour, minute).overall()
```

### Response

- The `result` variable will contain the generated Qimen chart data. The exact structure of the returned data is not specified in the source but is expected to be a representation of the divination chart.
```

--------------------------------

### Basic Divination with Kinqimen

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Demonstrates how to initialize the Qimen object and perform a basic divination using the Chabu method. Accesses key information from the result.

```python
from kinqimen import kinqimen

q = kinqimen.Qimen(2024, 6, 15, 14, 30)
result = q.pan(1)  # Chabu method

# Access key information
print(f"Date: {result['干支']}")
print(f"Solar term: {result['節氣']}")
print(f"Day type: {result['局日']}")
```

--------------------------------

### Initialize Qimen Object

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Instantiate the Qimen class with specific date and time parameters. This is a prerequisite for calling most Qimen methods.

```python
q = kinqimen.Qimen(2024, 6, 15, 14, 30)
```

--------------------------------

### Validate Basic Functionality

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Tests the core chart generation and configuration functions of the Kinqimen library. Ensures that chart objects are dictionaries with expected keys and that configuration functions return data in the correct format.

```python
from kinqimen import kinqimen
from kinqimen import config

# Test basic chart generation
q = kinqimen.Qimen(2024, 6, 15, 14, 30)
chart = q.pan(1)
assert isinstance(chart, dict)
assert '天盤' in chart
assert '地盤' in chart

# Test configuration functions
gz = config.gangzhi(2024, 6, 15, 14, 30)
assert len(gz) == 5
assert isinstance(gz[2], str)  # Day stems

print("All basic tests passed!")
```

--------------------------------

### Chat Completion with Configuration Options

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/cerebras_client.md

Performs chat completion with specified model, maximum tokens, and temperature for deterministic output.

```python
from kinqimen.cerebras_client import CerebrasClient

client = CerebrasClient(api_key="sk-...")
response = client.get_chat_completion(
    messages=[...],
    model="llama-3.3-70b",
    max_tokens=4096,
    temperature=0.3  # More deterministic
)
```

--------------------------------

### Initialize Qimen Chart

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Create a Qimen chart object for a specific Gregorian date and time. This is the primary constructor for the Qimen class.

```python
from kinqimen import kinqimen

# Create chart for June 15, 2024 at 14:30
q = kinqimen.Qimen(2024, 6, 15, 14, 30)
```

--------------------------------

### zhifu_n_zhishi_ke

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Gets the Master Star and Gate Master positions for minute-based divination. Returns the same structure as zhifu_n_zhishi.

```APIDOC
## zhifu_n_zhishi_ke(year, month, day, hour, minute)

### Description
Get Master Star and Gate Master for minute-based divination.

### Parameters
- **year** (int) - Required - The year.
- **month** (int) - Required - The month.
- **day** (int) - Required - The day.
- **hour** (int) - Required - The hour.
- **minute** (int) - Required - The minute.

### Returns
- **dict**: Same structure as `zhifu_n_zhishi()`.
```

--------------------------------

### Compare Calculation Methods

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Compares the results of different calculation methods (Chabu and Zhirun) for the same date and time. Shows how to access the '排局' key for comparison.

```python
q = kinqimen.Qimen(2024, 6, 15, 14, 30)

chabu = q.pan(1)      # Chabu method
zhirun = q.pan(2)     # Zhirun method

# Compare the configurations
print(f"Chabu: {chabu['排局']}")
print(f"Zhirun: {zhirun['排局']}")
```

--------------------------------

### hourganghzi_zhifu()

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Gets the Hour Heavenly Stem and Branch (時干支) and determines the Hour Master Star (值符).

```APIDOC
## hourganghzi_zhifu()

### Description
Get the Hour Heavenly Stem and Branch (時干支) and determine the Hour Master Star (值符).

### Method
`hourganghzi_zhifu(self) -> str`

### Returns
String representation of hour master star (e.g., "天蓬").
```

--------------------------------

### Generate Hour-based Qimen Chart (Chabu Method)

Source: https://github.com/kentang2017/kinqimen/blob/master/README.md

Create an hour-based Qimen chart using the Chabu calculation method. Specify year, month, day, hour, and minute.

```python
from kinqimen import kinqimen

year, month, day, hour, minute = 2024, 6, 15, 14, 30

# 時家奇門（拆補法） | Hour-based Qimen (Chabu method)
result = kinqimen.Qimen(year, month, day, hour, minute).pan(1)   # 1=拆補, 2=置閏
```

--------------------------------

### Clockwise Eight Trigrams

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/types.md

A list representing the Eight Trigrams arranged in clockwise order, starting from the North position.

```python
clockwise_eightgua = ["坎", "艮", "震", "巽", "離", "坤", "兌", "乾"]
```

--------------------------------

### Manual Backoff Strategy

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/cerebras_client.md

Illustrates a manual implementation of exponential backoff for handling `RateLimitError` when making API requests.

```APIDOC
## Manual Rate Limit Backoff

### Description
Illustrates a manual implementation of exponential backoff for handling `RateLimitError` when making API requests. This is useful for applications that need fine-grained control over retries.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
See `get_chat_completion` for detailed parameters.

### Request Example
```python
from kinqimen.cerebras_client import CerebrasClient, RateLimitError
import time

client = CerebrasClient(api_key="...")

for attempt in range(5):
    try:
        response = client.get_chat_completion(messages=[...])
        break  # Exit loop on success
    except RateLimitError:
        delay = 60 * (2 ** attempt)  # Exponential backoff: 1m, 2m, 4m, 8m, 16m
        print(f"Waiting {delay}s before retry...")
        time.sleep(delay)
```

### Response
#### Success Response (200)
- **response**: The successful response object from `get_chat_completion`.

#### Error Responses
- **RateLimitError**: Handled by the loop; if all retries fail, the exception will propagate.
```

--------------------------------

### Get Solar Term Name for a Date

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the name of the solar term for a specific Gregorian date and time. Essential for seasonal and astrological calculations.

```python
from kinqimen import config
term = config.jq(2024, 12, 21, 12, 0)
print(term)  # 冬至
```

--------------------------------

### Qimen Constructor

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Initializes a Qimen divination chart object with a specific Gregorian date and time. This is the primary entry point for creating a Qimen instance.

```APIDOC
## Qimen Constructor

### Description
Initializes a Qimen divination chart object with a specific date and time.

### Signature
`__init__(self, year: int, month: int, day: int, hour: int, minute: int) -> None`

### Parameters
#### Path Parameters
- **year** (int) - Required - Gregorian year (e.g., 2024)
- **month** (int) - Required - Month (1-12)
- **day** (int) - Required - Day of month (1-31)
- **hour** (int) - Required - Hour in 24-hour format (0-23)
- **minute** (int) - Required - Minute (0-59)

### Example
```python
from kinqimen import kinqimen

# Create chart for June 15, 2024 at 14:30
q = kinqimen.Qimen(2024, 6, 15, 14, 30)
```
```

--------------------------------

### tianyi(option)

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Gets the Heavenly Nobility star (天乙) position. The `option` parameter determines whether to use Chabu (1) or Zhirun (2) for calculation.

```APIDOC
## tianyi(option)

### Description
Get the Heavenly Nobility star (天乙) position.

### Parameters
#### Query Parameters
- **option** (int) - Required - 1 for Chabu, 2 for Zhirun

### Returns
- string: Star name from eight celestial deities (蓬, 芮, 沖, 輔, 禽, 心, 柱, 任, 英)

### Method Signature
```python
def tianyi(self, option: int) -> str
```
```

--------------------------------

### Advanced Minute-Level Analysis with Angan

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/angan.md

Shows how to use the Angan dictionary for advanced minute-level analysis by retrieving hidden stems for a specific configuration and mapping them to trigrams for detailed examination.

```python
from kinqimen.angan import Angan

# Get hidden stems for a specific minute configuration
config = "陽四丙午"
stems = Angan.get(config, [])
if stems:
    # Map to trigrams for analysis
    trigrams = ['坎', '坤', '震', '巽', '離', '坤', '兌', '艮', '乾']
    for i, (trig, stem) in enumerate(zip(trigrams, stems[:8])):
        print(f"{trig}: {stem}")
```

--------------------------------

### pan_earth_r(option)

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Gets the reverse mapping of the earth plate, showing Heavenly Stem to trigram palace. It supports two options: Chabu (1) and Zhirun (2).

```APIDOC
## pan_earth_r(option)

### Description
Get reverse mapping of earth plate: Heavenly Stem to trigram palace.

### Method
`pan_earth_r(self, option: int) -> dict`

### Parameters
#### Path Parameters
- **option** (int) - Required - 1 for Chabu, 2 for Zhirun

### Returns
Dictionary mapping Heavenly Stem character to trigram palace name.
```

--------------------------------

### Get Minute-Level Hour Master Star

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Calculates the Master Star for minute-level (刻家奇門) divinations. This method provides the specific master star name for minute calculations.

```python
minute_master = q.hourganghzi_zhifu_minute()
```

--------------------------------

### Generating Minute-Based Charts with Hidden Stems

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/angan.md

Demonstrates the practical application of generating a minute-based Qimen chart, highlighting the retrieval of '暗干' (hidden stems) which are derived from the Angan dictionary.

```python
from kinqimen import kinqimen

q = kinqimen.Qimen(2024, 6, 15, 14, 30)
minute_chart = q.pan_minute(1)

# Includes 暗干 (hidden stems) derived from Angan
print(minute_chart['暗干'])  # Maps trigrams to hidden stems
print(minute_chart['飛干'])  # Flying stem for the minute
```

--------------------------------

### Calculate Sky Plate

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Computes the sky plate (天盤) based on the provided option. Use this to get divined Heavenly Stem positions relative to the master star.

```python
sky = q.pan_sky(1)
print(sky.get('坎'))  # Stem at North palace
```

--------------------------------

### Minute-Based Chart Generation with Angan

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/angan.md

Illustrates how the Angan dictionary is used internally during the generation of minute-based Qimen charts. It shows that the '暗干' (hidden stems) are derived from Angan lookups.

```python
from kinqimen import kinqimen
from kinqimen.angan import Angan

q = kinqimen.Qimen(2024, 6, 15, 14, 30)
minute_chart = q.pan_minute(2)

# The minute chart includes:
# - 暗干: Hidden stems for the minute-based configuration
# - 飛干: Flying stem for the specific minute
# Both are derived using lookups from the Angan dictionary
```

--------------------------------

### Generate Minute-based Qimen Chart (Zhirun Method)

Source: https://github.com/kentang2017/kinqimen/blob/master/README.md

Generate a minute-based Qimen chart using the Zhirun calculation method for high-precision divination. Requires date and time inputs.

```python
from kinqimen import kinqimen

year, month, day, hour, minute = 2024, 6, 15, 14, 30

# 刻家奇門（置閏法） | Minute-based Qimen (Zhirun method)
result = kinqimen.Qimen(year, month, day, hour, minute).pan_minute(2)
```

--------------------------------

### Get Twelve Longevity Phases

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the Twelve Longevity Phases (十二長生) for a given Heavenly Stem. This is used to understand the cyclical progression of a stem through different life stages.

```python
def find_shier_luck(gan: str) -> dict
```

```python
from kinqimen import config
phases = config.find_shier_luck('甲')
print(phases['寅'])  # 長生
```

--------------------------------

### Golden Mirror Daily Chart

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Generates a daily chart using the Golden Mirror method. Displays the configuration, stars, and doors of the daily chart.

```python
q = kinqimen.Qimen(2024, 6, 15, 14, 30)
daily = q.gpan()

print(f"Configuration: {daily['局']}")
print(f"Stars: {daily['星']}")
print(f"Doors: {daily['門']}")
```

--------------------------------

### Get Heavenly Nobility Star Position

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Retrieves the Heavenly Nobility star (天乙) position. The option parameter determines whether to use Chabu (1) or Zhirun (2).

```python
def tianyi(self, option: int) -> str:
```

--------------------------------

### pan_god(year, month, day, hour, minute, option)

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Calculates the eight deities layout. Returns a dictionary mapping trigram palaces to deity names.

```APIDOC
## `pan_god(year, month, day, hour, minute, option)`

### Description
Calculate the eight deities layout.

### Method Signature
```python
def pan_god(year: int, month: int, day: int, hour: int, minute: int, option: int) -> dict
```

### Returns
Dictionary mapping trigram palace to deity name (符, 蛇, 陰, 合, etc.)
```

--------------------------------

### Get Hour Master Star

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Retrieves the Hour Heavenly Stem and Branch (時干支) and identifies the Hour Master Star (值符). The output is a string representation of the master star.

```python
hour_master = q.hourganghzi_zhifu()
```

--------------------------------

### Get Reverse Earth Plate Mapping

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/qimen.md

Retrieves a reverse mapping of the earth plate, where Heavenly Stems are mapped to trigram palace names. This is useful for looking up palaces by stem.

```python
earth_r = q.pan_earth_r(1)
```

--------------------------------

### Solar Term Information Dictionary Structure

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/types.md

The return type from get_jieqi_start_date() and get_before_jieqi_start_date(). It provides detailed date and time information for solar terms.

```python
{
    "年": int,              # Year (e.g., 2024)
    "月": int,              # Month (1-12)
    "日": int,              # Day (1-31)
    "時": int,              # Hour (0-23)
    "分": int,              # Minute (0-59)
    "節氣": str,            # Solar term name
    "時間": datetime        # Python datetime object
}
```

--------------------------------

### Get Chabu Method Qimen Configuration

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the Qimen divination configuration using the Chabu (拆補) method for hour-based calculations. Returns a string indicating the configuration, such as '陽遁五局上'.

```python
from kinqimen import config
config_str = config.qimen_ju_name_chaibu(2024, 6, 15, 14, 30)
print(config_str)  # e.g., 陽遁五局上
```

--------------------------------

### Chat Completion with Configuration Options

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/cerebras_client.md

Performs a chat completion request with specific model, token limits, and temperature settings for customized output.

```APIDOC
## get_chat_completion (with options)

### Description
Performs a chat completion request with specific model, token limits, and temperature settings for customized output.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **messages** (list[dict]) - Required - A list of message objects, where each object has a `role` (system, user, or assistant) and `content`.
- **model** (str) - Optional - The model to use for completion (e.g., "llama-3.3-70b").
- **max_tokens** (int) - Optional - The maximum number of tokens to generate in the response. Lower limits reduce cost and quota usage.
- **temperature** (float) - Optional - Controls the creativity of the output. `0.0` for deterministic, `1.0` for creative.

### Request Example
```json
{
  "messages": [
    {"role": "system", "content": "You are helpful."}, 
    {"role": "user", "content": "Explain Qimen Dunjia."}
  ],
  "model": "llama-3.3-70b",
  "max_tokens": 4096,
  "temperature": 0.3
}
```

### Response
#### Success Response (200)
- **choices** (list[object]) - A list containing the completion choices. Each choice includes a `message` object with `role` and `content`.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Qimen Dunjia is an ancient Chinese metaphysical system..."
      }
    }
  ]
}
```
```

--------------------------------

### List 60-Day Stem-Branch Cycle

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Generates and prints a reference of all 60 combinations of the Heavenly Stems and Earthly Branches (Jiazi cycle). Useful for creating a complete calendar reference.

```python
from kinqimen import jieqi

# Generate a reference of all 60 stem-branch combinations
cycle = jieqi.jiazi()
for i, gz in enumerate(cycle, 1):
    if i % 10 == 0:
        print(f"{i}. {gz}")
```

--------------------------------

### zhifu_n_zhishi

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Gets the Master Star (值符) and Gate Master (值使) positions for hour-based divination. Returns detailed assignments including Heavenly Stem, Star Name, and Palace Name.

```APIDOC
## zhifu_n_zhishi(year, month, day, hour, minute, option)

### Description
Get the Master Star (值符) and Gate Master (值使) positions for hour-based divination.

### Parameters
- **year** (int) - Required - The year.
- **month** (int) - Required - The month.
- **day** (int) - Required - The day.
- **hour** (int) - Required - The hour.
- **minute** (int) - Required - The minute.
- **option** (int) - Required - An option for calculation.

### Returns
- **dict**: Dictionary containing:
  - `值符天干` (list): [Hour Stem, Master Star Name]
  - `值符星宮` (list): [Star Name, Palace Name]
  - `值使門宮` (list): [Door Name, Palace Name]

### Example
```python
from kinqimen import config
zfzs = config.zhifu_n_zhishi(2024, 6, 15, 14, 30, 1)
print(zfzs['值符星宮'])  # [Star name, Palace]
```
```

--------------------------------

### Generate Combined Hour-based and Golden Mirror Chart

Source: https://github.com/kentang2017/kinqimen/blob/master/README.md

Generate a combined chart that includes both the hour-based Qimen and the Golden Mirror daily chart. Useful for comprehensive analysis.

```python
from kinqimen import kinqimen

year, month, day, hour, minute = 2024, 6, 15, 14, 30

# 綜合排盤（時家 + 金函） | Combined chart (Hour-based + Golden Mirror)
result = kinqimen.Qimen(year, month, day, hour, minute).overall()
```

--------------------------------

### List 60-Day Cycle (Jiazi)

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/jieqi.md

Generates and returns a list representing the full 60-day stem-branch cycle (Jiazi).

```APIDOC
## jiazi

### Description
Generates and returns a list of all 60 stem-branch combinations (Jiazi).

### Method
`jieqi.jiazi()`

### Parameters
None

### Response
- **cycle** (list of strings) - A list where each element is a stem-branch combination (e.g., '甲子', '乙丑').

### Request Example
```python
from kinqimen import jieqi

cycle = jieqi.jiazi()
print(cycle)
```

### Response Example
```json
[
  "甲子", "乙丑", "丙寅", "丁卯", "戊辰", "己巳", "庚午", "辛未", "壬申", "癸酉",
  "甲戌", "乙亥", "丙子", "丁丑", "戊寅", "己卯", "庚辰", "辛巳", "壬午", "癸未",
  "甲申", "乙酉", "丙戌", "丁亥", "戊子", "己丑", "庚寅", "辛卯", "壬辰", "癸巳",
  "甲午", "乙未", "丙申", "丁酉", "戊戌", "己亥", "庚子", "辛丑", "壬寅", "癸卯",
  "甲辰", "乙巳", "丙午", "丁未", "戊申", "己酉", "庚戌", "辛亥", "壬子", "癸丑",
  "甲寅", "乙卯", "丙辰", "丁巳", "戊午", "己未", "庚申", "辛酉", "壬戌", "癸亥"
]
```
```

--------------------------------

### Get Zhirun Method Qimen Configuration

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves the Qimen divination configuration using the Zhirun (置閏) method. This method is more accurate for complex date calculations as it accounts for leap months.

```python
def qimen_ju_name_zhirun(year: int, month: int, day: int, hour: int, minute: int) -> str
```

--------------------------------

### Get Heavenly Stem and Earthly Branch for a Date and Time

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Converts a Gregorian date and time into its corresponding Heavenly Stem and Earthly Branch representation. Useful for detailed calendrical analysis.

```python
from kinqimen import config
gz = config.gangzhi(2024, 6, 15, 14, 30)
# Returns: ('甲辰', '六月', ('甲子', '甲申'), ('己未', '癸卯'), ...)
```

--------------------------------

### Calculate Eight Deities Layout

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Calculates the eight deities layout for Qimen divination, mapping each trigram palace to its corresponding deity name.

```python
def pan_god(year: int, month: int, day: int, hour: int, minute: int, option: int) -> dict
```

--------------------------------

### Pan Results Dictionary Structure

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/types.md

The primary return type from divination calculation methods like pan(), pan_minute(), gpan(), and overall(). It contains detailed information about the divination setup and results.

```python
{
    "排盤方式": str,           # "拆補" or "置閏"
    "干支": str,              # Full Heavenly Stem/Branch notation
    "旬首": str,              # Xun head, single stem character
    "旬空": {
        "日空": str,          # Two earthly branches (void day)
        "時空": str           # Two earthly branches (void hour)
    },
    "局日": str,              # Day classification like "甲己日"
    "排局": tuple,            # (yin/yang, number, element) or similar
    "節氣": str,              # Solar term name
    "值符值使": {
        "值符天干": [str, str],       # [Hour stem, Star name]
        "值符星宮": [str, str],       # [Star name, Palace name]
        "值使門宮": [str, str]        # [Door name, Palace name]
    },
    "天乙": str,              # Heavenly Nobility star name
    "天盤": dict,             # Maps: trigram → stem
    "地盤": dict,             # Maps: trigram → stem
    "門": dict,               # Maps: trigram → door name
    "星": dict,               # Maps: trigram → star name
    "神": dict,               # Maps: trigram → deity name
    "馬星": {
        "天馬": str,          # Earthly branch
        "丁馬": str,
        "驛馬": str
    },
    "長生運": {               # Only in pan() results
        "天盤": dict,         # palace → {stem → longevity_phase}
        "地盤": dict
    },
    "暗干": dict,             # Only in pan_minute() results
    "飛干": str               # Only in pan_minute() results
}
```

--------------------------------

### Basic KinQiMen Divination Chart Generation

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/REFERENCE.md

Create a Qimen chart for a specific date and time and generate hourly, minute-based, or daily golden mirror charts. This snippet demonstrates the core usage of the Qimen class.

```python
from kinqimen import kinqimen

# Create a divination chart for a specific date and time
q = kinqimen.Qimen(2024, 6, 15, 14, 30)

# Generate hour-based chart (拆補 method)
hourly_chart = q.pan(1)

# Generate minute-based chart (置閏 method)
minute_chart = q.pan_minute(2)

# Generate golden mirror daily chart
daily_chart = q.gpan()

# Get all three charts at once
all_charts = q.overall(1)
```

--------------------------------

### Get Triadic Configuration Code for a Solar Term

Source: https://github.com/kentang2017/kinqimen/blob/master/_autodocs/api-reference/config.md

Retrieves a three-digit code representing the upper, middle, and lower configurations for a given solar term. Used in specific divination chart layouts.

```python
from kinqimen import config
code = config.jieqicode_jq('冬至')
print(code)  # 一七四
```