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

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

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

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

@@ -22,7 +22,9 @@ from dialectical_framework.agents.advisor.system_prompts import \
 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)

{dialectical_framework-1.6.7 → 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.7 → 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.7 → 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.7 → 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.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)