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

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

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

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

@@ -91,20 +91,9 @@ class ExpandPolarity(ReasonableConcern[list[Perspective]]):
         partial_pps = [pp for pp in existing_pps if not pp.is_complete()]
 
         if not partial_pps:
-            self._report.ok = True
-            self._report.summary = (
-                f"{len(complete_pps)} complete Perspective(s), no partial Perspectives to expand"
-            )
-            self._report.artifacts["perspective_hashes"] = [
-                pp.hash for pp in complete_pps if pp.hash
-            ]
-            self._report.artifacts["total_count"] = len(complete_pps)
-            self._report.artifacts["existing_count"] = len(complete_pps)
-            self._report.artifacts["new_count"] = 0
-            self._report.artifacts["perspectives"] = [
-                self._perspective_final_state(pp) for pp in complete_pps
-            ]
-            return complete_pps
+            # All existing perspectives are complete — create a new one
+            pp = self._create_perspective_for_polarity(polarity)
+            partial_pps = [pp]
 
         # Complete all partial PPs
         completed_pps: list[Perspective] = []
@@ -314,7 +303,7 @@ class ExpandPolarity(ReasonableConcern[list[Perspective]]):
 async def expand_polarities(
     polarity_hashes: Annotated[list[str], Field(description="Hashes of Polarities to expand into full Perspectives")],
 ) -> str:
-    """Build complete Perspectives from Polarities by generating evaluative aspects (T+, T-, A+, A-) for each. Runs in parallel. The Polarities must already exist in the graph."""
+    """Build complete Perspectives from Polarities by generating evaluative aspects (T+, T-, A+, A-) for each. Each call generates one new Perspective per Polarity — call multiple times for alternative perspectives on the same Polarity (duplicates in a single call are ignored). The Polarities must already exist in the graph."""
     import asyncio
 
     async def _expand_one(h: str) -> str:
@@ -322,5 +311,6 @@ async def expand_polarities(
         await concern.resolve()
         return str(concern.report)
 
-    results = await asyncio.gather(*[_expand_one(h) for h in polarity_hashes])
+    unique_hashes = list(dict.fromkeys(polarity_hashes))
+    results = await asyncio.gather(*[_expand_one(h) for h in unique_hashes])
     return "\n---\n".join(results)

{dialectical_framework-1.1.1 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/analyst/skills/find_polarities.py

@@ -155,8 +155,9 @@ class FindPolarities(ReasonableConcern[Optional[Ideas]]):
             result.existing = existing_antitheses
             return result
 
+        unique_hashes = list(dict.fromkeys(self.thesis_hashes))
         thesis_results = await asyncio.gather(
-            *[_process_thesis(h) for h in self.thesis_hashes]
+            *[_process_thesis(h) for h in unique_hashes]
         )
 
         for result in thesis_results:

{dialectical_framework-1.1.1 → 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.
@@ -94,6 +118,8 @@ Adapt depth and presentation to the persona defined in the app preamble.
 ## Rules
 
 - Never dump raw tool output. Synthesize into appropriate presentation.
+- Never rephrase Statement text. Use exact text (or display_text) from the graph — paraphrasing makes it ambiguous which node you're referring to.
+- When referencing structural nodes (Polarity, Perspective, Nexus, Cycle, Wheel, Transformation, Transition, Synthesis), always include the short hash for disambiguation.
 - User corrections take priority — act immediately, don't push back.
 - When resuming a session with existing data, use `present_analysis` to orient before acting.
 - Skill reports may contain truncated text previews. When you need to present exact node text to the user, use `inspect_node` or `present_analysis` by hash — never reconstruct or guess full text from truncated previews.

{dialectical_framework-1.1.1 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/apps.py

@@ -199,6 +199,13 @@ both sides contribute", "constructive co-existence", "where 1+1 > 2".
 - Frame pathways as options, not prescriptions. There are many valid recipes.
 - Present tensions as legitimate — both poles have constructive potential.
 
+## Viewport Scope
+
+Messages may include context about what the user is currently viewing. This tells you their active focus. Respect it:
+
+- Only operate on the node(s) in the user's viewport unless they explicitly reference something else or ask to switch.
+- Never silently pivot to other nodes outside the viewport. If you think working on a different node would help, ask first.
+
 ## Presentation Defaults
 
 Example of a correctly labeled position table:
@@ -213,7 +220,7 @@ Example of a correctly labeled position table:
 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, graph operations, or node hashes.
+- Never mention tool names, pipelines, or graph operations.
 - User-facing structural terms (Wheel, Nexus, Cycle, Transformation, Position,
   Polarity) are fine to use — these are part of the UX vocabulary.
 - Position labels (T+, T-, A+, A-) can be introduced once the user understands

{dialectical_framework-1.1.1 → dialectical_framework-1.1.3}/src/dialectical_framework/agents/conversation_facilitator.py

@@ -293,6 +293,12 @@ class ConversationFacilitator(SettingsAware):
         """Call LLM with format for structured output."""
         messages = self._messages
 
+        # Bedrock requires conversations to end with a user message.
+        # After the agentic tool loop, messages end with assistant — inject a
+        # user prompt so the extraction call is valid for all providers.
+        if messages and messages[-1].role == "assistant":
+            messages = [*messages, llm.messages.user("Provide your structured response.")]
+
         @use_brain(format=response_model)
         async def _llm_call():
             return messages

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

@@ -119,8 +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.create_nexus import \
-        create_nexus
+    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 \
@@ -133,7 +133,7 @@ def _build_tools() -> list:
     return [
         build_wheels,
         explore_transformations,
-        create_nexus,
+        expand_nexus,
         present_exploration,
         inspect_node,
         query_graph,

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

@@ -44,14 +44,10 @@ When the user wants to go deeper on a specific transformation:
 - Use `inspect_node` to show full detail.
 - Explain the tetrad structure: Ac/Ac+/Ac- and Re/Re+/Re-.
 
-When the user wants to create a sub-exploration:
-- Use `create_nexus` to group a subset of perspectives for focused exploration.
-
 ## Tools
 
 - `build_wheels` -- Generate causal structures (Cycles + Wheels) from this Nexus. Use nexus_hash: "{nexus_hash}".
 - `explore_transformations` -- Generate Action-Reflection transformations for a Wheel.
-- `create_nexus` -- Create a sub-nexus for focused exploration of specific perspectives.
 - `present_exploration` -- Show current state of this Nexus: perspectives, wheels, transformations.
 - `inspect_node` -- Deep-dive any node by hash.
 - `query_graph` -- Raw Cypher for custom queries. Call `get_schema` first.
@@ -64,7 +60,8 @@ Adapt depth and presentation to the persona defined in the app preamble.
 ## Rules
 
 - Never dump raw tool output. Synthesize into appropriate presentation.
-- Always work within this Nexus ({nexus_hash}) unless creating a sub-nexus.
+- Never rephrase Statement text. Use exact text (or display_text) from the graph — paraphrasing makes it ambiguous which node you're referring to.
+- When referencing structural nodes (Polarity, Perspective, Nexus, Cycle, Wheel, Transformation, Transition, Synthesis), always include the short hash for disambiguation.
 - If the user wants to analyze new material, suggest they return to the analysis thread.
 - Skill reports may contain truncated text previews. When you need to present exact node text to the user, use `inspect_node` or `present_analysis` by hash — never reconstruct or guess full text from truncated previews.
 """

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.1 → 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.1 → 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.1 → 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.1 → 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.1/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.1 → 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)})"