kerykeion 5.0.2__py3-none-any.whl → 5.1.1__py3-none-any.whl

{kerykeion-5.0.2.dist-info → kerykeion-5.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kerykeion
-Version: 5.0.2
+Version: 5.1.1
 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
@@ -86,6 +86,8 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
 - [**Donate**](#donate)
 - [Table of Contents](#table-of-contents)
 - [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation Map](#documentation-map)
 - [Basic Usage](#basic-usage)
 - [Generate a SVG Chart](#generate-a-svg-chart)
   - [Birth Chart](#birth-chart)
@@ -152,6 +154,48 @@ Kerykeion requires **Python 3.9** or higher.
 pip3 install kerykeion
 ```
 
+## Quick Start
+
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    name="Example Person",
+    year=1990, month=7, day=15,
+    hour=10, minute=30,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
+
+chart_data = ChartDataFactory.create_natal_chart_data(subject)
+chart_drawer = ChartDrawer(chart_data=chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+
+chart_drawer.save_svg(output_path=output_dir, filename="example-natal")
+print("Chart saved to", (output_dir / "example-natal.svg").resolve())
+```
+
+This script shows the recommended workflow:
+1. Create an `AstrologicalSubject` with explicit coordinates and timezone (offline mode).
+2. Build a `ChartDataModel` through `ChartDataFactory`.
+3. Render the SVG via `ChartDrawer`, saving it to a controlled folder (`charts_output`).
+
+Use the same pattern for synastry, composite, transit, or return charts by swapping the factory method.
+
+## Documentation Map
+
+- **README (this file):** Quick start, common recipes, and v5 migration notes.
+- **`site-docs/` (offline Markdown guides):** Deep dives for each factory (`chart_data_factory.md`, `charts.md`, `planetary_return_factory.md`, etc.) with runnable snippets. Run `python scripts/test_markdown_snippets.py site-docs` to validate them locally.
+- **[Auto-generated API Reference](https://www.kerykeion.net/pydocs/kerykeion.html):** Detailed model and function signatures straight from the codebase.
+- **[Kerykeion website](https://www.kerykeion.net/docs/):** Rendered documentation with additional context, tutorials, and showcase material.
+
 ## Basic Usage
 
 Below is a simple example illustrating the creation of an astrological subject and retrieving astrological details:
@@ -161,7 +205,13 @@ from kerykeion import AstrologicalSubjectFactory
 
 # Create an instance of the AstrologicalSubjectFactory class.
 # Arguments: Name, year, month, day, hour, minutes, city, nation
-john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Retrieve information about the Sun:
 print(john.sun.model_dump_json())
@@ -176,6 +226,9 @@ print(john.moon.element)
 # > 'Air'
 ```
 
+> **Working offline:** pass `online=False` and specify `lng`, `lat`, and `tz_str` as shown above.  
+> **Working online:** set `online=True` and provide `city`, `nation`, and a valid GeoNames username (see `AstrologicalSubjectFactory.from_birth_data()` for details).
+
 **To avoid using GeoNames online, specify longitude, latitude, and timezone instead of city and nation:**
 
 ```python
@@ -190,6 +243,8 @@ john = AstrologicalSubjectFactory.from_birth_data(
 
 ## Generate a SVG Chart
 
+All chart-rendering examples below create a local `charts_output/` folder so the tests can write without touching your home directory. Feel free to change the path when integrating into your own projects.
+
 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:**
@@ -199,40 +254,60 @@ To improve compatibility across different applications, you can use the `remove_
 ### Birth Chart
 
 ```python
+from pathlib import Path
 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")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_svg(output_path=output_dir, filename="john-lennon-natal")
 ```
 
-The SVG file will be saved in the home directory.
+The SVG file is saved under `charts_output/john-lennon-natal.svg`.
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Natal%20Chart.svg)
 
 ### External Birth Chart
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data for external natal chart
 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_svg(output_path=output_dir, filename="john-lennon-natal-external")
 ```
 
 ![John Lennon External Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20ExternalNatal%20-%20Natal%20Chart.svg)
@@ -240,20 +315,36 @@ birth_chart_svg.save_svg()
 ### Synastry Chart
 
 ```python
+from pathlib import Path
 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")
+first = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+synastry_chart.save_svg(output_path=output_dir, filename="lennon-mccartney-synastry")
 ```
 
 ![John Lennon and Paul McCartney Synastry](https://www.kerykeion.net/img/examples/synastry-chart.svg)
@@ -261,20 +352,36 @@ synastry_chart.save_svg()
 ### Transit Chart
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "Transit", 2025, 6, 8, 8, 45,
+    lng=-84.3880,
+    lat=33.7490,
+    tz_str="America/New_York",
+    online=False,
+)
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+transit_chart.save_svg(output_path=output_dir, filename="john-lennon-transit")
 ```
 
 ![John Lennon Transit Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Transit%20Chart.svg)
@@ -282,13 +389,20 @@ transit_chart.save_svg()
 ### Solar Return Chart (Dual Wheel)
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.planetary_return_factory import PlanetaryReturnFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create natal subject
-john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Calculate Solar Return subject (offline example with manual coordinates)
 return_factory = PlanetaryReturnFactory(
@@ -305,7 +419,10 @@ chart_data = ChartDataFactory.create_return_chart_data(john, solar_return_subjec
 
 # Step 4: Create visualization
 solar_return_chart = ChartDrawer(chart_data=chart_data)
-solar_return_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+solar_return_chart.save_svg(output_path=output_dir, filename="john-lennon-solar-return-dual")
 ```
 
 ![John Lennon Solar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Solar%20Return.svg)
@@ -313,13 +430,20 @@ solar_return_chart.save_svg()
 ### Solar Return Chart (Single Wheel)
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.planetary_return_factory import PlanetaryReturnFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create natal subject
-john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Calculate Solar Return subject (offline example with manual coordinates)
 return_factory = PlanetaryReturnFactory(
@@ -336,7 +460,10 @@ chart_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return
 
 # Step 4: Create visualization
 single_wheel_chart = ChartDrawer(chart_data=chart_data)
-single_wheel_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+single_wheel_chart.save_svg(output_path=output_dir, filename="john-lennon-solar-return-single")
 ```
 
 ![John Lennon Solar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Solar%20Return%20-%20SingleReturnChart%20Chart.svg)
@@ -344,13 +471,20 @@ single_wheel_chart.save_svg()
 ### Lunar Return Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.planetary_return_factory import PlanetaryReturnFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create natal subject
-john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Calculate Lunar Return subject
 return_factory = PlanetaryReturnFactory(
@@ -365,12 +499,15 @@ lunar_return_subject = return_factory.next_return_from_year(1964, "Lunar")
 # Step 3: Build a dual wheel (natal + lunar return)
 lunar_return_chart_data = ChartDataFactory.create_return_chart_data(john, lunar_return_subject)
 dual_wheel_chart = ChartDrawer(chart_data=lunar_return_chart_data)
-dual_wheel_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+dual_wheel_chart.save_svg(output_path=output_dir, filename="john-lennon-lunar-return-dual")
 
 # Optional: create a single-wheel lunar return
 single_wheel_data = ChartDataFactory.create_single_wheel_return_chart_data(lunar_return_subject)
 single_wheel_chart = ChartDrawer(chart_data=single_wheel_data)
-single_wheel_chart.save_svg()
+single_wheel_chart.save_svg(output_path=output_dir, filename="john-lennon-lunar-return-single")
 ```
 
 ![John Lennon Lunar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Lunar%20Return.svg)
@@ -380,14 +517,27 @@ single_wheel_chart.save_svg()
 ### Composite Chart
 
 ```python
+from pathlib import Path
 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")
+# Step 1: Create subjects (offline configuration)
+angelina = AstrologicalSubjectFactory.from_birth_data(
+    "Angelina Jolie", 1975, 6, 4, 9, 9,
+    lng=-118.2437,
+    lat=34.0522,
+    tz_str="America/Los_Angeles",
+    online=False,
+)
 
-brad = AstrologicalSubjectFactory.from_birth_data("Brad Pitt", 1963, 12, 18, 6, 31, "Shawnee", "US", lng=-96.56, lat=35.20, tz_str="America/Chicago")
+brad = AstrologicalSubjectFactory.from_birth_data(
+    "Brad Pitt", 1963, 12, 18, 6, 31,
+    lng=-96.7069,
+    lat=35.3273,
+    tz_str="America/Chicago",
+    online=False,
+)
 
 # Step 2: Create composite subject
 factory = CompositeSubjectFactory(angelina, brad)
@@ -398,7 +548,10 @@ chart_data = ChartDataFactory.create_composite_chart_data(composite_model)
 
 # Step 4: Create visualization
 composite_chart = ChartDrawer(chart_data=chart_data)
-composite_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+composite_chart.save_svg(output_path=output_dir, filename="jolie-pitt-composite")
 ```
 
 ![Angelina Jolie and Brad Pitt Composite Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/Angelina%20Jolie%20and%20Brad%20Pitt%20Composite%20Chart%20-%20Composite%20Chart.svg)
@@ -410,19 +563,29 @@ For _all_ the charts, you can generate a wheel-only chart by using the method `m
 ### Birth Chart
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_wheel_only_svg_file(output_path=output_dir, filename="john-lennon-natal-wheel")
 ```
 
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Wheel%20Only%20-%20Natal%20Chart%20-%20Wheel%20Only.svg)
@@ -430,22 +593,29 @@ birth_chart_svg.save_wheel_only_svg_file()
 ### Wheel Only Birth Chart (External)
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute external natal 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(
-    wheel_only=True,
-    wheel_only_external=True
-)
+# Step 3: Create visualization (external wheel view)
+birth_chart_svg = ChartDrawer(chart_data=chart_data, external_view=True)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_wheel_only_svg_file(output_path=output_dir, filename="john-lennon-natal-wheel-external")
 ```
 
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Wheel%20External%20Only%20-%20ExternalNatal%20Chart%20-%20Wheel%20Only.svg)
@@ -453,20 +623,36 @@ birth_chart_svg.save_wheel_only_svg_file(
 ### Synastry Chart
 
 ```python
+from pathlib import Path
 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")
+first = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+synastry_chart.save_wheel_only_svg_file(output_path=output_dir, filename="lennon-mccartney-synastry-wheel")
 ```
 
 ![John Lennon and Paul McCartney Synastry](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Wheel%20Synastry%20Only%20-%20Synastry%20Chart%20-%20Wheel%20Only.svg)
@@ -476,20 +662,37 @@ synastry_chart.save_wheel_only_svg_file()
 To save the SVG file in a custom location, specify the `output_path` parameter in `save_svg()`:
 
 ```python
+from pathlib import Path
 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")
+first = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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=".")
+
+output_dir = Path("my_charts")
+output_dir.mkdir(exist_ok=True)
+synastry_chart.save_svg(output_path=output_dir)
+print("Saved to", (output_dir / f"{synastry_chart.first_obj.name} - Synastry Chart.svg").resolve())
 ```
 
 ### Change Language
@@ -497,12 +700,19 @@ synastry_chart.save_svg(output_path=".")
 You can switch chart language by passing `chart_language` to the `ChartDrawer` class:
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
@@ -512,7 +722,10 @@ birth_chart_svg = ChartDrawer(
     chart_data=chart_data,
     chart_language="IT"  # Change to Italian
 )
-birth_chart_svg.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_svg(output_path=output_dir, filename="john-lennon-natal-it")
 ```
 
 You can also provide custom labels (or introduce a brand-new language) by passing
@@ -520,6 +733,20 @@ a dictionary to `language_pack`. Only the keys you supply are merged on top of t
 built-in strings:
 
 ```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
+
 custom_labels = {
     "PT": {
         "info": "Informações",
@@ -527,11 +754,15 @@ custom_labels = {
     }
 }
 
-birth_chart_svg = ChartDrawer(
+custom_chart = ChartDrawer(
     chart_data=chart_data,
     chart_language="PT",
     language_pack=custom_labels["PT"],
 )
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+custom_chart.save_svg(output_path=output_dir, filename="john-lennon-natal-pt")
 ```
 
 More details [here](https://www.kerykeion.net/docs/chart-language).
@@ -553,20 +784,32 @@ The available languages are:
 To generate a minified SVG, set `minify_svg=True` in the `makeSVG()` method:
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
 birth_chart_svg.save_svg(
-    minify=True
+    output_path=output_dir,
+    filename="john-lennon-natal-minified",
+    minify=True,
 )
 ```
 
@@ -575,20 +818,32 @@ birth_chart_svg.save_svg(
 To generate an SVG without CSS variables, set `remove_css_variables=True` in the `makeSVG()` method:
 
 ```python
+from pathlib import Path
 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 = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
 birth_chart_svg.save_svg(
-    remove_css_variables=True
+    output_path=output_dir,
+    filename="john-lennon-natal-no-css-variables",
+    remove_css_variables=True,
 )
 ```
 
@@ -599,20 +854,36 @@ This will inline all styles and eliminate CSS variables, resulting in an SVG tha
 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 pathlib import Path
 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")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+aspect_grid_chart.save_aspect_grid_only_svg_file(output_path=output_dir, filename="lennon-mccartney-aspect-grid")
 ```
 
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Aspect%20Grid%20Only%20-%20Natal%20Chart%20-%20Aspect%20Grid%20Only.svg)
@@ -628,7 +899,11 @@ from kerykeion import ReportGenerator, AstrologicalSubjectFactory, ChartDataFact
 
 # Subject-only report
 subject = AstrologicalSubjectFactory.from_birth_data(
-    "Sample Natal", 1990, 7, 21, 14, 45, "Rome", "IT"
+    "Sample Natal", 1990, 7, 21, 14, 45,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
 )
 ReportGenerator(subject).print_report(include_aspects=False)
 
@@ -638,7 +913,11 @@ 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"
+    "Sample Partner", 1992, 11, 5, 9, 30,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
 )
 synastry_data = ChartDataFactory.create_synastry_chart_data(subject, partner)
 ReportGenerator(synastry_data).print_report(max_aspects=12)
@@ -660,11 +939,21 @@ Each report contains:
 All section helpers remain available for targeted output:
 
 ```python
+from kerykeion import ReportGenerator, AstrologicalSubjectFactory, ChartDataFactory
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "Sample Natal", 1990, 7, 21, 14, 45,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
+natal_data = ChartDataFactory.create_natal_chart_data(subject)
+
 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))
+sections = report.generate_report(max_aspects=5).split("\n\n")
+for section in sections[:3]:
+    print(section)
 ```
 
 Refer to the refreshed [Report Documentation](https://www.kerykeion.net/report/) for end-to-end examples covering every supported chart model.
@@ -677,22 +966,32 @@ Kerykeion provides a unified `AspectsFactory` class for calculating astrological
 from kerykeion import AspectsFactory, AstrologicalSubjectFactory
 
 # Create astrological subjects
-jack = AstrologicalSubjectFactory.from_birth_data("Jack", 1990, 6, 15, 15, 15, "Roma", "IT")
-jane = AstrologicalSubjectFactory.from_birth_data("Jane", 1991, 10, 25, 21, 0, "Roma", "IT")
+jack = AstrologicalSubjectFactory.from_birth_data(
+    "Jack", 1990, 6, 15, 15, 15,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
+jane = AstrologicalSubjectFactory.from_birth_data(
+    "Jane", 1991, 10, 25, 21, 0,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
 
 # For single chart aspects (natal, return, composite, etc.)
-single_chart_aspects = AspectsFactory.single_chart_aspects(jack)
-print(f"Found {len(single_chart_aspects)} aspects in Jack's chart")
-print(single_chart_aspects[0])
-# Output: AspectModel with details like aspect type, orb, planets involved, etc.
+single_chart_result = AspectsFactory.single_chart_aspects(jack)
+print(f"Found {len(single_chart_result.aspects)} aspects in Jack's chart")
+print(single_chart_result.aspects[0])
 
 # For dual chart aspects (synastry, transits, comparisons, etc.)
-dual_chart_aspects = AspectsFactory.dual_chart_aspects(jack, jane)
-print(f"Found {len(dual_chart_aspects)} aspects between Jack and Jane's charts")
-print(dual_chart_aspects[0])
-# Output: AspectModel with cross-chart aspect details
+dual_chart_result = AspectsFactory.dual_chart_aspects(jack, jane)
+print(f"Found {len(dual_chart_result.aspects)} aspects between Jack and Jane's charts")
+print(dual_chart_result.aspects[0])
 
-# The factory returns structured AspectModel objects with properties like:
+# Each AspectModel includes:
 # - p1_name, p2_name: Planet/point names
 # - aspect: Aspect type (conjunction, trine, square, etc.)
 # - orbit: Orb tolerance in degrees
@@ -724,7 +1023,11 @@ You can refine the weighting without rebuilding the dictionary: pass lowercase p
 from kerykeion import AstrologicalSubjectFactory, ChartDataFactory
 
 subject = AstrologicalSubjectFactory.from_birth_data(
-    "Sample", 1986, 4, 12, 8, 45, "Bologna", "IT"
+    "Sample", 1986, 4, 12, 8, 45,
+    lng=11.3426,
+    lat=44.4949,
+    tz_str="Europe/Rome",
+    online=False,
 )
 
 # Equal weighting: every active point counts once
@@ -758,7 +1061,10 @@ By default, the zodiac type is **Tropical**. To use **Sidereal**, specify the si
 ```python
 johnny = AstrologicalSubjectFactory.from_birth_data(
     "Johnny Depp", 1963, 6, 9, 0, 0,
-    "Owensboro", "US",
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
     zodiac_type="Sidereal",
     sidereal_mode="LAHIRI"
 )
@@ -775,8 +1081,11 @@ By default, houses are calculated using **Placidus**. Configure a different hous
 ```python
 johnny = AstrologicalSubjectFactory.from_birth_data(
     "Johnny Depp", 1963, 6, 9, 0, 0,
-    "Owensboro", "US",
-    houses_system="M"
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
+    houses_system_identifier="M"
 )
 ```
 
@@ -793,7 +1102,10 @@ By default, Kerykeion uses the **Apparent Geocentric** perspective (the most sta
 ```python
 johnny = AstrologicalSubjectFactory.from_birth_data(
     "Johnny Depp", 1963, 6, 9, 0, 0,
-    "Owensboro", "US",
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
     perspective_type="Heliocentric"
 )
 ```
@@ -820,43 +1132,56 @@ The Black & White theme renders glyphs, rings, and aspects in solid black on lig
 Here's an example of how to set the theme:
 
 ```python
+from pathlib import Path
 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_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon - Dark Theme", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # 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()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+dark_theme_natal_chart.save_svg(output_path=output_dir, filename="john-lennon-natal-dark-high-contrast")
 ```
 
 ![John Lennon](https://www.kerykeion.net/img/showcase/John%20Lennon%20-%20Dark%20-%20Natal%20Chart.svg)
 
 ## Alternative Initialization
 
-Create an `AstrologicalSubject` from a UTC ISO 8601 string:
-
-```python
-subject = AstrologicalSubject.get_from_iso_utc_time(
-    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US"
-)
-```
-
-If you set `online=True`, provide a `geonames_username` to allow city-based geolocation:
+Create an `AstrologicalSubjectModel` from a UTC ISO 8601 string:
 
 ```python
-from kerykeion.astrological_subject import AstrologicalSubjectFactory
+from kerykeion import AstrologicalSubjectFactory
 
-subject = AstrologicalSubject.get_from_iso_utc_time(
-    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US", online=True
+subject = AstrologicalSubjectFactory.from_iso_utc_time(
+    name="Johnny Depp",
+    iso_utc_time="1963-06-09T05:00:00Z",
+    city="Owensboro",
+    nation="US",
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
 )
+
+print(subject.iso_formatted_local_datetime)
 ```
 
+If you prefer automatic geocoding, set `online=True` and provide your GeoNames credentials via `geonames_username`.
+
 ## Lunar Nodes (Rahu & Ketu)
 
 Kerykeion supports both **True** and **Mean** Lunar Nodes:
@@ -871,12 +1196,19 @@ In instances of the classes used to generate aspects and SVG charts, only the me
 Example:
 
 ```python
+from pathlib import Path
 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")
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data with custom active points including true nodes
 chart_data = ChartDataFactory.create_natal_chart_data(
@@ -905,7 +1237,10 @@ chart_data = ChartDataFactory.create_natal_chart_data(
 
 # Step 3: Create visualization
 chart = ChartDrawer(chart_data=chart_data)
-chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+chart.save_svg(output_path=output_dir, filename="johnny-depp-custom-points")
 ```
 
 ## JSON Support
@@ -915,9 +1250,15 @@ You can serialize the astrological subject (the base data used throughout the li
 ```python
 from kerykeion import AstrologicalSubjectFactory
 
-johnny = AstrologicalSubjectFactory.from_birth_data("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US")
+johnny = AstrologicalSubjectFactory.from_birth_data(
+    "Johnny Depp", 1963, 6, 9, 0, 0,
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
+)
 
-print(johnny.json(dump=False, indent=2))
+print(johnny.model_dump_json(indent=2))
 ```
 
 ## Auto Generated Documentation
@@ -949,24 +1290,44 @@ The old class-based approach has been replaced with a modern factory pattern:
 **Old v4 API:**
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
 # v4 - Class-based approach
-subject = AstrologicalSubject("John", 1990, 1, 1, 12, 0, "London", "GB")
-chart = KerykeionChartSVG(subject)
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+
+subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+chart = KerykeionChartSVG(subject, new_output_directory=output_dir)
 chart.makeSVG()
 ```
 
 **New v5 API:**
 
 ```python
+from pathlib import Path
 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")
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 chart_data = ChartDataFactory.create_natal_chart_data(subject)
 drawer = ChartDrawer(chart_data=chart_data)
-drawer.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+drawer.save_svg(output_path=output_dir, filename="john-factory-demo")
 ```
 
 #### Pydantic 2 Models & Type Safety
@@ -975,7 +1336,7 @@ 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
+-   **`AspectModel` list**: Raw aspect entries directly on `ChartDataModel.aspects`
 -   **`PlanetReturnModel`**: Planetary return data
 -   **`ElementDistributionModel`**: Element statistics (fire, earth, air, water)
 -   **`QualityDistributionModel`**: Quality statistics (cardinal, fixed, mutable)
@@ -1072,11 +1433,27 @@ All lunar node fields have been renamed for clarity:
 **Migration example:**
 
 ```python
-# v4
-print(subject.mean_node)
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory
 
-# v5
-print(subject.mean_north_lunar_node)
+# v4 alias (still available, emits DeprecationWarning)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+print(legacy_subject.mean_node)
+
+# v5 canonical name
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+print(modern_subject.mean_north_lunar_node)
 ```
 
 #### 5. Axis Orb Filtering
@@ -1090,16 +1467,43 @@ The two-step process (data + rendering) is now required:
 **Old v4:**
 
 ```python
-chart = KerykeionChartSVG(subject)
+from pathlib import Path
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+
+subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+chart = KerykeionChartSVG(subject, new_output_directory=output_dir)
 chart.makeSVG()
 ```
 
 **New v5:**
 
 ```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory, ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 chart_data = ChartDataFactory.create_natal_chart_data(subject)
 drawer = ChartDrawer(chart_data=chart_data)
-drawer.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+drawer.save_svg(output_path=output_dir, filename="john-v5-demo")
 ```
 
 #### 7. Aspects API Changes
@@ -1109,7 +1513,23 @@ Aspects are now calculated through the factory:
 **Old v4:**
 
 ```python
-from kerykeion import NatalAspects, SynastryAspects
+from kerykeion import AstrologicalSubjectFactory, NatalAspects, SynastryAspects
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+subject1 = subject
+subject2 = AstrologicalSubjectFactory.from_birth_data(
+    "Jane", 1990, 6, 5, 8, 30,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
 natal_aspects = NatalAspects(subject)
 synastry_aspects = SynastryAspects(subject1, subject2)
@@ -1118,12 +1538,30 @@ synastry_aspects = SynastryAspects(subject1, subject2)
 **New v5:**
 
 ```python
-from kerykeion import AspectsFactory
+from kerykeion import AstrologicalSubjectFactory, AspectsFactory
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+subject1 = subject
+subject2 = AstrologicalSubjectFactory.from_birth_data(
+    "Jane", 1990, 6, 5, 8, 30,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
 natal_aspects = AspectsFactory.single_chart_aspects(subject)
 synastry_aspects = AspectsFactory.dual_chart_aspects(subject1, subject2)
 ```
 
+Note (v5.1): The two lists `relevant_aspects` and `all_aspects` were unified into a single, cleaned list: `aspects`. If you previously used either property, switch to `aspects`. The legacy properties still work via the backward-compatibility layer but both return the same unified list.
+
 ### 🔄 Migration Guide
 
 #### Using the Backward Compatibility Layer
@@ -1133,7 +1571,13 @@ 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")
+subject = AstrologicalSubject(
+    "John Doe", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # These still work but show DeprecationWarnings
 print(subject.mean_node)  # Maps to mean_north_lunar_node
@@ -1146,58 +1590,127 @@ print(subject.true_node)  # Maps to true_north_lunar_node
 
 1. **Update imports**
 
-    ```python
-    # Old
-    from kerykeion import AstrologicalSubject, KerykeionChartSVG
+```python
+# Old (v4)
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
-    # New
-    from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
-    ```
+# New (v5)
+from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
+```
 
 2. **Update subject creation**
 
-    ```python
-    # Old
-    subject = AstrologicalSubject("John", 1990, 1, 1, 12, 0, "London", "GB")
+```python
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory
+
+# Old (v4)
+subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
-    # New
-    subject = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
-    ```
+# New (v5)
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+```
 
 3. **Update chart generation**
 
-    ```python
-    # Old
-    chart = KerykeionChartSVG(subject)
-    chart.makeSVG()
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory, ChartDataFactory, KerykeionChartSVG
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Old (v4)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
 
-    # New
-    chart_data = ChartDataFactory.create_natal_chart_data(subject)
-    drawer = ChartDrawer(chart_data=chart_data)
-    drawer.save_svg()
-    ```
+chart = KerykeionChartSVG(legacy_subject, new_output_directory=output_dir)
+chart.makeSVG()
+
+# New (v5)
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+chart_data = ChartDataFactory.create_natal_chart_data(modern_subject)
+drawer = ChartDrawer(chart_data=chart_data)
+drawer.save_svg(output_path=output_dir, filename="john-v5-migration")
+```
 
 4. **Update field access** (lunar nodes)
 
-    ```python
-    # Old
-    print(subject.mean_node.position)
+```python
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory
 
-    # New
-    print(subject.mean_north_lunar_node.position)
-    ```
+# Old (v4)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+legacy_mean_node = legacy_subject.mean_node
+print(getattr(legacy_mean_node, "position", "Legacy mean node not active"))
+
+# New (v5)
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+modern_mean_node = modern_subject.mean_north_lunar_node
+print(getattr(modern_mean_node, "position", "Modern mean node not active"))
+```
 
 5. **Update aspects**
 
-    ```python
-    # Old
-    from kerykeion import NatalAspects
-    aspects = NatalAspects(subject)
+```python
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory, NatalAspects, AspectsFactory
 
-    # New
-    from kerykeion import AspectsFactory
-    aspects = AspectsFactory.single_chart_aspects(subject)
-    ```
+# Old (v4)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+legacy_aspects = NatalAspects(legacy_subject)
+print(f"Legacy aspects count: {len(legacy_aspects.relevant_aspects)}")
+
+# New (v5)
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+modern_aspects = AspectsFactory.single_chart_aspects(modern_subject)
+print(f"Modern aspects count: {len(modern_aspects.aspects)}")
+```
 
 #### Automated Migration Script