Bazi Profile

Structured Bazi / Four Pillars of Destiny workflow for Codex, focused on deterministic chart calculation, high-specificity interpretation, continuous follow-up conversation design, and anti-generic linting.

中文介绍 / README.zh-CN

What This Project Is

bazi-profile is not a UI product and not a generic fortune-telling prompt.

It is a local-first open-source toolkit for:

• Bazi / Four Pillars / Chinese astrology chart calculation
• structured interpretation for self-understanding and people analysis
• chart signature extraction
• pairwise chart differentiation
• distinctiveness lint for anti-Barnum output
• deep follow-up conversation flow for multi-turn analysis

This repo is designed for Codex-style local agent workflows, but the CLI tools can also be used independently.

Why It Exists

Most AI-native Bazi demos fail in one of two ways:

1. the chart engine is approximate
2. the interpretation is generic enough to fit many unrelated charts

This project tries to solve both:

• use a deterministic chart engine instead of hand-written date tables
• extract machine-readable structural signatures before prose
• force exclusion lines, confidence labels, and pairwise differentiation
• support overview-first, follow-up-next conversation flows instead of one giant reading

Core Features

1. Deterministic chart engine

Powered by the local engine under engine/bazi-engineering, currently built around reliable calendar libraries instead of approximate handcrafted logic.

2. Structural signature extraction

scripts/extract_signature.cjs converts chart JSON into:

• unique anchors
• anti-patterns
• core tensions
• role counts
• element counts
• precision markers

3. Pairwise differentiation

scripts/compare_signatures.cjs compares two charts and forces explicit differences so two people do not receive near-identical narratives.

4. Distinctiveness lint

scripts/lint_distinctiveness.cjs blocks:

• generic high-frequency lines
• missing exclusion layer
• missing confidence markers
• weak structural coverage
• excessive overlap with a prior report

5. Deep follow-up conversation flow

scripts/generate_followup_flow.cjs generates a multi-turn analysis outline:

• overview round first
• top 3 follow-up domains
• one-domain-per-turn deep dive prompts
• timing-aware continuation flow

Repository Structure

bazi-profile/
├── SKILL.md
├── engine/bazi-engineering/
├── references/
├── scripts/
├── templates/
└── tests/

Important files:

• SKILL.md: main Codex skill entry
• scripts/extract_signature.cjs: chart signature extraction
• scripts/compare_signatures.cjs: chart-to-chart differentiation
• scripts/lint_distinctiveness.cjs: anti-generic lint
• scripts/generate_followup_flow.cjs: multi-turn deep follow-up planner
• references/deep-followup-flow.md: follow-up conversation design rules
• marketing/: GitHub social preview image and SEO/social copy

Quick Start

Install dependencies

The root project has no heavy runtime dependency. The Bazi engine lives under engine/bazi-engineering.

cd engine/bazi-engineering
npm install

Run tests

npm test

Generate a structural signature

node scripts/extract_signature.cjs --solar "1995-03-03 18:30:00" --gender male --sect 2

Generate a deep follow-up flow

node scripts/generate_followup_flow.cjs --solar "1995-03-03 18:30:00" --gender male --sect 2 --year 2026

Compare two charts

node scripts/compare_signatures.cjs --a ./a-signature.json --b ./b-signature.json

Lint a draft reading

node scripts/lint_distinctiveness.cjs --report ./report.md --signature ./signature.json --fail-on-error

Intended Workflow

Recommended pipeline:

1. compute chart JSON with the deterministic engine
2. extract structural signature
3. generate overview-first follow-up flow
4. draft the reading
5. lint the reading before sending

This is the main reason this repo stays more specific than a long all-in-one prompt.

SEO / Search Keywords

This project is intentionally optimized for discoverability around:

• Bazi
• Four Pillars of Destiny
• Chinese astrology
• Bazi calculator
• Bazi interpretation
• AI Bazi analysis
• Codex skill
• 八字
• 四柱
• 生辰八字
• 八字排盘
• 四柱命理
• 大运分析
• 命理解读

Scope And Boundaries

This repo is for:

• structured self-knowledge
• relationship/career/wealth/health-energy discussion
• conversation design for follow-up readings

This repo is not for:

• medical diagnosis
• legal or financial guarantees
• identity inflation or “chosen one” rhetoric
• pretending uncertain birth-hour data is precise

Release Status

This repository is the closing release for the current bazi-profile iteration:

• deterministic engine integrated
• signature layer added
• anti-generic lint added
• deep follow-up flow added
• open-source packaging completed

Contributing

Please read CONTRIBUTING.md.

License

MIT, see LICENSE.