dialectical-framework 0.4.4__py3-none-any.whl

dialectical_framework/analyst/domain/rationale.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import Optional, List
+
+from pydantic import Field
+
+from dialectical_framework.protocols.assessable import Assessable
+from dialectical_framework.protocols.ratable import Ratable
+from dialectical_framework.utils.gm import gm_with_zeros_and_nones_handled
+from dialectical_framework.wheel import Wheel
+
+class Rationale(Ratable):
+    headline: Optional[str] = Field(default=None)
+    summary: Optional[str] = Field(default=None)
+    text: Optional[str] = Field(default=None)
+    theses: list[str] = Field(default_factory=list, description="Theses of the rationale text.")
+    wheels: list[Wheel] = Field(default_factory=list, description="Wheels that are digging deeper into the rationale.")
+
+    def _hard_veto_on_own_zero(self) -> bool:
+        """
+        Why not veto Rationale by default
+
+        Rationale is commentary/evidence, not structure. It can be refuted by critiques or outweighed by spawned wheels. One mistaken rationale with CF=0 shouldn’t nuke the parent.
+
+        You already have a safe “off” switch: set rationale.rating = 0 → its contribution is ignored without collapsing CF to 0.
+
+        True veto belongs at structural leaves (Components, Transitions), where “this is contextually impossible” should indeed zero things.
+        """
+        return False
+
+    def _get_sub_assessables(self) -> list[Assessable]:
+        result = super()._get_sub_assessables()
+        result.extend(self.wheels)
+        return result
+
+    def _calculate_contextual_fidelity_for_sub_elements_excl_rationales(self, *, mutate: bool = True) -> list[float]:
+        """
+        CF(rationale) is evidence-driven:
+          - If there is child evidence (wheels/critiques), aggregate it.
+          - Otherwise, fall back to the rationale's own CF × rating (via get_fidelity()).
+        Do NOT apply self.get_rating() to child wheels; the parent that consumes this
+        rationale will apply rationale.rating to CF(rationale).
+        """
+        parts: list[float] = []
+
+        # Wheels spawned by this rationale — include as-is (no rating here)
+        for wheel in self.wheels:
+            w_cf = wheel.calculate_contextual_fidelity(mutate=mutate)
+            if w_cf is not None and w_cf > 0.0:
+                parts.append(w_cf)
+
+        return parts
+
+    def calculate_contextual_fidelity_evidence(self, *, mutate: bool = True) -> float | None:
+        parts: List[float] = []
+
+        # Critiques (child rationales) — recurse using EVIDENCE path
+        if self.rationales:
+            for r in self.rationales:
+                cf = r.calculate_contextual_fidelity_evidence(mutate=mutate)
+                if cf is not None and cf > 0.0:
+                    parts.append(cf)
+
+        # Wheels spawned by this rationale (unrated here)
+        for w in self.wheels:
+            cf = w.calculate_contextual_fidelity(mutate=mutate)
+            if cf is not None and cf > 0.0:
+                parts.append(cf)
+
+        # Own intrinsic CF (manual only), unweighted here
+        own_cf = self.contextual_fidelity
+        if own_cf is not None:
+            if own_cf == 0.0 and self._hard_veto_on_own_zero():
+                return 0.0  # explicit veto only if you enabled it for rationales
+            if own_cf > 0.0:
+                parts.append(own_cf)
+
+        # If no real CF signal, return None so parent SKIPS this rationale
+        return gm_with_zeros_and_nones_handled(parts) if parts else None
+
+    def calculate_contextual_fidelity(self, *, mutate: bool = True) -> float:
+        # ---- SELF-SCORING PATH (for the rationale itself). Allows neutral fallback = 1.0. ----
+        cf_e = self.calculate_contextual_fidelity_evidence(mutate=mutate)
+        fidelity = 1.0 if cf_e is None else cf_e
+
+        # IMPORTANT: do NOT write derived CF back into contextual_fidelity
+        # That field remains manual-only; writing here would be mistaken as evidence later.
+        return fidelity
+
+    def calculate_probability_evidence(self, *, mutate: bool = True) -> float | None:
+        parts: list[float] = []
+
+        # 1) Wheels spawned by this rationale
+        for wheel in self.wheels:
+            p = wheel.calculate_probability(mutate=mutate)
+            if p is not None:
+                parts.append(p)
+
+        # 2) Critiques as rationales (include their full probability, not just their wheels)
+        for critique in self.rationales:
+            p = critique.calculate_probability_evidence(mutate=mutate)
+            if p is not None:
+                parts.append(p)
+
+        # Child-first: if children exist, use them
+        return gm_with_zeros_and_nones_handled(parts) if parts else None
+
+    def calculate_probability(self, *, mutate: bool = True) -> float | None:
+        probability = self.calculate_probability_evidence(mutate=True)
+
+        if probability is None:
+            return 1.0
+
+        if mutate:
+            self.probability = probability
+        return probability

dialectical_framework/analyst/domain/spiral.py

@@ -0,0 +1,47 @@
+
+from pydantic import ConfigDict
+
+from dialectical_framework.analyst.domain.assessable_cycle import \
+    AssessableCycle
+from dialectical_framework.analyst.domain.transition_segment_to_segment import \
+    TransitionSegmentToSegment
+from dialectical_framework.directed_graph import DirectedGraph
+from dialectical_framework.wheel_segment import WheelSegment
+
+
+class Spiral(AssessableCycle):
+    model_config = ConfigDict(
+        extra="forbid",
+        arbitrary_types_allowed=True,
+    )
+
+    def __init__(self, graph: DirectedGraph[TransitionSegmentToSegment] = None, **data):
+        super().__init__(**data)
+        if self.graph is None:
+            self.graph = (
+                graph
+                if graph is not None
+                else DirectedGraph[TransitionSegmentToSegment]()
+            )
+
+    def pretty(self, *, start_wheel_segment: WheelSegment) -> str:
+        output = []
+
+        source_aliases_list = self.graph.find_outbound_source_aliases(
+            start=start_wheel_segment
+        )
+        for source_aliases in source_aliases_list:
+            output.append(self.graph.pretty(start_aliases=source_aliases))
+            path = self.graph.first_path(start_aliases=source_aliases)
+            if path:
+                for transition in path:
+                    output.append(str(transition))
+            else:
+                raise ValueError(f"No path found from {source_aliases}.")
+
+        return "\n".join(output)
+
+    def __str__(self):
+        return self.pretty(
+            start_wheel_segment=self.graph.get_all_transitions()[0].source
+        )

dialectical_framework/analyst/domain/transformation.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from dialectical_framework.protocols.assessable import Assessable
+from dialectical_framework.analyst.domain.spiral import Spiral
+from dialectical_framework.wisdom_unit import WisdomUnit
+
+
+class Transformation(Spiral):
+    model_config = ConfigDict(
+        extra="forbid",
+        arbitrary_types_allowed=True,
+    )
+
+    ac_re: WisdomUnit = Field(..., description="Action-reflection wisdom unit")
+
+    def _get_sub_assessables(self) -> list[Assessable]:
+        result = super()._get_sub_assessables()
+        result.append(self.ac_re)
+        return result
+
+    def _calculate_contextual_fidelity_for_sub_elements_excl_rationales(self, *, mutate: bool = True) -> list[float]:
+        return [self.ac_re.calculate_contextual_fidelity(mutate=mutate)]

dialectical_framework/analyst/domain/transition.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from typing import Tuple, Union
+
+from pydantic import ConfigDict, Field, field_validator
+
+from dialectical_framework.protocols.assessable import Assessable
+from dialectical_framework.dialectical_component import DialecticalComponent
+from dialectical_framework.enums.predicate import Predicate
+from dialectical_framework.protocols.ratable import Ratable
+from dialectical_framework.utils.gm import gm_with_zeros_and_nones_handled
+from dialectical_framework.wheel_segment import WheelSegment
+
+
+class Transition(Ratable):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    source_aliases: list[str] = Field(
+        default_factory=list, description="Aliases of the source segment of the wheel."
+    )
+    source: Union[WheelSegment, DialecticalComponent] = Field(
+        description="Source segment of the wheel or dialectical component."
+    )
+
+    target_aliases: list[str] = Field(
+        default_factory=list, description="Aliases of the target segment of the wheel."
+    )
+    target: Union[WheelSegment, DialecticalComponent] = Field(
+        description="Target segment of the wheel or dialectical component."
+    )
+
+    predicate: Predicate = Field(
+        ...,
+        description="The type of relationship between the source and target, e.g. T1 => causes => T2.",
+    )
+
+    manual_probability: float | None = Field(
+        default=None,
+        ge=0.0, le=1.0,
+        description="The normalized probability (Pr(S)) of the cycle to exist in reality.",
+    )
+
+    def _get_sub_assessables(self) -> list[Assessable]:
+        """
+        Don't add source/target here, as these are part of the wheel, and we'll end up infinitely recursing.
+        """
+        return super()._get_sub_assessables()
+
+    def get_key(self) -> Tuple[frozenset[str], frozenset[str]]:
+        """Get the key used to uniquely identify this transition based on source and target aliases."""
+        return (
+            frozenset(self.source_aliases),
+            frozenset(self.target_aliases),
+        )
+
+    @property
+    def advice(self) -> str | None:
+        r = self.best_rationale
+        if r:
+            return r.text
+        else:
+            return None
+
+    def calculate_probability(self, *, mutate: bool = True) -> float | None:
+        parts: list[float] = []
+
+        # Own manual probability (optional) × own confidence
+        p_self = self.manual_probability
+        if p_self is not None:
+            w_self = self.confidence_or_default()
+            if w_self > 0.0:
+                # include 0.0 if p_self==0 and w_self>0 (explicit veto is allowed at the leaf)
+                parts.append(p_self * w_self)
+
+        # Rationale probabilities × rationale confidence
+        for rationale in (self.rationales or []):
+            # NOTE: We rely on the evidence, not on the fallback value, that's important
+            p = rationale.calculate_probability_evidence(mutate=mutate)
+            if p is None:
+                continue
+            w = rationale.confidence_or_default()
+            v = p * w
+            if v > 0.0:  # skip non-positive after weighting
+                parts.append(v)
+
+        probability = gm_with_zeros_and_nones_handled(parts) if parts else None
+
+        if mutate:
+            self.probability = probability
+        return probability
+
+    @field_validator("source_aliases")
+    def validate_source_aliases(cls, v: list[str], info) -> list[str]: # Change list[str] from list[str]
+        if "source" in info.data and info.data["source"]:
+            source = info.data["source"]
+            valid_aliases = []
+
+            if isinstance(source, DialecticalComponent):
+                valid_aliases = [source.alias]
+            elif isinstance(source, WheelSegment):
+                # Extract aliases from all non-None components in the WheelSegment
+                for component in [source.t, source.t_plus, source.t_minus]:
+                    if component:
+                        valid_aliases.append(component.alias)
+
+            invalid_aliases = [alias for alias in v if alias not in valid_aliases]
+            if invalid_aliases:
+                raise ValueError(
+                    f"Invalid source aliases: {invalid_aliases}. Valid aliases: {valid_aliases}"
+                )
+        return v
+
+    @field_validator("target_aliases")
+    def validate_target_aliases(cls, v: list[str], info) -> list[str]: # Change list[str] from list[str]
+        if "target" in info.data and info.data["target"]:
+            target = info.data["target"]
+            valid_aliases = []
+
+            if isinstance(target, DialecticalComponent):
+                valid_aliases = [target.alias]
+            elif isinstance(target, WheelSegment):
+                # Extract aliases from all non-None components in the WheelSegment
+                for component in [target.t, target.t_plus, target.t_minus]:
+                    if component:
+                        valid_aliases.append(component.alias)
+
+            invalid_aliases = [alias for alias in v if alias not in valid_aliases]
+            if invalid_aliases:
+                raise ValueError(
+                    f"Invalid target aliases: {invalid_aliases}. Valid aliases: {valid_aliases}"
+                )
+        return v
+
+    def new_with(self, other: Transition) -> Transition:
+        self_dict = self.model_dump()
+        other_dict = other.model_dump()
+
+        merged_dict = {**other_dict}  # Start with other values
+        # Override with self values that are not None
+        for key, value in self_dict.items():
+            if value is not None:
+                merged_dict[key] = value
+
+        new_t_class: type[Transition] = type(self)
+        if not isinstance(other, Transition):
+            new_t_class = type(other)
+
+        return new_t_class(**merged_dict)
+
+    def pretty(self) -> str:
+        str_pieces = [
+            f"{', '.join(self.source_aliases)} → {', '.join(self.target_aliases)}",
+            f"Summary: {self.advice if self.advice else 'N/A'}",
+        ]
+        return "\n".join(str_pieces)
+
+    def __str__(self):
+        return self.pretty()

dialectical_framework/analyst/domain/transition_cell_to_cell.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from dialectical_framework.analyst.domain.transition import Transition
+from dialectical_framework.dialectical_component import DialecticalComponent
+
+
+class TransitionCellToCell(Transition):
+    source: DialecticalComponent = Field(
+        description="Source dialectical component of the wheel."
+    )
+    target: DialecticalComponent = Field(
+        description="Target dialectical component of the wheel."
+    )
+
+    @model_validator(mode="after")
+    def auto_populate_aliases(self) -> Self:
+        # Autopopulate source_aliases if empty
+        if not self.source_aliases and self.source:
+            self.source_aliases = [self.source.alias]
+
+        # Autopopulate target_aliases if empty
+        if not self.target_aliases and self.target:
+            self.target_aliases = [self.target.alias]
+
+        return self

dialectical_framework/analyst/domain/transition_segment_to_segment.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from dialectical_framework.analyst.domain.transition import Transition
+from dialectical_framework.wheel_segment import WheelSegment
+
+
+class TransitionSegmentToSegment(Transition):
+    """
+    Note that though the transition is from segment to segment,
+    the source aliases and target aliases can be subsets of segments components.
+    """
+
+    source: WheelSegment = Field(description="Source segment of the wheel.")
+    target: WheelSegment = Field(description="Target segment of the wheel.")

dialectical_framework/analyst/strategic_consultant.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Optional, List
+
+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
+from dialectical_framework.wheel_segment import WheelSegment
+
+
+class StrategicConsultant(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 think(self, focus: WheelSegment) -> Transition | List[Transition]: ...
+    """
+    The main method of the class. It should return a Transition to the next WisdomUnit.
+    This Transition must be saved into the current instance. 
+    """

dialectical_framework/analyst/think_action_reflection.py

@@ -0,0 +1,217 @@
+import asyncio
+from typing import List
+
+from mirascope import Messages, prompt_template
+from mirascope.integrations.langfuse import with_langfuse
+
+from dialectical_framework import TransitionSegmentToSegment, Transformation, Rationale
+from dialectical_framework.ai_dto.dialectical_components_deck_dto import \
+    DialecticalComponentsDeckDto
+from dialectical_framework.ai_dto.dto_mapper import map_list_from_dto
+from dialectical_framework.ai_dto.reciprocal_solution_dto import ReciprocalSolutionDto
+from dialectical_framework.analyst.strategic_consultant import \
+    StrategicConsultant
+from dialectical_framework.dialectical_component import DialecticalComponent
+from dialectical_framework.directed_graph import DirectedGraph
+from dialectical_framework.enums.dialectical_reasoning_mode import \
+    DialecticalReasoningMode
+from dialectical_framework.enums.predicate import Predicate
+from dialectical_framework.protocols.has_config import SettingsAware
+from dialectical_framework.utils.use_brain import use_brain
+from dialectical_framework.wheel_segment import (ALIAS_T, ALIAS_T_MINUS,
+                                                 ALIAS_T_PLUS, WheelSegment)
+from dialectical_framework.wisdom_unit import (ALIAS_A, ALIAS_A_MINUS,
+                                               ALIAS_A_PLUS, WisdomUnit)
+
+
+ALIAS_AC = "Ac"
+ALIAS_AC_PLUS = "Ac+"
+ALIAS_AC_MINUS = "Ac-"
+ALIAS_RE = "Re"
+ALIAS_RE_PLUS = "Re+"
+ALIAS_RE_MINUS = "Re-"
+
+class ThinkActionReflection(StrategicConsultant, SettingsAware):
+    @prompt_template(
+        """
+        USER:
+        <context>{text}</context>
+        
+        USER:
+        Previous Dialectical Analysis:
+        {dialectical_analysis}
+        
+        USER:
+        <instructions>
+        Given the initial context and the previous dialectical analysis, identify the transition steps Ac and Re that transform T and A into each other as follows:
+        1) Ac must transform T into A
+        2) Ac+ must transform T- and/or T into A+
+        3) Ac- must transform T+ and/or T into A-
+        4) Re must transform A into T
+        5) Re+ must transform A- and/or A into T+
+        6) Re- must transform A+ and/or A into T-
+        7) Re+ must oppose/contradict Ac-
+        8) Re- must oppose/contradict Ac+
+        </instructions>
+    
+        <formatting>
+        Output each transition step within {component_length} word(s), the shorter, the better. Compose the explanations how they were derived in the passive voice. Don't mention any special denotations such as "T", "T+", "A-", "Ac", "Re", etc.
+        </formatting>
+        """
+    )
+    def ac_re_prompt(self, text: str, focus: WisdomUnit) -> Messages.Type:
+        # TODO: do we want to include the whole wheel reengineered? Also transitions so far?
+        return {
+            "computed_fields": {
+                "text": text,
+                "dialectical_analysis": focus.pretty(),
+                "component_length": self.settings.component_length,
+            }
+        }
+
+    @prompt_template(
+        """
+        USER:
+        <context>{text}</context>
+
+        USER:
+        Previous Dialectical Analysis:
+        {dialectical_analysis}
+
+        USER:
+        <instructions>
+        Given the initial context and the previous dialectical analysis, suggest solution(s).
+
+        Step 1: Frame the problem as a tension between two opposing approaches, where:
+        - Thesis (T): The first approach or position
+        - Antithesis (A): The contrasting approach or position
+
+        The solution that is suggested or implied in the text must represent the Linear Action (Ac) that transforms the negative aspect of the thesis (T-) into the positive aspect of the antithesis (A+)
+
+        Step 2: Create a Dialectical Reflection (Re):
+        - A complementary solution that is NOT present in the analyzed text
+        - This solution should transform the negative aspect of the antithesis (A-) into the positive aspect of the thesis (T+)
+        - It should work harmoniously with the Linear Action to create a more complete solution
+
+        <example>
+            For example:
+            In a token vesting dispute, stakeholders disagreed about extending the lock period from January 2025 to January 2026. The original solution was a staged distribution with incentives.
+
+            Thesis T: Vest Now
+            T+ = Trust Building
+            T- = Loss of Value
+
+            Antithesis A: Vest Later
+            A+ = Value Protection (contradicts T-)
+            A- = Trust Erosion (contradicts T+)
+
+            Linear Action: Staged distribution with added incentives, offering 25% immediate unlock with enhanced benefits for the delayed 75% portion.
+
+            Dialectical Reflection: Liquid staking derivatives for immediate utility (25%) combined with guaranteed exit rights (75%) - complements the linear action.
+        </example>
+        </instructions>
+
+        <formatting>
+        Output Linear Action and Dialectical Reflection as a fluent text that could be useful for someone who provided the initial context. Compose the problem statement in the passive voice. Don't mention any special denotations such as "T", "T+", "A-", "Ac", "Re", etc.
+        </formatting>
+        """
+    )
+    def reciprocal_solution_prompt(self, text: str, focus: WisdomUnit) -> Messages.Type:
+        # TODO: do we want to include the whole wheel reengineered? Also transitions so far?
+        return {
+            "computed_fields": {
+                "text": text,
+                "dialectical_analysis": focus.pretty(),
+                "component_length": self.settings.component_length,
+            }
+        }
+
+    @with_langfuse()
+    @use_brain(
+        response_model=ReciprocalSolutionDto,
+    )
+    async def reciprocal_solution(self, focus: WisdomUnit):
+        return self.reciprocal_solution_prompt(self._text, focus=focus)
+
+    @with_langfuse()
+    @use_brain(response_model=DialecticalComponentsDeckDto)
+    async def action_reflection(self, focus: WisdomUnit):
+        return self.ac_re_prompt(self._text, focus=focus)
+
+    async def think(self, focus: WheelSegment) -> List[TransitionSegmentToSegment]:
+        wu = self._wheel.wisdom_unit_at(focus)
+
+        async_reasoning_threads = [
+            self.action_reflection(focus=wu),
+            self.reciprocal_solution(focus=wu)
+        ]
+
+        dc_deck_dto: DialecticalComponentsDeckDto
+        reciprocal_sol_dto: ReciprocalSolutionDto
+        dc_deck_dto, reciprocal_sol_dto  = await asyncio.gather(*async_reasoning_threads)
+
+        ac_re_wu = WisdomUnit(
+            reasoning_mode=DialecticalReasoningMode.ACTION_REFLECTION,
+            rationales=[Rationale(text=reciprocal_sol_dto.problem)]
+        )
+        dialectical_components: list[DialecticalComponent] = map_list_from_dto(dc_deck_dto.dialectical_components, DialecticalComponent)
+        for dc in dialectical_components:
+            alias = self._translate_to_canonical_alias(dc.alias)
+            setattr(ac_re_wu, alias, dc)
+
+        graph = DirectedGraph[TransitionSegmentToSegment]()
+        graph.add_transition(
+            TransitionSegmentToSegment(
+                predicate=Predicate.TRANSFORMS_TO,
+                source_aliases=[wu.t_minus.alias, wu.t.alias],
+                target_aliases=[wu.a_plus.alias],
+                source=wu.extract_segment_t(),
+                target=wu.extract_segment_a(),
+                rationales=[
+                    Rationale(text=reciprocal_sol_dto.linear_action)
+                ],
+            )
+        )
+        graph.add_transition(
+            TransitionSegmentToSegment(
+                predicate=Predicate.TRANSFORMS_TO,
+                source_aliases=[wu.a_minus.alias, wu.a.alias],
+                target_aliases=[wu.t_plus.alias],
+                source=wu.extract_segment_a(),
+                target=wu.extract_segment_t(),
+                rationales=[
+                    Rationale(text=reciprocal_sol_dto.dialectical_reflection)
+                ],
+            )
+        )
+
+        # TODO: maybe we should rather merge if there was a transformation already (e.g. as a separate rationale?)
+        wu.transformation = Transformation(
+            ac_re=ac_re_wu,
+            graph=graph
+        )
+
+        # We return empty, because we're not merging anything, and we're sure there will be nothing to do with the result
+        return []
+
+    @staticmethod
+    def _translate_to_canonical_alias(alias: str) -> str:
+        if alias == ALIAS_AC:
+            return ALIAS_T
+
+        if alias == ALIAS_AC_PLUS:
+            return ALIAS_T_PLUS
+
+        if alias == ALIAS_AC_MINUS:
+            return ALIAS_T_MINUS
+
+        if alias == ALIAS_RE:
+            return ALIAS_A
+
+        if alias == ALIAS_RE_PLUS:
+            return ALIAS_A_PLUS
+
+        if alias == ALIAS_RE_MINUS:
+            return ALIAS_A_MINUS
+
+        return alias