dialectical-framework 0.4.4__py3-none-any.whl

dialectical_framework/synthesist/wheel_builder.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+from typing import Dict, Union
+
+from dependency_injector.wiring import Provide
+
+from dialectical_framework.ai_dto.dto_mapper import (map_from_dto,
+                                                     map_list_from_dto)
+from dialectical_framework.analyst.domain.cycle import Cycle
+from dialectical_framework.dialectical_component import DialecticalComponent
+from dialectical_framework.dialectical_components_deck import \
+    DialecticalComponentsDeck
+from dialectical_framework.enums.di import DI
+from dialectical_framework.protocols.causality_sequencer import \
+    CausalitySequencer
+from dialectical_framework.protocols.has_config import SettingsAware
+from dialectical_framework.protocols.thesis_extractor import ThesisExtractor
+from dialectical_framework.synthesis import (ALIAS_S_MINUS, ALIAS_S_PLUS, Synthesis)
+from dialectical_framework.synthesist.polarity.polarity_reasoner import \
+    PolarityReasoner
+from dialectical_framework.wheel import Wheel, WheelSegmentReference
+from dialectical_framework.wheel_segment import ALIAS_T
+from dialectical_framework.wisdom_unit import WisdomUnit
+
+
+class WheelBuilder(SettingsAware):
+    def __init__(
+        self,
+        thesis_extractor: ThesisExtractor = Provide[DI.thesis_extractor],
+        causality_sequencer: CausalitySequencer = Provide[DI.causality_sequencer],
+        polarity_reasoner: PolarityReasoner = Provide[DI.polarity_reasoner],
+        *,
+        text: str = "",
+        wheels: list[Wheel] = None,
+    ):
+        self.__text = text
+        self.__wheels: list[Wheel] = wheels or []
+
+        # TODO: reloading singletons isn't very good design here, because we're guessing the parameters...
+
+        self.__extractor = thesis_extractor
+        self.__extractor.reload(text=text)
+
+        self.__sequencer = causality_sequencer
+        self.__sequencer.reload(text=text)
+
+        self.__reasoner = polarity_reasoner
+        self.__reasoner.reload(text=text)
+
+    @property
+    def wheel_permutations(self) -> list[Wheel]:
+        return self.__wheels
+
+    @property
+    def text(self) -> str | None:
+        return self.__text
+
+    @property
+    def extractor(self) -> ThesisExtractor:
+        return self.__extractor
+
+    @property
+    def reasoner(self) -> PolarityReasoner:
+        return self.__reasoner
+
+    @property
+    def sequencer(self) -> CausalitySequencer:
+        return self.__sequencer
+
+    async def t_cycles(self, *, theses: list[Union[str, None]] = None) -> list[Cycle]:
+        if theses is None:
+            # No theses provided, generate one automatically
+            t = await self.extractor.extract_single_thesis()
+            t.alias = ALIAS_T
+            theses = [t]
+        else:
+            # Handle mixed None and str values
+            final_theses: list[DialecticalComponent | None] = []
+            none_positions = []
+
+            # First pass: collect provided theses and identify positions that need generation
+            for i, thesis in enumerate(theses):
+                if thesis is None or (isinstance(thesis, str) and not thesis.strip()):
+                    none_positions.append(i)
+                    final_theses.append(None)  # Placeholder
+                else:
+                    provided_thesis = DialecticalComponent(
+                        alias=f"{ALIAS_T}",
+                        statement=thesis,
+                    )
+                    provided_thesis.set_human_friendly_index(i + 1)
+                    final_theses.append(provided_thesis)
+
+            # Generate all missing theses at once if needed
+            if none_positions:
+                if len(none_positions) == 1:
+                    # Single thesis case: place at the correct original position
+                    pos = none_positions[0]
+                    generated_thesis = map_from_dto(await self.reasoner.find_thesis(), DialecticalComponent)
+                    generated_thesis.alias = ALIAS_T
+                    generated_thesis.set_human_friendly_index(pos + 1)
+                    final_theses[pos] = generated_thesis
+                else:
+                    # Multiple theses case - extract all missing ones at once
+                    t_deck = await self.extractor.extract_multiple_theses(
+                        count=len(none_positions)
+                    )
+                    generated_theses = t_deck.dialectical_components
+
+                    # Place generated theses in their correct positions
+                    for i, pos in enumerate(none_positions):
+                        if i < len(generated_theses):
+                            generated_theses[i].alias = ALIAS_T
+                            generated_theses[i].set_human_friendly_index(pos + 1)
+                            final_theses[pos] = generated_theses[i]
+
+                    # Backfill any remaining None (it's a precaution, in case fewer were generated than requested)
+                    for pos in none_positions:
+                        if final_theses[pos] is None:
+                            generated_thesis = map_from_dto(await self.reasoner.find_thesis(), DialecticalComponent)
+                            generated_thesis.alias = ALIAS_T
+                            generated_thesis.set_human_friendly_index(pos + 1)
+                            final_theses[pos] = generated_thesis
+
+            theses = final_theses
+
+        cycles: list[Cycle] = await self.__sequencer.arrange(theses)
+        return cycles
+
+    async def build_wheel_permutations(
+        self, *, theses: list[Union[str, None]] = None, t_cycle: Cycle = None
+    ) -> list[Wheel]:
+        """
+        TODO: theses are used only when t_cycle is not provided. should be single param or so. Refactor
+        IMPORTANT: t_cycle is the "path" we take for permutations. If not provided, we'll take the most likely path.
+        Do not confuse it with building all wheels for all "paths"
+        """
+        if t_cycle is None:
+            cycles: list[Cycle] = await self.t_cycles(theses=theses)
+            # The first one is the highest probability
+            t_cycle = cycles[0]
+
+        wheel_wisdom_units = []
+        for dc in t_cycle.dialectical_components:
+            wu = await self.reasoner.think(thesis=dc.statement)
+            if dc.rationales:
+                wu.t.rationales.extend(dc.rationales)
+
+            idx = dc.get_human_friendly_index()
+            if idx:
+                wu.add_indexes_to_aliases(idx)
+
+            wheel_wisdom_units.append(wu)
+
+        cycles: list[Cycle] = await self.__sequencer.arrange(wheel_wisdom_units)
+
+        wheels = []
+        for cycle in cycles:
+            w = Wheel(
+                _rearrange_by_causal_sequence(wheel_wisdom_units, cycle, mutate=False),
+                t_cycle=t_cycle,
+                ta_cycle=cycle,
+            )
+            w.calculate_score()
+            wheels.append(w)
+
+        # Save results for reference
+        self.__wheels = wheels
+        return self.wheel_permutations
+
+    async def calculate_syntheses(
+        self,
+        *,
+        wheel: Wheel,
+        at: WheelSegmentReference | list[WheelSegmentReference] = None,
+    ):
+        if wheel not in self.wheel_permutations:
+            raise ValueError(f"Wheel permutation {wheel} not found in available wheels")
+
+        wisdom_units = []
+
+        if at is None:
+            # Calculate for each
+            wisdom_units = wheel.wisdom_units
+        elif isinstance(at, list):
+            # Calculate for some
+            for ref in at:
+                wisdom_units.append(wheel.wisdom_unit_at(ref))
+        else:
+            # Calculate for one
+            wisdom_units.append(wheel.wisdom_unit_at(at))
+
+        for wu in wisdom_units:
+            ss_deck_dto = await self.reasoner.find_synthesis(wu)
+            ss_deck = DialecticalComponentsDeck(dialectical_components=map_list_from_dto(ss_deck_dto.dialectical_components, DialecticalComponent))
+            wu.synthesis = Synthesis(
+                t_plus=ss_deck.get_by_alias(ALIAS_S_PLUS),
+                t_minus=ss_deck.get_by_alias(ALIAS_S_MINUS),
+            )
+            idx = wu.t.get_human_friendly_index()
+            if idx:
+                wu.synthesis.add_indexes_to_aliases(idx)
+
+        wheel.calculate_score()
+
+
+    async def redefine(
+        self, *, modified_statement_per_alias: Dict[str, str]
+    ) -> list[Wheel]:
+        """
+        We can give component statements by alias, e.g., T1 = "New thesis 1", A2+ = "New positive side of antithesis 2"
+
+        Returns a list of wheels with modified statements (updating the internal state)
+        """
+        if not self.wheel_permutations:
+            raise ValueError("No wheels have been built yet")
+        if modified_statement_per_alias:
+            wheels: list[Wheel] = []
+            for wheel in self.wheel_permutations:
+                new_wisdom_units: list[WisdomUnit] = []
+                is_dirty = False
+                for wu in wheel.wisdom_units:
+                    modifications = {}
+                    for field, alias in wu.field_to_alias.items():
+                        dc = wu.get(alias)
+                        if not dc:
+                            continue
+                        if dc.alias in modified_statement_per_alias:
+                            modifications[field] = modified_statement_per_alias[
+                                dc.alias
+                            ]
+                    if modifications:
+                        is_dirty = True
+                        wu_redefined = await self.reasoner.redefine(
+                            original=wu, **modifications
+                        )
+                        idx = wu.t.get_human_friendly_index()
+                        if idx:
+                            wu_redefined.add_indexes_to_aliases(idx)
+                    else:
+                        wu_redefined = wu
+                    new_wisdom_units.append(wu_redefined)
+                if not is_dirty:
+                    # No modifications were made, so preserve the original wheel
+                    wheels.append(wheel)
+                else:
+                    # Recalculate cycles
+                    analyst = self.__sequencer
+
+                    theses: list[str] = []
+                    for nwu in new_wisdom_units:
+                        if nwu.t.alias.startswith("T"):
+                            theses.append(nwu.t.statement)
+                        else:
+                            theses.append(nwu.a.statement)
+
+                    t_cycles: list[Cycle] = await analyst.arrange(theses)
+                    # TODO: we should do this for each t_cycle, not the first one only. Refactor
+                    t_cycle = t_cycles[0]
+
+                    wheel_wisdom_units = []
+                    for dc in t_cycle.dialectical_components:
+                        for nwu in new_wisdom_units:
+                            if dc.alias in nwu.t.alias:
+                                wheel_wisdom_units.append(nwu)
+                            elif dc.alias in nwu.a.alias:
+                                wheel_wisdom_units.append(
+                                    nwu.swap_segments(mutate=True)
+                                )
+
+                    cycles: list[Cycle] = await analyst.arrange(wheel_wisdom_units)
+
+                    for cycle in cycles:
+                        w = Wheel(
+                            _rearrange_by_causal_sequence(
+                                wheel_wisdom_units, cycle, mutate=False
+                            ),
+                            t_cycle=t_cycle,
+                            ta_cycle=cycle,
+                        )
+                        wheels.append(w)
+            self.__wheels = wheels
+
+        for wheel in self.wheel_permutations:
+            wheel.calculate_score()
+
+        return self.wheel_permutations
+
+
+def _rearrange_by_causal_sequence(
+    wisdom_units: list[WisdomUnit], cycle: Cycle, mutate: bool = True
+) -> list[WisdomUnit]:
+    """
+    We expect the cycle to be on the middle ring where theses and antitheses reside.
+    This way we can swap the wisdom unit oppositions if necessary.
+    """
+    all_aliases = []
+    if cycle.causality_direction == "clockwise":
+        for dc in cycle.dialectical_components:
+            all_aliases.append(dc.alias)
+    else:
+        for dc in reversed(cycle.dialectical_components):
+            all_aliases.append(dc.alias)
+
+    unique_aliases = dict.fromkeys(all_aliases)
+
+    if len(unique_aliases) != 2 * len(wisdom_units):
+        wu_aliases = [wu.t.alias for wu in wisdom_units] + [
+            wu.a.alias for wu in wisdom_units
+        ]
+        raise ValueError(
+            f"Not all aliases are present in the causal sequence. wisdom_unit_aliases={wu_aliases}, cycle_aliases={all_aliases}"
+        )
+
+    wu_sorted = []
+    wu_processed = []
+    for alias in unique_aliases:
+        for wu in wisdom_units:
+            if any(item is wu for item in wu_processed):
+                continue
+            if wu.t.alias == alias:
+                wu_sorted.append(wu)
+                wu_processed.append(wu)
+                break
+            if wu.a.alias == alias:
+                wu_sorted.append(wu.swap_segments(mutate=mutate))
+                wu_processed.append(wu)
+                break
+
+    if len(wu_sorted) != len(wisdom_units):
+        raise ValueError("Not all wisdom units were mapped in the causal sequence")
+
+    if mutate:
+        wisdom_units[:] = wu_sorted
+        return wisdom_units
+    else:
+        return wu_sorted

dialectical_framework/utils/__init__.py

@@ -0,0 +1 @@
+

dialectical_framework/utils/dc_replace.py

@@ -0,0 +1,42 @@
+import re
+
+
+def dc_replace(text: str, dialectical_component_name: str, replace_to: str) -> str:
+    """
+    # 1. **`(?<!\w)`**: Ensures `T-` is not preceded by a word character (prevents matches like `T-something`).
+    # 2. **`(["'\(\[\{]?)`**: Matches an optional opening character like `"`, `'`, `(`, `[`, or `{`. This is captured in group `\1`.
+    # 3. **`T-` **: Matches the literal `T-`.
+    # 4. **`(\s|[\]'"}).,!?:]|$)`**:
+    #     - Matches any of the following right after `T-`:
+    #     - A space (`\s`) (e.g., `T- something` or `T-`).
+    #     - A closing punctuation mark like `]`, `'`, `"`, `)`, `}`.
+    #     - Specific punctuation characters: `.`, `,`, `!`, `?`, or `:`.
+    #     - The end of the line (`$`).
+    #
+    #     - This captures both proper sentence endings (e.g., `T-.`) and cases where punctuation appears mid-sentence (e.g., `T-,` or `T-!`).
+    """
+    return re.sub(
+        r'(?<!\w)(["\'\(\[\{]?)'
+        rf"{re.escape(dialectical_component_name)}"
+        r"(\s|[\]\'\"\)\},.!?:]|$)",
+        # Replacement pattern (preserves surrounding characters and spaces)
+        r"\1" rf"{replace_to}" r"\2",
+        text,
+        flags=re.VERBOSE,
+    )
+
+
+def dc_safe_replace(text: str, replacements: dict[str, str]) -> str:
+    result = text
+    # Sort keys by length in descending order to replace longer keys first
+    sorted_keys = sorted(replacements.keys(), key=len, reverse=True)
+
+    # First pass: replace with temporary placeholders
+    for key in sorted_keys:
+        result = dc_replace(result, key, f"_{key}_")
+
+    # Second pass: replace placeholders with final values
+    for key in sorted_keys:
+        result = dc_replace(result, f"_{key}_", replacements[key])
+
+    return result

dialectical_framework/utils/decompose_probability_uniformly.py

@@ -0,0 +1,15 @@
+def decompose_probability_uniformly(probability: float, num_transitions: int) -> float:
+    """
+    Decompose probability uniformly across all transitions using nth root
+
+    Args:
+        probability: Overall probability (0.0 to 1.0)
+        num_transitions: Number of transitions
+
+    Returns:
+        Individual transition probability that when multiplied gives cycle_probability
+    """
+    if num_transitions == 0:
+        return 0.0
+
+    return probability ** (1.0 / num_transitions)

dialectical_framework/utils/extend_tpl.py

@@ -0,0 +1,12 @@
+
+from mirascope import Messages
+
+
+def extend_tpl(tpl: Messages.Type, prompt: Messages.Type) -> Messages.Type:
+    if isinstance(prompt, list):
+        tpl.extend(prompt)
+    elif hasattr(prompt, "messages"):
+        tpl.extend(prompt.messages)
+    else:
+        tpl.append(prompt)
+    return tpl

dialectical_framework/utils/gm.py

@@ -0,0 +1,12 @@
+from statistics import geometric_mean
+
+
+def gm_with_zeros_and_nones_handled(values: list[float]) -> float | None:
+    """Return GM of positives; 0.0 if any zero present; None if empty."""
+    has_zero = any(v == 0.0 for v in values)
+    positives = [v for v in values if v is not None and v > 0.0]
+    if not values:  # list is empty
+        return None
+    if has_zero:
+        return 0.0
+    return geometric_mean(positives) if positives else 0.0  # if only zeros, GM=0.0

dialectical_framework/utils/is_async.py

@@ -0,0 +1,13 @@
+import asyncio
+import inspect
+
+
+def is_async(func=None):
+    try:
+        asyncio.get_running_loop()  # Check if an active event loop exists
+        if func:
+            # OPTIONAL: Check if the given function is async
+            return inspect.iscoroutinefunction(func)
+        return True
+    except RuntimeError:
+        return False

dialectical_framework/utils/use_brain.py

@@ -0,0 +1,80 @@
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar
+
+import litellm
+from mirascope import llm
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from dialectical_framework.brain import Brain
+from dialectical_framework.protocols.has_brain import HasBrain
+
+T = TypeVar("T")
+
+def use_brain(brain: Optional[Brain] = None, **llm_call_kwargs):
+    """
+    Decorator factory for Mirascope that creates an LLM call using the brain's AI provider and model.
+
+    Args:
+        brain: Optional Brain instance to use. If not provided, will expect 'self' to implement HasBrain protocol
+        **llm_call_kwargs: All keyword arguments to pass to @llm.call, including response_model
+
+    Returns:
+        A decorator that wraps methods to make LLM calls
+    """
+
+    def decorator(method: Callable[..., Any]) -> Callable[..., T]:
+        @wraps(method)
+        async def wrapper(*args, **kwargs) -> T:
+            target_brain = None
+            if brain is not None:
+                target_brain = brain
+            else:
+                # Expect first argument to be self with HasBrain protocol
+                if not args:
+                    raise TypeError(
+                        "No arguments provided, no brain specified in decorator, and no brain available from DI container"
+                    )
+
+                first_arg = args[0]
+                if isinstance(first_arg, HasBrain) and target_brain is None:
+                    target_brain = first_arg.brain
+                else:
+                    raise TypeError(
+                        f"{first_arg.__class__.__name__} must implement {HasBrain.__name__} protocol, "
+                        "pass brain parameter to decorator, or have Brain available in DI container"
+                    )
+
+            overridden_ai_provider, overridden_ai_model = target_brain.specification()
+            if overridden_ai_provider == "bedrock":
+                # TODO: with Mirascope v2 async should be possible with bedrock, so we should get rid of fallback to litellm
+                # Issue: https://github.com/boto/botocore/issues/458, fallback to "litellm"
+                overridden_ai_provider, overridden_ai_model = (
+                    target_brain.modified_specification(ai_provider="litellm")
+                )
+
+            if overridden_ai_provider == "litellm":
+                # We use LiteLLM just for convenience, the real framework is Mirascope.
+                # So anything related to litellm can be supressed
+                litellm.turn_off_message_logging = True
+
+            # Merge brain specification with all parameters
+            call_params = {
+                "provider": overridden_ai_provider,
+                "model": overridden_ai_model,
+                **llm_call_kwargs,  # All parameters including response_model
+            }
+
+            # https://mirascope.com/docs/mirascope/learn/retries
+            @retry(
+                stop=stop_after_attempt(3),
+                wait=wait_exponential(multiplier=1, min=4, max=10),
+            )
+            @llm.call(**call_params)
+            async def _llm_call():
+                return await method(*args, **kwargs)
+
+            return await _llm_call()
+
+        return wrapper
+
+    return decorator

dialectical_framework/validator/__init__.py

@@ -0,0 +1 @@
+

dialectical_framework/validator/basic_checks.py

@@ -0,0 +1,75 @@
+from typing import Callable
+
+from mirascope import Messages, llm, prompt_template
+from mirascope.integrations.langfuse import with_langfuse
+from mirascope.llm import CallResponse
+
+from dialectical_framework.validator.check import Check
+
+
+def is_yes_parser(resp: CallResponse) -> bool:
+    return "YES" in resp.content[:3].upper()
+
+
+@prompt_template(
+    """
+    DIALECTICAL OPPOSITION:
+    
+    A dialectical opposition presents the conceptual or functional antithesis of the original statement that creates direct opposition, while potentially still allowing their mutual coexistence. For instance, Love vs. Hate or Indifference; Science vs. Superstition, Faith/Belief; Human-caused Global Warming vs. Natural Cycles.
+    
+    Can the statement "{antithesis}" be considered a valid dialectical opposition of statement "{thesis}"?
+    
+    Start answering with YES or NO. If NO, then provide a correct example. Explain your answer.
+    """
+)
+def is_valid_opposition(antithesis: str, thesis: str) -> Messages.Type: ...
+
+
+@prompt_template(
+    """
+    CONTRADICTORY/SEMANTIC OPPOSITION:
+    
+    A contradictory/semantic opposition presents a direct semantic opposition and/or contradiction to the original statement that excludes their mutual coexistence. For instance, Happiness vs. Unhappiness; Truthfulness vs. Lie/Deceptiveness; Dependence vs. Independence
+    
+    Can the statement "{opposition}" be considered as a contradictory/semantic opposition of "{statement}"?
+    
+    Start answering with YES or NO. If NO, then provide a correct example. Explain your answer.
+    """
+)
+def is_strict_opposition(opposition: str, statement: str) -> Messages.Type: ...
+
+
+@prompt_template(
+    """
+    Can the statement "{negative_side}" be considered as an exaggerated (overdeveloped, negative) side or outcome of the statement "{statement}"?
+    
+    Start answering with YES or NO. If NO, then provide a correct example. Explain your answer.
+    """
+)
+def is_negative_side(negative_side: str, statement: str) -> Messages.Type: ...
+
+
+@prompt_template(
+    """
+    Can the statement "{positive_side}" be considered as a positive (constructive and balanced) side of the statement "{statement}"?
+    
+    Start answering with YES or NO. If NO, then provide a correct example. Explain your answer.
+    """
+)
+def is_positive_side(positive_side: str, statement: str) -> Messages.Type: ...
+
+
+@with_langfuse()
+def check(
+    func: Callable[[str, str], Messages.Type],
+    reasoner,
+    statement1: str,
+    statement2: str,
+) -> Check:
+    (provider, model) = reasoner.brain.specification()
+
+    @llm.call(provider=provider, model=model, response_model=Check)
+    def _check() -> Check:
+        return func(statement1, statement2)
+
+    return _check()

dialectical_framework/validator/check.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, Field
+
+
+class Check(BaseModel):
+    valid: float = Field(
+        ...,
+        description="For boolean checks, Yes = 1, No = 0 (or True = 1, False = 0). Otherwise it's a float between 0 and 1.",
+    )
+    explanation: str = Field(
+        ...,
+        description="A brief explanation how the check was performed to get the resulting value.",
+    )