dialectical-framework 1.6.4__tar.gz → 1.6.5__tar.gz

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.6.4
+Version: 1.6.5
 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-1.6.4 → dialectical_framework-1.6.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "1.6.4"
+version = "1.6.5"
 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-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/agents/analyst/system_prompts.py

@@ -53,7 +53,7 @@ These words map to DIFFERENT tools depending on what's in scope:
 
 ## How to Work
 
-Act on clear intent for analysis actions (analyze, find/expand, anchor) — never ask "shall I analyze this?", just do it. Nexus creation is the one exception: confirm exploration direction first (see Exploration Setup).
+Act on clear intent for analysis actions (analyze, find/expand, anchor) — never ask "shall I analyze this?", just do it. Nexus creation follows the same rule: create immediately when the perspectives to group are clear. Only pause when the request is genuinely underspecified or a similar exploration already exists (see Exploration Setup).
 Always check resonance AFTER presenting results — but never before acting.
 
 - If the user describes a situation: call `analyze` or `introduce_polarity` depending on whether a clear tension is stated
@@ -106,13 +106,21 @@ pull"), not raw numbers, unless the app preamble or the user asks for the figure
 
 ## Exploration Setup (Nexus)
 
+"Nexus" is the internal name for what the user calls an **Exploration** — same
+thing. Use "nexus" freely in your own reasoning and when referring to the
+`create_nexus`/`expand_nexus` tools, but always say "exploration" in anything
+the user reads.
+
 When the user wants to explore interactions between perspectives:
 
 **Before creating:**
 1. Check existing nexuses via `present_analysis`.
 2. If a nexus with similar intent exists — suggest `expand_nexus` to add perspectives to it.
    Only create separate if user deliberately wants a different scope.
-3. Confirm the exploration direction with the user before creating.
+3. Create immediately when the perspectives to group are clear (named or unambiguous
+   from context). Only pause to ask when the request is genuinely underspecified —
+   no perspectives identifiable — or when Deduplication below applies. Do NOT ask the
+   user to state an exploration intent: infer it internally (see Intent below).
 
 **Grouping (which perspectives to combine):**
 - Prefer perspectives from different polarities (different T-A oppositions). Transformations
@@ -130,7 +138,7 @@ When the user wants to explore interactions between perspectives:
 - Derive a concise title (1-3 words) from the intent silently. No confirmation needed.
 
 **Deduplication (always communicate to the user):**
-- If a nexus with similar intent exists, tell the user: name the existing nexus, show its intent,
+- If a nexus with similar intent exists, tell the user: name the existing exploration, show its intent,
   and ask whether to add perspectives there or create a separate exploration.
 - Never silently redirect to `expand_nexus` — the user must see why and agree.
 - Only skip the prompt if the user explicitly names the existing nexus themselves.

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/agents/apps.py

@@ -301,8 +301,9 @@ both angles and both blindspots together. A complete map of one tension.
 
 ### Exploration Phase
 
-**Nexus** — the exploration space where positions interact. Use: "this
-exploration", "the nexus", "this group of positions".
+**Nexus** — the exploration space where positions interact. Internal term;
+say **"exploration"** to the user, never "nexus". Use: "this exploration",
+"the exploration", "this group of positions".
 
 **Wheel** — causal arrangement of positions into a cycle. Use: "wheel",
 "causal arrangement", "how these positions connect causally".
@@ -369,8 +370,11 @@ The "blindspot" label belongs ONLY to A+ and A- (the opposition's territory).
 T+ and T- are the holder's own visible territory — never label them as blindspots.
 
 - Never mention tool names, pipelines, or graph operations.
-- User-facing structural terms (Wheel, Nexus, Cycle, Transformation, Position,
+- User-facing structural terms (Wheel, Cycle, Transformation, Position,
   Polarity) are fine to use — these are part of the UX vocabulary.
+- "Nexus" is an internal name for what the user calls an **Exploration** —
+  they are the same thing. Always say "exploration" to the user; never surface
+  the word "Nexus" (some power users know it, but default to "exploration").
 - Position labels (T+, T-, A+, A-) can be introduced once the user understands
   the structure, or when they make presentation clearer. Don't hide them
   dogmatically — use them when they serve communication.

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/agents/conversation_facilitator.py

@@ -33,6 +33,7 @@ from dialectical_framework.utils.use_brain import use_brain
 from mirascope.llm import TextChunk, ThoughtChunk
 
 if TYPE_CHECKING:
+    from mirascope.llm import UserContent
     from mirascope.llm.calls import AsyncCall
     from mirascope.llm.responses import AsyncResponse
 
@@ -116,7 +117,7 @@ class ConversationFacilitator(SettingsAware):
     async def submit(
         self,
         response_model: type[T],
-        user_content: str,
+        user_content: UserContent,
         max_tool_rounds: int = 10,
     ) -> T:
         """
@@ -162,7 +163,7 @@ class ConversationFacilitator(SettingsAware):
     async def submit_stream(
         self,
         response_model: type[T],
-        user_content: str,
+        user_content: UserContent,
         max_tool_rounds: int = 10,
     ) -> AsyncGenerator[StreamEvent, None]:
         """

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/concerns/aspect_generation.py

@@ -100,17 +100,17 @@ Your task is to generate aspects (T+, T-, A+, A-) for a thesis-antithesis pair.
 
 ## Examples
 
+Each tetrad resolves into two diagonal contradiction pairs. A pair shares one
+**axis** — a single dimension on which its two aspects sit at opposite ends, so
+they cannot both hold at once. Name the axis first, then place each pole on it.
+
 T = Love, A = Indifference:
-- T+ = Bonding (love that also makes room for the other's autonomy)
-- T- = Enmeshment (love overdeveloped, smothering autonomy)
-- A+ = Autonomy (independence that also deepens the bond)
-- A- = Alienation (independence overdeveloped, severing the bond)
+- Axis "closeness": T+ = Bonding (love that makes room for autonomy) ⟷ A- = Alienation (independence severing the bond)
+- Axis "self-standing": A+ = Autonomy (independence that deepens the bond) ⟷ T- = Enmeshment (love smothering autonomy)
 
 T = Courage, A = Fear:
-- T+ = Trust
-- T- = Foolhardiness
-- A+ = Prudence
-- A- = Paranoia
+- Axis "risk-taking": T+ = Trust ⟷ A- = Paranoia
+- Axis "caution": A+ = Prudence ⟷ T- = Foolhardiness
 
 Generate aspect statements that fit the semantic structure."""
 
@@ -139,19 +139,56 @@ class AspectDto(BaseModel):
 
 
 class ContradictionPairDto(BaseModel):
-    """Two aspects that form a contradiction pair."""
+    """Two aspects that form a diagonal contradiction pair.
+
+    The pair is defined by its `axis`: a single dimension on which the two
+    aspects sit at opposite ends, so they cannot both hold at once. The model
+    must name the axis first, which forces a genuine opposition rather than two
+    independently-plausible aspects.
+    """
 
+    axis: str = Field(
+        description=(
+            "The single dimension on which the two aspects are opposite ends "
+            "(e.g. 'closeness', 'risk-taking'). If no such shared dimension "
+            "exists, the pair is not a genuine contradiction — say so here."
+        )
+    )
     positive_aspect: AspectDto = Field(description="The positive aspect (T+ or A+)")
     negative_aspect: AspectDto = Field(description="The negative aspect (A- or T-)")
 
 
 class TetradDto(BaseModel):
-    """Full tetrad of four aspects."""
+    """Full tetrad: four aspects grouped by the two axes they oppose along.
 
-    t_plus: AspectDto = Field(description="T+ - constructive thesis")
-    t_minus: AspectDto = Field(description="T- - exaggerated thesis")
-    a_plus: AspectDto = Field(description="A+ - constructive antithesis")
-    a_minus: AspectDto = Field(description="A- - exaggerated antithesis")
+    The four aspects stay as top-level fields (deep nesting made the model drop
+    a whole diagonal branch), but each diagonal pair leads with an explicit
+    `axis` field — the shared dimension its two poles sit at opposite ends of.
+    Naming the axis forces genuine diagonal contradiction into the output
+    instead of leaving it to a trailing constraint.
+    """
+
+    # --- Pair 1: T+ vs A- (thesis-constructive axis) ---
+    t_plus_vs_a_minus_axis: str = Field(
+        description=(
+            "The single dimension on which T+ and A- are opposite ends "
+            "(e.g. 'closeness'). If T and A share no such dimension, the pair "
+            "is not a genuine contradiction — say so here."
+        )
+    )
+    t_plus: AspectDto = Field(description="T+ - constructive thesis (positive end of the axis)")
+    a_minus: AspectDto = Field(description="A- - exaggerated antithesis (negative end of the axis)")
+
+    # --- Pair 2: A+ vs T- (antithesis-constructive axis) ---
+    a_plus_vs_t_minus_axis: str = Field(
+        description=(
+            "The single dimension on which A+ and T- are opposite ends. If A "
+            "and T share no such dimension, say so here rather than inventing "
+            "two unrelated aspects."
+        )
+    )
+    a_plus: AspectDto = Field(description="A+ - constructive antithesis (positive end of the axis)")
+    t_minus: AspectDto = Field(description="T- - exaggerated thesis (negative end of the axis)")
 
 
 # --- Result ---
@@ -178,6 +215,17 @@ class AspectGeneration(ReasonableConcern[list[AspectResult]], SettingsAware):
 
     Generates aspects with HS calculated against taxonomy apex and K values.
     Contradiction pairs are generated together to ensure coherence.
+
+    Design decision — diagonal contradiction is enforced by the PROMPT here, not
+    by a post-hoc scorer. `TetradDto` makes each diagonal pair name the `axis`
+    it opposes along, which forces genuine contradiction into the output. We do
+    NOT run `DiagonalOppositionsCheck` on this path: generation is latency- and
+    cost-sensitive (it fans out across polarities × aspects), and the scorer
+    would add 2 LLM calls per perspective. `DiagonalOppositionsCheck` exists as
+    a safety net only where the prompt is bypassed — user edits in
+    `edit_perspective._validate_tetrad_coherence`. If a T/A pair is genuinely
+    not an opposition, that is caught upstream at polarity formation
+    (AntitheticalThesisDetection / the HS gate), not here.
     """
 
     def __init__(self) -> None:
@@ -325,9 +373,9 @@ class AspectGeneration(ReasonableConcern[list[AspectResult]], SettingsAware):
         results = []
         position_to_dto = {
             POSITION_T_PLUS: result.t_plus,
-            POSITION_T_MINUS: result.t_minus,
-            POSITION_A_PLUS: result.a_plus,
             POSITION_A_MINUS: result.a_minus,
+            POSITION_A_PLUS: result.a_plus,
+            POSITION_T_MINUS: result.t_minus,
         }
 
         for pos in positions:
@@ -535,13 +583,17 @@ Taxonomy apex concepts for reference:
 - A+ apex: {a_plus_apex}
 - A- apex: {a_minus_apex}
 {existing_section}{avoid_section}
+Build the tetrad as its two diagonal contradiction pairs (T+ vs A-, A+ vs T-).
+For each pair:
+1. First name the **axis** — the single dimension on which the two aspects are opposite ends, so they cannot both hold at once.
+2. Then place each aspect at an opposite end of that axis.
+If T and A do not admit a genuine shared axis of opposition, say so in the pair's `axis` field rather than inventing two unrelated aspects.
+
 Generate each aspect (1-{max_words} words) with:
 
 {HS_SCALE}
 
-{COMPLEMENTARITY_SCALE}
-
-Ensure T+ contradicts A-, and A+ contradicts T-."""
+{COMPLEMENTARITY_SCALE}"""
 
     def _contradiction_pair_prompt(
         self,
@@ -590,7 +642,7 @@ Generate each aspect (1-{max_words} words) with:
 {COMPLEMENTARITY_SCALE}
 
 The positive_aspect is {positive_pos}, the negative_aspect is {negative_pos}.
-They must contradict each other - they cannot both be true/good simultaneously."""
+First name the **axis** — the single dimension on which they are opposite ends — then place each at an opposite end of it. They cannot both hold at once. If no such shared axis exists, say so in the `axis` field rather than inventing two unrelated aspects."""
 
     def _single_aspect_prompt(self, position: str, existing_context: str) -> str:
         """Build prompt for single aspect generation."""

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/concerns/source_digest.py

@@ -19,12 +19,15 @@ Programmatic usage:
 
 from __future__ import annotations
 
-from typing import Union
+from typing import TYPE_CHECKING, Union
 
 from dependency_injector.wiring import Provide, inject
 from gqlalchemy import Memgraph, Neo4j
 from pydantic import BaseModel, Field
 
+if TYPE_CHECKING:
+    from mirascope.llm import UserContent
+
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
@@ -96,11 +99,20 @@ class SourceDigest(ReasonableConcern[Input], SettingsAware):
         if not input_node:
             raise ValueError(f"Input not found: {input_hash}")
 
-        resolved_content = await input_resolver.resolve(input_node)
+        resolved_content = await input_resolver.resolve_native(input_node)
         if not resolved_content:
             raise ValueError(f"Input {input_hash} has no resolvable content")
 
-        if len(resolved_content) <= DIGEST_THRESHOLD and not input_node.digest:
+        is_text = isinstance(resolved_content, str)
+
+        # Only text can be used verbatim as its own digest. Native media
+        # (image/PDF parts) must always go through the model's vision pass —
+        # there is no meaningful "raw content" to store as a digest.
+        if (
+            is_text
+            and len(resolved_content) <= DIGEST_THRESHOLD
+            and not input_node.digest
+        ):
             new_digest = resolved_content
             self._report.summary = f"Content compact enough to use as digest for input {input_node.short_hash}"
         else:
@@ -122,7 +134,7 @@ class SourceDigest(ReasonableConcern[Input], SettingsAware):
 
     async def _generate_digest(
         self,
-        content: str,
+        content: UserContent,
         existing_digest: str | None = None,
         context: str = "",
     ) -> str:
@@ -140,17 +152,23 @@ class SourceDigest(ReasonableConcern[Input], SettingsAware):
 
     def _build_prompt(
         self,
-        content: str,
+        content: UserContent,
         existing_digest: str | None,
         context: str,
-    ) -> str:
+    ) -> UserContent:
+        # Text sources are interpolated inline; native media (image/PDF parts)
+        # are appended as a separate content part with a text placeholder in the
+        # <source> slot so the model knows where the attached source belongs.
+        is_text = isinstance(content, str)
+        source_text = content if is_text else "(see the attached source below)"
+
         sections = []
 
         if existing_digest:
             sections.append(f"<existing_digest>\n{existing_digest}\n</existing_digest>")
             if context:
                 sections.append(f"<context>\n{context}\n</context>")
-            sections.append(f"<source>\n{content}\n</source>")
+            sections.append(f"<source>\n{source_text}\n</source>")
             sections.append(
                 "Refine the existing digest incorporating the context provided. "
                 "Sharpen focus, add relevant details, remove irrelevant parts."
@@ -158,9 +176,20 @@ class SourceDigest(ReasonableConcern[Input], SettingsAware):
         else:
             if context:
                 sections.append(f"<context>\n{context}\n</context>")
-            sections.append(f"<source>\n{content}\n</source>")
+            sections.append(f"<source>\n{source_text}\n</source>")
             sections.append(
                 "Generate an initial analytical digest of this source."
             )
 
-        return "\n\n".join(sections)
+        prompt_text = "\n\n".join(sections)
+
+        if is_text:
+            return prompt_text
+
+        # Multimodal: text instructions followed by the native source part(s).
+        parts: list = [prompt_text]
+        if isinstance(content, (list, tuple)):
+            parts.extend(content)
+        else:
+            parts.append(content)
+        return parts

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/graph/composite_input_resolver.py

@@ -17,6 +17,8 @@ from dialectical_framework.graph.verbatim_input_resolver import VerbatimInputRes
 from dialectical_framework.protocols.input_resolver import InputResolver
 
 if TYPE_CHECKING:
+    from mirascope.llm import UserContent
+
     from dialectical_framework.graph.nodes.case import Case
     from dialectical_framework.graph.nodes.input import Input
 
@@ -88,6 +90,30 @@ class CompositeInputResolver(InputResolver):
         # VerbatimInputResolver handles plain text and data: URIs
         return await self._verbatim.resolve(input_node)
 
+    async def resolve_native(self, input_node: Input) -> UserContent:
+        """
+        Resolve an Input to native model content, preserving image/PDF modality.
+
+        Delegates data: and plain-text content to the VerbatimInputResolver's
+        native path (which emits Image/Document parts for supported media). dx://
+        references resolve to graph-node text, so they stay text.
+
+        Args:
+            input_node: Input node with content to resolve.
+
+        Returns:
+            `UserContent` — a media part for supported binary data: URIs,
+            otherwise the resolved text `str`.
+        """
+        content = input_node.content
+        if not content:
+            return ""
+
+        if content.startswith("dx://"):
+            return await self._dialexity.resolve(content)
+
+        return await self._verbatim.resolve_native(input_node)
+
     async def resolve_all(self, source: Union[Case, list[Input]]) -> str:
         """
         Resolve multiple inputs to combined text content.

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/graph/verbatim_input_resolver.py

@@ -14,9 +14,18 @@ from urllib.parse import unquote
 from dialectical_framework.protocols.input_resolver import InputResolver
 
 if TYPE_CHECKING:
+    from mirascope.llm import UserContent
+
     from dialectical_framework.graph.nodes.case import Case
     from dialectical_framework.graph.nodes.input import Input
 
+# Mime types Mirascope accepts as native image/document parts. Anything else
+# (text, unknown binary) falls back to text resolution.
+_IMAGE_MIME_TYPES = frozenset(
+    {"image/png", "image/jpeg", "image/webp", "image/gif", "image/heic", "image/heif"}
+)
+_DOCUMENT_MIME_TYPES = frozenset({"application/pdf"})
+
 
 class VerbatimInputResolver(InputResolver):
     """
@@ -68,6 +77,31 @@ class VerbatimInputResolver(InputResolver):
         # Otherwise, treat as plain text
         return content
 
+    async def resolve_native(self, input_node: Input) -> UserContent:
+        """
+        Resolve content to native model content, preserving image/PDF modality.
+
+        For a `data:` URI whose mime type is a supported image or PDF format,
+        returns a Mirascope `Image` / `Document` part carrying the base64 bytes,
+        so the model reads the source natively instead of a transcription. All
+        other content (text, `data:text/*`, non-base64, unsupported binary)
+        falls back to `resolve()` text.
+
+        Args:
+            input_node: Input node with content (plain text or data: URI).
+
+        Returns:
+            A multimodal part (`Image`/`Document`) for supported binary media,
+            otherwise the resolved text `str`.
+        """
+        content = input_node.content
+        if content and content.startswith("data:"):
+            part = self._decode_data_uri_native(content)
+            if part is not None:
+                return part
+
+        return await self.resolve(input_node)
+
     async def resolve_all(self, source: Union[Case, list[Input]]) -> str:
         """
         Resolve multiple inputs to combined text content.
@@ -106,6 +140,47 @@ class VerbatimInputResolver(InputResolver):
 
         return "\n\n".join(parts)
 
+    @staticmethod
+    def _decode_data_uri_native(uri: str) -> UserContent | None:
+        """
+        Build a native image/document part from a data: URI, if it is one.
+
+        Returns an `Image`/`Document` for a base64 data: URI whose mime type is a
+        supported image or PDF format. Returns None for anything that should be
+        handled as text (text mime types, non-base64 payloads, unsupported types),
+        letting the caller fall back to text resolution.
+        """
+        # data:<mime>[;base64],<data>
+        content_part = uri[5:]
+        if "," not in content_part:
+            return None
+
+        metadata, data = content_part.split(",", 1)
+        if ";base64" not in metadata.lower():
+            # Text data: URIs (or non-base64 binary) are handled as text.
+            return None
+
+        mime_type = metadata.split(";", 1)[0].strip().lower()
+
+        from mirascope.llm import (Base64DocumentSource, Base64ImageSource,
+                                   Document, Image)
+
+        if mime_type in _IMAGE_MIME_TYPES:
+            return Image(
+                source=Base64ImageSource(
+                    type="base64_image_source", data=data, mime_type=mime_type
+                )
+            )
+
+        if mime_type in _DOCUMENT_MIME_TYPES:
+            return Document(
+                source=Base64DocumentSource(
+                    type="base64_document_source", data=data, media_type=mime_type
+                )
+            )
+
+        return None
+
     @staticmethod
     def _decode_data_uri(uri: str) -> str:
         """Decode a data: URI to text."""

{dialectical_framework-1.6.4 → dialectical_framework-1.6.5}/src/dialectical_framework/protocols/input_resolver.py

@@ -8,6 +8,8 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from mirascope.llm import UserContent
+
     from dialectical_framework.graph.nodes.case import Case
     from dialectical_framework.graph.nodes.input import Input
 
@@ -51,6 +53,32 @@ class InputResolver(ABC):
         """
         ...
 
+    async def resolve_native(self, input_node: Input) -> UserContent:
+        """
+        Resolve a single Input to native model content, preserving modality.
+
+        Unlike `resolve()`, which always flattens to text, this returns Mirascope
+        `UserContent` — either a plain `str` for text sources, or multimodal parts
+        (`Image`, `Document`, or a list mixing text and such parts) for images/PDFs.
+        Callers that pass content straight to the model (e.g. the `SourceDigest`
+        concern's vision pass) use this to let the model read the source natively
+        rather than a lossy transcription.
+
+        The default implementation delegates to `resolve()`, so text-only resolvers
+        need not override it. Resolvers that back image/PDF sources should override
+        this to emit the corresponding `Image`/`Document` parts.
+
+        Args:
+            input_node: Input node with content to resolve.
+
+        Returns:
+            `UserContent` — a `str`, a single multimodal part, or a list of parts.
+
+        Raises:
+            ValueError: If content format is unsupported (implementation-dependent).
+        """
+        return await self.resolve(input_node)
+
     @abstractmethod
     async def resolve_all(self, source: Case | list[Input]) -> str:
         """