kerykeion 5.0.0a12__py3-none-any.whl → 5.0.0b1__py3-none-any.whl

{kerykeion-5.0.0a12.dist-info → kerykeion-5.0.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kerykeion
-Version: 5.0.0a12
+Version: 5.0.0b1
 Summary: A Python library for astrological calculations, including natal charts, houses, planetary aspects, and SVG chart generation.
 Project-URL: Homepage, https://www.kerykeion.net/
 Project-URL: Repository, https://github.com/g-battaglia/kerykeion
@@ -108,7 +108,9 @@ If you're looking for the latest stable version, please check out the [`master`]
   - [Minified SVG](#minified-svg)
   - [SVG without CSS Variables](#svg-without-css-variables)
   - [Grid Only SVG](#grid-only-svg)
-- [Report](#report)
+- [Report Generator](#report-generator)
+  - [Quick Examples](#quick-examples)
+  - [Section Access](#section-access)
 - [Example: Retrieving Aspects](#example-retrieving-aspects)
 - [Ayanamsa (Sidereal Modes)](#ayanamsa-sidereal-modes)
 - [House Systems](#house-systems)
@@ -119,6 +121,24 @@ If you're looking for the latest stable version, please check out the [`master`]
 - [JSON Support](#json-support)
 - [Auto Generated Documentation](#auto-generated-documentation)
 - [Development](#development)
+- [Kerykeion v5.0 – What's New](#kerykeion-v50--whats-new)
+  - [🎯 Key Highlights](#-key-highlights)
+    - [Factory-Centered Architecture](#factory-centered-architecture)
+    - [Pydantic 2 Models \& Type Safety](#pydantic-2-models--type-safety)
+    - [Enhanced Features](#enhanced-features)
+  - [🚨 Breaking Changes](#-breaking-changes)
+    - [1. Removed Legacy Classes](#1-removed-legacy-classes)
+    - [2. Import Changes](#2-import-changes)
+    - [3. Lunar Nodes Naming](#3-lunar-nodes-naming)
+    - [4. Chart Generation Changes](#4-chart-generation-changes)
+    - [5. Aspects API Changes](#5-aspects-api-changes)
+  - [🔄 Migration Guide](#-migration-guide)
+    - [Using the Backward Compatibility Layer](#using-the-backward-compatibility-layer)
+    - [Step-by-Step Migration](#step-by-step-migration)
+    - [Automated Migration Script](#automated-migration-script)
+  - [📦 Other Notable Changes](#-other-notable-changes)
+  - [🎨 New Themes](#-new-themes)
+  - [📚 Resources](#-resources)
 - [Integrating Kerykeion into Your Project](#integrating-kerykeion-into-your-project)
 - [License](#license)
 - [Contributing](#contributing)
@@ -170,7 +190,7 @@ john = AstrologicalSubjectFactory.from_birth_data(
 
 ## Generate a SVG Chart
 
-To generate a chart, use the `KerykeionChartSVG` class. You can create various types of charts, including birth, synastry, transit, and composite charts.
+To generate a chart, use the `ChartDataFactory` to pre-compute chart data, then `ChartDrawer` to create the visualization. This two-step process ensures clean separation between astrological calculations and chart rendering.
 
 **Tip:** 
 The optimized way to open the generated SVG files is with a web browser (e.g., Chrome, Firefox).
@@ -179,11 +199,19 @@ To improve compatibility across different applications, you can use the `remove_
 ### Birth Chart
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subject
 john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(john)
-birth_chart_svg.makeSVG()
+
+# Step 2: Pre-compute chart data
+chart_data = ChartDataFactory.create_natal_chart_data(john)
+
+# Step 3: Create visualization
+birth_chart_svg = ChartDrawer(chart_data=chart_data)
+birth_chart_svg.save_svg()
 ```
 
 The SVG file will be saved in the home directory.
@@ -192,23 +220,39 @@ The SVG file will be saved in the home directory.
 ### External Birth Chart
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create subject
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(birth_chart, chart_type="ExternalNatal")
-birth_chart_svg.makeSVG()
+
+# Step 2: Pre-compute chart data for external natal chart
+chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+
+# Step 3: Create visualization
+birth_chart_svg = ChartDrawer(chart_data=chart_data)
+birth_chart_svg.save_svg()
 ```
 ![John Lennon External Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/master/tests/charts/svg/John%20Lennon%20-%20ExternalNatal%20Chart.svg)
 
 ### Synastry Chart
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subjects
 first = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
-synastry_chart = KerykeionChartSVG(first, "Synastry", second)
-synastry_chart.makeSVG()
+# Step 2: Pre-compute synastry chart data
+chart_data = ChartDataFactory.create_synastry_chart_data(first, second)
+
+# Step 3: Create visualization
+synastry_chart = ChartDrawer(chart_data=chart_data)
+synastry_chart.save_svg()
 ```
 
 ![John Lennon and Paul McCartney Synastry](https://www.kerykeion.net/img/examples/synastry-chart.svg)
@@ -217,13 +261,20 @@ synastry_chart.makeSVG()
 ### Transit Chart
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subjects
 transit = AstrologicalSubjectFactory.from_birth_data("Transit", 2025, 6, 8, 8, 45, "Atlanta", "US")
 subject = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 
-transit_chart = KerykeionChartSVG(subject, "Transit", transit)
-transit_chart.makeSVG()
+# Step 2: Pre-compute transit chart data
+chart_data = ChartDataFactory.create_transit_chart_data(subject, transit)
+
+# Step 3: Create visualization
+transit_chart = ChartDrawer(chart_data=chart_data)
+transit_chart.save_svg()
 ```
 
 ![John Lennon Transit Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/master/tests/charts/svg/John%20Lennon%20-%20Transit%20Chart.svg)
@@ -231,17 +282,25 @@ transit_chart.makeSVG()
 ### Composite Chart
 
 ```python
-from kerykeion import CompositeSubjectFactory, AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import CompositeSubjectFactory, AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subjects
 angelina = AstrologicalSubjectFactory.from_birth_data("Angelina Jolie", 1975, 6, 4, 9, 9, "Los Angeles", "US", lng=-118.15, lat=34.03, tz_str="America/Los_Angeles")
 
 brad = AstrologicalSubjectFactory.from_birth_data("Brad Pitt", 1963, 12, 18, 6, 31, "Shawnee", "US", lng=-96.56, lat=35.20, tz_str="America/Chicago")
 
+# Step 2: Create composite subject
 factory = CompositeSubjectFactory(angelina, brad)
 composite_model = factory.get_midpoint_composite_subject_model()
 
-composite_chart = KerykeionChartSVG(composite_model, "Composite")
-composite_chart.makeSVG()
+# Step 3: Pre-compute composite chart data
+chart_data = ChartDataFactory.create_composite_chart_data(composite_model)
+
+# Step 4: Create visualization
+composite_chart = ChartDrawer(chart_data=chart_data)
+composite_chart.save_svg()
 ```
 
 ![Angelina Jolie and Brad Pitt Composite Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/master/tests/charts/svg/Angelina%20Jolie%20and%20Brad%20Pitt%20Composite%20Chart%20-%20Composite%20Chart.svg)
@@ -252,21 +311,38 @@ For *all* the charts, you can generate a wheel-only chart by using the method `m
 
 ### Birth Chart
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subject
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(birth_chart)
-birth_chart_svg.makeWheelOnlySVG()
+
+# Step 2: Pre-compute chart data
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
+
+# Step 3: Create visualization
+birth_chart_svg = ChartDrawer(chart_data=chart_data)
+birth_chart_svg.save_wheel_only_svg_file()
 ```
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/master/tests/charts/svg/John%20Lennon%20-%20Wheel%20Only%20-%20Natal%20Chart%20-%20Wheel%20Only.svg)
 
 ### Wheel Only Birth Chart (External)
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create subject
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(birth_chart, chart_type="ExternalNatal")
-birth_chart_svg.makeWheelOnlySVG(
+
+# Step 2: Pre-compute external natal chart data
+chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+
+# Step 3: Create visualization
+birth_chart_svg = ChartDrawer(chart_data=chart_data)
+birth_chart_svg.save_wheel_only_svg_file(
     wheel_only=True,
     wheel_only_external=True
 )
@@ -276,47 +352,66 @@ birth_chart_svg.makeWheelOnlySVG(
 
 ### Synastry Chart
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create subjects
 first = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
-synastry_chart = KerykeionChartSVG(
-    first, "Synastry", second
-)
-synastry_chart.makeWheelOnlySVG()
+
+# Step 2: Pre-compute synastry chart data
+chart_data = ChartDataFactory.create_synastry_chart_data(first, second)
+
+# Step 3: Create visualization
+synastry_chart = ChartDrawer(chart_data=chart_data)
+synastry_chart.save_wheel_only_svg_file()
 ```
 
 ![John Lennon and Paul McCartney Synastry](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/master/tests/charts/svg/John%20Lennon%20-%20Wheel%20Synastry%20Only%20-%20Synastry%20Chart%20-%20Wheel%20Only.svg)
 
 ### Change the Output Directory
 
-To save the SVG file in a custom location, specify `new_output_directory`:
+To save the SVG file in a custom location, specify the `output_path` parameter in `save_svg()`:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subjects
 first = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
 
-synastry_chart = KerykeionChartSVG(
-    first, "Synastry", second,
-    new_output_directory="."
-)
-synastry_chart.makeSVG()
+# Step 2: Pre-compute synastry chart data
+chart_data = ChartDataFactory.create_synastry_chart_data(first, second)
+
+# Step 3: Create visualization with custom output directory
+synastry_chart = ChartDrawer(chart_data=chart_data)
+synastry_chart.save_svg(output_path=".")
 ```
 
 ### Change Language
 
-You can switch chart language by passing `chart_language` to the  `KerykeionChartSVG` class:
+You can switch chart language by passing `chart_language` to the  `ChartDrawer` class:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subject
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(
-    birth_chart,
+
+# Step 2: Pre-compute chart data
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
+
+# Step 3: Create visualization with Italian language
+birth_chart_svg = ChartDrawer(
+    chart_data=chart_data,
     chart_language="IT"  # Change to Italian
 )
-birth_chart_svg.makeSVG()
+birth_chart_svg.save_svg()
 ```
 
 More details [here](https://www.kerykeion.net/docs/chart-language).
@@ -337,10 +432,19 @@ The available languages are:
 To generate a minified SVG, set `minify_svg=True` in the `makeSVG()` method:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create subject
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(birth_chart)
-birth_chart_svg.makeSVG(
+
+# Step 2: Pre-compute chart data
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
+
+# Step 3: Create visualization
+birth_chart_svg = ChartDrawer(chart_data=chart_data)
+birth_chart_svg.save_svg(
     minify=True
 )
 ```
@@ -349,11 +453,19 @@ birth_chart_svg.makeSVG(
 To generate an SVG without CSS variables, set `remove_css_variables=True` in the `makeSVG()` method:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subject
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-birth_chart_svg = KerykeionChartSVG(birth_chart)
-birth_chart_svg.makeSVG(
+
+# Step 2: Pre-compute chart data
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
+
+# Step 3: Create visualization
+birth_chart_svg = ChartDrawer(chart_data=chart_data)
+birth_chart_svg.save_svg(
     remove_css_variables=True
 )
 ```
@@ -362,83 +474,77 @@ This will inline all styles and eliminate CSS variables, resulting in an SVG tha
 
 ### Grid Only SVG
 
-It's possible to generate a grid-only SVG, useful for creating a custom layout. To do this, use the `makeAspectGridOnlySVG()` method:
+It's possible to generate a grid-only SVG, useful for creating a custom layout. To do this, use the `save_aspect_grid_only_svg_file()` method:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create subjects
 birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
-aspect_grid_chart = KerykeionChartSVG(birth_chart, "Synastry", second, theme="dark")
-aspect_grid_chart.makeAspectGridOnlySVG()
+
+# Step 2: Pre-compute synastry chart data
+chart_data = ChartDataFactory.create_synastry_chart_data(birth_chart, second)
+
+# Step 3: Create visualization with dark theme
+aspect_grid_chart = ChartDrawer(chart_data=chart_data, theme="dark")
+aspect_grid_chart.save_aspect_grid_only_svg_file()
 ```
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/master/tests/charts/svg/John%20Lennon%20-%20Aspect%20Grid%20Only%20-%20Natal%20Chart%20-%20Aspect%20Grid%20Only.svg)
 
-## Report
+## Report Generator
+
+`ReportGenerator` mirrors the chart-type dispatch of `ChartDrawer`. It accepts raw `AstrologicalSubjectModel` instances as well as any `ChartDataModel` produced by `ChartDataFactory`—including natal, composite, synastry, transit, and planetary return charts—and renders the appropriate textual report automatically.
+
+### Quick Examples
 
 ```python
-from kerykeion import Report, AstrologicalSubjectFactory
+from kerykeion import ReportGenerator, AstrologicalSubjectFactory, ChartDataFactory
 
-john = AstrologicalSubjectFactory.from_birth_data(
-    "John Lennon", 1940, 10, 9, 18, 30,
-    lng=-2.9833,  # Longitude for Liverpool
-    lat=53.4000,  # Latitude for Liverpool
-    tz_str="Europe/London",  # Timezone for Liverpool
-    city="Liverpool",
+# Subject-only report
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "Sample Natal", 1990, 7, 21, 14, 45, "Rome", "IT"
 )
-report = Report(john)
-report.print_report()
-```
-
-Report output:
-```plaintext
-+- Kerykeion report for John Lennon -+
-+-----------+-------+---------------+-----------+----------+
-| Date      | Time  | Location      | Longitude | Latitude |
-+-----------+-------+---------------+-----------+----------+
-| 9/10/1940 | 18:30 | Liverpool, GB | -2.9833   | 53.4     |
-+-----------+-------+---------------+-----------+----------+
-+-------------------+------+-------+------+----------------+
-| AstrologicalPoint | Sign | Pos.  | Ret. | House          |
-+-------------------+------+-------+------+----------------+
-| Sun               | Lib  | 16.27 | -    | Sixth_House    |
-| Moon              | Aqu  | 3.55  | -    | Eleventh_House |
-| Mercury           | Sco  | 8.56  | -    | Seventh_House  |
-| Venus             | Vir  | 3.22  | -    | Sixth_House    |
-| Mars              | Lib  | 2.66  | -    | Sixth_House    |
-| Jupiter           | Tau  | 13.69 | R    | First_House    |
-| Saturn            | Tau  | 13.22 | R    | First_House    |
-| Uranus            | Tau  | 25.55 | R    | First_House    |
-| Neptune           | Vir  | 26.03 | -    | Sixth_House    |
-| Pluto             | Leo  | 4.19  | -    | Fifth_House    |
-| Mean_Node         | Lib  | 10.58 | R    | Sixth_House    |
-| Mean_South_Node   | Ari  | 10.58 | R    | Twelfth_House  |
-| Mean_Lilith       | Ari  | 13.37 | -    | Twelfth_House  |
-| Chiron            | Leo  | 0.57  | -    | Fifth_House    |
-+-------------------+------+-------+------+----------------+
-+----------------+------+----------+
-| House          | Sign | Position |
-+----------------+------+----------+
-| First_House    | Ari  | 19.72    |
-| Second_House   | Tau  | 29.52    |
-| Third_House    | Gem  | 20.23    |
-| Fourth_House   | Can  | 7.07     |
-| Fifth_House    | Can  | 25.31    |
-| Sixth_House    | Leo  | 22.11    |
-| Seventh_House  | Lib  | 19.72    |
-| Eighth_House   | Sco  | 29.52    |
-| Ninth_House    | Sag  | 20.23    |
-| Tenth_House    | Cap  | 7.07     |
-| Eleventh_House | Cap  | 25.31    |
-| Twelfth_House  | Aqu  | 22.11    |
-+----------------+------+----------+
-```
-
-To export to a file:
+ReportGenerator(subject).print_report(include_aspects=False)
 
-```bash
-python3 your_script_name.py > file.txt
+# Single-chart data (elements, qualities, aspects enabled)
+natal_data = ChartDataFactory.create_natal_chart_data(subject)
+ReportGenerator(natal_data).print_report(max_aspects=10)
+
+# Dual-chart data (synastry, transit, dual return, …)
+partner = AstrologicalSubjectFactory.from_birth_data(
+    "Sample Partner", 1992, 11, 5, 9, 30, "Rome", "IT"
+)
+synastry_data = ChartDataFactory.create_synastry_chart_data(subject, partner)
+ReportGenerator(synastry_data).print_report(max_aspects=12)
+```
+
+Each report contains:
+- A chart-aware title summarising the subject(s) and chart type
+- Birth/event metadata and configuration settings
+- Celestial points with sign, position, **daily motion**, **declination**, retrograde flag, and house
+- House cusp tables for every subject involved
+- Lunar phase details when available
+- Element/quality distributions and active configuration summaries (for chart data)
+- Aspect listings tailored for single or dual charts, with symbols for type and movement
+- Dual-chart extras such as house comparisons and relationship scores (when provided by the data)
+
+### Section Access
+
+All section helpers remain available for targeted output:
+
+```python
+report = ReportGenerator(natal_data)
+print(report.get_subject_data_report())
+print(report.get_celestial_points_report())
+print(report.get_elements_report())
+print(report.get_aspects_report(max_aspects=5))
 ```
 
+Refer to the refreshed [Report Documentation](https://www.kerykeion.net/report/) for end-to-end examples covering every supported chart model.
+
 ## Example: Retrieving Aspects
 
 Kerykeion provides a unified `AspectsFactory` class for calculating astrological aspects within single charts or between two charts:
@@ -499,7 +605,7 @@ johnny = AstrologicalSubjectFactory.from_birth_data(
 
 More examples [here](https://www.kerykeion.net/docs//sidereal-modes/).
 
-Full list of supported sidereal modes [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#SiderealMode).
+Full list of supported sidereal modes [here](https://www.kerykeion.net/pydocs/kerykeion/schemas/kr_literals.html#SiderealMode).
 
 ## House Systems
 
@@ -515,7 +621,7 @@ johnny = AstrologicalSubjectFactory.from_birth_data(
 
 More examples [here](https://www.kerykeion.net/docs//houses-systems/).
 
-Full list of supported house systems [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#HousesSystem).
+Full list of supported house systems [here](https://www.kerykeion.net/pydocs/kerykeion/schemas/kr_literals.html#HousesSystem).
 
 So far all the available houses system in the Swiss Ephemeris are supported but the Gauquelin Sectors.
 
@@ -533,7 +639,7 @@ johnny = AstrologicalSubjectFactory.from_birth_data(
 
 More examples [here](https://www.kerykeion.net/docs//perspective-type/).
 
-Full list of supported perspective types [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#PerspectiveType).
+Full list of supported perspective types [here](https://www.kerykeion.net/pydocs/kerykeion/schemas/kr_literals.html#PerspectiveType).
 
 ## Themes
 
@@ -549,11 +655,19 @@ Each theme offers a distinct visual style, allowing you to choose the one that b
 Here's an example of how to set the theme:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subject
 dark_theme_subject = AstrologicalSubjectFactory.from_birth_data("John Lennon - Dark Theme", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-dark_theme_natal_chart = KerykeionChartSVG(dark_theme_subject, theme="dark_high_contrast")
-dark_theme_natal_chart.makeSVG()
+
+# Step 2: Pre-compute chart data
+chart_data = ChartDataFactory.create_natal_chart_data(dark_theme_subject)
+
+# Step 3: Create visualization with dark high contrast theme
+dark_theme_natal_chart = ChartDrawer(chart_data=chart_data, theme="dark_high_contrast")
+dark_theme_natal_chart.save_svg()
 ```
 
 ![John Lennon](https://www.kerykeion.net/img/showcase/John%20Lennon%20-%20Dark%20-%20Natal%20Chart.svg)
@@ -587,16 +701,20 @@ Kerykeion supports both **True** and **Mean** Lunar Nodes:
 - **Mean North Lunar Node**: `"mean_node"` (name kept without "north" for backward compatibility).
 - **Mean South Lunar Node**: `"mean_south_node"`.
 
-In instances of the classes used to generate aspects and SVG charts, only the mean nodes are active. To activate the true nodes, you need to pass the `active_points` parameter to the `KerykeionChartSVG` class.
+In instances of the classes used to generate aspects and SVG charts, only the mean nodes are active. To activate the true nodes, you need to pass the `active_points` parameter to the `ChartDataFactory` methods.
 
 Example:
 
 ```python
-from kerykeion import AstrologicalSubjectFactory, KerykeionChartSVG
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
 
+# Step 1: Create subject
 subject = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
 
-chart = KerykeionChartSVG(
+# Step 2: Pre-compute chart data with custom active points including true nodes
+chart_data = ChartDataFactory.create_natal_chart_data(
     subject,
     active_points=[
         "Sun", 
@@ -619,7 +737,10 @@ chart = KerykeionChartSVG(
         "Imum_Coeli"
     ]
 )
-chart.makeSVG()
+
+# Step 3: Create visualization
+chart = ChartDrawer(chart_data=chart_data)
+chart.save_svg()
 ```
 
 ## JSON Support
@@ -642,6 +763,272 @@ You can find auto-generated documentation [here](https://www.kerykeion.net/pydoc
 
 Clone the repository or download the ZIP via the GitHub interface.
 
+## Kerykeion v5.0 – What's New
+
+Kerykeion v5 is a **complete redesign** that modernizes the library with a data-first approach, factory-based architecture, and Pydantic 2 models. This version brings significant improvements in API design, type safety, and extensibility.
+
+### 🎯 Key Highlights
+
+#### Factory-Centered Architecture
+The old class-based approach has been replaced with a modern factory pattern:
+
+- **`AstrologicalSubjectFactory`**: Replaces the old `AstrologicalSubject` class
+- **`ChartDataFactory`**: Pre-computes enriched chart data (elements, qualities, aspects)
+- **`ChartDrawer`**: Pure SVG rendering separated from calculations
+- **`AspectsFactory`**: Unified aspects calculation for natal and synastry charts
+- **`PlanetaryReturnFactory`**: Solar and Lunar returns computation
+- **`HouseComparisonFactory`**: House overlay analysis for synastry
+- **`RelationshipScoreFactory`**: Compatibility scoring between charts
+
+**Old v4 API:**
+```python
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
+
+# v4 - Class-based approach
+subject = AstrologicalSubject("John", 1990, 1, 1, 12, 0, "London", "GB")
+chart = KerykeionChartSVG(subject)
+chart.makeSVG()
+```
+
+**New v5 API:**
+```python
+from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
+
+# v5 - Factory-based approach with separation of concerns
+subject = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
+chart_data = ChartDataFactory.create_natal_chart_data(subject)
+drawer = ChartDrawer(chart_data=chart_data)
+drawer.save_svg()
+```
+
+#### Pydantic 2 Models & Type Safety
+All data structures are now strongly typed Pydantic models:
+
+- **`AstrologicalSubjectModel`**: Subject data with full validation
+- **`ChartDataModel`**: Enriched chart data with elements, qualities, aspects
+- **`SingleChartAspectsModel` / `DualChartAspectsModel`**: Typed aspect collections
+- **`PlanetReturnModel`**: Planetary return data
+- **`ElementDistributionModel`**: Element statistics (fire, earth, air, water)
+- **`QualityDistributionModel`**: Quality statistics (cardinal, fixed, mutable)
+
+All models support:
+- JSON serialization/deserialization
+- Dictionary export
+- Subscript access
+- Full IDE autocomplete and type checking
+
+#### Enhanced Features
+- **Speed & Declination**: All celestial points now include daily motion speed and declination
+- **Element & Quality Analysis**: Automatic calculation of element/quality distributions
+- **Relationship Scoring**: Built-in compatibility analysis for synastry
+- **House Comparison**: Detailed house overlay analysis
+- **Transit Time Ranges**: Advanced transit tracking over time periods
+- **Report Module**: Comprehensive text reports with ASCII tables
+
+### 🚨 Breaking Changes
+
+#### 1. Removed Legacy Classes
+The following classes have been **completely removed** and must be replaced:
+
+| Removed (v4) | Replacement (v5) |
+|--------------|------------------|
+| `AstrologicalSubject` | `AstrologicalSubjectFactory.from_birth_data()` |
+| `KerykeionChartSVG` | `ChartDrawer` + `ChartDataFactory` |
+| `NatalAspects` | `AspectsFactory.single_chart_aspects()` |
+| `SynastryAspects` | `AspectsFactory.dual_chart_aspects()` |
+| `relationship_score()` | `RelationshipScoreFactory` |
+
+**Note**: The `kerykeion.backword` module provides temporary wrappers for `AstrologicalSubject` and `KerykeionChartSVG` with deprecation warnings. These will be **removed in v6.0**.
+
+#### 2. Import Changes
+Module structure has been completely reorganized:
+
+**Old imports (v4):**
+```python
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
+from kerykeion.kr_types import KerykeionException
+```
+
+**New imports (v5):**
+```python
+from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
+from kerykeion.schemas.kerykeion_exception import KerykeionException
+```
+
+#### 3. Lunar Nodes Naming
+All lunar node fields have been renamed for clarity:
+
+| Old Name (v4) | New Name (v5) |
+|---------------|---------------|
+| `Mean_Node` | `Mean_North_Lunar_Node` |
+| `True_Node` | `True_North_Lunar_Node` |
+| `Mean_South_Node` | `Mean_South_Lunar_Node` |
+| `True_South_Node` | `True_South_Lunar_Node` |
+
+**Migration example:**
+```python
+# v4
+print(subject.mean_node)
+
+# v5
+print(subject.mean_north_lunar_node)
+```
+
+#### 4. Chart Generation Changes
+The two-step process (data + rendering) is now required:
+
+**Old v4:**
+```python
+chart = KerykeionChartSVG(subject)
+chart.makeSVG()
+```
+
+**New v5:**
+```python
+chart_data = ChartDataFactory.create_natal_chart_data(subject)
+drawer = ChartDrawer(chart_data=chart_data)
+drawer.save_svg()
+```
+
+#### 5. Aspects API Changes
+Aspects are now calculated through the factory:
+
+**Old v4:**
+```python
+from kerykeion import NatalAspects, SynastryAspects
+
+natal_aspects = NatalAspects(subject)
+synastry_aspects = SynastryAspects(subject1, subject2)
+```
+
+**New v5:**
+```python
+from kerykeion import AspectsFactory
+
+natal_aspects = AspectsFactory.single_chart_aspects(subject)
+synastry_aspects = AspectsFactory.dual_chart_aspects(subject1, subject2)
+```
+
+### 🔄 Migration Guide
+
+#### Using the Backward Compatibility Layer
+
+For a gradual migration, use the `kerykeion.backword` module:
+
+```python
+from kerykeion import AstrologicalSubject  # Legacy wrapper
+
+subject = AstrologicalSubject("John Doe", 1990, 1, 1, 12, 0, "London", "GB")
+
+# These still work but show DeprecationWarnings
+print(subject.mean_node)  # Maps to mean_north_lunar_node
+print(subject.true_node)  # Maps to true_north_lunar_node
+```
+
+**⚠️ Warning**: This compatibility layer will be **removed in v6.0**.
+
+#### Step-by-Step Migration
+
+1. **Update imports**
+   ```python
+   # Old
+   from kerykeion import AstrologicalSubject, KerykeionChartSVG
+   
+   # New
+   from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
+   ```
+
+2. **Update subject creation**
+   ```python
+   # Old
+   subject = AstrologicalSubject("John", 1990, 1, 1, 12, 0, "London", "GB")
+   
+   # New
+   subject = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
+   ```
+
+3. **Update chart generation**
+   ```python
+   # Old
+   chart = KerykeionChartSVG(subject)
+   chart.makeSVG()
+   
+   # New
+   chart_data = ChartDataFactory.create_natal_chart_data(subject)
+   drawer = ChartDrawer(chart_data=chart_data)
+   drawer.save_svg()
+   ```
+
+4. **Update field access** (lunar nodes)
+   ```python
+   # Old
+   print(subject.mean_node.position)
+   
+   # New
+   print(subject.mean_north_lunar_node.position)
+   ```
+
+5. **Update aspects**
+   ```python
+   # Old
+   from kerykeion import NatalAspects
+   aspects = NatalAspects(subject)
+   
+   # New
+   from kerykeion import AspectsFactory
+   aspects = AspectsFactory.single_chart_aspects(subject)
+   ```
+
+#### Automated Migration Script
+
+Use this sed script to update Python files automatically:
+
+```bash
+# Update lunar node references
+find . -name "*.py" -type f -exec sed -i.bak \
+    -e 's/\.mean_node/.mean_north_lunar_node/g' \
+    -e 's/\.true_node/.true_north_lunar_node/g' \
+    -e 's/\.mean_south_node/.mean_south_lunar_node/g' \
+    -e 's/\.true_south_node/.true_south_lunar_node/g' \
+    -e 's/"Mean_Node"/"Mean_North_Lunar_Node"/g' \
+    -e 's/"True_Node"/"True_North_Lunar_Node"/g' \
+    -e 's/"Mean_South_Node"/"Mean_South_Lunar_Node"/g' \
+    -e 's/"True_South_Node"/"True_South_Lunar_Node"/g' \
+    {} \;
+```
+
+**Note**: Always review automated changes and test thoroughly before committing.
+
+### 📦 Other Notable Changes
+
+- **Packaging**: Migrated from Poetry to PEP 621 + Hatchling with `uv.lock`
+- **Settings**: Centralized in `kerykeion.schemas` and `kerykeion.settings`
+- **Configuration**: Legacy presets available in `settings/legacy/`
+- **Type System**: All literals consolidated in `kr_literals.py`
+- **Performance**: Caching improvements with `functools.lru_cache`
+- **Testing**: 376 tests with 87% coverage, regenerated fixtures for v5
+
+### 🎨 New Themes
+
+Additional chart themes added:
+- `classic` (default)
+- `dark`
+- `dark_high_contrast`
+- `light`
+- `strawberry`
+
+### 📚 Resources
+
+- **Full Release Notes**: [v5.0.0.md](release_notes/v5.0.0b1.md)
+- **Documentation**: [kerykeion.readthedocs.io](https://kerykeion.readthedocs.io)
+- **API Reference**: [kerykeion.net/pydocs](https://www.kerykeion.net/pydocs/kerykeion.html)
+- **Examples**: See the `examples/` folder for runnable code
+- **Support**: [GitHub Discussions](https://github.com/g-battaglia/kerykeion/discussions)
+
+**Migration Timeline:**
+- **v5.0**: Current - Backward compatibility layer available
+- **v6.0**: Future - Compatibility layer will be removed
+
 ## Integrating Kerykeion into Your Project
 
 If you would like to incorporate Kerykeion's astrological features into your application, please reach out via [email](mailto:kerykeion.astrology@gmail.com?subject=Integration%20Request). Whether you need custom features, support, or specialized consulting, I am happy to discuss potential collaborations.