dialectical-framework 1.1.2__tar.gz → 1.1.3__tar.gz

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/PKG-INFO

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

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

@@ -113,6 +113,8 @@ def _build_tools() -> list:
         place_statement
     from dialectical_framework.agents.explorer.tools.create_nexus import \
         create_nexus
+    from dialectical_framework.agents.explorer.tools.expand_nexus import \
+        expand_nexus
     from dialectical_framework.agents.orchestrator.tools.add_input import \
         add_input
     from dialectical_framework.agents.orchestrator.tools.get_schema import \
@@ -138,6 +140,7 @@ def _build_tools() -> list:
         edit_perspective,
         discard,
         create_nexus,
+        expand_nexus,
         present_analysis,
         inspect_node,
         query_graph,

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/analyst/system_prompts.py

@@ -51,7 +51,7 @@ Always check resonance AFTER presenting results — but never before acting.
 - If the user gives a single concept: call `anchor_theses` with that concept as a statement.
 - If the user disagrees with a generated aspect: offer `edit_perspective` with their correction, or `discard` if the whole perspective misses the mark.
 - If the user corrects or refines: use `edit_perspective` or `discard` immediately
-- If the user wants to explore interactions: use `create_nexus`
+- If the user wants to explore interactions: see "Exploration Setup" section below
 - If the user asks "what do we have?": use `present_analysis`
 - If the user works step-by-step: follow their lead with granular tools
 - When resuming with existing data: use `present_analysis` to orient
@@ -59,6 +59,29 @@ Always check resonance AFTER presenting results — but never before acting.
 When new tensions emerge from conversation:
 - Call `analyze` with `thesis_hashes` to develop them without re-processing everything.
 
+## Exploration Setup (Nexus)
+
+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.
+
+**Intent (internal quality gate — do not surface to user):**
+- Must be specific: what the user wants to understand or navigate.
+- Refine vague requests ("explore this") into purposeful intents internally.
+
+**Title:**
+- 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,
+  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.
+
 ## Tools
 
 **Full pipeline:**
@@ -79,7 +102,8 @@ When new tensions emerge from conversation:
 - `discard` — Discard statements or perspectives the user doesn't want.
 
 **Exploration setup:**
-- `create_nexus` — Group perspectives for exploration in a dedicated thread.
+- `create_nexus` — Create a new exploration grouping perspectives.
+- `expand_nexus` — Add perspectives to an existing exploration.
 
 **Querying:**
 - `present_analysis` — Overview of what's been built.

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/explorer/explorer.py

@@ -119,6 +119,8 @@ def _build_tools() -> list:
         build_wheels
     from dialectical_framework.agents.explorer.skills.explore_transformations import \
         explore_transformations
+    from dialectical_framework.agents.explorer.tools.expand_nexus import \
+        expand_nexus
     from dialectical_framework.agents.explorer.tools.present_exploration import \
         present_exploration
     from dialectical_framework.agents.orchestrator.tools.get_schema import \
@@ -131,6 +133,7 @@ def _build_tools() -> list:
     return [
         build_wheels,
         explore_transformations,
+        expand_nexus,
         present_exploration,
         inspect_node,
         query_graph,

dialectical_framework-1.1.3/src/dialectical_framework/agents/explorer/tools/create_nexus.py

@@ -0,0 +1,41 @@
+"""
+create_nexus tool: thin LLM-facing wrapper around the CreateNexus concern.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.concerns.create_nexus import CreateNexus
+
+
+@llm.tool
+async def create_nexus(
+    intent: Annotated[
+        str, Field(description="Exploration purpose — what to understand or navigate")
+    ],
+    perspective_hashes: Annotated[
+        list[str], Field(description="Hashes of Perspectives to include")
+    ],
+    title: Annotated[
+        Optional[str],
+        Field(
+            description="Short title for UI display (1-3 words, derived from intent)"
+        ),
+    ] = None,
+    preset: Annotated[
+        str,
+        Field(
+            description="Estimation strategy: 'preset:auto', 'preset:balanced', 'preset:realistic', 'preset:desirable', 'preset:feasible'"
+        ),
+    ] = "preset:auto",
+) -> str:
+    """Create a Nexus — an exploration container that groups Perspectives for structural combination into Cycles and Wheels. The intent describes what to explore or navigate."""
+    concern = CreateNexus()
+    await concern.resolve(
+        intent=intent, perspective_hashes=perspective_hashes, preset=preset, title=title
+    )
+    return str(concern.report)

dialectical_framework-1.1.3/src/dialectical_framework/agents/explorer/tools/expand_nexus.py

@@ -0,0 +1,27 @@
+"""
+expand_nexus tool: thin LLM-facing wrapper around the ExpandNexus concern.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.concerns.expand_nexus import ExpandNexus
+
+
+@llm.tool
+async def expand_nexus(
+    nexus_hash: Annotated[
+        str, Field(description="Hash of the existing Nexus to expand")
+    ],
+    perspective_hashes: Annotated[
+        list[str], Field(description="Hashes of Perspectives to add")
+    ],
+) -> str:
+    """Add Perspectives to an existing Nexus. Skips any already connected. Use when the user wants to include additional perspectives in an existing exploration rather than creating a new one."""
+    concern = ExpandNexus()
+    await concern.resolve(nexus_hash=nexus_hash, perspective_hashes=perspective_hashes)
+    return str(concern.report)

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/explorer/tools/present_exploration.py

@@ -82,6 +82,8 @@ class PresentExploration(ReasonableConcern[str]):
     @staticmethod
     def _format_nexus_header(nexus: Nexus) -> str:
         lines = [f"## Nexus [{nexus.short_hash}]"]
+        if nexus.title:
+            lines.append(f"Title: {nexus.title}")
         if nexus.intent:
             lines.append(f"Intent: {nexus.intent}")
         if nexus.preset:

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/orchestrator/tools/get_schema.py

@@ -25,7 +25,7 @@ GRAPH_SCHEMA = """## Graph Schema
 | Statement | A thesis, position, or claim | `text`, `meaning`, `discarded` |
 | Polarity | A tension — structural T-A pair (thesis vs antithesis) | |
 | Perspective | Full interpretation: Polarity + evaluative aspects (T+, T-, A+, A-) | `intent`, `discarded` |
-| Nexus | Exploration container grouping Perspectives for combination | `intent`, `preset` |
+| Nexus | Exploration container grouping Perspectives for combination | `intent`, `preset`, `title` |
 | Cycle | Ordered sequence of Perspectives defining causality | `intent` |
 | Wheel | Concrete T-A arrangement implementing a Cycle | `intent` |
 | Transformation | Action-reflection structure (Ac, Re, Ac+, Ac-, Re+, Re-) on a Wheel edge | `intent` |

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/orchestrator/tools/inspect_node.py

@@ -238,7 +238,8 @@ def _inspect_nexus(nexus: Nexus) -> str:
     lines: list[str] = []
 
     # Header
-    lines.append(f"## Nexus [{_node_id(nexus)}]{_status_tag(nexus)}")
+    title_suffix = f" — {nexus.title}" if nexus.title else ""
+    lines.append(f"## Nexus [{_node_id(nexus)}]{title_suffix}{_status_tag(nexus)}")
     lines.append(repr(nexus))
     lines.append("")
 

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/orchestrator/tools/present_analysis.py

@@ -136,7 +136,10 @@ class PresentAnalysis(ReasonableConcern[str]):
         lines = ["## Nexuses"]
         for n in nexuses:
             pp_list = [(pp, _) for pp, _ in n.perspectives.all() if not pp.discarded]
-            lines.append(f"\n  [{n.short_hash}] {n.intent or '(no intent)'} ({len(pp_list)} perspectives)")
+            display = n.title or n.intent or "(no intent)"
+            lines.append(f"\n  [{n.short_hash}] {display} ({len(pp_list)} perspectives)")
+            if n.title and n.intent:
+                lines.append(f"    Intent: {n.intent}")
             lines.append(f"    Preset: {n.preset or 'default'}")
             for pp, _ in pp_list:
                 lines.append(f"    - [{pp.short_hash}] {pp:positions:0}")

{dialectical_framework-1.1.2/src/dialectical_framework/agents/explorer/tools → dialectical_framework-1.1.3/src/dialectical_framework/concerns}/create_nexus.py

@@ -1,23 +1,18 @@
 """
-CreateNexus: Concern + tool for creating exploration containers.
+CreateNexus concern: creates an exploration container and connects Perspectives to it.
 """
 
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Annotated, Optional, Union
-
-from dependency_injector.wiring import Provide, inject
-from gqlalchemy import Memgraph, Neo4j
-from mirascope import llm
-from pydantic import Field
+from typing import Optional
 
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
 from dialectical_framework.enums.causality_preset import CausalityPreset
-from dialectical_framework.enums.di import DI
 from dialectical_framework.graph.nodes.nexus import Nexus
 from dialectical_framework.graph.nodes.perspective import Perspective
-from dialectical_framework.graph.repositories.node_repository import NodeRepository
+from dialectical_framework.graph.repositories.node_repository import \
+    NodeRepository
 
 
 @dataclass
@@ -44,6 +39,7 @@ class CreateNexus(ReasonableConcern[CreateNexusResult]):
         intent: str,
         perspective_hashes: list[str],
         preset: str = CausalityPreset.AUTO,
+        title: Optional[str] = None,
     ) -> CreateNexusResult:
         if not perspective_hashes:
             raise ValueError("At least one Perspective hash is required.")
@@ -58,6 +54,11 @@ class CreateNexus(ReasonableConcern[CreateNexusResult]):
 
         nexus = Nexus(intent=intent, preset=preset)
         nexus.commit()
+
+        if title:
+            nexus.title = title
+            nexus.save()
+
         self._report.node_created(nexus)
 
         for pp in perspectives:
@@ -73,15 +74,3 @@ class CreateNexus(ReasonableConcern[CreateNexusResult]):
         self._report.artifacts["preset"] = preset
 
         return CreateNexusResult(nexus=nexus, perspectives=perspectives)
-
-
-@llm.tool
-async def create_nexus(
-    intent: Annotated[str, Field(description="Exploration purpose — what to understand or navigate")],
-    perspective_hashes: Annotated[list[str], Field(description="Hashes of Perspectives to include")],
-    preset: Annotated[str, Field(description="Estimation strategy: 'preset:auto', 'preset:balanced', 'preset:realistic', 'preset:desirable', 'preset:feasible'")] = "preset:auto",
-) -> str:
-    """Create a Nexus — an exploration container that groups Perspectives for structural combination into Cycles and Wheels. The intent describes what to explore or navigate."""
-    concern = CreateNexus()
-    await concern.resolve(intent=intent, perspective_hashes=perspective_hashes, preset=preset)
-    return str(concern.report)

dialectical_framework-1.1.3/src/dialectical_framework/concerns/expand_nexus.py

@@ -0,0 +1,79 @@
+"""
+ExpandNexus concern: adds Perspectives to an existing Nexus.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.graph.nodes.nexus import Nexus
+from dialectical_framework.graph.nodes.perspective import Perspective
+from dialectical_framework.graph.repositories.node_repository import \
+    NodeRepository
+
+
+@dataclass
+class ExpandNexusResult:
+    nexus: Nexus
+    added: list[Perspective] = field(default_factory=list)
+    skipped: list[Perspective] = field(default_factory=list)
+
+
+class ExpandNexus(ReasonableConcern[ExpandNexusResult]):
+    """
+    Adds Perspectives to an existing Nexus, skipping already-connected ones.
+
+    Programmatic usage:
+        concern = ExpandNexus()
+        result = await concern.resolve(
+            nexus_hash="abc123",
+            perspective_hashes=["def456", "ghi789"],
+        )
+        print(f"Added {len(result.added)}, skipped {len(result.skipped)}")
+    """
+
+    async def resolve(
+        self,
+        nexus_hash: str,
+        perspective_hashes: list[str],
+    ) -> ExpandNexusResult:
+        if not perspective_hashes:
+            raise ValueError("At least one Perspective hash is required.")
+
+        repo = NodeRepository()
+
+        nexus = repo.find_by_hash(nexus_hash, node_type=Nexus)
+        if nexus is None:
+            raise ValueError(f"Nexus not found: {nexus_hash}")
+
+        perspectives: list[Perspective] = []
+        for pp_hash in perspective_hashes:
+            node = repo.find_by_hash(pp_hash, node_type=Perspective)
+            if node is None:
+                raise ValueError(f"Perspective not found: {pp_hash}")
+            perspectives.append(node)
+
+        existing_hashes = {pp.hash for pp, _ in nexus.perspectives.all()}
+        added: list[Perspective] = []
+        skipped: list[Perspective] = []
+
+        for pp in perspectives:
+            if pp.hash not in existing_hashes:
+                pp.nexus.connect(nexus)
+                self._report.relationship_created(pp.nexus, pp, nexus)
+                existing_hashes.add(pp.hash)
+                added.append(pp)
+            else:
+                skipped.append(pp)
+
+        self._report.ok = True
+        self._report.summary = (
+            f"Expanded Nexus {nexus.short_hash}: added {len(added)} perspectives"
+            + (f", skipped {len(skipped)} already connected" if skipped else "")
+        )
+        self._report.artifacts["nexus_hash"] = nexus.short_hash
+        self._report.artifacts["added_count"] = len(added)
+        self._report.artifacts["skipped_count"] = len(skipped)
+
+        return ExpandNexusResult(nexus=nexus, added=added, skipped=skipped)

{dialectical_framework-1.1.2 → dialectical_framework-1.1.3}/src/dialectical_framework/graph/nodes/nexus.py

@@ -17,7 +17,10 @@ from dialectical_framework.enums.causality_preset import CausalityPreset
 from dialectical_framework.enums.di import DI
 from dialectical_framework.graph.nodes.base_node import BaseNode
 from dialectical_framework.graph.mixins.intent_mixin import IntentMixin
-from dialectical_framework.graph.relationship_manager import RelationshipFrom, RelationshipManager
+from dialectical_framework.graph.relationship_manager import (
+    RelationshipFrom,
+    RelationshipManager,
+)
 from dialectical_framework.graph.relationships.belongs_to_nexus_relationship import (
     BelongsToNexusRelationship,
 )
@@ -73,12 +76,16 @@ class Nexus(IntentMixin, BaseNode, label="Nexus"):
     # Prompt strategy for causality estimation (preset selector)
     preset: str = CausalityPreset.BALANCED
 
+    # Display title (not part of hash — purely metadata).
+    # NOTE: Cannot use Optional[str] here due to GQLAlchemy metaclass + future annotations.
+    title: str = None
+
     # Perspectives in this exploration
     # PP→Nexus: Perspective belongs to this Nexus
     perspectives: ClassVar[RelationshipManager[Perspective]] = RelationshipFrom(
         "Perspective",
         model=BelongsToNexusRelationship,
-        cardinality=(0, None)  # Zero or more PPs
+        cardinality=(0, None),  # Zero or more PPs
     )
 
     # NOTE: Cycles are derived from PPs, not stored as relationship.
@@ -93,10 +100,7 @@ class Nexus(IntentMixin, BaseNode, label="Nexus"):
         return [self.preset]
 
     @inject
-    def commit(
-        self,
-        graph_db: Union[Memgraph, Neo4j] = Provide[DI.graph_db]
-    ) -> Self:
+    def commit(self, graph_db: Union[Memgraph, Neo4j] = Provide[DI.graph_db]) -> Self:
         """
         Commit this Nexus to the database.
 
@@ -117,12 +121,15 @@ class Nexus(IntentMixin, BaseNode, label="Nexus"):
         """Debug representation of the Nexus."""
         id_str = self.short_hash or "uncommitted"
         pp_count = self.perspectives.count()
-        return f"Nexus({id_str}, pps={pp_count}, preset={self.preset}, intent={self.intent})"
+        title_str = f", title={self.title}" if self.title else ""
+        return f"Nexus({id_str}{title_str}, pps={pp_count}, preset={self.preset}, intent={self.intent})"
 
     def __str__(self) -> str:
         """String representation of the Nexus."""
         id_str = self.short_hash or "uncommitted"
         parts = [f"hash={id_str}", f"preset={self.preset}"]
+        if self.title:
+            parts.append(f"title={self.title}")
         if self.intent:
             parts.append(f"intent={self.intent}")
         return f"Nexus({', '.join(parts)})"