Astro Daily Transits

SKILL.md

---
name: astro-daily-transits
version: 1.0.0
Daily astrological transit forecast over natal chart using Swiss Ephemeris (pyswisseph) + Pillow. Calculates transit positions, aspects to natal chart, house activations, and renders a 3-column chart (natal wheel + transit wheel + forecast panel). Bilingual (RU/EN). Windows 10/11 compatible with bundled .pyd.dat binary. Accuracy ensured by Swiss Ephemeris (JPL DE431 ephemerides, ~0.003° precision). Requires: Python 3.14.x, Pillow 12.x, MSVC++ Redist 2015-2022. Related: astro-natal-chart skill for natal chart calculation.
metadata:
  openclaw:
    requires:
      bins:
        - python3
    emoji: "🌞"
    homepage: https://github.com/dynamicsAlex/astro-daily-transits
---

# Astrology — Daily Transit Forecast

## Engine: Swiss Ephemeris (pyswisseph 2.10.3.2) + Pillow (PIL)

This skill calculates **daily transits** over a natal chart and generates an astrological forecast for any given day. It renders a composite 3-column chart showing the natal wheel, transit wheel with aspect lines, and a textual forecast panel.

## ⚠️ Requirements

| Requirement | Details |
|---|---| 
| **OS** | Windows (x64) |
| **Python** | **3.14.x** |
| **Runtime** | **Microsoft Visual C++ Redistributable 2015–2022 (x64)** |
| **Pillow** | **12.x** — `pip install pillow` |
| **Swiss Ephemeris** | Bundled as `swisseph.cp314-win_amd64.pyd.dat` |

---

## Architecture

```
daily_transits.py --json  →  JSON data (natal + transits + aspects)  →  draw_daily.py  →  PNG image
         ↕
   daily_transits.py  →  text forecast output
```

`daily_transits.py` is the **sole calculation engine**. `draw_daily.py` renders the chart by calling it via subprocess.

---

## How Daily Transits Work

### Step 1: Natal Chart → Fixed Foundation
The natal chart is the birth snapshot — positions of planets at the moment of birth. This never changes.

### Step 2: Transit Positions → Moving Planets Today
Transit positions are where the planets are **right now** (or on any target date). These change constantly.

### Step 3: Aspects Between Transits and Natal
When a transit planet forms an angle (aspect) with a natal planet, it activates that natal planet's energy:

| Aspect | Symbol | Meaning |
|---|---|---|
| Conjunction | ☌ | Fusion of energies — powerful, direct impact |
| Opposition | ☍ | Tension, confrontation, awareness through contrast |
| Trine | △ | Harmony, flow, luck — energy works naturally |
| Square | □ | Challenge, friction — crisis that mobilizes |
| Sextile | ✶ | Opportunity — potential that needs action |
| Semisextile | ⚺ | Subtle influence, minor adjustments |
| Semisquare | ∠ | Irritation, minor tension |
| Quincunx | ⚹ | Adjustment needed, discomfort |

### Step 4: House Activation
Transit planets falling in specific natal houses show **which life areas** are activated:

| House | Life Area |
|---|---|
| I | Personality, appearance, self |
| II | Money, values, resources |
| III | Communication, siblings, learning |
| IV | Home, family, roots |
| V | Creativity, children, romance |
| VI | Health, work, routine |
| VII | Partnership, marriage |
| VIII | Transformation, shared resources |
| IX | Philosophy, travel, higher education |
| X | Career, reputation, public life |
| XI | Friends, groups, hopes |
| XII | Subconscious, solitude, karma |

### Step 5: Forecast Generation
The script combines aspects + house activations into a human-readable forecast, prioritizing harmonious aspects (trines, sextiles) and warning about challenging ones (squares, oppositions).

---

## Usage

### Text Forecast (CLI)

```bash
# Forecast for today
python scripts/daily_transits.py 24.04.1983 07:00 Ижевск --lang ru --name "Алексей"

# Forecast for specific date
python scripts/daily_transits.py 24.04.1983 07:00 Ижевск --target-date 04.06.2026 --lang ru

# English output
python scripts/daily_transits.py 24.04.1983 07:00 Ижевск --lang en

# JSON output (for renderers / AI)
python scripts/daily_transits.py 24.04.1983 07:00 Ижевск --json --target-date 04.06.2026
```

### Graphical Chart

```bash
# Chart for today (Russian)
python scripts/draw_daily.py 24.04.1983 07:00 Ижевск --lang ru --name "Алексей"

# Chart for specific date with forecast file
python scripts/draw_daily.py 24.04.1983 07:00 Ижевск --target-date 04.06.2026 --lang ru --name "Алексей" --forecast forecast.txt

# Chart output is saved to workspace/
```

### CLI Arguments

| Argument | Description |
|---|---|
| `date` | Birth date DD.MM.YYYY |
| `time` | Birth time HH:MM |
| `city` | Birth city |
| `--target-date` | Forecast date DD.MM.YYYY (default: today) |
| `--lang` | Language: `ru` or `en` (default: `ru`) |
| `--name` | Person's name for display |
| `--json` | Output JSON instead of text |
| `--forecast` | Path to text file with forecast (for draw_daily.py) |

---

## JSON Output Format

```json
{
  "name": "Алексей",
  "birth_date": "24.04.1983",
  "target_date": "04.06.2026",
  "natal": {
    "Sun": {"lon": 33.38, "speed": 0.974, "retro": false},
    "Moon": {"lon": 172.92, "speed": 14.116, "retro": false},
    ...
  },
  "transits": {
    "Sun": {"lon": 103.5, "speed": 0.955, "retro": false},
    ...
  },
  "transit_houses": {"Sun": 3, "Moon": 7, ...},
  "aspects": [
    {"transit": "Jupiter", "natal": "Sun", "type": "trine", "symbol": "△", "name": "Трин", "nature": "harmonious", "orb": 1.2}
  ]
}
```

---

## Image Layout (5760×2880 px)

```
+------------------+------------------+---------------------------+
|                  |                  |                           |
|   NATAL WHEEL    |  TRANSIT WHEEL   |      FORECAST PANEL       |
|   (2160×2160)    |   (2160×2160)    |      (1440×2880)          |
|                  |                  |                           |
|  - Sign sectors  |  - Natal houses  |  - Date header            |
|  - House cusps   |  - Transit planets|  - Key transits list     |
|  - Natal planets |  - Aspect lines  |  - House activations      |
|  - ASC/MC lines  |  - Retro markers |  - Summary                |
|                  |                  |                           |
+------------------+------------------+---------------------------+
```

---

## Font Handling

Two bundled fonts in `scripts/`:

| Font | Purpose | Extension |
|---|---|---|
| `seguisym.ttf.dat` | Zodiac symbols ♈♉♊... | `.dat` (ClawHub-compatible) |
| `segoeuisl.ttf.dat` | Cyrillic, latin, digits | `.dat` (ClawHub-compatible) |

Both are auto-copied to `.ttf` at runtime for Pillow compatibility.

---

## Scripts Reference

| Script | Purpose | Dependencies |
|---|---|---|
| `scripts/daily_transits.py` | **Sole calculation engine.** Text forecast + JSON export | swisseph, math, json |
| `scripts/draw_daily.py` | **Renderer.** Calls daily_transits.py --json, draws 5760×2880 chart | subprocess, json, math, Pillow |
| `scripts/swisseph.cp314-win_amd64.pyd.dat` | Swiss Ephemeris binary (2 MB) | MSVC++ Redist |
| `scripts/seguisym.ttf.dat` | Zodiac symbol font (2.4 MB) | — |
| `scripts/segoeuisl.ttf.dat` | Cyrillic/latin font (854 KB) | — |

---

## AI Conclusion Workflow (for OpenClaw agents)

```
Step 1: python scripts/daily_transits.py <date> <time> <city> --json --target-date <date>
Step 2: AI analyzes JSON and writes enhanced conclusion to a file
Step 3: python scripts/draw_daily.py <date> <time> <city> --lang ru --name "Name" --forecast <file>
```

---

## Disclaimer

This is an entertainment/educational tool, not a scientific method. Do not make medical or financial decisions based on astrological readings.

---

## Changelog

### v1.0.0 (2026-06-04)
- Initial release
- Daily transit calculation with Swiss Ephemeris
- Aspect detection (8 types) with configurable orbs
- House activation analysis
- Bilingual text forecast (RU/EN)
- 3-column graphical chart (natal + transit + forecast)
- JSON export for AI integration
- Bundled fonts and swisseph as .dat files (ClawHub-compatible)