# Quizzman Zodiac Sign — About (V2.0)

- HTML: https://lab.quizzman.com/tool/about-zodiac
- Tool: https://lab.quizzman.com/zodiac-sign
- Markdown (this file): https://lab.quizzman.com/tool/about-zodiac.md
- Engine: `qm-zodiacsign` **v2.0** (2026-07-29)
- Canonical language: Vietnamese (`lang=vi`)

## Keywords

Western astrology · Natal chart · Birth chart · Sun sign · Horoscope · Planetary transit · Transit astrology · Ascendant · Midheaven · Whole-sign houses · Astrology engine · Ephemeris · Rule-based astrology · Tropical zodiac · Synastry · Natural language generation (NLG) · Expert system

## Definition

**Quizzman Zodiac Sign** is an **astrology interpretation engine** that combines **real astronomical positions** with **transparent, deterministic rule-based astrology models** to generate **daily sun-sign readings** and **personal natal chart interpretations**.

It is a tropical (Western) expert-system tool on lab.quizzman.com — **not** a single Sun-sign fortune cookie and **not** a hand-written horoscope blog. Astronomy (sky snapshot / natal geometry) is computed first; interpretation runs only after rule evaluation and evidence fusion.

| Mode | Input | What you get |
|------|--------|----------------|
| **Theo cung** (sun-sign daily) | Date + tropical sign | One shared **Today's Sky** → rule engine relative to that sign → Career / Love / Health / Finance (+ study/family) + NLG |
| **Theo ngày sinh** (personal chart) | Birth date (+ default place HCM / noon if time/place omitted) | Full **natal chart** (Asc, MC, houses, planets, aspects) + transit overlays + domain readings |

## Design principles

- **Astronomy and interpretation are separated.** Positions and events come from the ephemeris layer; text never invents sky facts.
- **Astronomical positions come from Astro Support API** (`astro.quizzman.com`), with local `@quizzman/qm-astro` fallback when configured.
- **Interpretations are generated only after rule evaluation** (Condition Engine + domain fusion).
- **Rules are deterministic and reproducible** for the same `when` / birth / sign inputs.
- **Natural-language generation never invents evidence** that does not exist in the scored evidence / condition bag.
- **Sun-sign and natal modes stay distinct** — daily sun-sign does not pretend to have a personal Asc from a fake birth chart.

## Why V2.0

Earlier versions generated sun-sign readings using **representative mid-season chart dates** (a probe “natal” at lat 0). That mixed artificial natal assumptions into a daily horoscope workflow.

**Version 2.0** instead evaluates **one real sky snapshot** and projects it consistently across all twelve tropical signs via sign-relative rules (symbolic whole-sign houses from the sun sign). This produces more coherent daily interpretations and **removes artificial natal assumptions** from the sun-sign path. Natal / birth-chart analysis remains a separate, full-geometry mode.

## What V2.0 adds

1. **Today's Sky (1 snapshot)** — Sun–Saturn positions, retrograde list, moon phase, major sky aspects, ingress/eclipse accents
2. **Sign-relative scoring** — whole-sign houses with Asc = 0° of the sun sign; planet-in-house, ruler dignity/Rx, moon element affinity, sky aspects to ruler / houses 1·7·10
3. **Batch API** — one sky → up to 12 sign readings (`POST /v1/sunsign/batch`)
4. **Personal lá số UI** — Asc/MC chips, SVG wheel, planet×house table, major aspects; transit chips separate from natal structure
5. **Day / week / month** cycles with period-aware NLG (evidence-led Vietnamese prose)
6. **Synastry** screen (compatibility axes)
7. **Astro Support API 1.1** consumer — stations, eclipses, moon phase, retrograde periods, snapshot/range

## Feature status

| Feature | Status |
|---------|--------|
| Astronomical calculation (ephemeris / snapshot) | Supported |
| Rule engine (conditions + domain fusion) | Supported |
| Natural language generation (reading-v2) | Supported |
| Birth / natal chart (Asc, MC, houses, aspects) | Supported |
| Transit analysis | Supported |
| Synastry | Supported |
| Daily sun-sign horoscope (Today's Sky × sign) | Supported |
| Weekly / monthly cycles | Supported |
| Batch 12-sign API | Supported |

## Scope

### Supported

- Tropical (Western) zodiac
- Natal / birth charts
- Daily sun-sign horoscope from a shared sky
- Weekly and monthly cycles
- Transit overlays on natal
- Synastry (compatibility)
- Evidence-bound NLG (VI primary)
- Public Lab gateway APIs (`/v1/sky`, `/v1/sunsign`, `/v1/interpret`, …)

### Not supported

- Sidereal / Vedic astrology
- Human fortune prediction or guarantees of future events
- Psychic / mediumship readings
- Numerology as a core engine
- Claiming a personal Ascendant without birth place/time (sun-sign mode uses only symbolic houses for scoring)

## Architecture

```text
Today's Sky (astro.quizzman.com snapshot + events)
        │
        ▼
Zodiac Rule Engine (sign-relative OR natal+transit)
        │
        ├── Theo cung → ×12 tropical signs
        └── Theo ngày sinh → natal chart + temporal deltas
        │
        ▼
Domain scores → Evidence fusion → NLG reading-v2
```

Pipeline in plain terms: **astronomical snapshot → rule engine → evidence fusion → natural language generation**. Readings are not a bag of pre-written fortune paragraphs disconnected from the sky.

### Sun-sign path (V2.0)

1. `buildSkySnapshot(when)` — geocentric ecliptic longitudes for ☉☽☿♀♂♃♄; Rx; moon phase; mutual aspects; stations / VOC / solar proximity / eclipses / ingress from events
2. For each sign: synthetic Asc = `signIndex × 30°`, whole-sign houses
3. Hits → `fuseEvidence` (base 50, caps, conflict damping, confidenceCap ≈ 0.72)
4. `generateReading` / evidence-led trend (VI terms in parentheses where jargon remains)

### Natal path

1. Birth → natal chart (Asc/MC via spherical astronomy; houses whole-sign or Placidus)
2. Features + domain rule packs → baseline scores
3. If `when`: transit window → Condition Engine → temporal deltas → cycle score
4. UI shows natal structure + “Transit hôm nay” separately

## Astronomical data source

| Layer | Source | Notes |
|-------|--------|--------|
| Primary | **`https://astro.quizzman.com`** Zodiac Support API (HTTP snapshot / events / range) | Lab default; version **1.1.0+** fields (stations, eclipses, moonPhase, retrograde_period, declination) |
| Fallback | Local `@quizzman/qm-astro` package | Used if remote fails and `QM_ASTRO_FALLBACK_LOCAL` allows |
| Time base | Julian Day (UT/TT), tropical ecliptic longitude | Observer lat/lon for Asc/MC; planet longitudes are geocentric |

Config (engine): `QM_ASTRO_BASE_URL`, `QM_ASTRO_SERVICE_TOKEN`. Contract: engine `docs/ASTRO_API_REQUIREMENTS.md` · Astro `ZODIAC_SUPPORT_API.md`.

**Not used for sun-sign daily:** houses/ASC from a mid-season fake birth at lat 0 — that anti-pattern was removed in V2.0.

## Algorithms (scoring sketch)

- **Orb / aspect types:** conjunction, opposition, square, trine, sextile with type-specific orbs; applying/separating from speeds
- **Fusion:** base 50; positive/negative caps; conflict damping; strength × orb tightness weights
- **Temporal deltas:** moon phase, VOC, eclipse, solar proximity (cazimi/combust), Rx/station, transit–natal or sky–sign aspects → clamped domain deltas
- **NLG:** condition gloss (VI explanation + jargon in parentheses) → evidence-select by period → assembler (lede / trend / strengths / cautions / advice)

## Reliability / accuracy meaning

| Claim | Meaning |
|-------|---------|
| Ephemeris / chart geometry | Positions and Asc/MC follow astronomical formulas + Astro Support snapshots; regression suites in `qm-zodiacsign` and Astro parity tests |
| Domain scores 0–100 | **Relative** expert-system scores from transparent rules — not probability of life events |
| Confidence | Soft confidence from evidence weight; sun-sign mode intentionally capped below full natal |
| Fortune / prophecy | Interpretations describe **symbolic astrological tendencies** derived from the chosen astrology model. They are **not** presented as factual predictions or guarantees of future events. |

Internal tests (examples): condition/Rx/VOC/cycle/sunsign-sky suites; Astro 1.1 contract tests. Exact counts evolve with the repo — see `npm test` in `qm-zodiacsign`.

## Public API (Lab gateway)

Base: `https://lab.quizzman.com/api/tool-module/zodiac`

| Method | Path | Role |
|--------|------|------|
| GET | `/health` | Engine + Astro config |
| POST | `/v1/sky` | Today's Sky snapshot |
| POST | `/v1/sunsign` | One sign × sky |
| POST | `/v1/sunsign/batch` | Up to 12 signs |
| POST | `/v1/interpret` | Natal (or legacy sunSignDate) interpret |
| POST | `/v1/chart` | Natal chart only |
| POST | `/v1/synastry` | Compatibility |

## FAQ

1. **Is this Vedic / sidereal?** No — tropical Western zodiac.
2. **Why no houses on “Theo cung”?** Houses need a birth place/time (Asc). Sun-sign mode uses symbolic whole-sign from the sun sign only for scoring, and does not claim a personal Asc.
3. **Where does data come from?** Primarily `astro.quizzman.com` Support API; local qm-astro fallback.
4. **How trustworthy are scores?** Transparent rule fusion over real sky positions — symbolic tendencies, not prophetic accuracy.

## Terms of use (Science Lab)

- https://lab.quizzman.com/tool/about-terms
- https://wiki.quizzman.com/wiki/loi-canh-tinh-danh-cho-nguoi-dung-quizzman-tinh-than-kalama-va-lan-ranh-giua-tham-khao-voi-me-tin
- https://wiki.quizzman.com/wiki/tu-luc-va-hanh-dong-moi-la-yeu-to-quyet-dinh-so-phan

## Related Lab pages

- Tool: https://lab.quizzman.com/zodiac-sign
- Calendar / ephemeris context: https://lab.quizzman.com/tool/about-calendar
- Astro tools: https://lab.quizzman.com/tool/astro-tools
- Sky viewer: https://lab.quizzman.com/tool/sky-viewer
- Lab llms.txt: https://lab.quizzman.com/llms.txt
- Tarot (same Chiêm tinh group): https://lab.quizzman.com/tarot
- Science Lab Terms: https://lab.quizzman.com/tool/about-terms

## Related engine docs (repo)

- `/opt/qm-lab/qm-zodiacsign/README.md`
- `/opt/qm-lab/qm-zodiacsign/docs/ASTRO_API_REQUIREMENTS.md`
- `/opt/qm-lab/qm-zodiacsign/docs/ASTRO_REQUIREMENTS_ZODIAC_2.0.md`
- `/opt/qm-lab/qm-zodiacsign/docs/VERSION_2.0.md`