AI Astrology Assistant

Build an astrology assistant that computes birth charts with the same logic as professional tools (e.g. Astro-Seek). Use Swiss Ephemeris (or pyswisseph, swephR, swisseph-js) as the calculation engine.

When to Apply This Skill

• User asks for birth chart calculation, natal chart, or horoscope by birth data
• Building an astrology API, chatbot, or web calculator
• Interpreting planetary positions, houses, or aspects
• Implementing ephemeris-based astrology features

---

Core Workflow

1. Parse birth data (date, time, location) → validate inputs
2. Convert local time → UTC → Julian Day
3. Compute planetary positions (swe_calc_ut)
4. Compute houses, Ascendant, MC (swe_houses)
5. Assign planets to houses (swe_house_pos)
6. Calculate aspects between all pairs
7. Optionally apply sidereal ayanamsha
8. Format and interpret results

---

Required Inputs

Input	Required	Notes
Date of birth	Yes	Day, month, year
Time	No*	Local time (h, m, s). *Required for houses/Ascendant
Birth place	Yes	City name or lat/long
Timezone	Yes	Auto from location or manual (e.g. UTC+1)
DST	Yes	Observed / Not-Observed
House system	No	Default: Placidus
Zodiac	No	Default: Tropical

---

Implementation Checklist

1. Time Conversion

# Local → UTC (apply timezone + DST)
# UTC → Julian Day
jd_ut = swe_utc_to_jd(year, month, day, hour, min, sec, SE_GREG_CAL)
# Returns: dret[0]=JD_TT, dret[1]=JD_UT

2. Planetary Positions

# For each body: Sun(0), Moon(1), Mercury(2)... Pluto(9), Node(10/11), Chiron(12), Lilith(15)
ret, xx = swe_calc_ut(jd_ut, planet_id, SEFLG_SWIEPH)
# xx[0]=longitude, xx[1]=latitude, xx[2]=distance, xx[3]=speed (retrograde if < 0)

3. Houses

# Requires: jd_ut, latitude, longitude, house_system
cusps, ascmc = swe_houses(jd_ut, lat, lon, hsys)
# cusps[1..12] = house cusps, ascmc[0]=Ascendant, ascmc[1]=MC

4. House Assignment

house = swe_house_pos(armc, lat, obliquity, hsys, [lon, lat])

5. Aspects

Compute angular distance between each planet pair. Aspect is valid if |distance - aspect_angle| <= orb.

Aspect	Angle	Default orb
Conjunction	0°	8°
Opposition	180°	7°
Trine	120°	6°
Square	90°	6°
Sextile	60°	4°

6. Sidereal (Optional)

swe_set_sid_mode(ayanamsha_type)  # e.g. SE_SIDM_LAHIRI
# Then swe_calc_ut returns sidereal positions
# Or: sidereal_lon = tropical_lon - swe_get_ayanamsa_ut(jd_ut)

---

Output Format

Present results as:

1. Planet table: Planet | Sign | Degree | House | Retrograde
2. House cusps: ASC, MC, and houses 1–12
3. Aspects list: Planet A – Aspect – Planet B (orb)
4. Special points: Part of Fortune, Vertex, Nodes, Lilith (if enabled)

---

Key Constants

• Planet IDs: Sun=0, Moon=1, Mercury=2, Venus=3, Mars=4, Jupiter=5, Saturn=6, Uranus=7, Neptune=8, Pluto=9, MeanNode=10, TrueNode=11, Chiron=12, MeanLilith=15
• House systems: P=Placidus, K=Koch, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign
• Zodiac signs: 0°=Aries, 30°=Taurus, 60°=Gemini... 330°=Pisces

---

Part of Fortune

Diurnal (Sun above horizon): Fortune = ASC + Moon - Sun
Nocturnal (Sun below horizon): Fortune = ASC + Sun - Moon

---

Error Handling

• Unknown birth time: Compute chart without houses; use noon or offer "chart for date only"
• Invalid coordinates: Reject or use fallback (e.g. capital city)
• Polar latitudes: Placidus fails; suggest Equal or Whole Sign
• Date out of range: Swiss Ephemeris covers ~13,000 years; validate 1800–2100 for typical use

---

Dependencies

• Python: pyswisseph + ephemeris files (download from astro.com)
• Node.js: swisseph or astronomia
• R: swephR

Set ephemeris path: swe_set_ephe_path("/path/to/ephe")

---

Reference & Examples

• Full API specs, formulas, ayanamshas: reference.md
• User flows, response formats, edge cases: examples.md