dialectical-framework 0.4.4__py3-none-any.whl

dialectical_framework/__init__.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+
+# Import all core Pydantic models that participate in potential circular dependencies.
+# The order of imports here ensures classes are defined before their `.model_rebuild()`
+# methods are called below.
+from .analyst.domain.assessable_cycle import AssessableCycle
+from .analyst.domain.cycle import Cycle
+from .analyst.domain.rationale import Rationale
+from .analyst.domain.spiral import Spiral
+from .analyst.domain.transformation import Transformation
+from .analyst.domain.transition import Transition
+from .analyst.domain.transition_cell_to_cell import TransitionCellToCell
+from .analyst.domain.transition_segment_to_segment import \
+    TransitionSegmentToSegment
+from .dialectical_component import DialecticalComponent
+from .protocols.assessable import Assessable
+from .protocols.ratable import Ratable
+from .synthesis import Synthesis
+from .wheel import Wheel
+from .wheel_segment import WheelSegment
+from .wisdom_unit import WisdomUnit
+
+# Explicitly call `model_rebuild()` on all models that might have forward references
+# or be part of circular dependencies. This forces Pydantic to resolve their schemas
+# after all classes are defined in the module.
+# The order of these rebuild calls is generally from base classes to derived classes,
+# or simply ensuring all interdependent models are covered.
+
+Assessable.model_rebuild()
+Ratable.model_rebuild()
+DialecticalComponent.model_rebuild()
+Rationale.model_rebuild()
+Synthesis.model_rebuild()
+Wheel.model_rebuild()
+WheelSegment.model_rebuild()
+Transition.model_rebuild()
+TransitionCellToCell.model_rebuild()
+TransitionSegmentToSegment.model_rebuild()
+AssessableCycle.model_rebuild()
+Cycle.model_rebuild()
+Spiral.model_rebuild()
+Transformation.model_rebuild()
+WisdomUnit.model_rebuild()

dialectical_framework/ai_dto/causal_cycle_assessment_dto.py

@@ -0,0 +1,16 @@
+
+from pydantic import BaseModel, Field
+
+
+class CausalCycleAssessmentDto(BaseModel):
+    probability: float = Field(
+        default=0,
+        description="The probability 0 to 1 of the arranged cycle to exist in reality.",
+    )
+    reasoning_explanation: str = Field(
+        default="", description="Explanation why/how this cycle might occur."
+    )
+    argumentation: str = Field(
+        default="",
+        description="Circumstances or contexts where this cycle would be most applicable or useful.",
+    )

dialectical_framework/ai_dto/causal_cycle_dto.py

@@ -0,0 +1,16 @@
+
+from pydantic import Field
+
+from dialectical_framework.ai_dto.causal_cycle_assessment_dto import \
+    CausalCycleAssessmentDto
+
+
+class CausalCycleDto(CausalCycleAssessmentDto):
+    """
+    Causal circular sequence of statements, where aliases reference each statement
+    """
+
+    aliases: list[str] = Field(
+        ...,
+        description="Aliases (not the explicit statements) arranged in the circular causality sequence (cycle) where the last element points to the first",
+    )

dialectical_framework/ai_dto/causal_cycles_deck_dto.py

@@ -0,0 +1,11 @@
+
+from pydantic import BaseModel, Field
+
+from dialectical_framework.ai_dto.causal_cycle_dto import CausalCycleDto
+
+
+class CausalCyclesDeckDto(BaseModel):
+    causal_cycles: list[CausalCycleDto] = Field(
+        ...,
+        description="A list of causal circular sequences (cycles). It might also be filled with only one if only one is to be found.",
+    )

dialectical_framework/ai_dto/dialectical_component_dto.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel, Field
+
+
+class DialecticalComponentDto(BaseModel):
+    alias: str = Field(
+        ...,
+        description="The user friendly name of the dialectical component such as T, A, T+, A+, etc.",
+    )
+    statement: str = Field(
+        ...,
+        description="The dialectical component value that is provided after analysis.",
+    )
+    explanation: str = Field(
+        default="",
+        description="The explanation how the dialectical component (statement) is derived.",
+    )

dialectical_framework/ai_dto/dialectical_components_deck_dto.py

@@ -0,0 +1,12 @@
+
+from pydantic import BaseModel, Field
+
+from dialectical_framework.ai_dto.dialectical_component_dto import \
+    DialecticalComponentDto
+
+
+class DialecticalComponentsDeckDto(BaseModel):
+    dialectical_components: list[DialecticalComponentDto] = Field(
+        ...,
+        description="A list of dialectical components. It can be empty when no dialectical components are found. It might also be filled with only one dialectical component if only one is to be found.",
+    )

dialectical_framework/ai_dto/dto_mapper.py

@@ -0,0 +1,103 @@
+from typing import Dict, Generic, Type, TypeVar
+
+from pydantic import BaseModel
+
+from dialectical_framework import DialecticalComponent, Rationale
+from dialectical_framework.ai_dto.dialectical_component_dto import DialecticalComponentDto
+
+# Type variables for generic mapping
+DtoType = TypeVar('DtoType', bound=BaseModel)
+ModelType = TypeVar('ModelType', bound=BaseModel)
+
+
+class DtoMapper(Generic[DtoType, ModelType]):
+    """
+    Generic auto-mapper that uses field introspection to map between DTOs and models.
+    Works when models have compatible field names.
+    """
+
+    def __init__(self, dto_class: Type[DtoType], model_class: Type[ModelType]):
+        self.dto_class = dto_class
+        self.model_class = model_class
+
+    def map_from_dto(self, dto: DtoType, **kwargs) -> ModelType:
+        """
+        Auto-maps from DTO to model using common fields plus any additional kwargs.
+        """
+        # Get DTO field values
+        dto_data = dto.model_dump()
+
+        # Merge with additional kwargs (kwargs take precedence)
+        merged_data = {**dto_data, **kwargs}
+
+        # Filter to only include fields that exist in the target model
+        model_fields = self.model_class.model_fields.keys()
+        filtered_data = {k: v for k, v in merged_data.items() if k in model_fields}
+
+        return self.model_class(**filtered_data)
+
+    def map_list_from_dto(self, dtos: list[DtoType], **kwargs) -> list[ModelType]:
+        """
+        Maps a list of DTOs to domain models.
+
+        Args:
+            dtos: List of DTO instances to convert
+            **kwargs: Additional parameters for mapping
+
+        Returns:
+            List of domain model instances
+        """
+        return [self.map_from_dto(dto, **kwargs) for dto in dtos]
+
+class DialecticalComponentMapper(DtoMapper[DialecticalComponentDto, DialecticalComponent]):
+    def map_from_dto(self, dto: DialecticalComponentDto, **kwargs) -> ModelType:
+        mapped: DialecticalComponent = super().map_from_dto(dto, **kwargs)
+        if dto.explanation:
+            mapped.rationales.append(Rationale(
+                text=dto.explanation,
+            ))
+        return mapped
+
+# Registry for mappers
+_mapper_registry: Dict[tuple[Type, Type], DtoMapper] = {
+    # Use default DtoMapper if no specific mapper is registered
+
+    (DialecticalComponentDto, DialecticalComponent): DialecticalComponentMapper(DialecticalComponentDto, DialecticalComponent),
+}
+
+
+def register_mapper(dto_class: Type[DtoType], model_class: Type[ModelType], mapper: DtoMapper[DtoType, ModelType]):
+    """
+    Register a mapper for a specific DTO-Model pair.
+    """
+    _mapper_registry[(dto_class, model_class)] = mapper
+
+
+def get_mapper(dto_class: Type[DtoType], model_class: Type[ModelType]) -> DtoMapper[DtoType, ModelType]:
+    """
+    Get a mapper for a specific DTO-Model pair.
+    If no specific mapper is registered, returns an AutoMapper.
+    """
+    key = (dto_class, model_class)
+    if key in _mapper_registry:
+        return _mapper_registry[key]
+
+    # Return auto-mapper as fallback
+    return DtoMapper(dto_class, model_class)
+
+
+def map_from_dto(dto: DtoType, model_class: Type[ModelType], **kwargs) -> ModelType:
+    """
+    Convenience function to map from DTO to model.
+    """
+    mapper = get_mapper(type(dto), model_class)
+    return mapper.map_from_dto(dto, **kwargs)
+
+def map_list_from_dto(dtos: list[DtoType], model_class: Type[ModelType], **kwargs) -> list[ModelType]:
+    """
+    Convenience function to map a list of DTOs to domain models.
+    """
+    if not dtos:
+        return []
+    mapper = get_mapper(type(dtos[0]), model_class)
+    return mapper.map_list_from_dto(dtos, **kwargs)

dialectical_framework/ai_dto/reciprocal_solution_dto.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ReciprocalSolutionDto(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    problem: str | None = Field(default=None, description="Problem statement")
+    linear_action: str | None = Field(
+        default=None, description="Solution(s) that transforms T- into A+"
+    )
+    dialectical_reflection: str | None = Field(
+        default=None, description="Complementary solution(s) that transforms A- into T+"
+    )
+
+    def __str__(self):
+        str_pieces = []
+        if self.problem:
+            str_pieces.append(f"Problem: {self.problem}")
+        if self.linear_action:
+            str_pieces.append(f"Linear action: {self.linear_action}")
+        if self.dialectical_reflection:
+            str_pieces.append(f"Dialectical reflection: {self.dialectical_reflection}")
+        return "\n".join(str_pieces)

dialectical_framework/analyst/__init__.py

@@ -0,0 +1 @@
+

dialectical_framework/analyst/consultant.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from dialectical_framework.analyst.domain.transition import Transition
+from dialectical_framework.brain import Brain
+from dialectical_framework.protocols.has_brain import HasBrain
+from dialectical_framework.wheel import Wheel
+
+
+class Consultant(ABC, HasBrain):
+    def __init__(
+        self,
+        *,
+        text: str,
+        wheel: Wheel,
+        brain: Optional[Brain] = None,
+    ):
+        self._text = text
+        self._wheel = wheel
+        self._brain = brain
+
+    @property
+    def brain(self) -> Brain:
+        return super().brain if self._brain is None else self._brain
+
+    @abstractmethod
+    async def rationalize(self, transition: Transition) -> Transition: ...
+    """
+    The main method of the class. It should return an enriched Transition with the new rationale.
+    """

dialectical_framework/analyst/decorator_action_reflection.py

@@ -0,0 +1,28 @@
+from dialectical_framework.analyst.domain.transition_segment_to_segment import \
+    TransitionSegmentToSegment
+from dialectical_framework.analyst.think_action_reflection import \
+    ThinkActionReflection
+from dialectical_framework.analyst.wheel_builder_transition_calculator import \
+    WheelBuilderTransitionCalculator
+from dialectical_framework.wheel import Wheel
+from dialectical_framework.wheel_segment import WheelSegment
+
+
+class DecoratorActionReflection(WheelBuilderTransitionCalculator):
+    async def _do_calculate_transitions(
+        self, wheel: Wheel, at: WheelSegment
+    ) -> list[TransitionSegmentToSegment]:
+        consultant = ThinkActionReflection(
+            text=self.text, wheel=wheel, brain=self.reasoner.brain
+        )
+
+        return await consultant.think(focus=at)
+
+    async def _do_calculate_transitions_all(
+        self, wheel: Wheel
+    ) -> list[TransitionSegmentToSegment]:
+        result: list[TransitionSegmentToSegment] = []
+        for wu in wheel.wisdom_units:
+            tr = await self._do_calculate_transitions(wheel, wu)
+            result.extend(tr)
+        return result

dialectical_framework/analyst/decorator_discrete_spiral.py

@@ -0,0 +1,30 @@
+
+from dialectical_framework.analyst.domain.transition_segment_to_segment import \
+    TransitionSegmentToSegment
+from dialectical_framework.analyst.think_constructive_convergence import \
+    ThinkConstructiveConvergence
+from dialectical_framework.analyst.wheel_builder_transition_calculator import \
+    WheelBuilderTransitionCalculator
+from dialectical_framework.wheel import Wheel
+from dialectical_framework.wheel_segment import WheelSegment
+
+
+class DecoratorDiscreteSpiral(WheelBuilderTransitionCalculator):
+    async def _do_calculate_transitions(
+        self, wheel: Wheel, at: WheelSegment
+    ) -> list[TransitionSegmentToSegment]:
+        consultant = ThinkConstructiveConvergence(
+            text=self.text, wheel=wheel, brain=self.reasoner.brain
+        )
+
+        return [await consultant.think(at)]
+
+    async def _do_calculate_transitions_all(
+        self, wheel: Wheel
+    ) -> list[TransitionSegmentToSegment]:
+        # TODO: use a single prompt to derive all transitions faster?
+        result: list[TransitionSegmentToSegment] = []
+        for i in range(wheel.degree):
+            tr = await self._do_calculate_transitions(wheel, wheel.wheel_segment_at(i))
+            result.extend(tr)
+        return result

dialectical_framework/analyst/domain/assessable_cycle.py

@@ -0,0 +1,128 @@
+from abc import ABC
+
+from pydantic import ConfigDict, Field
+
+from dialectical_framework.analyst.domain.transition import Transition
+from dialectical_framework.directed_graph import DirectedGraph
+from dialectical_framework.protocols.assessable import Assessable
+from dialectical_framework.utils.decompose_probability_uniformly import decompose_probability_uniformly
+
+
+class AssessableCycle(Assessable, ABC):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    graph: DirectedGraph[Transition] = Field(
+        default=None,
+        description="Directed graph representing the cycle of dialectical components.",
+    )
+
+    def _get_sub_assessables(self) -> list[Assessable]:
+        result = super()._get_sub_assessables()
+        result.extend(self.graph.get_all_transitions())
+        return result
+
+    def _calculate_contextual_fidelity_for_sub_elements_excl_rationales(self, *, mutate: bool = True) -> list[float]:
+        """
+        Calculates the cycle fidelity (CF_S) as the geometric mean of:
+        1. All dialectical components' contextual fidelity scores within the cycle's transitions
+        2. All cycle-level rationales/opinions (weighted by their rating)
+
+        Components/rationales with contextual_fidelity of 0.0 or None are excluded from the calculation.
+        """
+        parts = []
+
+        # Collect fidelities from dialectical components
+        transitions = self.graph.get_all_transitions()
+        if transitions:
+            for transition in transitions:
+                parts.append(transition.calculate_contextual_fidelity(mutate=mutate))
+
+        return parts
+
+    def calculate_probability(self, *, mutate: bool = True) -> float | None:
+        """
+        Pr(Cycle) = product of ALL transition probabilities, in order.
+        - If any transition Pr is 0.0 -> 0.0 (hard veto)
+        - If any transition Pr is None -> None (unknown)
+        - Else product of all
+        No cycle-level opinions here.
+        """
+        transitions: list[Transition] = self.graph.first_path()  # ensure this is the ordered full cycle
+        if not transitions:
+            prob = None
+        else:
+            prob = 1.0
+            for tr in transitions:
+                p = tr.calculate_probability(mutate=mutate)
+                if p is None:
+                    prob = None
+                    break
+                if p == 0.0:
+                    prob = 0.0
+                    break
+                prob *= p
+
+        if mutate:
+            self.probability = prob
+        return prob
+
+def decompose_probability_into_transitions(
+        probability: float,
+        transitions: list[Transition],
+        overwrite_existing_transition_probabilities: bool = False
+) -> None:
+    """
+    **Case 1: No existing probabilities**
+    - Uses uniform decomposition: `cycle_prob^(1/n)` for all transitions
+
+    **Case 2: All transitions have probabilities**
+    - Does nothing - respects existing assignments
+
+    **Case 3: Mixed (some have, some don't)**
+    - Calculates "remaining probability" after accounting for assigned ones
+    - Distributes remaining probability uniformly among unassigned transitions
+
+    """
+    if not transitions:
+        return
+
+    if overwrite_existing_transition_probabilities:
+        for t in transitions:
+            t.probability = None
+
+    # Check which transitions already have probabilities
+    transitions_with_probs = [t for t in transitions if t.probability is not None and t.probability != 0]
+    transitions_without_probs = [t for t in transitions if t.probability is None or t.probability == 0]
+
+    if not transitions_without_probs:
+        # All transitions already have probabilities - don't override
+        return
+
+    if not transitions_with_probs:
+        # No transitions have probabilities - use uniform decomposition
+        individual_prob = decompose_probability_uniformly(
+            probability,
+            len(transitions)
+        )
+        for transition in transitions:
+            transition.manual_probability = individual_prob
+    else:
+        # Mixed case: some have probabilities, some don't
+        # Calculate what's "left over" for the unassigned transitions
+        assigned_prob_product = 1.0
+        for transition in transitions_with_probs:
+            assigned_prob_product *= transition.probability
+
+        # Remaining probability to distribute
+        remaining_prob = probability / assigned_prob_product if assigned_prob_product > 0 else probability
+
+        # Distribute remaining probability uniformly among unassigned transitions
+        if transitions_without_probs and remaining_prob > 0:
+            individual_prob = decompose_probability_uniformly(
+                remaining_prob,
+                len(transitions_without_probs)
+            )
+            for transition in transitions_without_probs:
+                transition.probability = individual_prob

dialectical_framework/analyst/domain/cycle.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from dialectical_framework.analyst.domain.assessable_cycle import \
+    AssessableCycle
+from dialectical_framework.analyst.domain.transition_cell_to_cell import \
+    TransitionCellToCell
+from dialectical_framework.dialectical_component import DialecticalComponent
+from dialectical_framework.dialectical_components_deck import \
+    DialecticalComponentsDeck
+from dialectical_framework.directed_graph import DirectedGraph
+from dialectical_framework.enums.causality_type import CausalityType
+from dialectical_framework.enums.predicate import Predicate
+
+
+class Cycle(AssessableCycle):
+    model_config = ConfigDict(
+        extra="forbid",
+        arbitrary_types_allowed=True,
+    )
+
+    causality_type: CausalityType = Field(
+        ..., description="The type of causality in the cycle."
+    )
+    causality_direction: Literal["clockwise", "counterclockwise"] = Field(
+        default="clockwise", description="The direction of causality in the ring."
+    )
+
+    argumentation: str = Field(
+        default="",
+        description="Circumstances or contexts where this cycle would be most applicable or useful.",
+    )
+
+    def __init__(
+        self,
+        dialectical_components: list[DialecticalComponent],
+        causality_type: CausalityType = CausalityType.REALISTIC,
+        **data,
+    ):
+        data["causality_type"] = causality_type
+        super().__init__(**data)
+        if self.graph is None:
+            self.graph = DirectedGraph[TransitionCellToCell]()
+            for i in range(len(dialectical_components)):
+                next_i = (i + 1) % len(dialectical_components)
+                if self.causality_direction == "clockwise":
+                    source = dialectical_components[i]
+                    target = dialectical_components[next_i]
+                else:
+                    source = dialectical_components[next_i]
+                    target = dialectical_components[i]
+
+                self.graph.add_transition(
+                    TransitionCellToCell(
+                        source=source,
+                        predicate=Predicate.CAUSES,
+                        target=target,
+                        # TODO: how do we set the transition text?
+                    )
+                )
+
+    @property
+    def dialectical_components(self) -> list[DialecticalComponent]:
+        """Returns list of dialectical components from the first path of the ring."""
+        path = self.graph.first_path()
+        return [transition.source for transition in path] if path else []
+
+    def cycle_str(self) -> str:
+        """Returns a string representation of the cycle sequence."""
+        aliases = [dc.alias for dc in self.dialectical_components]
+        if not aliases:
+            return ""
+        if len(aliases) == 1:
+            return f"{aliases[0]} → {aliases[0]}..."
+        return " → ".join(aliases) + f" → {aliases[0]}..."
+
+    def is_same_structure(self, other: Cycle) -> bool:
+        """Check if cycles represent the same sequence regardless of starting point."""
+        self_aliases = DialecticalComponentsDeck(
+            dialectical_components=self.dialectical_components
+        ).get_aliases()
+
+        other_aliases = DialecticalComponentsDeck(
+            dialectical_components=other.dialectical_components
+        ).get_aliases()
+
+        # Same length check
+        if len(self_aliases) != len(other_aliases):
+            return False
+
+        # Convert to sets for same elements check
+        if set(self_aliases) != set(other_aliases):
+            return False
+
+        # Check rotations only if sets are equal
+        if len(self_aliases) <= 1:
+            return True
+
+        return any(
+            self_aliases == other_aliases[i:] + other_aliases[:i]
+            for i in range(len(other_aliases))
+        )
+
+    def pretty(
+        self,
+        *,
+        skip_dialectical_component_explanation=False,
+        start_alias: str | DialecticalComponent | None = None,
+    ) -> str:
+        output = [self.graph.pretty() + f" | Probability: {self.probability}"]
+
+        path = self.graph.first_path(
+            start_aliases=[start_alias] if start_alias else None
+        )
+        if not path:
+            raise ValueError(
+                f"No path found between {start_alias} and the first dialectical component in the cycle."
+            )
+        for transition in path:
+            dc = transition.source
+            output.append(
+                dc.pretty(skip_explanation=skip_dialectical_component_explanation)
+            )
+
+        output.append(f"Rationale: {self.best_rationale.text if self.best_rationale else ''}")
+
+        return "\n".join(output)
+
+    def __str__(self):
+        return self.pretty()

dialectical_framework/analyst/domain/interpretation.py

@@ -0,0 +1,16 @@
+
+from pydantic import BaseModel, Field
+
+from dialectical_framework.analyst.domain.cycle import Cycle
+from dialectical_framework.analyst.domain.spiral import Spiral
+from dialectical_framework.analyst.domain.transformation import Transformation
+from dialectical_framework.wheel import Wheel
+
+
+class Interpretation(BaseModel):
+    wheel: Wheel
+    coherence: float = Field(default=0.0, description="geometric mean of all cycle probabilities")
+    t_cycle: Cycle
+    ta_cycle: Cycle
+    spiral: Spiral
+    transformations: list[Transformation]