kerykeion 5.0.0a9__py3-none-any.whl → 5.0.0a11__py3-none-any.whl

kerykeion/relationship_score_factory.py

@@ -1,34 +1,85 @@
 # -*- coding: utf-8 -*-
 """
-    This is part of Kerykeion (C) 2025 Giacomo Battaglia
+Relationship Score Factory Module
+
+This module calculates relationship scores between two astrological subjects using the
+Ciro Discepolo method. It analyzes synastry aspects to generate numerical compatibility
+scores with descriptive categories.
+
+Key Features:
+    - Point-based scoring system using synastry aspects
+    - Configurable major/minor aspect filtering
+    - Orbital precision weighting
+    - Categorical score descriptions
+
+Score Categories:
+    - 0-5: Minimal relationship
+    - 5-10: Medium relationship
+    - 10-15: Important relationship
+    - 15-20: Very important relationship
+    - 20-30: Exceptional relationship
+    - 30+: Rare exceptional relationship
+
+Classes:
+    RelationshipScoreFactory: Main factory for calculating relationship scores
+
+Example:
+    >>> from kerykeion import AstrologicalSubjectFactory
+    >>> from kerykeion.relationship_score_factory import RelationshipScoreFactory
+    >>>
+    >>> person1 = AstrologicalSubjectFactory.from_birth_data("John", 1990, 5, 15, 12, 0, "New York", "US")
+    >>> person2 = AstrologicalSubjectFactory.from_birth_data("Jane", 1988, 8, 22, 14, 30, "London", "GB")
+    >>> factory = RelationshipScoreFactory(person1, person2)
+    >>> score = factory.get_relationship_score()
+    >>> print(f"Score: {score.score_value} ({score.score_description})")
+
+Reference:
+    Ciro Discepolo Method: http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
+
+Author: Giacomo Battaglia
+Copyright: (C) 2025 Kerykeion Project
+License: AGPL-3.0
 """
 
 from kerykeion import AstrologicalSubjectFactory
-from kerykeion.aspects.synastry_aspects import SynastryAspects
+from kerykeion.aspects.synastry_aspects_factory import SynastryAspectsFactory
 import logging
-from pathlib import Path
-from typing import Union
 from kerykeion.kr_types.kr_models import AstrologicalSubjectModel, RelationshipScoreAspectModel, RelationshipScoreModel
 from kerykeion.kr_types.kr_literals import RelationshipScoreDescription
 
+# Scoring constants
+DESTINY_SIGN_POINTS = 5
+HIGH_PRECISION_ORBIT_THRESHOLD = 2
+MAJOR_ASPECT_POINTS_HIGH_PRECISION = 11
+MAJOR_ASPECT_POINTS_STANDARD = 8
+MINOR_ASPECT_POINTS = 4
+SUN_ASCENDANT_ASPECT_POINTS = 4
+MOON_ASCENDANT_ASPECT_POINTS = 4
+VENUS_MARS_ASPECT_POINTS = 4
+
 
 class RelationshipScoreFactory:
     """
-    Calculates the relevance of the relationship between two subjects using the Ciro Discepolo method.
+    Calculates relationship scores between two subjects using the Ciro Discepolo method.
 
-    Results:
-        - 0 to 5: Minimal relationship
-        - 5 to 10: Medium relationship
-        - 10 to 15: Important relationship
-        - 15 to 20: Very important relationship
-        - 20 to 35: Exceptional relationship
-        - 30 and above: Rare Exceptional relationship
+    The scoring system evaluates synastry aspects between planetary positions to generate
+    numerical compatibility scores with categorical descriptions.
 
-    Documentation: http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
+    Score Ranges:
+        - 0-5: Minimal relationship
+        - 5-10: Medium relationship
+        - 10-15: Important relationship
+        - 15-20: Very important relationship
+        - 20-30: Exceptional relationship
+        - 30+: Rare exceptional relationship
 
     Args:
-        first_subject (AstrologicalSubjectModel): First subject instance
-        second_subject (AstrologicalSubjectModel): Second subject instance
+        first_subject (AstrologicalSubjectModel): First astrological subject
+        second_subject (AstrologicalSubjectModel): Second astrological subject
+        use_only_major_aspects (bool, optional): Filter to major aspects only. Defaults to True.
+
+    Reference:
+        http://www.cirodiscepolo.it/Articoli/Discepoloele.htm
     """
 
     SCORE_MAPPING = [
@@ -56,24 +107,27 @@ class RelationshipScoreFactory:
         self.relationship_score_description: RelationshipScoreDescription = "Minimal"
         self.is_destiny_sign = True
         self.relationship_score_aspects: list[RelationshipScoreAspectModel] = []
-        self._synastry_aspects = SynastryAspects(self.first_subject, self.second_subject).all_aspects
+        self._synastry_aspects = SynastryAspectsFactory.from_subjects(self.first_subject, self.second_subject).all_aspects
 
     def _evaluate_destiny_sign(self):
         """
-        Evaluates if the subjects share the same sun sign quality and adds points if true.
+        Checks if subjects share the same sun sign quality and adds points.
+
+        Adds 5 points if both subjects have sun signs with matching quality
+        (cardinal, fixed, or mutable).
         """
-        if self.first_subject.sun["quality"] == self.second_subject.sun["quality"]:
+        if self.first_subject.sun["quality"] == self.second_subject.sun["quality"]: # type: ignore
             self.is_destiny_sign = True
-            self.score_value += 5
-            logging.debug(f"Destiny sign found, adding 5 points, total score: {self.score_value}")
+            self.score_value += DESTINY_SIGN_POINTS
+            logging.debug(f"Destiny sign found, adding {DESTINY_SIGN_POINTS} points, total score: {self.score_value}")
 
     def _evaluate_aspect(self, aspect, points):
         """
-        Evaluates an aspect and adds points to the score.
+        Processes an aspect and adds points to the total score.
 
         Args:
-            aspect (dict): Aspect information.
-            points (int): Points to add.
+            aspect (dict): Aspect data containing planetary positions and geometry
+            points (int): Points to add to the total score
         """
         if self.use_only_major_aspects and aspect["aspect"] not in self.MAJOR_ASPECTS:
             return
@@ -91,93 +145,100 @@ class RelationshipScoreFactory:
 
     def _evaluate_sun_sun_main_aspect(self, aspect):
         """
-        Evaluates Sun-Sun main aspects and adds points accordingly:
-        - 8 points for conjunction/opposition/square
-        - 11 points if the aspect's orbit is <= 2 degrees
+        Evaluates Sun-Sun conjunction, opposition, or square aspects.
+
+        Adds 8 points for standard orbs, 11 points for tight orbs (≤2°).
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if aspect["p1_name"] == "Sun" and aspect["p2_name"] == "Sun" and aspect["aspect"] in {"conjunction", "opposition", "square"}:
-            points = 11 if aspect["orbit"] <= 2 else 8
+            points = MAJOR_ASPECT_POINTS_HIGH_PRECISION if aspect["orbit"] <= HIGH_PRECISION_ORBIT_THRESHOLD else MAJOR_ASPECT_POINTS_STANDARD
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_sun_moon_conjunction(self, aspect):
         """
-        Evaluates Sun-Moon conjunctions and adds points accordingly:
-        - 8 points for conjunction
-        - 11 points if the aspect's orbit is <= 2 degrees
+        Evaluates Sun-Moon conjunction aspects.
+
+        Adds 8 points for standard orbs, 11 points for tight orbs (≤2°).
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Moon", "Sun"} and aspect["aspect"] == "conjunction":
-            points = 11 if aspect["orbit"] <= 2 else 8
+            points = MAJOR_ASPECT_POINTS_HIGH_PRECISION if aspect["orbit"] <= HIGH_PRECISION_ORBIT_THRESHOLD else MAJOR_ASPECT_POINTS_STANDARD
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_sun_sun_other_aspects(self, aspect):
         """
-        Evaluates Sun-Sun aspects that are not conjunctions and adds points accordingly:
-        - 4 points for other aspects
+        Evaluates Sun-Sun aspects other than conjunction, opposition, or square.
+
+        Adds 4 points for any qualifying aspect.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if aspect["p1_name"] == "Sun" and aspect["p2_name"] == "Sun" and aspect["aspect"] not in {"conjunction", "opposition", "square"}:
-            points = 4
+            points = MINOR_ASPECT_POINTS
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_sun_moon_other_aspects(self, aspect):
         """
-        Evaluates Sun-Moon aspects that are not conjunctions and adds points accordingly:
-        - 4 points for other aspects
+        Evaluates Sun-Moon aspects other than conjunctions.
+
+        Adds 4 points for any qualifying aspect.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Moon", "Sun"} and aspect["aspect"] != "conjunction":
-            points = 4
+            points = MINOR_ASPECT_POINTS
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_sun_ascendant_aspect(self, aspect):
         """
-        Evaluates Sun-Ascendant aspects and adds points accordingly:
-        - 4 points for any aspect
+        Evaluates Sun-Ascendant aspects.
+
+        Adds 4 points for any aspect between Sun and Ascendant.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Sun", "Ascendant"}:
-            points = 4
+            points = SUN_ASCENDANT_ASPECT_POINTS
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_moon_ascendant_aspect(self, aspect):
         """
-        Evaluates Moon-Ascendant aspects and adds points accordingly:
-        - 4 points for any aspect
+        Evaluates Moon-Ascendant aspects.
+
+        Adds 4 points for any aspect between Moon and Ascendant.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Moon", "Ascendant"}:
-            points = 4
+            points = MOON_ASCENDANT_ASPECT_POINTS
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_venus_mars_aspect(self, aspect):
         """
-        Evaluates Venus-Mars aspects and adds points accordingly:
-        - 4 points for any aspect
+        Evaluates Venus-Mars aspects.
+
+        Adds 4 points for any aspect between Venus and Mars.
 
         Args:
-            aspect (dict): Aspect information.
+            aspect (dict): Aspect data
         """
         if {aspect["p1_name"], aspect["p2_name"]} == {"Venus", "Mars"}:
-            points = 4
+            points = VENUS_MARS_ASPECT_POINTS
             self._evaluate_aspect(aspect, points)
 
     def _evaluate_relationship_score_description(self):
         """
-        Evaluates the relationship score description based on the total score.
+        Determines the categorical description based on the numerical score.
+
+        Maps the total score to predefined description ranges.
         """
         for description, threshold in self.SCORE_MAPPING:
             if self.score_value < threshold:
@@ -186,10 +247,11 @@ class RelationshipScoreFactory:
 
     def get_relationship_score(self):
         """
-        Calculates the relationship score based on synastry aspects.
+        Calculates the complete relationship score using all evaluation methods.
 
         Returns:
-            RelationshipScoreModel: The calculated relationship score.
+            RelationshipScoreModel: Score object containing numerical value, description,
+                destiny sign status, contributing aspects, and subject data.
         """
         self._evaluate_destiny_sign()
 
@@ -218,10 +280,12 @@ if __name__ == "__main__":
 
     setup_logging(level="critical")
 
-    john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-    yoko = AstrologicalSubjectFactory.from_birth_data("Yoko Ono", 1933, 2, 18, 18, 30, "Tokyo", "JP")
+    john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB", lng=53.416666, lat=-3, tz_str="Europe/London")
+    yoko = AstrologicalSubjectFactory.from_birth_data("Yoko Ono", 1933, 2, 18, 20, 30, "Tokyo", "JP", lng=35.68611, lat=139.7525, tz_str="Asia/Tokyo")
 
     factory = RelationshipScoreFactory(john, yoko)
     score = factory.get_relationship_score()
-    print(score)
 
+    # Remove subjects key
+    score.subjects = []
+    print(score.model_dump_json(indent=4))

kerykeion/report.py

@@ -1,7 +1,6 @@
 from kerykeion import AstrologicalSubjectFactory
 from simple_ascii_tables import AsciiTable
 from kerykeion.utilities import get_houses_list, get_available_astrological_points_list
-from typing import Union
 from kerykeion.kr_types.kr_models import AstrologicalSubjectModel
 
 class Report:
@@ -15,6 +14,12 @@ class Report:
     houses_table: str
 
     def __init__(self, instance: AstrologicalSubjectModel):
+        """
+        Initialize a new Report instance.
+
+        Args:
+            instance: The astrological subject model to create a report for.
+        """
         self.instance = instance
 
         self.get_report_title()
@@ -23,6 +28,7 @@ class Report:
         self.get_houses_table()
 
     def get_report_title(self) -> None:
+        """Generate the report title based on the subject's name."""
         self.report_title = f"\n+- Kerykeion report for {self.instance.name} -+"
 
     def get_data_table(self) -> None:

kerykeion/settings/__init__.py

@@ -1 +1,6 @@
 from .kerykeion_settings import KerykeionSettingsModel, get_settings
+
+__all__ = [
+    "KerykeionSettingsModel",
+    "get_settings",
+]

kerykeion/settings/config_constants.py

@@ -14,10 +14,10 @@ DEFAULT_ACTIVE_POINTS: List[AstrologicalPoint] = [
     "Uranus",
     "Neptune",
     "Pluto",
-    "Mean_Node",
-    # "True_Node",
-    "Mean_South_Node",
-    # "True_South_Node",
+    # "Mean_Node",
+    "True_Node",
+    # "Mean_South_Node",
+    "True_South_Node",
     "Chiron",
     "Mean_Lilith",
     # "True_Lilith",
@@ -38,8 +38,8 @@ DEFAULT_ACTIVE_POINTS: List[AstrologicalPoint] = [
     # "Spica",
     "Ascendant",
     "Medium_Coeli",
-    # "Descendant",
-    # "Imum_Coeli",
+    "Descendant",
+    "Imum_Coeli",
     # "Vertex",
     # "Anti_Vertex",
     # "Pars_Fortunae",
@@ -70,6 +70,20 @@ Default list of active aspects in the aspects calculations.
 The full list of aspects is available in the `kr_types.kr_literals.AspectName` literal.
 """
 
+DISCEPOLO_SCORE_ACTIVE_ASPECTS: List[ActiveAspect] = [
+    {"name": "conjunction", "orb": 8},
+    {"name": "semi-sextile", "orb": 2},
+    {"name": "semi-square", "orb": 2},
+    {"name": "sextile", "orb": 4},
+    {"name": "square", "orb": 5},
+    {"name": "trine", "orb": 7},
+    {"name": "sesquiquadrate", "orb": 2},
+    {"name": "opposition", "orb": 8},
+]
+"""
+List of active aspects with their orbs according to Ciro Discepolo's affinity scoring methodology.
+"""
+
 DEFAULT_AXIS_ORBIT: int = 1
 """
 Default orbit for the axes aspects.

kerykeion/settings/kr.config.json

@@ -85,6 +85,14 @@
             "Return": "Return",
             "natal": "Natal",
             "perspective_type": "Perspective",
+            "location": "Location",
+            "day_of_week": "Day of Week",
+            "elements": "Elements",
+            "qualities": "Qualities",
+            "cardinal": "Cardinal",
+            "fixed": "Fixed",
+            "mutable": "Mutable",
+            "birth_chart": "Birth Chart",
             "celestial_points": {
                 "Sun": "Sun",
                 "Moon": "Moon",
@@ -215,6 +223,14 @@
             "Return": "Révolution",
             "natal": "Radix",
             "perspective_type": "Perspective",
+            "location": "Lieu",
+            "day_of_week": "Jour de la semaine",
+            "elements": "Éléments",
+            "qualities": "Qualités",
+            "cardinal": "Cardinal",
+            "fixed": "Fixe",
+            "mutable": "Mutable",
+            "birth_chart": "Thème Natal",
             "celestial_points": {
                 "Sun": "Soleil",
                 "Moon": "Lune",
@@ -345,6 +361,14 @@
             "return_point": "Ponto (ret.)",
             "natal": "Natal",
             "perspective_type": "Perspectiva",
+            "location": "Localização",
+            "day_of_week": "Dia da semana",
+            "elements": "Elementos",
+            "qualities": "Qualidades",
+            "cardinal": "Cardinal",
+            "fixed": "Fixo",
+            "mutable": "Mutável",
+            "birth_chart": "Mapa Natal",
             "celestial_points": {
                 "Sun": "Sol",
                 "Moon": "Lua",
@@ -475,6 +499,14 @@
             "Return": "Ritorno",
             "natal": "Radix",
             "perspective_type": "Prospettiva",
+            "location": "Località",
+            "day_of_week": "Giorno della settimana",
+            "elements": "Elementi",
+            "qualities": "Qualità",
+            "cardinal": "Cardinale",
+            "fixed": "Fisso",
+            "mutable": "Mutevole",
+            "birth_chart": "Tema Natale",
             "celestial_points": {
                 "Sun": "Sole",
                 "Moon": "Luna",
@@ -605,6 +637,14 @@
             "Return": "回归",
             "natal": "本命",
             "perspective_type": "视角",
+            "location": "位置",
+            "day_of_week": "星期",
+            "elements": "元素",
+            "qualities": "性质",
+            "cardinal": "本位",
+            "fixed": "固定",
+            "mutable": "变动",
+            "birth_chart": "出生图",
             "celestial_points": {
                 "Sun": "太陽",
                 "Moon": "月亮",
@@ -735,6 +775,14 @@
             "return_point": "Punto (rev.)",
             "natal": "Radix",
             "perspective_type": "Perspectiva",
+            "location": "Ubicación",
+            "day_of_week": "Día de la semana",
+            "elements": "Elementos",
+            "qualities": "Cualidades",
+            "cardinal": "Cardinal",
+            "fixed": "Fijo",
+            "mutable": "Mutable",
+            "birth_chart": "Carta Natal",
             "celestial_points": {
                 "Sun": "Sol",
                 "Moon": "Luna",
@@ -865,6 +913,14 @@
             "Return": "Возвращение",
             "natal": "Радикс",
             "perspective_type": "Перспектива",
+            "location": "Местоположение",
+            "day_of_week": "День недели",
+            "elements": "Стихии",
+            "qualities": "Качества",
+            "cardinal": "Кардинальный",
+            "fixed": "Фиксированный",
+            "mutable": "Мутабельный",
+            "birth_chart": "Натальная Карта",
             "celestial_points": {
                 "Sun": "Солнце",
                 "Moon": "Луна",
@@ -995,6 +1051,14 @@
             "Return": "Dönüş",
             "natal": "Doğum haritası",
             "perspective_type": "Perspektif",
+            "location": "Konum",
+            "day_of_week": "Haftanın günü",
+            "elements": "Elementler",
+            "qualities": "Nitelikler",
+            "cardinal": "Kardinal",
+            "fixed": "Sabit",
+            "mutable": "Değişken",
+            "birth_chart": "Doğum Haritası",
             "celestial_points": {
                 "Sun": "Güneş",
                 "Moon": "Ay",
@@ -1125,6 +1189,14 @@
             "return_point": "Rückkehrpunkt",
             "natal": "Radix",
             "perspective_type": "Perspektive",
+            "location": "Ort",
+            "day_of_week": "Wochentag",
+            "elements": "Elemente",
+            "qualities": "Qualitäten",
+            "cardinal": "Kardinal",
+            "fixed": "Fix",
+            "mutable": "Veränderlich",
+            "birth_chart": "Geburtshoroskop",
             "celestial_points": {
                 "Sun": "Sonne",
                 "Moon": "Mond",
@@ -1255,6 +1327,14 @@
             "return_point": "पुनरागमन बिंदु",
             "natal": "जन्म कुंडली",
             "perspective_type": "दृष्टिकोण",
+            "location": "स्थान",
+            "day_of_week": "सप्ताह का दिन",
+            "elements": "तत्व",
+            "qualities": "गुण",
+            "cardinal": "चल",
+            "fixed": "स्थिर",
+            "mutable": "द्विस्वभाव",
+            "birth_chart": "जन्म चार्ट",
             "celestial_points": {
                 "Sun": "सूर्य",
                 "Moon": "चंद्रमा",