BaZi Oracle — Methodology
How this app turns a birth date into a personality profile and life reading, explained from first principles.
1. Introduction
What is BaZi?
BaZi (八字, literally “eight characters”) is a Chinese astrological system that maps the exact moment of a person’s birth onto five natural elements — Wood, Fire, Earth, Metal, and Water — and reads the relationships between them to describe personality, strengths, blind spots, and life tendencies.
The system is also called the Four Pillars of Destiny because it encodes birth data into four columns (pillars), one each for the Year, Month, Day, and Hour of birth. Each pillar contains two characters: a Heavenly Stem on top and an Earthly Branch on the bottom — hence “eight characters” in total.
What this app does
The BaZi Oracle takes a user’s birth data and produces a structured life reading through a multi-stage pipeline:
Birth input (date, time, gender, city)
→ True Solar Time correction
→ Four Pillars (via lunar-javascript)
→ Ten Gods (relationship between each stem and the Day Master)
→ Weighted scoring with seasonal multipliers
→ Dominant profile + Day Master strength + balancing element
→ Zodiac compatibility
→ AI narrative generation (Gemini)
→ Structured reading (personality, career, love, money, health, fate, habits)
Everything before the AI step is deterministic — the same input always produces the same pillars, scores, and profiles. The AI layer turns those pre-calculated results into natural-language paragraphs and actionable habits.
2. Input & Time Correction
What the user provides
| Field | Format | Required |
|---|---|---|
| Date of birth | DD.MM.YYYY | Yes |
| Gender | Male / Female | Yes |
| Time of birth | HH:MM (24h) | No |
| City | Selected from 246-city list | Only when time is provided |
When no birth time is given, the app produces a 3-pillar reading (Year, Month, Day). The Hour Pillar is set to null and excluded from all calculations.
True Solar Time
Clock time is a civic convenience. The sun does not reach noon at exactly 12:00 everywhere inside a timezone — a city 500 km west of the timezone’s reference meridian sees the sun about 30 minutes later than the clock says.
BaZi assigns the Hour Pillar based on where the sun actually is, not what the clock reads. The app corrects for this with True Solar Time (TST):
TST = Clock Time + Longitude Correction + Equation of Time
Longitude Correction. Each timezone is centred on a standard meridian (timezone offset × 15°). The sun takes 4 minutes to travel 1° of longitude. If you are east of the standard meridian, the sun arrives early; if west, it arrives late.
Longitude Correction (minutes) = (birth longitude − standard meridian) × 4
Equation of Time. Earth’s orbit is slightly elliptical and its axis is tilted, so the sun drifts up to 16 minutes ahead or 14 minutes behind the “mean sun” depending on the time of year. The app uses a simplified trigonometric formula:
B = 2π × (dayOfYear − 81) / 365
EoT = 9.87 × sin(2B) − 7.53 × cos(B) − 1.5 × sin(B) (minutes)
DST handling. When the city provides an IANA timezone identifier (e.g. America/New_York), the app uses the browser’s Intl.DateTimeFormat API to resolve the actual UTC offset for the specific birth date and time, automatically accounting for Daylight Saving Time. The DST-aware offset is used for the standard meridian calculation — this is mathematically equivalent to subtracting DST from the clock time and using the standard offset, because the DST in the civil time cancels out the DST in the meridian.
Day boundary. If the correction pushes the time before midnight or past midnight, the app adjusts the calendar date accordingly (the dayOffset field), because the Day Pillar and all downstream calculations depend on the correct solar date.
3. The Four Pillars
The app uses the lunar-javascript library to convert the (possibly TST-adjusted) Gregorian date into the traditional Chinese calendar and extract the Four Pillars via the getEightChar() method.
Year Pillar
- Determined by the BaZi year, which starts at Li Chun (立春, Start of Spring) — around February 4 — not at the Lunar New Year.
- A person born on January 15, 1990 belongs to the 1989 BaZi year because Li Chun has not yet occurred.
- The Year Branch maps to a zodiac animal (e.g. 寅 = Tiger). The
lunar-javascriptlibrary handles the Li Chun boundary internally.
Month Pillar
- Represents the seasonal context of birth.
- The Month Branch divides the year into twelve solar terms (not lunar months).
- The Month Pillar is the single most important pillar for profile scoring — it determines the “season” that all seasonal multipliers reference.
Day Pillar
- The Day Stem is the Day Master (日主) — the character that represents “you” in the chart.
- The Day Master is the reference point for every Ten God calculation. It does not receive a Ten God of its own (comparing something to itself produces “Companion” by default).
- The Day Branch contains Hidden Stems that reveal inner personality traits.
Hour Pillar
- Only present when the user provides a birth time.
- Represents the innermost layer of personality and ambition.
- When absent, all scoring and compatibility calculations adapt to use three pillars instead of four.
Structure
Each pillar = 1 Heavenly Stem (top) + 1 Earthly Branch (bottom).
Year Month Day Hour
Stem: 甲 丙 戊 庚
Branch: 寅 午 辰 申
4. Heavenly Stems & Earthly Branches
The 10 Heavenly Stems
Each stem has an element and a polarity (Yin or Yang):
| Stem | Element | Polarity | Pinyin | Meaning |
|---|---|---|---|---|
| 甲 | Wood | Yang | jiǎ | Growing tree |
| 乙 | Wood | Yin | yǐ | Flower, vine |
| 丙 | Fire | Yang | bǐng | Blazing sun |
| 丁 | Fire | Yin | dīng | Candle flame |
| 戊 | Earth | Yang | wù | Mountain |
| 己 | Earth | Yin | jǐ | Garden soil |
| 庚 | Metal | Yang | gēng | Axe, raw ore |
| 辛 | Metal | Yin | xīn | Jewelry, refined metal |
| 壬 | Water | Yang | rén | River, ocean |
| 癸 | Water | Yin | guǐ | Rain, dew |
The 12 Earthly Branches
Each branch maps to a zodiac animal:
| Branch | Animal | Branch | Animal |
|---|---|---|---|
| 子 | Rat | 午 | Horse |
| 丑 | Ox | 未 | Goat |
| 寅 | Tiger | 申 | Monkey |
| 卯 | Rabbit | 酉 | Rooster |
| 辰 | Dragon | 戌 | Dog |
| 巳 | Snake | 亥 | Pig |
Hidden Stems (藏干)
Each Earthly Branch contains between one and three hidden stems — additional stems “buried” inside the branch that influence personality at a deeper, less visible level.
The first hidden stem is the Main qi (本气), the strongest. The second is the Secondary qi (中气), and the third is the Tertiary qi (余气), the weakest.
| Branch | Animal | Main (本气) | Secondary (中气) | Tertiary (余气) |
|---|---|---|---|---|
| 子 | Rat | 癸 (Yin Water) | — | — |
| 丑 | Ox | 己 (Yin Earth) | 癸 (Yin Water) | 辛 (Yin Metal) |
| 寅 | Tiger | 甲 (Yang Wood) | 丙 (Yang Fire) | 戊 (Yang Earth) |
| 卯 | Rabbit | 乙 (Yin Wood) | — | — |
| 辰 | Dragon | 戊 (Yang Earth) | 乙 (Yin Wood) | 癸 (Yin Water) |
| 巳 | Snake | 丙 (Yang Fire) | 庚 (Yang Metal) | 戊 (Yang Earth) |
| 午 | Horse | 丁 (Yin Fire) | 己 (Yin Earth) | — |
| 未 | Goat | 己 (Yin Earth) | 丁 (Yin Fire) | 乙 (Yin Wood) |
| 申 | Monkey | 庚 (Yang Metal) | 壬 (Yang Water) | 戊 (Yang Earth) |
| 酉 | Rooster | 辛 (Yin Metal) | — | — |
| 戌 | Dog | 戊 (Yang Earth) | 辛 (Yin Metal) | 丁 (Yin Fire) |
| 亥 | Pig | 壬 (Yang Water) | 甲 (Yang Wood) | — |
5. The Five Elements & Their Cycles
The five elements are: Wood, Fire, Earth, Metal, Water.
Production Cycle (生 shēng)
Each element feeds the next. Think of it as a nurturing chain:
Wood → Fire → Earth → Metal → Water → Wood
- Wood feeds Fire (wood burns)
- Fire creates Earth (ash becomes soil)
- Earth yields Metal (ore is mined)
- Metal collects Water (condensation on metal)
- Water nourishes Wood (trees drink water)
Control Cycle (克 kè)
Each element restrains another. Think of it as a check-and-balance system:
Wood → Earth → Water → Fire → Metal → Wood
- Wood breaks Earth (roots split soil)
- Earth dams Water (dikes hold floods)
- Water quenches Fire (water puts out flames)
- Fire melts Metal (forge softens iron)
- Metal chops Wood (axe fells trees)
Why these cycles matter
Every Ten God relationship (Section 6) is derived from these two cycles plus polarity. If element A produces element B, the Ten God is an “Output” type. If A controls B, it is a “Wealth” type. And so on.
The app also tracks the reverse lookups:
| Lookup | Meaning | Example |
|---|---|---|
PRODUCES | What this element feeds | Wood → Fire |
PRODUCED_BY | What feeds this element | Fire → Wood |
CONTROLS | What this element restrains | Wood → Earth |
CONTROLLED_BY | What restrains this element | Wood → Metal |
6. The Ten Gods (十神)
The Ten Gods describe the relationship between the Day Master (your stem) and every other stem in the chart. There are five relationship categories, each split into two variants based on polarity — making ten in total.
The polarity rule
- Same polarity as the Day Master → one variant
- Opposite polarity → the other variant
For example, if the Day Master is Yang Wood (甲) and another stem is also Yang Wood (甲), both are same element AND same polarity → Companion. If the other stem is Yin Wood (乙), same element but opposite polarity → Rob Wealth.
Full Ten Gods table
| # | Chinese | English | Profile Name | Element Relationship | Polarity Match | Plain-English Meaning |
|---|---|---|---|---|---|---|
| 1 | 比肩 | Companion | The Self-Reliant | Same element | Same | Peers, independence, self-reliance |
| 2 | 劫财 | Rob Wealth | The Social Magnet | Same element | Opposite | Boldness, competition, risk-taking |
| 3 | 食神 | Eating God | The Deep Thinker | DM produces | Same | Creativity, enjoyment, gentle expression |
| 4 | 伤官 | Hurting Officer | The Spotlight Seeker | DM produces | Opposite | Rebellion, brilliance, sharp tongue |
| 5 | 正财 | Direct Wealth | The Steady Builder | DM controls | Opposite | Steady income, practicality, stability |
| 6 | 偏财 | Indirect Wealth | The Risk Taker | DM controls | Same | Windfalls, networking, side ventures |
| 7 | 正官 | Direct Officer | The Rule Keeper | Controls DM | Opposite | Authority, discipline, integrity |
| 8 | 七杀 | Seven Killings | The Crisis Solver | Controls DM | Same | Pressure, ambition, breakthroughs |
| 9 | 正印 | Direct Resource | The Mentor | Produces DM | Opposite | Education, nurturing, traditional wisdom |
| 10 | 偏印 | Indirect Resource | The Strategist | Produces DM | Same | Intuition, unconventional knowledge, pattern-seeing |
How the Day Master’s own stem is handled
The Day Master is the reference point for all Ten God calculations. It is excluded from profile and dominant-god scoring — only the stems that surround it (Year, Month, Hour pillars and all hidden stems) contribute to the profile. Comparing the Day Master to itself would always produce “Companion”, giving it an artificial head start in every chart.
7. Weight System
Not all stems carry equal influence. Visible stems (the ones you can see at the top of each pillar) are fully expressed traits. Hidden stems are latent potential — they shape personality beneath the surface but are not as directly apparent.
| Position | Weight | Rationale |
|---|---|---|
| Visible stem (天干) | 1.0 | Manifest, directly expressed trait |
| Main hidden stem (本气) | 0.5 | Strongest latent influence |
| Secondary hidden stem (中气) | 0.2 | Moderate latent influence |
| Tertiary hidden stem (余气) | 0.1 | Minor latent influence |
Why hidden stems are discounted
- Prevent over-counting. Each branch can contain up to three hidden stems. Without discounting, hidden stems would overwhelm visible stems in the score.
- Traditional practice. Classical BaZi practitioners give hidden stems less interpretive weight than visible stems — they represent potential rather than manifested behaviour.
8. Seasonal Strength (月令 Yuè Lìng)
The concept
In BaZi, the month branch determines which element is “in season.” An element that matches the current season is at peak strength; an element controlled by the season is at its weakest. This is called the 五行旺相休囚死 (Five Phases Seasonal Strength) system.
Branch-to-season mapping
| Branches | Season | Dominant Element |
|---|---|---|
| 寅 卯 | Spring | Wood |
| 巳 午 | Summer | Fire |
| 申 酉 | Autumn | Metal |
| 亥 子 | Winter | Water |
| 辰 未 丑 戌 | Transitional | Earth |
The Five Seasonal Phases
Given the season’s element, every element falls into one of five states:
| Phase | Chinese | Meaning | Multiplier | Relationship to the season |
|---|---|---|---|---|
| Wang | 旺 (wàng) | Prosperous | 1.5 | Element IS the season |
| Xiang | 相 (xiàng) | Prime minister | 1.2 | Season produces this element |
| Xiu | 休 (xiū) | Resting | 1.0 | Element produces the season |
| Qiu | 囚 (qiú) | Imprisoned | 0.6 | Element controls the season |
| Si | 死 (sǐ) | Dead | 0.3 | Season controls this element |
How multipliers are applied
Every stem’s base weight is multiplied by the seasonal multiplier of that stem’s element:
final_weight = base_weight × seasonal_multiplier
For example, a visible Wood stem (base 1.0) in a Spring month (Wood is Wang) scores:
1.0 × 1.5 = 1.5
A visible Earth stem (base 1.0) in a Spring month (Wood controls Earth → Si) scores:
1.0 × 0.3 = 0.3
This means the same stem can score five times higher when it is in season versus out of season.
9. Chart Structure & Profiles (格局)
The chart structure (格局 gé jú) determines the user’s primary personality archetype. Rather than accumulating weights across all stems, the app uses the traditional month branch penetration method.
How the dominant profile is determined
- Examine the month branch’s hidden stems. The month branch (月支) contains one to three hidden stems, checked in priority order: Main qi (本气), then Secondary qi (中气), then Tertiary qi (余气).
- Check for penetration (透出). A hidden stem “penetrates” when the same stem appears as a visible Heavenly Stem in the Year, Month, or Hour pillar. The first hidden stem (in priority order) that penetrates determines the chart structure.
- Determine the Ten God. The penetrating stem’s Ten God (relative to the Day Master) becomes the dominant Ten God. This Ten God is then mapped to a named profile archetype containing tagline, strengths, challenges, work style, relationship style, and inner motive.
- Fallback. If no hidden stem of the month branch penetrates through any visible pillar, the Main qi (本气) is used directly — its Ten God becomes the dominant profile.
Example
If the month branch is 午 (Horse), its hidden stems are: 丁 (Main qi), 己 (Secondary qi). If 丁 appears as a visible stem in the Year, Month, or Hour pillar, it penetrates — and its Ten God becomes the dominant profile. If 丁 does not appear but 己 does, then 己’s Ten God is used instead.
10. Day Master Strength
Day Master strength determines whether the chart has excess energy that needs channelling or a deficit that needs nurturing.
Element classification
| Category | Elements | Role |
|---|---|---|
| Support | Same element as DM + resource element (what produces DM) | Strengthens the Day Master |
| Drain | Output element (DM produces) + wealth element (DM controls) + power element (controls DM) | Weakens the Day Master |
Scoring
The scoring uses the same base weights as profile scoring — visible stems at 1.0, hidden stems at 0.5 / 0.2 / 0.1 — with seasonal multipliers applied. Each stem is classified as Support or Drain based on its element. Its base weight is multiplied by the seasonal multiplier, then by a polarity adjustment:
- Same-polarity Companion (比肩): ×1.1 — slightly stronger bond with the Day Master
- Opposite-polarity Resource (正印): ×1.1 — more nurturing than same-polarity resource
- Other combinations: ×0.9
The Day Master’s own stem is excluded from this calculation (it is the reference point, not a data point).
Advanced adjustments
Season advantage (得令)
Before counting individual stems, the algorithm awards a +1.5 bonus to either the Support or Drain total based on the month branch (月令). If the season’s element matches the Day Master or its resource element, Support gets +1.5. If the season’s element matches the output, wealth, or power element, Drain gets +1.5. This reflects the traditional BaZi principle that the month branch alone accounts for roughly 40–50% of Day Master strength.
Stem bonding (合绊)
When two Heavenly Stems form a recognized combination (天干五合), both stems are considered “busy” combining and contribute only 50% of their normal weight to the strength calculation.
Branch combination shifts
When Earthly Branches in the chart form recognized combinations, the hidden stems’ element weights shift partially toward the combination’s transform element. The shift percentages are:
| Formation | Chinese | Shift % | Notes |
|---|---|---|---|
| Six Harmonies pair | 六合 | 30% | Two-branch bond |
| Half Combination | 半合 | 15% | Two of three triad members present |
| Three Harmonies | 三合局 | 50% | Complete elemental triad |
| Directional Combination | 三会局 | 65% | Strongest — three seasonal branches aligned |
Clash breaks combination (冲破合)
If a branch involved in a combination is also clashed by another branch in the chart, the combination is nullified — the clash takes priority and the element shift does not occur. For Directional Combinations (三会局), which are very strong, the combination only breaks if two or more of the three members are clashed.
Threshold
difference = supportScore − drainScore
| Condition | Classification |
|---|---|
| difference > 1.0 | Strong — abundant energy that needs expression and output |
| difference < −1.0 | Weak — needs nurturing and support to thrive |
| −1.0 ≤ difference ≤ 1.0 | Neutral — relatively balanced with flexibility |
The threshold of 1.0 is a calibrated heuristic chosen to avoid over-classifying charts as strong or weak.
11. Balancing Element (用神)
The balancing element (用神 yòng shén, “Useful God”) is the single most important prescriptive output. It drives all advice — habits, career guidance, relationship tips, and health suggestions. The app uses a 5-priority system that goes beyond simple strong/weak logic.
Priority 0 — 从格 (Follow Structure)
If the Day Master’s support ratio falls below 12% of total chart weight, the DM is considered too weak to sustain. Rather than trying to strengthen an abandoned Day Master, the app “follows” the dominant drain element — whichever of the output, wealth, or power elements has the highest weight becomes the balancing element. The action verb becomes “flow with and embrace.”
Priority 1 — 调候 (Climate Regulation)
For charts born in extreme seasons, temperature balance overrides the standard support/drain logic. For example, a chart born in deep summer may need Water regardless of Day Master strength, and a chart born in deep winter may need Fire. The app maintains a lookup table of element–month combinations that trigger this override.
Priority 1.5 — 通关 (Bridging)
When two strong non-DM elements (each ≥28% of total chart weight) are in a CONTROLS relationship — one attacking the other — the chart has internal conflict. The “bridge” element that mediates between them (controller → bridge → controlled, following the production cycle) becomes the balancing element. The action verb becomes “harmonize through.”
Priority 2 — Strong DM (扶抑)
When the Day Master is strong and no higher-priority override applies, the app selects a drain element. It prefers gentler drains first:
- Output element (食伤 food/creativity) — gentlest, most creative drain
- Wealth element (财 finances) — moderate, practical drain
- Power element (官杀 authority) — harshest, confrontational drain
Among candidates at the same priority level, the one with the lowest current weight in the chart is chosen (the chart needs what it lacks most). The action verb is “express and channel.”
Priority 3 — Weak / Neutral DM (扶抑)
When the Day Master is weak or neutral, the app picks the least-present support element from two candidates: the resource element (what produces the DM) and the DM’s own element (companion). Whichever has less weight in the chart is chosen. The action verb is “cultivate and nurture.”
Default balancing table (Priority 2 & 3 simplified)
| Day Master Element | If Weak / Neutral → | If Strong → |
|---|---|---|
| Wood | Water (resource) or Wood (companion) | Fire (output) > Earth (wealth) > Metal (power) |
| Fire | Wood (resource) or Fire (companion) | Earth (output) > Metal (wealth) > Water (power) |
| Earth | Fire (resource) or Earth (companion) | Metal (output) > Water (wealth) > Wood (power) |
| Metal | Earth (resource) or Metal (companion) | Water (output) > Wood (wealth) > Fire (power) |
| Water | Metal (resource) or Water (companion) | Wood (output) > Fire (wealth) > Earth (power) |
Each balancing element comes with a qualities string (e.g. Water = “wisdom, flexibility, going with the flow, introspection, adaptability”) and an action verb. These are injected into the AI prompt to ensure all habits and advice are thematically consistent.
12. Chart Profiles
How profiles are assigned
The profile system extends the dominant chart structure (Section 9) by identifying secondary personality facets from the remaining visible stems.
- Dominant profile is determined by the 格局 (chart structure) method described in Section 9 — via month branch penetration.
- Secondary profiles are the visible stem Ten Gods from the remaining pillars (those not used for the dominant profile), checked in order: Month → Year → Hour. Each is mapped to its own profile archetype.
Output structure
- Dominant profile: The Ten God determined by chart structure → mapped to a full profile archetype (tagline, strengths, challenges, work style, relationship style, inner motive). Includes the pillar location where penetration was found.
- Secondary profiles: The remaining visible stems’ Ten Gods, each with their profile archetype and pillar location.
The UI displays the dominant profile prominently and shows secondary profiles as complementary facets of personality.
13. Zodiac Compatibility
Compatibility is assessed from two perspectives, each using a different reference animal combined with the balancing element:
- Spouse Palace (夫妻宫) — uses the Day Branch animal. This represents relationship dynamics and romantic compatibility.
- Year Branch — uses the Year Branch animal (birth year zodiac). This represents general social and life compatibility.
Both perspectives are calculated independently using the same relationship rules below, and both sets of results are provided to the AI for narrative generation.
Relationship types
Six Clashes 六冲 — Direct opposition
These are pairs sitting across from each other on the zodiac wheel. They create tension and conflict.
| Pair 1 | Pair 2 | Pair 3 | Pair 4 | Pair 5 | Pair 6 |
|---|---|---|---|---|---|
| Rat ↔ Horse | Ox ↔ Goat | Tiger ↔ Monkey | Rabbit ↔ Rooster | Dragon ↔ Dog | Snake ↔ Pig |
Six Harms 六害 — Hidden conflict
These pairs create subtle friction and misunderstanding, less obvious than clashes but still challenging.
| Pair 1 | Pair 2 | Pair 3 | Pair 4 | Pair 5 | Pair 6 |
|---|---|---|---|---|---|
| Rat ↔ Goat | Ox ↔ Horse | Tiger ↔ Snake | Rabbit ↔ Dragon | Monkey ↔ Pig | Rooster ↔ Dog |
Six Harmonies 六合 — Deep affinity
These are the strongest natural bonds — pairs with deep mutual support.
| Pair 1 | Pair 2 | Pair 3 | Pair 4 | Pair 5 | Pair 6 |
|---|---|---|---|---|---|
| Rat ↔ Ox | Tiger ↔ Pig | Rabbit ↔ Dog | Dragon ↔ Rooster | Snake ↔ Monkey | Horse ↔ Goat |
Three Harmonies 三合 — Elemental triads
Groups of three animals sharing a deep elemental bond:
| Triad | Element | Animals |
|---|---|---|
| Water Frame | Water | Monkey, Rat, Dragon (申子辰) |
| Wood Frame | Wood | Pig, Rabbit, Goat (亥卯未) |
| Fire Frame | Fire | Tiger, Horse, Dog (寅午戌) |
| Metal Frame | Metal | Snake, Rooster, Ox (巳酉丑) |
Three Punishments 三刑 — Friction and conflict
Punishments create friction, legal trouble, or interpersonal conflict — more intense than harms.
| Type | Chinese | Animals |
|---|---|---|
| Bullying Punishment | 拗势之刑 | Tiger ↔ Snake ↔ Monkey |
| Ungrateful Punishment | 无恩之刑 | Ox ↔ Dog ↔ Goat |
| Uncivilized Punishment | 无礼之刑 | Rat ↔ Rabbit |
Self-Punishment 自刑
When the same animal appears in two different pillars of the chart, certain animals create a self-punishment — internal tension and self-sabotage. The self-punishing animals are: Dragon, Horse, Rooster, Pig.
Supporting element animals
Any zodiac animal whose native element matches the user’s balancing element provides supportive energy.
| Animal | Native Element |
|---|---|
| Rat | Water |
| Ox | Earth |
| Tiger | Wood |
| Rabbit | Wood |
| Dragon | Earth |
| Snake | Fire |
| Horse | Fire |
| Goat | Earth |
| Monkey | Metal |
| Rooster | Metal |
| Dog | Earth |
| Pig | Water |
Priority and limits
- Clashes and Harms take priority. If an animal both clashes/harms AND has a harmonious relationship, it is classified as challenging only.
- Harmonious ranking: Liu He (六合) > San He (三合) > element match.
- Maximum 3 per category — the app returns at most 3 harmonious and 3 challenging animals for a cleaner reading.
14. AI Narrative Generation
Model selection
| Scenario | Model | Reason |
|---|---|---|
| All readings | gemini-3-flash-preview | Fast, cost-effective, with sufficient reasoning for both 3-pillar and 4-pillar charts |
Generation parameters
| Parameter | Value | Purpose |
|---|---|---|
| Temperature | 0 | Deterministic output — same prompt always produces the same reading |
| Seed | 42 | Additional reproducibility guarantee across sessions |
| Max tokens | 16,384 | Sufficient space for a complete structured reading |
What is pre-calculated vs. what the AI generates
Pre-calculated (deterministic, injected into the prompt):
- All four pillars with stems, branches, and Ten Gods
- Hidden stems for every branch
- Day Master identity, element, polarity, and zodiac animal
- Day Master strength (strong / weak / neutral with support and drain scores)
- Chart Structure (格局) with penetration analysis
- Dominant Ten God and profile archetype
- Balancing element with qualities and action verb
- Favorable/Unfavorable analysis (喜忌: 用神, 喜神, 忌神, 仇神, 闲神)
- Zodiac compatibility from both Spouse Palace and Year Branch perspectives
- Heavenly Stem combinations (天干五合) with transform elements
- Current Luck Pillar (大运) with age range, stem Ten God, and branch hidden stems
- Spouse Palace (夫妻宫) — Day Branch details for relationship analysis
- Intra-chart branch interactions (clashes, harmonies, harms, punishments, San He, San Hui formations)
- Void Branches (空亡) — weakened positions in the chart
- Symbolic Stars (神煞) — Noble Person, Peach Blossom, Traveling Horse, Literary Star, Blade, Canopy
- Na Yin (納音) elemental imagery for all pillars
- Annual Pillar (流年) with branch interactions against the natal chart
AI-generated (from Gemini, based on the above):
pillarDescription— personality narrative (“Who am I?”)career— career outlook and advice (2 paragraphs)love— relationship outlook and advice (2 paragraphs)money— financial outlook and advice (2 paragraphs)health— health outlook and advice (2 paragraphs)fate— life direction and 2026 analysis (2 paragraphs)habits— 3 actionable habits per category (career, love, money, health, fate, compatibility), all themed around the balancing element
Prompt structure
The prompt instructs the AI to act as a BaZi expert writing in plain, accessible English — like a knowledgeable mentor explaining results to a modern audience. An alternate “Uncle Roger” mode delivers the same BaZi-accurate reading in a comedic voice. The prompt contains 16 structured sections:
- Subject data — gender, date, time, location
- Four Pillars — exact stems, branches, Ten Gods, and hidden stems (provided as pre-calculated data)
- Day Master identity — stem, polarity, element, zodiac animal, strength description
- Dominant Ten God — name and profile archetype
- Chart Structure (格局) — structure name in Chinese and English
- Balancing element (用神) — element, action, qualities
- Favorable/Unfavorable analysis (喜忌) — all five god roles
- Compatibility summary — Spouse Palace and Year Branch perspectives
- Stem Combinations (天干五合) — detected bonding pairs and transform elements
- Current Luck Pillar (大运) — the active 10-year cycle with Ten Gods
- Spouse Palace (夫妻宫) — Day Branch hidden stems for relationship dynamics
- Intra-chart branch interactions — clashes, harmonies, harms, punishments, San He/Hui formations, self-punishments
- Void Branches (空亡) — weakened palace positions
- Symbolic Stars (神煞) — Noble Person, Peach Blossom, Traveling Horse, Literary Star, Blade, Canopy
- Na Yin (納音) — elemental imagery for each pillar
- Annual Pillar (流年) — current year’s stem, branch, Ten God, and interactions with the natal chart
The prompt concludes with interpretation instructions (personality via Day Master + Stars, advice via Balancing Element) and output formatting rules (pillarDescription format, 2-paragraph categories, 3 habits per category themed around the balancing element).
Output schema
The response is constrained to a structured JSON schema, guaranteeing the output matches the expected format. This prevents the AI from returning free-form text and ensures every field is present and correctly typed:
{
zodiacSign, pillarDescription,
career, love, money, health, fate,
habits: { career[], love[], money[], health[], fate[], compatibility[] },
compatibility: { harmonious[], challenging[] }
}
After receiving the AI response, the app overrides certain fields with pre-calculated values (compatibility data, zodiac sign, year element, chart profiles) to ensure deterministic accuracy — the AI’s narrative is trusted, but structured data always comes from the calculation engine.
15. Assumptions & Design Decisions
- Li Chun zodiac boundary. The app uses Li Chun (立春, ~Feb 4) as the BaZi year start, not the Lunar New Year. This is the traditional BaZi convention and means people born in January or early February may belong to the previous zodiac year.
- True Solar Time over clock time. When a birth location is provided, TST correction is always applied. This can shift the time enough to change the Hour Pillar or even the Day Pillar.
- Hidden stem weights (0.5 / 0.2 / 0.1). These values are chosen to prevent hidden stems from dominating the score while still reflecting traditional practice. They are not universally standardized — different practitioners use different weights.
- Seasonal multiplier values (1.5 / 1.2 / 1.0 / 0.6 / 0.3). These are app-specific tuning values. Classical BaZi describes the five phases qualitatively (Wang is strongest, Si is weakest) but does not specify exact multipliers. The chosen values produce strong score differentiation — an element in season (Wang, 1.5) scores five times higher than one controlled by the season (Si, 0.3).
- Day Master Strength threshold of 1.0. This is a calibrated heuristic. A margin of 1.0 ensures only clearly imbalanced charts are classified as strong or weak — borderline cases stay neutral, which avoids over-prescribing.
- Chart structure uses month branch penetration. The dominant profile is determined by which hidden stem of the month branch “penetrates” (appears as a visible stem), not by accumulating weights. This follows the classical 格局 method and prioritises the month branch as the seat of the chart’s structure.
- Balancing element uses a 5-priority system. Rather than a simple strong/weak lookup, the app checks for structural override (从格), climate regulation (调候), bridging (通关), then standard support/drain logic. This more closely mirrors traditional BaZi practice.
- AI temperature 0 for reproducibility. Deterministic output means the same person always receives the same reading, which builds trust and consistency.
- Day Master excluded from strength scoring. The Day Master is the reference frame, not a data point — counting it would bias every chart toward “support” by one unit.
- Day Master excluded from profile scoring. The Day Master is the reference frame for both strength and profile calculations. Including it would give Companion a guaranteed head start (1.0 × seasonal multiplier) in every chart, biasing results away from classical BaZi interpretation where the profile is determined by what surrounds the Day Master.
16. Glossary
Every technical term used in this document, explained in plain English.
BaZi (八字) — Literally “eight characters.” A Chinese astrology system that reads personality and life tendencies from the exact moment of birth, encoded as four pairs of characters.
Four Pillars — The four columns of a BaZi chart: Year, Month, Day, and Hour. Each pillar has a Heavenly Stem on top and an Earthly Branch on the bottom.
Heavenly Stem (天干) — The top character of each pillar. There are 10 stems in the cycle, each mapped to one of the five elements with either Yin or Yang polarity.
Earthly Branch (地支) — The bottom character of each pillar. There are 12 branches in the cycle, each mapped to a zodiac animal.
Day Master (日主) — The Heavenly Stem of your Day Pillar. It represents “you” — your core identity. Every other stem in the chart is interpreted relative to the Day Master.
Hidden Stems (藏干) — Stems embedded inside each Earthly Branch (1 to 3 per branch). They represent latent personality traits and potential that are not immediately visible but still influence behaviour.
Ten Gods (十神) — The 10 relationship types between the Day Master and any other stem, determined by the element cycle and polarity. Each Ten God describes a different life dynamic.
Companion (比肩) — Same element, same polarity as Day Master. Represents independence, self-reliance, and peer relationships.
Rob Wealth (劫财) — Same element, opposite polarity. Represents boldness, competition, and risk-taking.
Eating God (食神) — Day Master produces, same polarity. Represents creativity, enjoyment, and gentle self-expression.
Hurting Officer (伤官) — Day Master produces, opposite polarity. Represents rebellion, brilliance, and sharp unconventional talent.
Direct Wealth (正财) — Day Master controls, opposite polarity. Represents steady income, practical finances, and stability.
Indirect Wealth (偏财) — Day Master controls, same polarity. Represents windfalls, networking, side ventures, and generosity.
Direct Officer (正官) — Controls Day Master, opposite polarity. Represents authority, discipline, career structure, and reputation.
Seven Killings (七杀) — Controls Day Master, same polarity. Represents intense pressure, ambition, power, and breakthrough through adversity.
Direct Resource (正印) — Produces Day Master, opposite polarity. Represents education, nurturing, emotional support, and traditional knowledge.
Indirect Resource (偏印) — Produces Day Master, same polarity. Represents intuition, unconventional learning, solitude, and esoteric knowledge.
Wang (旺) — “Prosperous.” The seasonal phase where an element matches the current season — its strongest state. Multiplier: 1.5.
Xiang (相) — “Prime minister.” The element produced by the season — second strongest. Multiplier: 1.2.
Xiu (休) — “Resting.” The element that produces the season — neutral strength. Multiplier: 1.0.
Qiu (囚) — “Imprisoned.” The element that controls the season — weakened. Multiplier: 0.6.
Si (死) — “Dead.” The element controlled by the season — most weakened. Multiplier: 0.3.
Seasonal Strength / 月令 (Yuè Lìng) — The month branch’s influence on how strong or weak each element is at the time of birth. The season amplifies elements that are “in phase” and dampens elements that are out of phase.
Production Cycle (生 shēng) — The nurturing cycle: Wood feeds Fire, Fire creates Earth, Earth yields Metal, Metal collects Water, Water nourishes Wood.
Control Cycle (克 kè) — The restraining cycle: Wood breaks Earth, Earth dams Water, Water quenches Fire, Fire melts Metal, Metal chops Wood.
Polarity (Yin/Yang 阴阳) — Each Heavenly Stem has a polarity. Same-polarity pairs between the Day Master and another stem produce one Ten God variant; opposite-polarity pairs produce the other. For example, same element + same polarity = Companion, but same element + opposite polarity = Rob Wealth.
True Solar Time — The actual position of the sun at your birth location, corrected from clock time using longitude offset and the Equation of Time. BaZi uses solar position, not civic timekeeping.
Equation of Time — A correction factor (ranging from −14 to +16 minutes) that accounts for Earth’s elliptical orbit and axial tilt. It varies throughout the year.
Li Chun (立春) — “Start of Spring,” around February 4 each year. This is the BaZi year boundary — not the Lunar New Year. A person born in late January belongs to the previous BaZi year.
Six Clashes (六冲) — Six pairs of zodiac animals in direct opposition: Rat–Horse, Ox–Goat, Tiger–Monkey, Rabbit–Rooster, Dragon–Dog, Snake–Pig. These create tension and conflict.
Six Harms (六害) — Six pairs of zodiac animals with hidden friction: Rat–Goat, Ox–Horse, Tiger–Snake, Rabbit–Dragon, Monkey–Pig, Rooster–Dog. More subtle than clashes but still challenging.
Six Harmonies (六合) — Six pairs of zodiac animals with deep natural affinity: Rat–Ox, Tiger–Pig, Rabbit–Dog, Dragon–Rooster, Snake–Monkey, Horse–Goat. The strongest bond type.
Three Harmonies (三合) — Groups of three zodiac animals sharing an elemental bond: Water (Monkey–Rat–Dragon), Wood (Pig–Rabbit–Goat), Fire (Tiger–Horse–Dog), Metal (Snake–Rooster–Ox).
Balancing Element — The single element prescribed to bring the chart into balance. For weak/neutral Day Masters, it is the element that produces them (resource). For strong Day Masters, it is the element they produce (output). All habits and prescriptive advice revolve around this element.
Day Master Strength — Whether the Day Master has more support than drain (strong), more drain than support (weak), or roughly equal (neutral). Determined by summing the weights of supporting vs. draining elements across all stems in the chart.
Profile / Profile Archetype — The personality type associated with a Ten God. Each of the 10 Ten Gods maps to a named archetype (e.g. Companion → “The Self-Reliant”) with a tagline, strengths, challenges, work style, relationship style, and inner motive.
Chart Structure (格局) — The chart’s structural classification, determined by which hidden stem of the month branch penetrates through a visible pillar stem. This determines the dominant personality archetype.
Dominant Profile — The profile determined by the chart structure (格局) method — the Ten God of the first penetrating hidden stem of the month branch. This is the primary personality archetype shown to the user.
Secondary Profiles — Profiles from the remaining visible stem Ten Gods (Month, Year, Hour pillars), representing complementary personality facets.