dialectical-framework 1.2.5__tar.gz → 1.3.0__tar.gz

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.2.5
+Version: 1.3.0
 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
@@ -87,6 +87,19 @@ Think of a Wheel as a pizza: segments are slices (T, T+, T-), Perspectives are h
 |--------|----------|
 | ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme.png) | ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme2.png) |
 
+## Why a Reasoning Graph
+
+Most AI systems treat knowledge as flat context — dump text into the prompt and hope the LLM figures out the structure. The dialectical framework builds a **persistent reasoning graph** where the structure itself encodes how to think about a domain:
+
+- **Oppositions are explicit.** The LLM doesn't need to discover tensions — they're mapped as T/A pairs with typed aspects showing where each side overreaches (T-, A-) and where it constructively balances the other (T+, A+).
+- **Transformations encode causality.** Edges don't just connect — they show how one position's failure becomes another's strength. This is the circular causality that drives synthesis.
+- **Quality is measurable.** Complementarity, modality balance, area metrics tell the LLM which reasoning paths are well-developed and which are thin — no guessing about confidence.
+- **Knowledge compounds.** Each new perspective enters an existing graph of validated reasoning. The LLM builds on prior synthesis rather than re-deriving from scratch.
+
+The result: an LLM with this graph in context doesn't just have facts about a topic — it has the intellectual terrain mapped. What opposes what, where balance was achieved, what assumptions remain untested, and where synthesis is possible.
+
+This is the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern realized as a semantic graph rather than a pile of markdown files — knowledge that is structured, rule-validated, and queryable by reasoning topology.
+
 ## Integration
 
 The framework is designed as a drop-in reasoning engine for AI applications that need dialectical analysis — decision support, systems thinking, mediation, ethical modeling.

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/README.md

@@ -46,6 +46,19 @@ Think of a Wheel as a pizza: segments are slices (T, T+, T-), Perspectives are h
 |--------|----------|
 | ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme.png) | ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme2.png) |
 
+## Why a Reasoning Graph
+
+Most AI systems treat knowledge as flat context — dump text into the prompt and hope the LLM figures out the structure. The dialectical framework builds a **persistent reasoning graph** where the structure itself encodes how to think about a domain:
+
+- **Oppositions are explicit.** The LLM doesn't need to discover tensions — they're mapped as T/A pairs with typed aspects showing where each side overreaches (T-, A-) and where it constructively balances the other (T+, A+).
+- **Transformations encode causality.** Edges don't just connect — they show how one position's failure becomes another's strength. This is the circular causality that drives synthesis.
+- **Quality is measurable.** Complementarity, modality balance, area metrics tell the LLM which reasoning paths are well-developed and which are thin — no guessing about confidence.
+- **Knowledge compounds.** Each new perspective enters an existing graph of validated reasoning. The LLM builds on prior synthesis rather than re-deriving from scratch.
+
+The result: an LLM with this graph in context doesn't just have facts about a topic — it has the intellectual terrain mapped. What opposes what, where balance was achieved, what assumptions remain untested, and where synthesis is possible.
+
+This is the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern realized as a semantic graph rather than a pile of markdown files — knowledge that is structured, rule-validated, and queryable by reasoning topology.
+
 ## Integration
 
 The framework is designed as a drop-in reasoning engine for AI applications that need dialectical analysis — decision support, systems thinking, mediation, ethical modeling.

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/pyproject.toml

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

@@ -117,6 +117,8 @@ def _build_tools() -> list:
         expand_nexus
     from dialectical_framework.agents.orchestrator.tools.add_input import \
         add_input
+    from dialectical_framework.agents.orchestrator.tools.digest_input import \
+        digest_input
     from dialectical_framework.agents.orchestrator.tools.get_schema import \
         get_schema
     from dialectical_framework.agents.orchestrator.tools.inspect_node import \
@@ -125,11 +127,18 @@ def _build_tools() -> list:
         present_analysis
     from dialectical_framework.agents.orchestrator.tools.query_graph import \
         query_graph
+    from dialectical_framework.agents.orchestrator.tools.read_digest import \
+        read_digest
+    from dialectical_framework.agents.orchestrator.tools.read_input import \
+        read_input
     from dialectical_framework.agents.orchestrator.tools.discard import discard
 
     return [
         analyze,
         add_input,
+        digest_input,
+        read_digest,
+        read_input,
         anchor_theses,
         surface_theses,
         find_polarities,

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/analyst/skills/anchor_theses.py

@@ -163,16 +163,10 @@ class AnchorTheses(ReasonableConcern[Optional[Ideas]]):
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        inputs = self._get_inputs()
-        if not inputs:
-            return ""
-
-        texts = []
-        for input_node in inputs:
-            resolved = await input_resolver.resolve(input_node)
-            texts.append(resolved)
+        from dialectical_framework.utils.input_context import input_context
 
-        return "\n\n---\n\n".join(texts)
+        inputs = self._get_inputs()
+        return await input_context(inputs, input_resolver)
 
 
 @llm.tool

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/analyst/skills/expand_polarities.py

@@ -284,19 +284,13 @@ class ExpandPolarity(ReasonableConcern[list[Perspective]]):
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        """Get concatenated text from all inputs in scope."""
+        """Get input context from digests (falls back to full content if no digest)."""
+        from dialectical_framework.utils.input_context import input_context
+
         repo = InputRepository()
         inputs = repo.get_all()
 
-        if not inputs:
-            return ""
-
-        texts = []
-        for input_node in inputs:
-            resolved = await input_resolver.resolve(input_node)
-            texts.append(resolved)
-
-        return "\n\n---\n\n".join(texts)
+        return await input_context(inputs, input_resolver)
 
 
 @llm.tool

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/analyst/skills/find_polarities.py

@@ -383,19 +383,13 @@ class FindPolarities(ReasonableConcern[Optional[Ideas]]):
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        """Get concatenated text from all inputs in scope."""
+        """Get input context from digests (falls back to full content if no digest)."""
+        from dialectical_framework.utils.input_context import input_context
+
         repo = InputRepository()
         inputs = repo.get_all()
 
-        if not inputs:
-            return ""
-
-        texts = []
-        for input_node in inputs:
-            resolved = await input_resolver.resolve(input_node)
-            texts.append(resolved)
-
-        return "\n\n---\n\n".join(texts)
+        return await input_context(inputs, input_resolver)
 
     def _reconnect_oppositions(
         self,

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/analyst/skills/introduce_polarity.py

@@ -194,19 +194,13 @@ class IntroducePolarity(ReasonableConcern[IntroducePolarityResult]):
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        """Get concatenated text from all inputs in scope."""
+        """Get input context from digests (falls back to full content if no digest)."""
+        from dialectical_framework.utils.input_context import input_context
+
         repo = InputRepository()
         inputs = repo.get_all()
 
-        if not inputs:
-            return ""
-
-        texts = []
-        for input_node in inputs:
-            resolved = await input_resolver.resolve(input_node)
-            texts.append(resolved)
-
-        return "\n\n---\n\n".join(texts)
+        return await input_context(inputs, input_resolver)
 
 
 @llm.tool

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/analyst/skills/surface_theses.py

@@ -347,7 +347,7 @@ Determine:
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        """Get preview (first 500 chars) of each input."""
+        """Get preview of each input (uses digest if available, else first 500 chars)."""
         inputs = self._get_inputs()
 
         if not inputs:
@@ -355,9 +355,12 @@ Determine:
 
         previews = []
         for i, input_node in enumerate(inputs, 1):
-            resolved = await input_resolver.resolve(input_node)
-            preview = resolved[:500] + "..." if len(resolved) > 500 else resolved
-            previews.append(f"[Input {i}]\n{preview}")
+            if input_node.digest:
+                previews.append(f"[Input {i}]\n{input_node.digest}")
+            else:
+                resolved = await input_resolver.resolve(input_node)
+                preview = resolved[:500] + "..." if len(resolved) > 500 else resolved
+                previews.append(f"[Input {i}]\n{preview}")
 
         return "\n\n".join(previews)
 

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/explorer/explorer.py

@@ -126,12 +126,18 @@ def _build_tools() -> list:
         generate_synthesis
     from dialectical_framework.agents.explorer.tools.present_exploration import \
         present_exploration
+    from dialectical_framework.agents.orchestrator.tools.digest_input import \
+        digest_input
     from dialectical_framework.agents.orchestrator.tools.get_schema import \
         get_schema
     from dialectical_framework.agents.orchestrator.tools.inspect_node import \
         inspect_node
     from dialectical_framework.agents.orchestrator.tools.query_graph import \
         query_graph
+    from dialectical_framework.agents.orchestrator.tools.read_digest import \
+        read_digest
+    from dialectical_framework.agents.orchestrator.tools.read_input import \
+        read_input
 
     return [
         build_wheels,
@@ -139,6 +145,9 @@ def _build_tools() -> list:
         generate_synthesis,
         expand_nexus,
         present_exploration,
+        digest_input,
+        read_digest,
+        read_input,
         inspect_node,
         query_graph,
         get_schema,

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/explorer/skills/build_wheels.py

@@ -113,7 +113,7 @@ class BuildWheels(ReasonableConcern[BuildWheelsResult]):
 
     Creates structural combinations (Cycles + Wheels) from Perspectives
     within a Nexus, then estimates them using the appropriate estimator
-    based on the Nexus intent.
+    based on the Nexus intent. Purely structural — no transformations.
 
     Flow:
     1. Resolve Nexus by hash
@@ -213,16 +213,7 @@ class BuildWheels(ReasonableConcern[BuildWheelsResult]):
         if causal_cycles or causal_wheels:
             await self._run_estimation(causal_cycles, causal_wheels)
 
-        # 6. Generate Transformations for 1-PP wheels (circular causality base case)
-        #    These are foundational — higher-layer transformations use them as context.
-        layer1_wheels = [
-            w for w in new_wheels
-            if self._safe_polarity_count(w) == 1
-        ]
-        if layer1_wheels:
-            await self._run_layer1_transformations(layer1_wheels)
-
-        # 7. Build summary
+        # 6. Build summary
         if not new_cycles and not new_wheels:
             self._report.summary = (
                 f"All structures already exist for Nexus {nexus.short_hash} "
@@ -265,28 +256,6 @@ class BuildWheels(ReasonableConcern[BuildWheelsResult]):
             await estimation.resolve(wheels)
             self._report = self._report.merge(estimation.report)
 
-    async def _run_layer1_transformations(self, wheels: list[Wheel]) -> None:
-        """
-        Generate Transformations for 1-PP wheels.
-
-        1-PP wheels are the circular causality base case: Ac+ (T- → A+) and
-        Re+ (A- → T+) within a single Perspective. These serve as foundational
-        context for higher-layer transformation generation.
-        """
-        from dialectical_framework.agents.explorer.skills.explore_transformations import (
-            ExploreTransformations,
-        )
-
-        for wheel in wheels:
-            try:
-                concern = ExploreTransformations(wheel_hash=wheel.hash)
-                await concern.resolve()
-                self._report = self._report.merge(concern.report)
-            except (ValueError, Exception) as e:
-                self._report.artifacts.setdefault("transformation_errors", []).append(
-                    f"Wheel {wheel.short_hash}: {e}"
-                )
-
     @staticmethod
     def _safe_polarity_count(wheel: Wheel) -> int:
         try:

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/explorer/skills/explore_transformations.py

@@ -440,22 +440,15 @@ class ExploreTransformations(ReasonableConcern[ExploreTransformationsResult]):
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        """Get concatenated text from all inputs in scope."""
+        """Get input context from digests (falls back to full content if no digest)."""
         from dialectical_framework.graph.repositories.input_repository import \
             InputRepository
+        from dialectical_framework.utils.input_context import input_context
 
         repo = InputRepository()
         inputs = repo.get_all()
 
-        if not inputs:
-            return ""
-
-        texts = []
-        for input_node in inputs:
-            resolved = await input_resolver.resolve(input_node)
-            texts.append(resolved)
-
-        return "\n\n---\n\n".join(texts)
+        return await input_context(inputs, input_resolver)
 
     def _create_transformation(
         self,

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/explorer/skills/generate_synthesis.py

@@ -165,23 +165,16 @@ class GenerateSynthesis(ReasonableConcern[GenerateSynthesisResult]):
         self,
         input_resolver: InputResolver = Provide[DI.input_resolver],
     ) -> str:
-        """Get concatenated text from all inputs in scope."""
+        """Get input context from digests (falls back to full content if no digest)."""
         from dialectical_framework.graph.repositories.input_repository import (
             InputRepository,
         )
+        from dialectical_framework.utils.input_context import input_context
 
         repo = InputRepository()
         inputs = repo.get_all()
 
-        if not inputs:
-            return ""
-
-        texts = []
-        for input_node in inputs:
-            resolved = await input_resolver.resolve(input_node)
-            texts.append(resolved)
-
-        return "\n\n---\n\n".join(texts)
+        return await input_context(inputs, input_resolver)
 
     def _build_lower_layer_context(self, wheel: Wheel) -> str:
         """Find synthesis from sub-wheels (lower PP layers) sharing perspectives."""

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/orchestrator/tools/add_input.py

@@ -46,7 +46,12 @@ class AddInput(ReasonableConcern[Input]):
 
 @llm.tool
 async def add_input(
-    content: Annotated[str, Field(description="Source material: user-provided text, URL, or captured conversation fragment")],
+    content: Annotated[
+        str,
+        Field(
+            description="Source material: user-provided text, URL, or captured conversation fragment"
+        ),
+    ],
 ) -> str:
     """Add source material for analysis — user-provided text, URL, or captured conversation fragment. Use proactively when the user describes their situation. Not for storing your analytical outputs."""
     concern = AddInput()

dialectical_framework-1.3.0/src/dialectical_framework/agents/orchestrator/tools/digest_input.py

@@ -0,0 +1,92 @@
+"""
+DigestInput: Concern + tool for generating/refining the living digest of an Input source.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Union
+
+from dependency_injector.wiring import Provide, inject
+from gqlalchemy import Memgraph, Neo4j
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.concerns.source_digest import SourceDigest
+from dialectical_framework.enums.di import DI
+from dialectical_framework.graph.nodes.input import Input
+from dialectical_framework.graph.repositories.node_repository import \
+    NodeRepository
+from dialectical_framework.protocols.input_resolver import InputResolver
+
+
+# Content shorter than this is used as its own digest (no LLM call needed)
+DIGEST_THRESHOLD = 1500
+
+
+class DigestInput(ReasonableConcern[Input]):
+    """
+    Generates or refines the digest for an Input node.
+
+    Resolves the full content, runs SourceDigest with any provided context,
+    and persists the result to the Input's digest field.
+
+    Short content (under ~1500 chars) is used directly as the digest
+    without an LLM call — it's already compact enough.
+    """
+
+    @inject
+    async def resolve(
+        self,
+        input_hash: str,
+        context: str = "",
+        input_resolver: InputResolver = Provide[DI.input_resolver],
+        graph_db: Union[Memgraph, Neo4j] = Provide[DI.graph_db],
+    ) -> Input:
+        repo = NodeRepository()
+        input_node = repo.find_by_hash(input_hash, node_type=Input)
+
+        if not input_node:
+            raise ValueError(f"Input not found: {input_hash}")
+
+        resolved_content = await input_resolver.resolve(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:
+            new_digest = resolved_content
+            self._report.summary = f"Content compact enough to use as digest for input {input_node.short_hash}"
+        else:
+            concern = SourceDigest()
+            new_digest = await concern.resolve(
+                content=resolved_content,
+                existing_digest=input_node.digest,
+                context=context,
+            )
+            self._report = self._report.merge(concern.report)
+            self._report.summary = f"Digest {'refined' if input_node.digest else 'created'} for input {input_node.short_hash}"
+
+        input_node.digest = new_digest
+        input_node.save()
+
+        self._report.ok = True
+        self._report.artifacts["input_hash"] = input_node.short_hash
+        self._report.artifacts["digest"] = new_digest
+
+        return input_node
+
+
+@llm.tool
+async def digest_input(
+    input_hash: Annotated[str, Field(description="Hash of the Input node to digest")],
+    context: Annotated[
+        str,
+        Field(
+            description="Direction for the digest: user guidance, framework state, or focus instructions"
+        ),
+    ] = "",
+) -> str:
+    """Generate or refine the analytical digest of an input source. Use to build initial understanding of new inputs, or to sharpen the digest with user direction or framework learnings."""
+    concern = DigestInput()
+    await concern.resolve(input_hash=input_hash, context=context)
+    return str(concern.report)

{dialectical_framework-1.2.5 → dialectical_framework-1.3.0}/src/dialectical_framework/agents/orchestrator/tools/get_schema.py

@@ -20,7 +20,7 @@ GRAPH_SCHEMA = """## Graph Schema
 | Node | Description | Key Properties |
 |------|-------------|----------------|
 | Case | Root session container | |
-| Input | External content (text, URL) for analysis | `content` |
+| Input | External content (text, URL) for analysis | `content`, `digest` |
 | Ideas | Collection of extracted Statements from Inputs | `intent` |
 | Statement | A thesis, position, or claim | `text`, `meaning`, `discarded` |
 | Polarity | A tension — structural T-A pair (thesis vs antithesis) | |

dialectical_framework-1.3.0/src/dialectical_framework/agents/orchestrator/tools/read_digest.py

@@ -0,0 +1,45 @@
+"""
+read_digest: Tool for inspecting the current analytical digest of an Input source.
+
+Used by conversational agents to see the current understanding before deciding
+whether to refine it or pull full content.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Union
+
+from dependency_injector.wiring import Provide, inject
+from gqlalchemy import Memgraph, Neo4j
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.enums.di import DI
+from dialectical_framework.graph.nodes.input import Input
+from dialectical_framework.graph.repositories.node_repository import \
+    NodeRepository
+
+
+@inject
+def _read_digest(
+    input_hash: str,
+    graph_db: Union[Memgraph, Neo4j] = Provide[DI.graph_db],
+) -> str:
+    repo = NodeRepository()
+    input_node = repo.find_by_hash(input_hash, node_type=Input)
+
+    if not input_node:
+        return f"Input not found: {input_hash}"
+
+    if not input_node.digest:
+        return f"No digest yet for input {input_node.short_hash}. Use digest_input to generate one."
+
+    return input_node.digest
+
+
+@llm.tool
+async def read_digest(
+    input_hash: Annotated[str, Field(description="Hash of the Input node")],
+) -> str:
+    """Read the current analytical digest of an input source. Use to see what the framework currently understands about a source before deciding to refine or pull full content."""
+    return _read_digest(input_hash)

dialectical_framework-1.3.0/src/dialectical_framework/agents/orchestrator/tools/read_input.py

@@ -0,0 +1,47 @@
+"""
+read_input: Tool for pulling full resolved content from an Input source.
+
+Used when the LLM decides the digest isn't enough and needs the full source text.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Union
+
+from dependency_injector.wiring import Provide, inject
+from gqlalchemy import Memgraph, Neo4j
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.enums.di import DI
+from dialectical_framework.graph.nodes.input import Input
+from dialectical_framework.graph.repositories.node_repository import \
+    NodeRepository
+from dialectical_framework.protocols.input_resolver import InputResolver
+
+
+@inject
+async def _resolve_input(
+    input_hash: str,
+    input_resolver: InputResolver = Provide[DI.input_resolver],
+    graph_db: Union[Memgraph, Neo4j] = Provide[DI.graph_db],
+) -> str:
+    repo = NodeRepository()
+    input_node = repo.find_by_hash(input_hash, node_type=Input)
+
+    if not input_node:
+        return f"Input not found: {input_hash}"
+
+    resolved = await input_resolver.resolve(input_node)
+    if not resolved:
+        return f"Input {input_hash} has no content"
+
+    return resolved
+
+
+@llm.tool
+async def read_input(
+    input_hash: Annotated[str, Field(description="Hash of the Input node to read")],
+) -> str:
+    """Read the full source content of an input. Use when the digest doesn't have enough detail for your current task."""
+    return await _resolve_input(input_hash)