dialectical-framework 2.0.1__tar.gz → 2.0.3__tar.gz

{dialectical_framework-2.0.1 → dialectical_framework-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 2.0.1
+Version: 2.0.3
 Summary: A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.).
 License: MIT
 Keywords: dialectics,dialectical-reasoning,synthesis,thesis-antithesis,ai,artificial-intelligence,llm,reasoning-framework,philosophy,logic,argumentation,conflict-resolution,decision-making,critical-thinking,semantic-graph,mirascope,pydantic,perspectives,polarity-reasoning

{dialectical_framework-2.0.1 → dialectical_framework-2.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "2.0.1"
+version = "2.0.3"
 description = "A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.)."
 authors = ["Evaldas Taroza <evaldas@dialexity.com>"]
 readme = "README.md"

{dialectical_framework-2.0.1 → dialectical_framework-2.0.3}/src/dialectical_framework/agents/consultant/consultant.py

@@ -51,7 +51,7 @@ from dialectical_framework.agents.conversation_facilitator import (
     FROM_SETTINGS, ConversationFacilitator)
 from dialectical_framework.agents.stream_events import StreamEvent
 from dialectical_framework.agents.turn_timing import TurnTiming
-from dialectical_framework.graph.views import ExplorationView
+from dialectical_framework.graph.views import ExplorationView, PerspectiveView
 
 #: Tool verbs → mental acts. These are REWRITES, not drops: dropping every
 #: paragraph that mentions a tool name would also delete the discrimination test
@@ -324,7 +324,12 @@ class Consultant:
         if messages:
             self._conversation.load_messages(messages)
         parts = [p for p in (preamble, method_prompt(include_decision)) if p]
-        self._conversation.set_system_prompt("\n\n".join(parts))
+        # Kept because the view turn's system prompt is this text plus the
+        # static half of its request (`exploration_view`): appending keeps the
+        # head a PREFIX of it, so the chat turns' cached prefix is readable by
+        # the sketch turns instead of each paying for its own.
+        self._system_prompt = "\n\n".join(parts)
+        self._conversation.set_system_prompt(self._system_prompt)
 
     async def chat(self, user_message: str) -> str:
         result = await self._conversation.submit(ChatResponse, user_message)
@@ -362,7 +367,8 @@ class Consultant:
         view shows what has been ESTABLISHED, and where `focus` asks for
         structure not yet worked out ("a perspective for the thesis you
         named") the turn builds it by the method first
-        (`concerns/view_sketch.py::view_sketch_prompt`). What it built is
+        (`concerns/view_sketch.py`: the static instructions ride on the system
+        prompt, the focus is the turn). What it built is
         kept in `messages` as the consultant's own words, so the next turn can
         be asked about a corner it just drew.
 
@@ -380,16 +386,30 @@ class Consultant:
         """
         from dialectical_framework.concerns.view_sketch import (
             ViewSketchDto, exploration_view_from_sketch, history_ask,
-            history_text, view_sketch_prompt)
+            history_text, perspective_from_sketch, view_sketch_focus,
+            view_sketch_instructions)
 
         import asyncio
+        import dataclasses
 
         from dialectical_framework.concerns.tetrad_candidates import (
-            clamp_attempts, select_sketch)
+            clamp_attempts, ranking, select_sketch)
 
         level = self._conversation._thinking_kwargs().get("thinking")
         history = self._conversation._messages
-        request = view_sketch_prompt(focus, self._conversation.settings.component_length)
+        # The request travels in two places, not one. Its static half
+        # (definitions, rules, the build procedure) goes on the SYSTEM prompt,
+        # after this head's own, because that is where the provider's cache
+        # breakpoint sits: as part of the user message it followed the history
+        # and was re-prefilled at full rate on every draw (~1.2k tokens x N a
+        # card, measured 2026-10-06). Only the focus — the person's own ask —
+        # is the turn. Same words, and the history record is untouched
+        # (`history_ask`, which is why the long request was never kept anyway).
+        system = (
+            f"{self._system_prompt}\n\n"
+            f"{view_sketch_instructions(self._conversation.settings.component_length)}"
+        )
+        ask = view_sketch_focus(focus)
 
         async def draw() -> ViewSketchDto:
             # Each draw works on a COPY of the history: the turns run in
@@ -397,9 +417,20 @@ class Consultant:
             # read. What the view leaves behind is appended once, below.
             sketch_turn = ConversationFacilitator(format_mode="json", thinking=level)
             sketch_turn._messages = list(history)
-            return await sketch_turn.submit(ViewSketchDto, request)
+            sketch_turn.set_system_prompt(system)
+            return await sketch_turn.submit(ViewSketchDto, ask)
 
         n = clamp_attempts(attempts)
+        # Fully parallel, deliberately. On a COLD cache all N draws write the
+        # ~12k system head instead of one writing and the rest reading (~$0.06
+        # a card at list prices, 2026-10-06), and the fix would be to await the
+        # first draw before firing the rest — but these turns do not stream, so
+        # nothing here can tell a cold cache from a warm one, and the stagger
+        # would spend a whole draw's latency (~6 s) on EVERY card to save money
+        # on the rare one. The 1h breakpoint TTL
+        # (`utils/bedrock_provider.py::_CACHE_TTL`) attacks the same cost
+        # without the latency, which is the trade taken. Revisit only with a
+        # measured cold-start rate.
         drawn = await asyncio.gather(*(draw() for _ in range(n)), return_exceptions=True)
         sketches = [d for d in drawn if not isinstance(d, BaseException)]
         if not sketches:
@@ -407,19 +438,24 @@ class Consultant:
         # With several draws the framework's own coherence check picks the one
         # whose FIRST tension holds best (`concerns/tetrad_candidates.py`); a
         # draw with no complete first tension sorts last. The card a blindspot
-        # screen shows is that first tension.
+        # screen shows is that first tension. The judged draws that lost come
+        # back too, best first, as `runners_up` — a host's "again"/"another"
+        # can serve one without a new call (the module's stated intent).
+        runners_up: list[PerspectiveView] = []
         if len(sketches) > 1:
             firsts = [s.tensions[0] if s.tensions else None for s in sketches]
             judgeable = [i for i, t in enumerate(firsts) if t is not None and all(
                 (getattr(t, k) or "").strip() for k in ("thesis", "antithesis", "t_plus", "t_minus", "a_plus", "a_minus"))]
             if len(judgeable) > 1:
-                best_among, _verdicts = await select_sketch([firsts[i] for i in judgeable])
-                sketch = sketches[judgeable[best_among]]
+                _best, verdicts = await select_sketch([firsts[i] for i in judgeable])
+                order = ranking(verdicts)
+                sketch = sketches[judgeable[order[0]]]
+                runners_up = [perspective_from_sketch(firsts[judgeable[i]]) for i in order[1:]]
             else:
                 sketch = sketches[judgeable[0]] if judgeable else sketches[0]
         else:
             sketch = sketches[0]
-        view = exploration_view_from_sketch(sketch)
+        view = dataclasses.replace(exploration_view_from_sketch(sketch), runners_up=runners_up)
         # What the turn leaves behind is NOT what it sent: the long request and
         # the DTO come off, and the person's ask plus the drawing in words go
         # on. Kept as a request→prose pair, the long request taught the next

{dialectical_framework-2.0.1 → dialectical_framework-2.0.3}/src/dialectical_framework/concerns/control_statements_check.py

@@ -97,6 +97,47 @@ class CoherenceEvaluationDto(BaseModel):
     )
 
 
+def control_statements(
+    *, t_plus: str, t_minus: str, a_plus: str, a_minus: str
+) -> tuple[str, str]:
+    """The paper's two control statements, built from four texts.
+
+    One builder for both askers (`resolve` off a committed Perspective,
+    `score_texts` off bare texts) so the quoting cannot drift: a verdict taken
+    before persistence and one taken after must be the same question asked of
+    the same words.
+    """
+    return (
+        f'"{t_plus}" without "{a_plus}" yields "{t_minus}"',
+        f'"{a_plus}" without "{t_plus}" yields "{a_minus}"',
+    )
+
+
+# --- Prompt text ---
+#
+# The pattern and the two scales of `_evaluate_control_statement`, as constants
+# so a probe can put the SAME scales in front of a candidate judge
+# (`tests/e2e/probe_joint_judge_stability.py` did, 2026-10-06, and rejected two
+# cheaper shapes against this one).
+
+_PATTERN = """The pattern "[Positive] without [Balancing factor] yields [Negative]" tests whether
+the absence of a balancing positive aspect naturally leads to the negative/shadow aspect."""
+
+_CC_SCALE = """Conceptual Coherence (CC) — is the statement logically meaningful?
+- 0.9-1.0: Highly coherent, clear logical/causal relationship
+- 0.7-0.9: Coherent, reasonable logical connection
+- 0.5-0.7: Somewhat coherent, plausible but weak
+- 0.3-0.5: Weak coherence, tenuous connection
+- 0.0-0.3: Not coherent, no clear logical relationship"""
+
+_DV_SCALE = """Dialectical Validity (DV) — is the dialectical relationship natural, judged
+independently of coherence? A statement can be perfectly coherent yet dialectically
+distorted (e.g. one pole arbitrarily privileged, outcomes enforced by coercion or
+ideology rather than natural system dynamics). 1.0 = natural, balanced, generative;
+0.0 = forced, artificial, distorted. Ignore factual correctness; evaluate only the
+quality of the dialectical relationship as a generative principle."""
+
+
 # --- Result ---
 
 
@@ -182,8 +223,12 @@ class ControlStatementsCheck(ReasonableConcern[ControlStatementsCheckResult]):
         a_minus = perspective.get_component(POSITION_A_MINUS)
 
         # Build control statements
-        stmt_1 = f'"{t_plus.prompt_text}" without "{a_plus.prompt_text}" yields "{t_minus.prompt_text}"'
-        stmt_2 = f'"{a_plus.prompt_text}" without "{t_plus.prompt_text}" yields "{a_minus.prompt_text}"'
+        stmt_1, stmt_2 = control_statements(
+            t_plus=t_plus.prompt_text,
+            t_minus=t_minus.prompt_text,
+            a_plus=a_plus.prompt_text,
+            a_minus=a_minus.prompt_text,
+        )
 
         # Evaluate both statements in parallel using isolated conversations
         result_1, result_2 = await asyncio.gather(
@@ -268,12 +313,15 @@ class ControlStatementsCheck(ReasonableConcern[ControlStatementsCheckResult]):
 
         What `resolve` does after reading the four aspects off a committed
         node, offered to callers that hold a tetrad as text: the best-of-N
-        selector (`concerns/tetrad_candidates.py`) and the harness. Built with
-        the same quoting as `resolve`'s statements so a verdict here is the
-        same question as the one asked after persistence.
+        selector (`concerns/tetrad_candidates.py`) and the harness. Built by
+        the same statement builder and asked with the same prompt as `resolve`,
+        so a verdict here is the same question as the one asked after
+        persistence. Two calls per tetrad is the cost of that: the cheaper
+        shapes measured against it disagreed (`tetrad_candidates.judge_sketches`).
         """
-        stmt_1 = f'"{t_plus}" without "{a_plus}" yields "{t_minus}"'
-        stmt_2 = f'"{a_plus}" without "{t_plus}" yields "{a_minus}"'
+        stmt_1, stmt_2 = control_statements(
+            t_plus=t_plus, t_minus=t_minus, a_plus=a_plus, a_minus=a_minus
+        )
         return await asyncio.gather(
             self._evaluate_control_statement(stmt_1, text),
             self._evaluate_control_statement(stmt_2, text),
@@ -291,22 +339,11 @@ class ControlStatementsCheck(ReasonableConcern[ControlStatementsCheckResult]):
 
 {statement}
 
-The pattern "[Positive] without [Balancing factor] yields [Negative]" tests whether
-the absence of a balancing positive aspect naturally leads to the negative/shadow aspect.
+{_PATTERN}
 
-1. Conceptual Coherence (CC) — is the statement logically meaningful?
-- 0.9-1.0: Highly coherent, clear logical/causal relationship
-- 0.7-0.9: Coherent, reasonable logical connection
-- 0.5-0.7: Somewhat coherent, plausible but weak
-- 0.3-0.5: Weak coherence, tenuous connection
-- 0.0-0.3: Not coherent, no clear logical relationship
+1. {_CC_SCALE}
 
-2. Dialectical Validity (DV) — is the dialectical relationship natural, judged
-independently of coherence? A statement can be perfectly coherent yet dialectically
-distorted (e.g. one pole arbitrarily privileged, outcomes enforced by coercion or
-ideology rather than natural system dynamics). 1.0 = natural, balanced, generative;
-0.0 = forced, artificial, distorted. Ignore factual correctness; evaluate only the
-quality of the dialectical relationship as a generative principle."""
+2. {_DV_SCALE}"""
 
         conversation = ConversationFacilitator()
         return await conversation.submit(

{dialectical_framework-2.0.1 → dialectical_framework-2.0.3}/src/dialectical_framework/concerns/synthesis_generation.py

@@ -30,6 +30,8 @@ from dialectical_framework.agents.conversation_facilitator import (
     ConversationFacilitator,
 )
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.concerns.transformation_sketch import (
+    SYNTHESIS_SHAPE, TRANSFORMATION_POSITIONS)
 from dialectical_framework.graph.nodes.statement import Statement
 from dialectical_framework.protocols.has_config import SettingsAware
 
@@ -39,7 +41,12 @@ if TYPE_CHECKING:
     from dialectical_framework.graph.nodes.wheel import Wheel
 
 
-SYSTEM_PROMPT = """You are an expert in dialectical synthesis — the emergent properties arising from circular causality loops.
+#: "The shape of the inputs" is the framework's ONE statement of the
+#: Transformation (`transformation_sketch.TRANSFORMATION_POSITIONS`) and of S±
+#: (`SYNTHESIS_SHAPE`), not a copy: this prompt reads graph-built
+#: Transformations and the one-shot writes them, and the two must not define
+#: Ac-/Re- differently (2026-10-06 — this paragraph had dropped where Ac- GOES).
+SYSTEM_PROMPT = f"""You are an expert in dialectical synthesis — the emergent properties arising from circular causality loops.
 
 ## What Synthesis IS
 
@@ -57,7 +64,7 @@ S+ produces new qualitative dimensions — it increases a system's capacity for
 ## S- (Negative Synthesis): Collapse Pattern (1+1<2)
 
 S- emerges when the failure modes (Ac- and Re-) reinforce each other:
-- Acting without reflecting yields Ac- (the action's own drift); reflecting without acting yields Re- (the reflection's own regression)
+- Ac+ without Re+ yields Ac- (the action's own drift, which carries T+ into A-); Re+ without Ac+ yields Re- (the reflection's own regression, which carries A+ into T-)
 - Together these create downward spirals — dominance of one pole, or unstable oscillation between them
 - Diversity is reduced and qualitative growth is replaced by quantitative amplification
 
@@ -65,7 +72,11 @@ S- manifests as imitation rather than transformation: external forms, metrics, o
 
 ## The shape of the inputs, exactly
 
-Each Transformation is itself a tetrad: Ac (the action) and Re (the reflection) are its poles; Ac+/Ac- and Re+/Re- are their constructive and one-sided developments. So Ac- is the ACTION gone wrong and Re- is the REFLECTION gone wrong — they are not the segments' own traps (T-, A-) restated, and S- is not those traps either. S- is the ONE named state the degraded action and the degraded reflection produce together: a single way of failing that is neither trap on its own and not a choice between them. "Either X or Y", "X versus Y" and "X while Y" with X and Y the two traps are the inputs listed, not the collapse named. Likewise S+ is a gain in dimension the pathways produce together — not "both", not the two strengths listed side by side.
+Each Transformation is itself a tetrad, built this way:
+
+{TRANSFORMATION_POSITIONS}
+
+{SYNTHESIS_SHAPE}
 
 ## Requirements
 

{dialectical_framework-2.0.1 → dialectical_framework-2.0.3}/src/dialectical_framework/concerns/tetrad_candidates.py

@@ -106,25 +106,54 @@ def is_complete(candidate: Any) -> bool:
     )
 
 
-async def judge_sketch(tension: Any, context: str = "") -> SketchVerdict:
-    """The validator's two control statements, on the candidate's texts, graph-free.
-
-    Statement texts are built exactly as `ControlStatementsCheck.resolve`
-    builds them from committed Statements, so a verdict here and one taken
-    after persistence are the same question asked of the same words.
+async def judge_sketches(
+    candidates: Sequence[Any], context: str = ""
+) -> list[Optional[SketchVerdict]]:
+    """The validator's two control statements for every candidate, each draft
+    judged on its own, each statement in its own call (gathered).
+
+    Statement texts are built by the same builder `ControlStatementsCheck.resolve`
+    uses, and the prompt is the one `resolve` asks, so a verdict here and one
+    taken after persistence are the same question asked of the same words. The
+    judge sees only the four aspects of each draft, never the thesis or the
+    antithesis. Fail-soft per candidate: a judging that fails is `None` for
+    that draft alone, which sorts last.
+
+    Deliberately NOT cheaper, by measurement (2026-10-06,
+    `tests/e2e/probe_joint_judge_stability.py`, 40 stored triples). Judging is
+    the costliest part of a best-of-3 card (6 of its 11 calls, about a third of
+    its cost), and two cheaper shapes were tried and rejected:
+    - one call for the whole field: pass/fail agreement with the stored verdict
+      70% against this judge's own 92% on the same drafts, the same winner
+      across a reversed order in 7/40, the first-listed draft winning 29/40;
+      it picked by position and ties;
+    - one call per draft with both statements in it (the same lean prompt):
+      73% against 90%, the same winner as this judge in 23/40 — stable with
+      itself, but measuring something else.
+    A cheaper judge has to be measured against this one on that probe first.
     """
-    first, second = await ControlStatementsCheck().score_texts(
-        t_plus=aspect_text(tension.t_plus),
-        t_minus=aspect_text(tension.t_minus),
-        a_plus=aspect_text(tension.a_plus),
-        a_minus=aspect_text(tension.a_minus),
-        text=context,
-    )
-    return SketchVerdict(
-        t_plus_without_a_plus=first.coherence_score,
-        a_plus_without_t_plus=second.coherence_score,
-        reasoning=f"{first.reasoning} / {second.reasoning}".strip(" /"),
-    )
+
+    async def one(tension: Any) -> Optional[SketchVerdict]:
+        # Reading the verdict is inside the `try` too: a malformed response
+        # is a failed judging (sorts last), never a failed selection.
+        try:
+            first, second = await ControlStatementsCheck().score_texts(
+                t_plus=aspect_text(tension.t_plus),
+                t_minus=aspect_text(tension.t_minus),
+                a_plus=aspect_text(tension.a_plus),
+                a_minus=aspect_text(tension.a_minus),
+                text=context,
+            )
+            return SketchVerdict(
+                t_plus_without_a_plus=first.coherence_score,
+                a_plus_without_t_plus=second.coherence_score,
+                reasoning=f"{first.reasoning} / {second.reasoning}".strip(" /"),
+            )
+        except Exception as exc:  # noqa: BLE001 — degrade to "unjudged"
+            logger.warning("Judging a sketch failed; it sorts last: %s", exc)
+            return None
+
+    return list(await asyncio.gather(*(one(c) for c in candidates)))
 
 
 async def select_sketch(
@@ -137,18 +166,21 @@ async def select_sketch(
     mean, then the earlier draw — a deterministic tie-break, not a preference.
     A candidate whose judging failed sorts last; if every judging failed the
     first draw is kept, which is exactly what `attempts=1` would have done.
+
+    ONE candidate is never judged: there is nothing to select among, so
+    `attempts=1` costs no extra call.
     """
     if len(candidates) == 1:
         return 0, [None]
 
-    async def one(tension: Any) -> Optional[SketchVerdict]:
-        try:
-            return await judge_sketch(tension, context)
-        except Exception as exc:  # noqa: BLE001 — degrade to "unjudged"
-            logger.warning("Judging a sketch failed; it sorts last: %s", exc)
-            return None
+    verdicts = await judge_sketches(candidates, context)
+    return ranking(verdicts)[0], verdicts
+
 
-    verdicts = list(await asyncio.gather(*(one(c) for c in candidates)))
+def ranking(verdicts: Sequence[Optional[SketchVerdict]]) -> list[int]:
+    """Candidate indices best first, by `select_sketch`'s rule: the weaker
+    control statement, then the mean, then the earlier draw; unjudged last.
+    `[0]` is the winner; the rest are the runners-up in order."""
 
     def key(index: int) -> tuple[int, float, float, int]:
         verdict = verdicts[index]
@@ -157,5 +189,4 @@ async def select_sketch(
         mean = (verdict.t_plus_without_a_plus + verdict.a_plus_without_t_plus) / 2
         return (1, verdict.floor, mean, -index)
 
-    best = max(range(len(candidates)), key=key)
-    return best, verdicts
+    return sorted(range(len(verdicts)), key=key, reverse=True)