kerykeion 4.26.2__py3-none-any.whl → 5.0.0__py3-none-any.whl

kerykeion/charts/themes/strawberry.css

@@ -0,0 +1,158 @@
+:root {
+    /* -------- */
+    /* General */
+    /* ------- */
+    --kerykeion-color-black: #141012; /* quasi nero con traccia impercettibile di rosa */
+    --kerykeion-color-white: #fef5f9; /* rosa tenue */
+    --kerykeion-color-neutral-content: #5c2d41; /* oklch(25% 0.08 330) - rosa scuro */
+    --kerykeion-color-base-content: #5c2d41; /* stessa di neutral-content */
+    --kerykeion-color-primary: #d91aa6; /* oklch(55% 0.35 320) - rosa magenta vibrante */
+    --kerykeion-color-secondary: #ff1b6b; /* oklch(70% 0.35 340) - rosa fucsia brillante */
+    --kerykeion-color-accent: #ff4dd2; /* oklch(80% 0.3 330) - rosa elettrico */
+    --kerykeion-color-neutral: #3d1f2a; /* oklch(16% 0.05 330) - rosa scuro */
+    --kerykeion-color-base-100: #fef0f5; /* oklch(96% 0.03 330) - sfondo rosa chiaro */
+    --kerykeion-color-info: #e056f2; /* oklch(74% 0.3 310) - rosa-viola brillante */
+    --kerykeion-color-info-content: #6b2e5d; /* oklch(32% 0.12 310) */
+    --kerykeion-color-success: #4fdc9a; /* oklch(78% 0.18 130) - verde con base rosa */
+    --kerykeion-color-warning: #ff8a6c; /* oklch(80% 0.25 50) - arancione rosato */
+    --kerykeion-color-error: #ff4f9a; /* oklch(73% 0.28 340) - rosa error vibrante */
+    /* Zodiac */
+    --kerykeion-color-base-200: #fce8f1; /* oklch(93% 0.05 330) - rosa delicato evidente */
+    --kerykeion-color-base-300: #f5d1e3; /* rosa chiaro invece di grigio */
+
+    /* ----------- */
+    /* Chart Color */
+    /* ----------- */
+
+    /* Main colors */
+    --kerykeion-chart-color-paper-0: var(--kerykeion-color-neutral-content);
+    --kerykeion-chart-color-paper-1: var(--kerykeion-color-base-100);
+
+    /* Zodiac Sign Sectors */
+    --kerykeion-chart-color-zodiac-bg-0: var(--kerykeion-color-base-200);
+    --kerykeion-chart-color-zodiac-bg-1: var(--kerykeion-color-base-300);
+    --kerykeion-chart-color-zodiac-bg-2: var(--kerykeion-color-base-200);
+    --kerykeion-chart-color-zodiac-bg-3: var(--kerykeion-color-base-300);
+    --kerykeion-chart-color-zodiac-bg-4: var(--kerykeion-color-base-200);
+    --kerykeion-chart-color-zodiac-bg-5: var(--kerykeion-color-base-300);
+    --kerykeion-chart-color-zodiac-bg-6: var(--kerykeion-color-base-200);
+    --kerykeion-chart-color-zodiac-bg-7: var(--kerykeion-color-base-300);
+    --kerykeion-chart-color-zodiac-bg-8: var(--kerykeion-color-base-200);
+    --kerykeion-chart-color-zodiac-bg-9: var(--kerykeion-color-base-300);
+    --kerykeion-chart-color-zodiac-bg-10: var(--kerykeion-color-base-200);
+    --kerykeion-chart-color-zodiac-bg-11: var(--kerykeion-color-base-300);
+
+    /* Zodiac Sign Rings */
+    --kerykeion-chart-color-zodiac-radix-ring-0: var(--kerykeion-color-neutral);
+    --kerykeion-chart-color-zodiac-radix-ring-1: var(--kerykeion-color-neutral);
+    --kerykeion-chart-color-zodiac-radix-ring-2: var(--kerykeion-color-neutral);
+    --kerykeion-chart-color-zodiac-transit-ring-0: var(
+        --kerykeion-color-neutral
+    );
+    --kerykeion-chart-color-zodiac-transit-ring-1: var(
+        --kerykeion-color-neutral
+    );
+    --kerykeion-chart-color-zodiac-transit-ring-2: var(
+        --kerykeion-color-neutral
+    );
+    --kerykeion-chart-color-zodiac-transit-ring-3: var(
+        --kerykeion-color-neutral
+    );
+    --kerykeion-chart-color-houses-radix-line: var(
+        --kerykeion-color-base-content
+    );
+    --kerykeion-chart-color-houses-transit-line: var(
+        --kerykeion-color-base-content
+    );
+
+    /* Aspects */
+    --kerykeion-chart-color-conjunction: var(--kerykeion-color-success);
+    --kerykeion-chart-color-semi-sextile: var(--kerykeion-color-success);
+    --kerykeion-chart-color-semi-square: var(--kerykeion-color-error);
+    --kerykeion-chart-color-sextile: var(--kerykeion-color-success);
+    --kerykeion-chart-color-quintile: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-square: var(--kerykeion-color-error);
+    --kerykeion-chart-color-trine: var(--kerykeion-color-success);
+    --kerykeion-chart-color-sesquiquadrate: var(--kerykeion-color-error);
+    --kerykeion-chart-color-biquintile: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-quincunx: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-opposition: var(--kerykeion-color-error);
+
+    /* Planets */
+    --kerykeion-chart-color-sun: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-moon: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-mercury: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-venus: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-mars: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-jupiter: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-saturn: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-uranus: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-neptune: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-pluto: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-true-node: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-mean-node: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-chiron: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-first-house: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-tenth-house: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-seventh-house: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-fourth-house: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-mean-lilith: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-true-lilith: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-ceres: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-pallas: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-juno: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-vesta: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-pars-fortunae: var(--kerykeion-color-success);
+    --kerykeion-chart-color-vertex: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-east-point: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-eris: var(--kerykeion-color-error);
+    --kerykeion-chart-color-earth: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-pholus: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-sedna: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-haumea: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-makemake: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-ixion: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-orcus: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-quaoar: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-regulus: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-spica: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-anti-vertex: var(--kerykeion-color-secondary);
+
+    /* Arab Parts */
+    --kerykeion-chart-color-pars-spiritus: var(--kerykeion-color-success);
+    --kerykeion-chart-color-pars-amoris: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-pars-fortunae: var(--kerykeion-color-success);
+    --kerykeion-chart-color-pars-fidei: var(--kerykeion-color-success);
+
+    /* Zodiac Signs */
+    --kerykeion-chart-color-zodiac-icon-0: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-zodiac-icon-1: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-zodiac-icon-2: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-zodiac-icon-3: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-zodiac-icon-4: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-zodiac-icon-5: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-zodiac-icon-6: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-zodiac-icon-7: var(--kerykeion-color-secondary);
+    --kerykeion-chart-color-zodiac-icon-8: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-zodiac-icon-9: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-zodiac-icon-10: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-zodiac-icon-11: var(--kerykeion-color-secondary);
+
+    /* Elements Percentage */
+    --kerykeion-chart-color-air-percentage: var(--kerykeion-color-primary);
+    --kerykeion-chart-color-earth-percentage: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-fire-percentage: var(--kerykeion-color-accent);
+    --kerykeion-chart-color-water-percentage: var(--kerykeion-color-secondary);
+
+    /* Modalities Percentage */
+    --kerykeion-chart-color-cardinal-percentage: var(--kerykeion-color-success);
+    --kerykeion-chart-color-fixed-percentage: var(--kerykeion-color-warning);
+    --kerykeion-chart-color-mutable-percentage: var(--kerykeion-color-error);
+
+    /* Aspects */
+    --kerykeion-chart-color-lunar-phase-0: var(--kerykeion-color-black);
+    --kerykeion-chart-color-lunar-phase-1: var(--kerykeion-color-white);
+
+    /* Houses Numbers */
+    --kerykeion-chart-color-house-number: var(--kerykeion-color-base-content);
+}

kerykeion/composite_subject_factory.py

@@ -1,29 +1,104 @@
+"""
+Composite Subject Factory Module
+
+This module provides functionality for creating composite astrological charts from two
+individual astrological subjects. A composite chart represents the relationship between
+two people by calculating midpoint positions between corresponding planetary placements
+and house cusps.
+
+The module implements the midpoint composite technique, which is the most commonly used
+method for relationship astrology. This technique creates a single chart that symbolizes
+the energy and dynamics of the relationship itself, rather than comparing individual charts.
+
+Key Features:
+- Midpoint calculation for all planetary positions
+- Midpoint calculation for house cusp positions
+- Proper handling of zodiacal boundary crossings (0°/360°)
+- Validation of compatible astrological settings between subjects
+- Lunar phase calculation for composite charts
+- Support for all standard astrological points and house systems
+
+Classes:
+    CompositeSubjectFactory: Main factory class for creating composite charts
+
+Dependencies:
+    - AstrologicalSubjectFactory: For working with individual astrological subjects
+    - Various schemas modules: For type definitions and models
+    - utilities module: For astrological calculations and helper functions
+
+Example Usage:
+    >>> from kerykeion import AstrologicalSubjectFactory, CompositeSubjectFactory
+    >>> person1 = AstrologicalSubjectFactory.from_birth_data(...)
+    >>> person2 = AstrologicalSubjectFactory.from_birth_data(...)
+    >>> composite = CompositeSubjectFactory(person1, person2)
+    >>> composite_chart = composite.get_midpoint_composite_subject_model()
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
+"""
+
 from typing import Union
 
-from kerykeion import AstrologicalSubject
-from kerykeion import KerykeionException
-from kerykeion.kr_types.kr_models import CompositeSubjectModel, AstrologicalSubjectModel
-from kerykeion.kr_types.kr_literals import ZodiacType, PerspectiveType, HousesSystemIdentifier, SiderealMode, Planet, Houses, AxialCusps, CompositeChartType
+# Fix the circular import by changing this import
+from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
+from kerykeion.schemas.kerykeion_exception import KerykeionException
+from kerykeion.schemas.kr_models import CompositeSubjectModel, AstrologicalSubjectModel
+from kerykeion.schemas.kr_literals import ZodiacType, PerspectiveType, HousesSystemIdentifier, SiderealMode, AstrologicalPoint, Houses, CompositeChartType
 from kerykeion.utilities import (
     get_kerykeion_point_from_degree,
     get_planet_house,
     circular_mean,
     calculate_moon_phase,
-    circular_sort
+    circular_sort,
+    find_common_active_points
 )
 
 
 class CompositeSubjectFactory:
     """
-    Factory class to create a Composite Subject Model from two Astrological Subjects
-    Currently, the only available method for creating composite charts is the midpoint method.
-    The composite houses and planets are calculated based on the midpoint of the corresponding points of the two subjects.
-    The house are then reordered to match the original house system of the first subject.
-
-    Args:
-        first_subject (AstrologicalSubject): First astrological subject
-        second_subject (AstrologicalSubject): Second astrological subject
-        chart_name (str): Name of the composite chart. If None, it will be automatically generated.
+    Factory class to create composite astrological charts from two astrological subjects.
+
+    A composite chart represents the relationship between two people by calculating the midpoint
+    between corresponding planetary positions and house cusps. This creates a single chart
+    that symbolizes the energy of the relationship itself.
+
+    Currently supports the midpoint method for composite chart calculation, where:
+    - Planetary positions are calculated as the circular mean of corresponding planets
+    - House cusps are calculated as the circular mean of corresponding houses
+    - Houses are reordered to maintain consistency with the original house system
+    - Only common active points between both subjects are included
+
+    The resulting composite chart maintains the zodiac type, sidereal mode, houses system,
+    and perspective type of the input subjects (which must be identical between subjects).
+
+    Attributes:
+        model (CompositeSubjectModel | None): The generated composite subject model
+        first_subject (AstrologicalSubjectModel): First astrological subject
+        second_subject (AstrologicalSubjectModel): Second astrological subject
+        name (str): Name of the composite chart
+        composite_chart_type (CompositeChartType): Type of composite chart (currently "Midpoint")
+        zodiac_type (ZodiacType): Zodiac system used (Tropical or Sidereal)
+        sidereal_mode (SiderealMode | None): Sidereal calculation mode if applicable
+        houses_system_identifier (HousesSystemIdentifier): House system identifier
+        houses_system_name (str): Human-readable house system name
+        perspective_type (PerspectiveType): Astrological perspective type
+        houses_names_list (list[Houses]): List of house names
+        active_points (list[AstrologicalPoint]): Common active planetary points
+
+    Example:
+        >>> first_person = AstrologicalSubjectFactory.from_birth_data(
+        ...     "John", 1990, 1, 1, 12, 0, "New York", "US"
+        ... )
+        >>> second_person = AstrologicalSubjectFactory.from_birth_data(
+        ...     "Jane", 1992, 6, 15, 14, 30, "Los Angeles", "US"
+        ... )
+        >>> composite = CompositeSubjectFactory(first_person, second_person)
+        >>> composite_model = composite.get_midpoint_composite_subject_model()
+
+    Raises:
+        KerykeionException: When subjects have incompatible settings (different zodiac types,
+                           sidereal modes, house systems, or perspective types)
     """
 
     model: Union[CompositeSubjectModel, None]
@@ -36,26 +111,45 @@ class CompositeSubjectFactory:
     houses_system_identifier: HousesSystemIdentifier
     houses_system_name: str
     perspective_type: PerspectiveType
-    planets_names_list: list[Planet]
     houses_names_list: list[Houses]
-    axial_cusps_names_list: list[AxialCusps]
+    active_points: list[AstrologicalPoint]
 
     def __init__(
             self,
-            first_subject: Union[AstrologicalSubject, AstrologicalSubjectModel],
-            second_subject: Union[AstrologicalSubject, AstrologicalSubjectModel],
+            first_subject: AstrologicalSubjectModel,
+            second_subject: AstrologicalSubjectModel,
             chart_name: Union[str, None] = None
     ):
+        """
+        Initialize the composite subject factory with two astrological subjects.
+
+        Validates that both subjects have compatible settings and extracts common
+        active points for composite chart calculation.
+
+        Args:
+            first_subject (AstrologicalSubjectModel): First astrological subject for the composite
+            second_subject (AstrologicalSubjectModel): Second astrological subject for the composite
+            chart_name (str | None, optional): Custom name for the composite chart.
+                                             If None, generates name from subject names.
+                                             Defaults to None.
+
+        Raises:
+            KerykeionException: If subjects have different zodiac types, sidereal modes,
+                              house systems, house system names, or perspective types.
+
+        Note:
+            Both subjects must have identical astrological calculation settings to ensure
+            meaningful composite chart calculations.
+        """
         self.model: Union[CompositeSubjectModel, None] = None
         self.composite_chart_type = "Midpoint"
 
-        # Subjects
-        if isinstance(first_subject, AstrologicalSubject) or isinstance(first_subject, AstrologicalSubjectModel):
-            self.first_subject = first_subject.model() # type: ignore
-            self.second_subject = second_subject.model() # type: ignore
-        else:
-            self.first_subject = first_subject
-            self.second_subject = second_subject
+        self.first_subject = first_subject
+        self.second_subject = second_subject
+        self.active_points = find_common_active_points(
+            first_subject.active_points,
+            second_subject.active_points
+        )
 
         # Name
         if chart_name is None:
@@ -93,42 +187,123 @@ class CompositeSubjectFactory:
         self.perspective_type = first_subject.perspective_type
 
         # Planets Names List
-        self.planets_names_list = []
-        for planet in first_subject.planets_names_list:
-            if planet in second_subject.planets_names_list:
-                self.planets_names_list.append(planet)
+        self.active_points = []
+        for planet in first_subject.active_points:
+            if planet in second_subject.active_points:
+                self.active_points.append(planet)
 
         # Houses Names List
         self.houses_names_list = self.first_subject.houses_names_list
 
-        # Axial Cusps Names List
-        self.axial_cusps_names_list = self.first_subject.axial_cusps_names_list
-
     def __str__(self):
+        """
+        Return string representation of the composite subject.
+
+        Returns:
+            str: Human-readable string describing the composite chart.
+        """
         return f"Composite Chart Data for {self.name}"
 
     def __repr__(self):
+        """
+        Return detailed string representation of the composite subject.
+
+        Returns:
+            str: Detailed string representation for debugging purposes.
+        """
         return f"Composite Chart Data for {self.name}"
 
     def __eq__(self, other):
+        """
+        Check equality with another composite subject.
+
+        Args:
+            other (CompositeSubjectFactory): Another composite subject to compare with.
+
+        Returns:
+            bool: True if both subjects and chart name are identical.
+        """
         return self.first_subject == other.first_subject and self.second_subject == other.second_subject and self.name == other.chart_name
 
     def __ne__(self, other):
+        """
+        Check inequality with another composite subject.
+
+        Args:
+            other (CompositeSubjectFactory): Another composite subject to compare with.
+
+        Returns:
+            bool: True if subjects or chart name are different.
+        """
         return not self.__eq__(other)
 
     def __hash__(self):
+        """
+        Generate hash for the composite subject.
+
+        Returns:
+            int: Hash value based on both subjects and chart name.
+        """
         return hash((self.first_subject, self.second_subject, self.name))
 
     def __copy__(self):
+        """
+        Create a shallow copy of the composite subject.
+
+        Returns:
+            CompositeSubjectFactory: New instance with the same subjects and name.
+        """
         return CompositeSubjectFactory(self.first_subject, self.second_subject, self.name)
 
     def __setitem__(self, key, value):
+        """
+        Set an attribute using dictionary-style access.
+
+        Args:
+            key (str): Attribute name to set.
+            value: Value to assign to the attribute.
+        """
         setattr(self, key, value)
 
     def __getitem__(self, key):
+        """
+        Get an attribute using dictionary-style access.
+
+        Args:
+            key (str): Attribute name to retrieve.
+
+        Returns:
+            Any: Value of the requested attribute.
+
+        Raises:
+            AttributeError: If the attribute doesn't exist.
+        """
         return getattr(self, key)
 
     def _calculate_midpoint_composite_points_and_houses(self):
+        """
+        Calculate midpoint positions for all planets and house cusps in the composite chart.
+
+        This method implements the midpoint composite technique by:
+        1. Computing circular means of house cusp positions from both subjects
+        2. Sorting house positions to maintain proper house order
+        3. Creating composite house cusps with calculated positions
+        4. Computing circular means of planetary positions for common active points
+        5. Assigning planets to their appropriate houses in the composite chart
+
+        The circular mean calculation ensures proper handling of zodiacal positions
+        around the 360-degree boundary (e.g., when one position is at 350° and
+        another at 10°, the midpoint is correctly calculated as 0°).
+
+        Side Effects:
+            - Updates instance attributes with calculated house cusp positions
+            - Updates instance attributes with calculated planetary positions
+            - Sets house assignments for each planetary position
+
+        Note:
+            This is an internal method called by get_midpoint_composite_subject_model().
+            Only planets that exist in both subjects' active_points are included.
+        """
         # Houses
         house_degree_list_ut = []
         for house in self.first_subject.houses_names_list:
@@ -152,8 +327,8 @@ class CompositeSubjectFactory:
 
         # Planets
         common_planets = []
-        for planet in self.first_subject.planets_names_list:
-            if planet in self.second_subject.planets_names_list:
+        for planet in self.first_subject.active_points:
+            if planet in self.second_subject.active_points:
                 common_planets.append(planet)
 
         planets = {}
@@ -164,30 +339,57 @@ class CompositeSubjectFactory:
                 self.first_subject[planet_lower]["abs_pos"],
                 self.second_subject[planet_lower]["abs_pos"]
             )
-            self[planet_lower] = get_kerykeion_point_from_degree(planets[planet_lower]["abs_pos"], planet, "Planet")
+            self[planet_lower] = get_kerykeion_point_from_degree(planets[planet_lower]["abs_pos"], planet, "AstrologicalPoint")
             self[planet_lower]["house"] = get_planet_house(self[planet_lower]['abs_pos'], house_degree_list_ut)
 
+    def _calculate_composite_lunar_phase(self):
+        """
+        Calculate the lunar phase for the composite chart based on Sun-Moon midpoints.
 
-        # Axial Cusps
-        for cusp in self.first_subject.axial_cusps_names_list:
-            cusp_lower = cusp.lower()
-            self[cusp_lower] = get_kerykeion_point_from_degree(
-                circular_mean(
-                    self.first_subject[cusp_lower]["abs_pos"],
-                    self.second_subject[cusp_lower]["abs_pos"]
-                ),
-                cusp,
-                "AxialCusps"
-            )
-            self[cusp_lower]["house"] = get_planet_house(self[cusp_lower]['abs_pos'], house_degree_list_ut)
+        Uses the composite positions of the Sun and Moon to determine the lunar phase
+        angle, representing the relationship's emotional and instinctual dynamics.
 
-    def _calculate_composite_lunar_phase(self):
+        Side Effects:
+            Sets the lunar_phase attribute with the calculated phase information.
+
+        Note:
+            This method should be called after _calculate_midpoint_composite_points_and_houses()
+            to ensure Sun and Moon composite positions are available.
+        """
         self.lunar_phase = calculate_moon_phase(
             self['moon'].abs_pos,
             self['sun'].abs_pos
         )
 
     def get_midpoint_composite_subject_model(self):
+        """
+        Generate the complete composite chart model using the midpoint technique.
+
+        This is the main public method for creating a composite chart. It orchestrates
+        the calculation of all composite positions and creates a complete CompositeSubjectModel
+        containing all necessary astrological data for the relationship chart.
+
+        The process includes:
+        1. Calculating midpoint positions for all planets and house cusps
+        2. Computing the composite lunar phase
+        3. Assembling all data into a comprehensive model
+
+        Returns:
+            CompositeSubjectModel: Complete composite chart data model containing:
+                - All calculated planetary positions and their house placements
+                - House cusp positions maintaining proper house system order
+                - Lunar phase information for the composite chart
+                - All metadata from the original subjects (names, chart type, etc.)
+
+        Example:
+            >>> composite = CompositeSubjectFactory(person1, person2, "Our Relationship")
+            >>> model = composite.get_midpoint_composite_subject_model()
+            >>> print(f"Composite Sun at {model.sun.abs_pos}° in House {model.sun.house}")
+
+        Note:
+            This method performs all calculations internally and returns a complete,
+            ready-to-use composite chart model suitable for analysis or chart drawing.
+        """
         self._calculate_midpoint_composite_points_and_houses()
         self._calculate_composite_lunar_phase()
 
@@ -197,10 +399,10 @@ class CompositeSubjectFactory:
 
 
 if __name__ == "__main__":
-    from kerykeion.astrological_subject import AstrologicalSubject
+    from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
 
-    first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-    second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
+    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")
 
     composite_chart = CompositeSubjectFactory(first, second)
     print(composite_chart.get_midpoint_composite_subject_model().model_dump_json(indent=4))