kerykeion 5.0.0a9__py3-none-any.whl → 5.1.8__py3-none-any.whl

kerykeion/charts/themes/black-and-white.css

@@ -0,0 +1,148 @@
+:root {
+    /* -------- */
+    /* General */
+    /* ------- */
+    --kerykeion-color-black: #000000;
+    --kerykeion-color-white: #ffffff;
+
+    --kerykeion-color-neutral-content: #111111;
+    --kerykeion-color-base-content: #111111;
+    --kerykeion-color-primary: #222222;
+    --kerykeion-color-secondary: #444444;
+    --kerykeion-color-accent: #666666;
+    --kerykeion-color-neutral: #1a1a1a;
+    --kerykeion-color-base-100: #ffffff;
+    --kerykeion-color-info: #222222;
+    --kerykeion-color-info-content: #ffffff;
+    --kerykeion-color-success: #333333;
+    --kerykeion-color-warning: #555555;
+    --kerykeion-color-error: #777777;
+
+    /* Zodiac */
+    --kerykeion-color-base-200: #f0f0f0;
+    --kerykeion-color-base-300: #d9d9d9;
+
+    /* ----------- */
+    /* 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-black);
+    --kerykeion-chart-color-zodiac-radix-ring-1: var(--kerykeion-color-black);
+    --kerykeion-chart-color-zodiac-radix-ring-2: var(--kerykeion-color-black);
+    --kerykeion-chart-color-zodiac-transit-ring-0: var(--kerykeion-color-black);
+    --kerykeion-chart-color-zodiac-transit-ring-1: var(--kerykeion-color-black);
+    --kerykeion-chart-color-zodiac-transit-ring-2: var(--kerykeion-color-black);
+    --kerykeion-chart-color-zodiac-transit-ring-3: var(--kerykeion-color-black);
+    --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: #222222;
+    --kerykeion-chart-color-semi-sextile: #333333;
+    --kerykeion-chart-color-semi-square: #444444;
+    --kerykeion-chart-color-sextile: #333333;
+    --kerykeion-chart-color-quintile: #555555;
+    --kerykeion-chart-color-square: #000000;
+    --kerykeion-chart-color-trine: #222222;
+    --kerykeion-chart-color-sesquiquadrate: #444444;
+    --kerykeion-chart-color-biquintile: #555555;
+    --kerykeion-chart-color-quincunx: #444444;
+    --kerykeion-chart-color-opposition: #000000;
+
+    /* Planets */
+    --kerykeion-chart-color-sun: #000000;
+    --kerykeion-chart-color-moon: #000000;
+    --kerykeion-chart-color-mercury: #000000;
+    --kerykeion-chart-color-venus: #000000;
+    --kerykeion-chart-color-mars: #000000;
+    --kerykeion-chart-color-jupiter: #000000;
+    --kerykeion-chart-color-saturn: #000000;
+    --kerykeion-chart-color-uranus: #000000;
+    --kerykeion-chart-color-neptune: #000000;
+    --kerykeion-chart-color-pluto: #000000;
+    --kerykeion-chart-color-true-node: #000000;
+    --kerykeion-chart-color-mean-node: #000000;
+    --kerykeion-chart-color-chiron: #000000;
+    --kerykeion-chart-color-first-house: #000000;
+    --kerykeion-chart-color-tenth-house: #000000;
+    --kerykeion-chart-color-seventh-house: #000000;
+    --kerykeion-chart-color-fourth-house: #000000;
+    --kerykeion-chart-color-mean-lilith: #000000;
+    --kerykeion-chart-color-true-lilith: #000000;
+    --kerykeion-chart-color-ceres: #000000;
+    --kerykeion-chart-color-pallas: #000000;
+    --kerykeion-chart-color-juno: #000000;
+    --kerykeion-chart-color-vesta: #000000;
+    --kerykeion-chart-color-pars-fortunae: #000000;
+    --kerykeion-chart-color-vertex: #000000;
+    --kerykeion-chart-color-east-point: #000000;
+    --kerykeion-chart-color-eris: #000000;
+    --kerykeion-chart-color-earth: #000000;
+    --kerykeion-chart-color-pholus: #000000;
+    --kerykeion-chart-color-sedna: #000000;
+    --kerykeion-chart-color-haumea: #000000;
+    --kerykeion-chart-color-makemake: #000000;
+    --kerykeion-chart-color-ixion: #000000;
+    --kerykeion-chart-color-orcus: #000000;
+    --kerykeion-chart-color-quaoar: #000000;
+    --kerykeion-chart-color-regulus: #000000;
+    --kerykeion-chart-color-spica: #000000;
+    --kerykeion-chart-color-anti-vertex: #000000;
+
+    /* Arab Parts */
+    --kerykeion-chart-color-pars-spiritus: #000000;
+    --kerykeion-chart-color-pars-amoris: #000000;
+    --kerykeion-chart-color-pars-fortunae: #000000;
+    --kerykeion-chart-color-pars-fidei: #000000;
+
+    /* Zodiac Signs */
+    --kerykeion-chart-color-zodiac-icon-0: #000000;
+    --kerykeion-chart-color-zodiac-icon-1: #000000;
+    --kerykeion-chart-color-zodiac-icon-2: #000000;
+    --kerykeion-chart-color-zodiac-icon-3: #000000;
+    --kerykeion-chart-color-zodiac-icon-4: #000000;
+    --kerykeion-chart-color-zodiac-icon-5: #000000;
+    --kerykeion-chart-color-zodiac-icon-6: #000000;
+    --kerykeion-chart-color-zodiac-icon-7: #000000;
+    --kerykeion-chart-color-zodiac-icon-8: #000000;
+    --kerykeion-chart-color-zodiac-icon-9: #000000;
+    --kerykeion-chart-color-zodiac-icon-10: #000000;
+    --kerykeion-chart-color-zodiac-icon-11: #000000;
+
+    /* Elements Percentage */
+    --kerykeion-chart-color-air-percentage: #111111;
+    --kerykeion-chart-color-earth-percentage: #333333;
+    --kerykeion-chart-color-fire-percentage: #555555;
+    --kerykeion-chart-color-water-percentage: #777777;
+
+    /* Modalities Percentage */
+    --kerykeion-chart-color-cardinal-percentage: #222222;
+    --kerykeion-chart-color-fixed-percentage: #444444;
+    --kerykeion-chart-color-mutable-percentage: #666666;
+
+    /* 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: #000000;
+}

kerykeion/charts/themes/classic.css

@@ -79,6 +79,17 @@
     --kerykeion-chart-color-vertex: #52064e;
     --kerykeion-chart-color-east-point: #482b7f;
     --kerykeion-chart-color-eris: #800000;
+    --kerykeion-chart-color-earth: #6a2d04;
+    --kerykeion-chart-color-pholus: #5a5a5a;
+    --kerykeion-chart-color-sedna: #b8860b;
+    --kerykeion-chart-color-haumea: #8b4513;
+    --kerykeion-chart-color-makemake: #a0522d;
+    --kerykeion-chart-color-ixion: #556b2f;
+    --kerykeion-chart-color-orcus: #2f4f4f;
+    --kerykeion-chart-color-quaoar: #8a2be2;
+    --kerykeion-chart-color-regulus: #ffd700;
+    --kerykeion-chart-color-spica: #87ceeb;
+    --kerykeion-chart-color-anti-vertex: #4b0082;
 
     /* Arab Parts */
     --kerykeion-chart-color-pars-spiritus: #095242;

kerykeion/charts/themes/dark-high-contrast.css

@@ -107,6 +107,17 @@
     --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/charts/themes/dark.css

@@ -108,6 +108,17 @@
     --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/charts/themes/light.css

@@ -108,6 +108,17 @@
     --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/charts/themes/strawberry.css

@@ -107,6 +107,16 @@
     --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/composite_subject_factory.py

@@ -1,10 +1,50 @@
-from typing import Union, TYPE_CHECKING
+"""
+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
 
 # Fix the circular import by changing this import
 from kerykeion.astrological_subject_factory import AstrologicalSubjectFactory
-from kerykeion.kr_types.kerykeion_exception import KerykeionException
-from kerykeion.kr_types.kr_models import CompositeSubjectModel, AstrologicalSubjectModel
-from kerykeion.kr_types.kr_literals import ZodiacType, PerspectiveType, HousesSystemIdentifier, SiderealMode, AstrologicalPoint, Houses, CompositeChartType
+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,
@@ -17,15 +57,48 @@ from kerykeion.utilities import (
 
 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]
@@ -47,6 +120,27 @@ class CompositeSubjectFactory:
             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"
 
@@ -102,30 +196,114 @@ class CompositeSubjectFactory:
         self.houses_names_list = self.first_subject.houses_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:
@@ -165,12 +343,53 @@ class CompositeSubjectFactory:
             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.
+
+        Uses the composite positions of the Sun and Moon to determine the lunar phase
+        angle, representing the relationship's emotional and instinctual dynamics.
+
+        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()