dialectical-framework 1.6.6__tar.gz → 1.6.8__tar.gz

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.6.6
+Version: 1.6.8
 Summary: A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.).
 License: MIT
 Keywords: dialectics,dialectical-reasoning,synthesis,thesis-antithesis,ai,artificial-intelligence,llm,reasoning-framework,philosophy,logic,argumentation,conflict-resolution,decision-making,critical-thinking,semantic-graph,mirascope,pydantic,perspectives,polarity-reasoning

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "1.6.6"
+version = "1.6.8"
 description = "A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.)."
 authors = ["Evaldas Taroza <evaldas@dialexity.com>"]
 readme = "README.md"

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/advisor/advisor.py

@@ -17,12 +17,14 @@ from typing import AsyncGenerator, Optional
 
 from pydantic import BaseModel, Field
 
-from dialectical_framework.agents.advisor.system_prompts import (
-    SYSTEM_PROMPT, system_prompt)
+from dialectical_framework.agents.advisor.system_prompts import \
+    system_prompt
 from dialectical_framework.agents.agent_context import agent_scope
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
+from dialectical_framework.agents.app_spec import AppSpec, resolve_app_layer
 from dialectical_framework.agents.stream_events import StreamEvent
+from dialectical_framework.agents.toolsets import merge_app_tools
 
 logger = logging.getLogger(__name__)
 
@@ -69,6 +71,18 @@ class Advisor:
             advisor = Advisor(app_preamble=COUNSELOR_APP, messages=saved_messages)
             response = await advisor.chat("What about the other angle?")
 
+    Usage (app-provided domain tools):
+        # The app brings field knowledge two ways: prose in the preamble,
+        # and callable resources as app @llm.tool functions. The engine
+        # prompt carries no docs for app tools (their tool-schema docstrings
+        # travel to the LLM automatically) — introduce them and their usage
+        # rules in the app preamble, where domain vocabulary lives.
+        with scope(case.sid):
+            advisor = Advisor(
+                app_preamble=ASTRO_COUNSELOR_APP,  # explains when to consult the chart
+                app_tools=[lookup_natal_chart],   # @llm.tool from the app
+            )
+
     Usage (Advisor mode of an exploration session — Explorer handover):
         # User was chatting in Explorer (operator mode) and asks "what does
         # this all mean for me?" — the host toggles to counsel mode by
@@ -104,13 +118,28 @@ class Advisor:
         dialectical_context: Optional[str] = None,
         messages: Optional[list] = None,
         nexus_hash: Optional[str] = None,
+        app_tools: Optional[list] = None,
+        app: Optional[AppSpec] = None,
     ) -> None:
         self._nexus_hash = nexus_hash
+        # app: declarative app definition — composition depends on the mode:
+        # counsel toggle (nexus_hash set) keeps the Navigator contract
+        # (EXPLORATION_ADVISOR_APP + voicing + tool_guide); standalone uses
+        # the spec's advisor_persona (machinery hidden). See AppSpec.
+        app_preamble, app_tools = resolve_app_layer(
+            app,
+            app_preamble,
+            app_tools,
+            preamble_for="advisor_scoped" if nexus_hash else "advisor_unscoped",
+        )
         if nexus_hash:
             self._validate_nexus(nexus_hash)
             self._tools = _build_scoped_tools(nexus_hash)
         else:
             self._tools = _build_tools()
+        # App-provided @llm.tool functions (domain resources: chart lookups,
+        # methodology references, ...) — see toolsets.merge_app_tools.
+        self._tools = merge_app_tools(self._tools, app_tools)
         self._conversation = ConversationFacilitator(tools=self._tools)
         if messages:
             self._conversation._messages = list(messages)
@@ -144,13 +173,13 @@ class Advisor:
             dialectical_context
             or "No prior understanding — this is a fresh conversation."
         )
-        if self._nexus_hash:
-            engine = system_prompt(
-                tool_names=[t.__name__ for t in self._tools],
-                scoped_nexus_hash=self._nexus_hash,
-            )
-        else:
-            engine = SYSTEM_PROMPT
+        # Rendered at construction (not the import-time SYSTEM_PROMPT
+        # constant) so settings-derived prompt values (max_wheel_layer)
+        # reflect the live DI configuration.
+        engine = system_prompt(
+            tool_names=[t.__name__ for t in self._tools],
+            scoped_nexus_hash=self._nexus_hash,
+        )
         parts.append(engine.replace("{dialectical_context}", context_text))
 
         return "\n\n".join(parts)

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/advisor/system_prompts.py

@@ -34,6 +34,51 @@ def _ladder_lines(scale: dict[str, float], annotations: dict[float, str]) -> str
     return "\n".join(lines)
 
 
+def _resolve_max_wheel_layer() -> int:
+    """The live settings.max_wheel_layer, falling back to the Pydantic field
+    default when DI isn't wired (e.g. the import-time SYSTEM_PROMPT render).
+    """
+    from dialectical_framework.settings import Settings
+
+    try:
+        from dialectical_framework.protocols.has_config import SettingsAware
+
+        value = SettingsAware().settings.max_wheel_layer
+        if isinstance(value, int) and value >= 1:
+            return value
+    except Exception:
+        pass
+    return Settings.model_fields["max_wheel_layer"].default
+
+
+def _nexus_evolution(cap: int) -> str:
+    """Render the explore doc's 'How a nexus evolves' ladder from the live
+    wheel-layer cap (settings.max_wheel_layer), so the prompt's nexus-size
+    guidance never drifts from what PerspectiveCombination actually builds.
+    """
+    lines = [
+        "  How a nexus evolves:",
+        "  - 1 perspective: a single self-referential wheel. Already generates",
+        "    transformations and synthesis — useful even alone.",
+    ]
+    if cap >= 2:
+        lines += [
+            "  - 2 perspectives: the causal question emerges (which thesis enables which?).",
+            "    Produces multiple wheels (arrangements), each with its own pathways.",
+        ]
+    if cap >= 3:
+        span = f"3-{cap}" if cap > 3 else "3"
+        lines += [
+            f"  - {span} perspectives: richer causal chains, more transformation variety,",
+            "    deeper synthesis. The sweet spot for insight.",
+        ]
+    lines.append(
+        f"  - >{cap}: combinatorial explosion — arrangements aren't built beyond"
+        f" {cap} perspectives; start a new nexus for more tensions."
+    )
+    return "\n".join(lines)
+
+
 _ROLE = """## Role
 
 You are in conversation with someone navigating a decision, tension, or
@@ -277,14 +322,7 @@ _TOOL_DOCS: dict[str, str] = {
   and sibling nexuses on one theme fragment the pathways. Create separate
   nexuses only for genuinely distinct themes.
 
-  How a nexus evolves:
-  - 1 perspective: a single self-referential wheel. Already generates
-    transformations and synthesis — useful even alone.
-  - 2 perspectives: the causal question emerges (which thesis enables which?).
-    Produces multiple wheels (arrangements), each with its own pathways.
-  - 3-4 perspectives: richer causal chains, more transformation variety,
-    deeper synthesis. The sweet spot for insight.
-  - >4: combinatorial explosion — cap at 4, start a new nexus for more tensions.
+{nexus_evolution}
 
   Grouping principle: prefer perspectives from different polarities (different
   T-A oppositions) — transformations between them represent genuine synthesis
@@ -314,11 +352,15 @@ _TOOL_DOCS: dict[str, str] = {
   them. Deepening only adds analytical depth to existing structure — it
   never changes what the exploration contains, so no consent ceremony is
   needed. Harmless on already-developed wheels.""",
-    "sync": """- `sync` — Re-reads the full graph state. Use when you need a fresh full
-  picture — e.g., after multiple ingest/anchor calls, to see all perspectives
-  with scores before deciding what to group for explore. NOT needed after every
-  tool call (ingest/anchor/explore return their results directly), and NOT
-  needed at conversation start — the full state is already in your context.""",
+    "sync": """- `sync` — Re-reads the graph state. Without arguments: the full picture —
+  e.g., after multiple ingest/anchor calls, to see all perspectives with
+  scores before deciding what to group for explore. With a `nexus_hash`:
+  zooms into that one exploration in full depth — the overview caps wheels
+  per cycle for compactness, the zoom does not. Zoom when counsel settles on
+  one exploration and you need arrangements the overview truncated. NOT
+  needed after every tool call (ingest/anchor/explore return their results
+  directly), and NOT needed at conversation start — the full state is
+  already in your context.""",
     "sync_scoped": """- `sync` — Re-reads this exploration's state. Use when you need a fresh
   picture after changes. NOT needed at conversation start — the exploration
   is already in your context.""",
@@ -485,6 +527,22 @@ Use `inspect_node` when you want to understand the reasoning behind a score,
 explain WHY a specific blindspot exists, or ground a pathway recommendation
 in the actual analytical logic rather than restating the dump.
 
+**Cross-exploration correspondences.** When several explorations coexist,
+some perspectives carry correspondence lines — machine-stated facts, not
+suggestions: "Also woven into Nexus [[x]]" (literally the same tension in
+both explorations) and "Same opposition family (...) as perspective N in
+[[x]]" (both tensions anchored to the same deep-structure category). These
+are your invitation to draw parallels across the person's situations —
+often the most powerful counsel move available: the same structural dynamic
+playing out in two arenas of their life means an insight earned in one
+transfers to the other. But family-level correspondence is coarse (few
+families exist, collisions are common) — before drawing the parallel, check
+it holds in substance: read both tetrads and confirm the dynamics actually
+mirror each other, not just the category. The family name itself (Integrity,
+Fire, ...) is framework vocabulary — the How You Speak rules above govern
+it like any other; by default, name what the two tensions share in the
+person's own terms, not the category label.
+
 **Sequences are circular causality.** Both Cycle and Wheel sequences are
 closed loops — they start and end with the same element (e.g., "T1 → T2 → T1..."
 or "T1 → A2 → A1 → T2 → T1..."). The "..." indicates the circle continues.
@@ -520,6 +578,13 @@ Use these scores to prioritize what you draw on:
 - `rectangularity`: Tetrad balance (lower = better).
   <0.01 = well-balanced. 0.01–0.09 = mild imbalance, acceptable.
   >0.09 = one side overdeveloped — note the imbalance.
+- `DV`: Dialectical validity — how NATURAL the tension's dynamics are
+  (higher = the poles genuinely complement each other and the pathologies
+  arise organically; lower = the framing is forced, one-sided, or held
+  together by coercion/ideology rather than natural dynamics). Comparative
+  signal, no fixed cutoff: prefer high-DV tensions when choosing what to
+  build counsel on, and treat a low-DV tension as a hint the framing itself
+  may be distorted — consider re-anchoring rather than polishing aspects.
 - `Ks` on aspects: Complementarity toward synthesis.
   T+/A+ should be >0.4 (constructive poles complement the whole).
   T-/A- should be <0.6 (destructive poles don't overpower).
@@ -549,12 +614,13 @@ Use these scores to prioritize what you draw on:
 
 **Prioritization rules:**
 
-The dump is pre-pruned: tensions below the quality floor (weak opposition,
-blurred structure, failed validation) and low-probability wheels are already
-suppressed — count lines note what was filtered. Everything you see passed
-the floor; you rank within it, you don't re-filter.
+The dump is pre-pruned: tensions below the quality floors (weak opposition,
+blurred structure, unnatural/distorted framing, failed validation) and
+low-probability wheels are already suppressed — count lines note what was
+filtered. Everything you see passed the floors; you rank within them, you
+don't re-filter.
 
-1. Lead with the strongest tensions (highest HS on A, best area). Softer
+1. Lead with the strongest tensions (highest HS on A, best area, best DV). Softer
    ones are still visible by design — usable, and they may resonate with
    the person's lived experience, but don't build your primary counsel
    around them.
@@ -635,7 +701,13 @@ def system_prompt(
         # Scoped variants of sync/explore have their own doc text.
         key = f"{name}_scoped" if scoped and f"{name}_scoped" in _TOOL_DOCS else name
         if key in _TOOL_DOCS:
-            tool_docs.append(_TOOL_DOCS[key])
+            doc = _TOOL_DOCS[key]
+            if "{nexus_evolution}" in doc:
+                doc = doc.replace(
+                    "{nexus_evolution}",
+                    _nexus_evolution(_resolve_max_wheel_layer()),
+                )
+            tool_docs.append(doc)
 
     conversation_use = _CONVERSATION_USE
     if scoped and "ingest" not in names:

dialectical_framework-1.6.8/src/dialectical_framework/agents/advisor/tools/sync.py

@@ -0,0 +1,32 @@
+"""
+sync tool: Re-read the dialectical graph state.
+
+Returns a structured dump of tensions, pathways, and synthesis for the
+current case scope. With `nexus_hash`, zooms into one exploration and
+renders it in full depth (the unscoped dump caps wheels per cycle for
+compactness; the zoomed render is exempt, same as counsel-mode dumps).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.concerns.dialectical_context import \
+    DialecticalContext
+
+
+@llm.tool
+async def sync(
+    nexus_hash: Annotated[
+        str | None,
+        Field(
+            description="Zoom into one exploration: render only this nexus, in full depth (no wheel cap). Omit for the full-case overview."
+        ),
+    ] = None,
+) -> str:
+    """Re-read the graph state. Without arguments: the full picture across all explorations (compact — wheels capped per cycle). With a nexus_hash: one exploration in full depth. Use the zoom when counsel centers on one exploration and the overview's capped view isn't enough."""
+    concern = DialecticalContext(nexus_hash=nexus_hash)
+    return await concern.resolve()

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/analyst/analyst.py

@@ -20,7 +20,9 @@ from dialectical_framework.agents.analyst.system_prompts import SYSTEM_PROMPT
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.agents.app_spec import AppSpec, resolve_app_layer
 from dialectical_framework.agents.stream_events import StreamEvent
+from dialectical_framework.agents.toolsets import merge_app_tools
 
 if TYPE_CHECKING:
     pass
@@ -48,13 +50,17 @@ class Analyst:
 
     Usage:
         with scope(case.sid):
-            analyst = Analyst(app_preamble="You are a counselor...")
+            analyst = Analyst(app=MY_APP_SPEC)  # declarative (see AppSpec)
             response = await analyst.chat("I'm struggling with work-life balance")
 
         # Resuming with history:
         with scope(case.sid):
             analyst = Analyst(messages=loaded_messages)
             response = await analyst.chat("What about the second tension?")
+
+        # Manual preamble control (app_preamble replaces AppSpec composition):
+        with scope(case.sid):
+            analyst = Analyst(app_preamble="You are a counselor...")
     """
 
     AGENT_NAME = "analyst"
@@ -63,8 +69,17 @@ class Analyst:
         self,
         app_preamble: Optional[str] = None,
         messages: Optional[list] = None,
+        app_tools: Optional[list] = None,
+        app: Optional[AppSpec] = None,
     ) -> None:
-        self._tools = _build_tools()
+        # app: declarative app definition — the framework composes the
+        # Navigator preamble (NAVIGATOR_APP + voicing + tool_guide) and tool
+        # set from it. app_preamble/app_tools remain for manual control;
+        # mixing them with app= raises (see app_spec.resolve_app_layer).
+        app_preamble, app_tools = resolve_app_layer(
+            app, app_preamble, app_tools, preamble_for="navigator"
+        )
+        self._tools = merge_app_tools(_build_tools(), app_tools)
         self._conversation = ConversationFacilitator(tools=self._tools)
         if messages:
             self._conversation._messages = list(messages)

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/analyst/system_prompts.py

@@ -130,6 +130,16 @@ the user wants it fixed; absent = not validated (neutral). Communicate the
 verdict as meaning ("this one held up under the coherence check"), not as a
 flag name.
 
+Validation also scores `DV` (dialectical validity) — how NATURAL the
+tension's dynamics are, separate from coherence: high DV means the poles
+genuinely complement each other and the pathologies arise organically; low
+DV means the framing itself is forced or one-sided even if it reads
+coherently. A low-DV tension is better re-framed (`edit_perspective` or
+discard-and-re-anchor) than polished aspect-by-aspect — the distortion sits
+in the T/A framing, not the aspects. Note: counsel mode prunes very-low-DV
+tensions from its working view, so a framing you keep here may be absent
+there — re-framing it fixes both.
+
 ## Exploration Setup (Nexus)
 
 "Nexus" is the internal name for what the user calls an **Exploration** — same

dialectical_framework-1.6.8/src/dialectical_framework/agents/app_spec.py

@@ -0,0 +1,119 @@
+"""
+AppSpec: declarative app definition — the host describes WHAT its app is,
+each agent head composes the right preamble from it.
+
+Without this, an app developer must know framework lore to preamble an app:
+which base constant belongs to which head (NAVIGATOR_APP for Analyst/Explorer,
+EXPLORATION_ADVISOR_APP for the counsel toggle, bare persona for a standalone
+Advisor), that later preamble sections override earlier ones, and that the
+same tool guide must be repeated into every head's preamble. AppSpec owns
+that lore: the app supplies only its custom pieces, the framework supplies
+the generic contract.
+
+Usage:
+    ASTRO_APP = AppSpec(
+        voicing=\"\"\"## Astrological Voicing
+        Phrase oppositions in elemental and zodiacal terms where natural...\"\"\",
+        advisor_persona=\"\"\"## Persona
+        You are a wise astrologer. The person seeks counsel through their chart...\"\"\",
+        tool_guide=\"\"\"## Chart Resources
+        - lookup_natal_chart(person): fetch a natal chart. Use when...\"\"\",
+        tools=[lookup_natal_chart],
+    )
+
+    Analyst(app=ASTRO_APP)
+    Explorer(nexus_hash=nx, messages=msgs, app=ASTRO_APP)
+    Advisor(nexus_hash=nx, messages=msgs, app=ASTRO_APP)   # counsel toggle
+    Advisor(app=ASTRO_APP)                                  # standalone advisor
+
+Every field is optional — an AppSpec with only `voicing` is a pure
+re-skinning of the Navigator; one with only `tools` + `tool_guide` adds
+domain resources without touching voice. The low-level `app_preamble` /
+`app_tools` constructor params remain for full manual control; passing
+both `app` and either of them raises (ambiguous composition).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class AppSpec:
+    """Declarative definition of a host app, composed per agent head.
+
+    voicing: Domain flavor layered on the Navigator user contract
+        (Analyst/Explorer and the counsel toggle). Vocabulary direction,
+        framing, domain emphasis — NOT tool docs, NOT persona for the
+        standalone Advisor.
+    advisor_persona: Persona for the STANDALONE (unscoped) Advisor, where
+        the machinery is hidden and the preamble is the entire user-facing
+        identity (like COUNSELOR_APP). Ignored in counsel-toggle mode,
+        which keeps the Navigator contract.
+    tool_guide: Shared documentation for the app's tools — what each does,
+        when to reach for it. Included verbatim in EVERY head's preamble
+        so the usage rules cannot drift between heads. How tool use
+        SURFACES to the user still follows each head's disclosure rules.
+    tools: App-provided @llm.tool functions, passed to every head
+        (see toolsets.merge_app_tools).
+    """
+
+    voicing: Optional[str] = None
+    advisor_persona: Optional[str] = None
+    tool_guide: Optional[str] = None
+    tools: list = field(default_factory=list)
+
+    def navigator_preamble(self, advanced: bool = False) -> str:
+        """Preamble for Analyst/Explorer heads: Navigator contract + app pieces."""
+        from dialectical_framework.agents.apps import (
+            NAVIGATOR_ADVANCED_MODE_APP, NAVIGATOR_APP)
+
+        base = NAVIGATOR_ADVANCED_MODE_APP if advanced else NAVIGATOR_APP
+        return _join(base, self.voicing, self.tool_guide)
+
+    def advisor_preamble(self, scoped: bool) -> str:
+        """Preamble for the Advisor head.
+
+        scoped=True (counsel toggle of a Navigator session): the Navigator
+        contract survives the toggle — EXPLORATION_ADVISOR_APP + app pieces.
+        scoped=False (standalone Advisor): the persona IS the identity —
+        no Navigator base, machinery stays hidden.
+        """
+        from dialectical_framework.agents.apps import EXPLORATION_ADVISOR_APP
+
+        if scoped:
+            return _join(EXPLORATION_ADVISOR_APP, self.voicing, self.tool_guide)
+        return _join(self.advisor_persona, self.tool_guide)
+
+
+def _join(*parts: Optional[str]) -> str:
+    return "\n\n".join(p.strip() for p in parts if p and p.strip())
+
+
+def resolve_app_layer(
+    app: Optional[AppSpec],
+    app_preamble: Optional[str],
+    app_tools: Optional[list],
+    preamble_for: str,  # "navigator" | "advisor_scoped" | "advisor_unscoped"
+) -> tuple[Optional[str], Optional[list]]:
+    """Resolve the (preamble, tools) pair from either an AppSpec or the
+    low-level params. Mixing both raises — composition would be ambiguous
+    (does app_preamble replace the spec's derived preamble or stack on it?).
+    """
+    if app is None:
+        return app_preamble, app_tools
+    if app_preamble is not None or app_tools is not None:
+        raise ValueError(
+            "Pass either app= (declarative) or app_preamble=/app_tools= "
+            "(manual), not both."
+        )
+    if preamble_for == "navigator":
+        preamble = app.navigator_preamble()
+    elif preamble_for == "advisor_scoped":
+        preamble = app.advisor_preamble(scoped=True)
+    elif preamble_for == "advisor_unscoped":
+        preamble = app.advisor_preamble(scoped=False)
+    else:
+        raise ValueError(f"Unknown preamble_for: {preamble_for}")
+    return preamble or None, app.tools or None

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/apps.py

@@ -19,6 +19,12 @@ There are two territories:
 Apps define HOW the agents communicate — vocabulary, depth, framing, persona.
 They are injected by the host application at agent construction time.
 
+The recommended host interface is `AppSpec` (agents/app_spec.py): the app
+declares its custom pieces (voicing, advisor_persona, tool_guide, tools) and
+each agent head composes the right base from THIS module itself — hosts never
+concatenate these constants by hand. Direct `app_preamble=` passing remains
+for full manual control.
+
 Prompt Revision Methodology
 ===========================
 When fixing LLM output bugs in these prompts, use /df-review-reasoning-layer for the

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/explorer/explorer.py

@@ -20,7 +20,9 @@ from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
 from dialectical_framework.agents.explorer.system_prompts import system_prompt
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.agents.app_spec import AppSpec, resolve_app_layer
 from dialectical_framework.agents.stream_events import StreamEvent
+from dialectical_framework.agents.toolsets import merge_app_tools
 from dialectical_framework.graph.repositories.nexus_repository import \
     NexusRepository
 
@@ -66,9 +68,21 @@ class Explorer:
         nexus_hash: str,
         app_preamble: Optional[str] = None,
         messages: Optional[list] = None,
+        app_tools: Optional[list] = None,
+        app: Optional[AppSpec] = None,
     ) -> None:
         self._nexus_hash = nexus_hash
-        self._tools = _build_tools()
+        # app: declarative app definition (Navigator base + voicing +
+        # tool_guide + tools) — see AppSpec. Pass the SAME AppSpec to every
+        # head (Analyst, Explorer, Advisor): the Explorer<->Advisor toggle
+        # shares literal history (a missing tool breaks capability
+        # mid-conversation), and the Analyst thread owes the user the same
+        # domain resources by parity. For advanced-mode preambles compose
+        # manually: app_preamble=my_app.navigator_preamble(advanced=True).
+        app_preamble, app_tools = resolve_app_layer(
+            app, app_preamble, app_tools, preamble_for="navigator"
+        )
+        self._tools = merge_app_tools(_build_tools(), app_tools)
         self._conversation = ConversationFacilitator(tools=self._tools)
 
         if messages:

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/agents/orchestrator/tools/inspect_node.py

@@ -149,6 +149,8 @@ from pydantic import Field
 
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
 from dialectical_framework.enums.di import DI
+from dialectical_framework.graph.nodes.estimation import \
+    DialecticalValidityEstimation
 from dialectical_framework.graph.rendering import (
     build_pp_index,
     component_alias,
@@ -215,7 +217,11 @@ def _inspect_perspective(pp: Perspective) -> str:
     # Tetrad quality metrics
     diff_t = pp.diff_t
     diff_a = pp.diff_a
-    area = pp.area_normalized
+    # Raw area (= theory's SP, -2..2) — the scale every band/gate/prompt in the
+    # system speaks (settings min_sp, advisor bands, dialectical_context).
+    # area_normalized (area/2) is a UI-only hint; showing it here under a
+    # different scale than the Advisor's dump confused cross-surface reads.
+    area = pp.area
     rect = pp.rectangularity
     metrics: list[str] = []
     if diff_t is not None:
@@ -223,9 +229,15 @@ def _inspect_perspective(pp: Perspective) -> str:
     if diff_a is not None:
         metrics.append(f"diff_a={diff_a:.3f}")
     if area is not None:
-        metrics.append(f"area_normalized={area:.3f}")
+        metrics.append(f"area={area:.3f}")
     if rect is not None:
         metrics.append(f"rect={rect:.4f}")
+    # DV (Dialectical Validity, paper's naturalness companion to SP) — read
+    # from the persisted estimation, annotation only.
+    for est, _ in pp.estimations.all():
+        if isinstance(est, DialecticalValidityEstimation):
+            metrics.append(f"DV={est.value:.3f}")
+            break
     if metrics:
         lines.append(f"Quality: {', '.join(metrics)}")
 

dialectical_framework-1.6.8/src/dialectical_framework/agents/toolsets.py

@@ -0,0 +1,33 @@
+"""
+Shared helper for merging app-provided tools into an agent's built-in set.
+
+All three conversational agents (Analyst, Explorer, Advisor) expose an
+`app_tools` constructor parameter — the app-side seam for domain
+resources (chart lookups, methodology references, knowledge-base fetches).
+The merge rules are identical across agents, so they live here.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def merge_app_tools(builtin: list, app_tools: Optional[list]) -> list:
+    """Append app-provided @llm.tool functions to an agent's built-in set.
+
+    The agent's system prompt has no docs for app tools and skips unknown
+    names — apps describe them in the app preamble, where domain vocabulary
+    lives; the tool schemas (name, params, docstring) reach the LLM through
+    the tool protocol itself.
+
+    Raises:
+        ValueError: If an app tool shadows a built-in tool name — the app
+            tool would silently hijack framework machinery.
+    """
+    if not app_tools:
+        return builtin
+    builtin_names = {t.__name__ for t in builtin}
+    collisions = [t.__name__ for t in app_tools if t.__name__ in builtin_names]
+    if collisions:
+        raise ValueError(f"app_tools shadow built-in tools: {collisions}")
+    return builtin + list(app_tools)

{dialectical_framework-1.6.6 → dialectical_framework-1.6.8}/src/dialectical_framework/concerns/action_extraction.py

@@ -111,8 +111,9 @@ APEX
 2. Must help transition FROM T- (problem) TOWARD A+ (benefit)
 3. Must NOT simply restate A+ - it's the PATH, not the destination
 4. Should be generative: enable discovery rather than prescribe specific outcomes
-5. Length: a fuller actionable form, longer than the headline
-6. Choose the insight level that best matches the nature of the action
+5. Must stay subtle, not forceful: an action that imposes, coerces, or overpowers reverses its polarity from Ac+ to Ac-. Prefer enabling over forcing
+6. Length: a fuller actionable form, longer than the headline
+7. Choose the insight level that best matches the nature of the action
 """