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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.1.2
+Version: 1.2.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

{dialectical_framework-1.1.2 → dialectical_framework-1.2.0}/pyproject.toml

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

@@ -152,6 +152,7 @@ class ConversationFacilitator(SettingsAware):
 
         # Sync full conversation history from the response chain
         self._messages = list(response.messages)
+        self._strip_unsupported_input_fields()
 
         # Extract structured response
         return await self._call_with_response_model(response_model)
@@ -209,11 +210,30 @@ class ConversationFacilitator(SettingsAware):
             stream = await stream.resume(tool_outputs)
 
         self._messages = list(stream.messages)
+        self._strip_unsupported_input_fields()
         result = await self._call_with_response_model(response_model)
         yield ResponseComplete(result=result)
 
     # --- Internal helpers ---
 
+    def _strip_unsupported_input_fields(self) -> None:
+        """Strip output-only fields from raw_message before replaying to API.
+
+        Mirascope passes raw_message dicts back verbatim as input. If the API
+        added output-only fields (like 'caller' on tool_use blocks), they cause
+        400 errors on the next call. This strips them.
+        """
+        for msg in self._messages:
+            raw = getattr(msg, "raw_message", None)
+            if not isinstance(raw, dict):
+                continue
+            content = raw.get("content")
+            if not isinstance(content, list):
+                continue
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    block.pop("caller", None)
+
     @staticmethod
     def _log_tool_calls(tool_calls: list) -> None:
         """Log tool invocations to the effect logger if configured."""

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

@@ -119,6 +119,10 @@ 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.generate_synthesis import \
+        generate_synthesis
     from dialectical_framework.agents.explorer.tools.present_exploration import \
         present_exploration
     from dialectical_framework.agents.orchestrator.tools.get_schema import \
@@ -131,6 +135,8 @@ def _build_tools() -> list:
     return [
         build_wheels,
         explore_transformations,
+        generate_synthesis,
+        expand_nexus,
         present_exploration,
         inspect_node,
         query_graph,

dialectical_framework-1.2.0/src/dialectical_framework/agents/explorer/skills/generate_synthesis.py

@@ -0,0 +1,207 @@
+"""
+GenerateSynthesis: Skill for generating S+/S- synthesis from a Wheel.
+
+Orchestrates: resolve wheel → verify transformations → gather lower-layer
+context → call SynthesisGeneration concern → create Synthesis node → commit.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import combinations
+from typing import Optional, TYPE_CHECKING
+
+from dependency_injector.wiring import Provide, inject
+
+from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.concerns.synthesis_generation import (
+    SynthesisGeneration,
+    SynthesisResult,
+)
+from dialectical_framework.enums.di import DI
+from dialectical_framework.graph.nodes.statement import Statement
+from dialectical_framework.graph.nodes.synthesis import (
+    POSITION_S_MINUS,
+    POSITION_S_PLUS,
+    Synthesis,
+)
+from dialectical_framework.graph.relationships.polarity_relationship import (
+    SMinusRelationship,
+    SPlusRelationship,
+)
+from dialectical_framework.graph.relationships.synthesis_of_relationship import (
+    SynthesisOfRelationship,
+)
+
+if TYPE_CHECKING:
+    from dialectical_framework.graph.nodes.nexus import Nexus
+    from dialectical_framework.graph.nodes.perspective import Perspective
+    from dialectical_framework.graph.nodes.wheel import Wheel
+    from dialectical_framework.protocols.input_resolver import InputResolver
+
+
+@dataclass
+class GenerateSynthesisResult:
+    """Result from GenerateSynthesis skill."""
+
+    synthesis: Synthesis
+    is_new: bool = True
+
+
+class GenerateSynthesis(ReasonableConcern[GenerateSynthesisResult]):
+    """
+    Skill for generating S+/S- synthesis from a Wheel's Transformations.
+
+    Idempotent: returns existing Synthesis if one already exists for the Wheel.
+    """
+
+    def __init__(self, wheel_hash: str) -> None:
+        self.wheel_hash = wheel_hash
+
+    async def resolve(self) -> GenerateSynthesisResult:
+        """
+        Generate synthesis for a Wheel.
+
+        Returns:
+            GenerateSynthesisResult with the Synthesis node
+
+        Raises:
+            ValueError: If wheel not found or has no Transformations
+        """
+        wheel = self._resolve_wheel()
+
+        # Check transformations exist
+        transformations = wheel.transformations
+        if not transformations:
+            raise ValueError(
+                f"Wheel {wheel.short_hash} has no Transformations — "
+                f"run explore_transformations first"
+            )
+
+        # Idempotent: return existing synthesis
+        existing = self._find_existing_synthesis(wheel)
+        if existing:
+            self._report.summary = (
+                f"Synthesis already exists for Wheel {wheel.short_hash}"
+            )
+            self._report.artifacts["wheel"] = wheel.short_hash
+            self._report.artifacts["existing"] = True
+            return GenerateSynthesisResult(synthesis=existing, is_new=False)
+
+        # Gather context
+        input_text = await self._get_input_text()
+        lower_layer_context = self._build_lower_layer_context(wheel)
+
+        # Call the concern
+        concern = SynthesisGeneration()
+        result = await concern.resolve(
+            wheel=wheel,
+            input_text=input_text,
+            lower_layer_context=lower_layer_context,
+        )
+        self._report = self._report.merge(concern.report)
+
+        if result is None:
+            raise ValueError(
+                f"Synthesis generation failed for Wheel {wheel.short_hash}"
+            )
+
+        # Create Synthesis node and wire up
+        synthesis = Synthesis()
+        synthesis.save()
+
+        synthesis.s_plus.connect(
+            result.s_plus_statement,
+            relationship=SPlusRelationship(
+                alias=POSITION_S_PLUS, heuristic_similarity=None
+            ),
+        )
+        synthesis.s_minus.connect(
+            result.s_minus_statement,
+            relationship=SMinusRelationship(
+                alias=POSITION_S_MINUS, heuristic_similarity=None
+            ),
+        )
+        synthesis.target.connect(wheel, relationship=SynthesisOfRelationship())
+        synthesis.commit()
+
+        # Report
+        self._report.node_created(synthesis)
+        self._report.artifacts["wheel"] = wheel.short_hash
+        self._report.artifacts["s_plus"] = result.s_plus_statement.text
+        self._report.artifacts["s_minus"] = result.s_minus_statement.text
+        self._report.summary = (
+            f"Generated synthesis for Wheel {wheel.short_hash}: "
+            f"S+ = \"{result.s_plus_statement.text}\", "
+            f"S- = \"{result.s_minus_statement.text}\""
+        )
+
+        return GenerateSynthesisResult(synthesis=synthesis)
+
+    def _resolve_wheel(self) -> Wheel:
+        """Resolve Wheel from hash or prefix."""
+        from dialectical_framework.graph.nodes.wheel import Wheel
+        from dialectical_framework.graph.repositories.node_repository import (
+            NodeRepository,
+        )
+
+        repo = NodeRepository()
+        node = repo.find_by_hash(self.wheel_hash, node_type=Wheel)
+        if node is None:
+            raise ValueError(f"Wheel not found: {self.wheel_hash}")
+        return node
+
+    @staticmethod
+    def _find_existing_synthesis(wheel: Wheel) -> Optional[Synthesis]:
+        """Check if the wheel already has a synthesis."""
+        existing = list(wheel.synthesis.all())
+        if existing:
+            return existing[0][0]
+        return None
+
+    @inject
+    async def _get_input_text(
+        self,
+        input_resolver: InputResolver = Provide[DI.input_resolver],
+    ) -> str:
+        """Get concatenated text from all inputs in scope."""
+        from dialectical_framework.graph.repositories.input_repository import (
+            InputRepository,
+        )
+
+        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)
+
+    def _build_lower_layer_context(self, wheel: Wheel) -> str:
+        """Find synthesis from sub-wheels (lower PP layers) sharing perspectives."""
+        from dialectical_framework.graph.repositories.wheel_repository import (
+            WheelRepository,
+        )
+
+        pps = wheel._perspectives
+        if len(pps) < 2:
+            return ""
+
+        wheel_repo = WheelRepository()
+        parts: list[str] = []
+
+        # Look one layer down (N-1 perspectives)
+        for combo in combinations(pps, len(pps) - 1):
+            sub_wheels = wheel_repo.find_by_layer(list(combo))
+            for sub_wheel in sub_wheels:
+                for synth, _ in sub_wheel.synthesis.all():
+                    parts.append(
+                        f"Sub-wheel [{sub_wheel.short_hash}]: {synth:positions:0}"
+                    )
+
+        return "\n".join(parts)

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

@@ -25,6 +25,7 @@ On first message (or when resuming):
 - If wheels don't exist yet, call `build_wheels` to create them.
 - If build_wheels yields no wheels (e.g., only one position), explain that exploration needs at least two positions interacting — suggest the user adds more via the analysis thread.
 - If transformations don't exist yet, call `explore_transformations` for each wheel.
+- After transformations exist, call `generate_synthesis` to derive S+/S- for each wheel.
 
 When presenting transformations:
 - Focus on the Ac+ (constructive action: T- -> A+) and Re+ (constructive reflection: A- -> T+).
@@ -48,6 +49,7 @@ When the user wants to go deeper on a specific transformation:
 
 - `build_wheels` -- Generate causal structures (Cycles + Wheels) from this Nexus. Use nexus_hash: "{nexus_hash}".
 - `explore_transformations` -- Generate Action-Reflection transformations for a Wheel.
+- `generate_synthesis` -- Generate S+/S- synthesis for a Wheel. Requires transformations first.
 - `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.

dialectical_framework-1.2.0/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.2.0/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.2.0/src/dialectical_framework/agents/explorer/tools/generate_synthesis.py

@@ -0,0 +1,27 @@
+"""
+generate_synthesis tool: thin LLM-facing wrapper around the GenerateSynthesis skill.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.agents.explorer.skills.generate_synthesis import (
+    GenerateSynthesis,
+)
+
+
+@llm.tool
+async def generate_synthesis(
+    wheel_hash: Annotated[
+        str,
+        Field(description="Hash of the Wheel to generate synthesis for"),
+    ],
+) -> str:
+    """Generate S+/S- synthesis for a Wheel — the emergent properties arising from circular causality. S+ represents complementary harmony (1+1>2), S- represents reinforcing uniformity (1+1<2). The wheel must have transformations computed first."""
+    skill = GenerateSynthesis(wheel_hash=wheel_hash)
+    await skill.resolve()
+    return str(skill.report)

{dialectical_framework-1.1.2 → dialectical_framework-1.2.0}/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.2.0}/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.2.0}/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.2.0}/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 → dialectical_framework-1.2.0}/src/dialectical_framework/agents/reasonable_concern.py

@@ -10,15 +10,40 @@ All three levels inherit from ReasonableConcern — same interface (resolve + re
 
 from __future__ import annotations
 
+import asyncio
+import inspect
 from abc import ABC, abstractmethod
+from functools import wraps
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
+from langfuse import get_client, observe
+
 if TYPE_CHECKING:
     from dialectical_framework.agents.execution_report import ExecutionReport
 
 R_co = TypeVar("R_co", covariant=True)
 
 
+def _conditional_observe(name: str, fn: Any) -> Any:
+    """Wrap fn with @observe only when an active Langfuse trace exists."""
+    observed = observe(name=name)(fn)
+
+    if asyncio.iscoroutinefunction(fn):
+        @wraps(fn)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if get_client().get_current_trace_id():
+                return await observed(*args, **kwargs)
+            return await fn(*args, **kwargs)
+    else:
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if get_client().get_current_trace_id():
+                return observed(*args, **kwargs)
+            return fn(*args, **kwargs)
+
+    return wrapper
+
+
 class ReasonableConcern(ABC, Generic[R_co]):
     """
     Base class for concerns, skills, and tools.
@@ -34,6 +59,12 @@ class ReasonableConcern(ABC, Generic[R_co]):
 
     _report: ExecutionReport
 
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if "resolve" in cls.__dict__:
+            original = cls.__dict__["resolve"]
+            cls.resolve = _conditional_observe(cls.__name__, original)  # type: ignore[assignment]
+
     def __getattr__(self, name: str) -> Any:
         if name == "_report":
             from dialectical_framework.agents.execution_report import ExecutionReport

{dialectical_framework-1.1.2/src/dialectical_framework/agents/explorer/tools → dialectical_framework-1.2.0/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)