dialectical-framework 1.8.1__tar.gz → 1.9.2__tar.gz

{dialectical_framework-1.8.1 → dialectical_framework-1.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.8.1
+Version: 1.9.2
 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
@@ -57,7 +57,9 @@ And the synthesis is *earned*, not asserted. Where "think step by step" leaves r
 
 ## How It Works
 
-1. **Input** — text, URLs, or raw ideas from any domain
+1. **Input** — text or raw ideas from any domain (URLs, uploads and other sources
+   once you supply an [`InputResolver`](docs/graph.md#input-resolution) — the default
+   fetches nothing)
 2. **Analysis** — extract the theses, find each one's true antithesis, develop the four aspects (T+, T-, A+, A-) that say where each side helps and where it overreaches
 3. **Graph curation** — commit every insight as content-addressed, rule-validated nodes and edges — nothing is stored until it holds up
 4. **Exploration** — combine perspectives into Cycles, arrange them into Wheels, and trace the Transformations whose circular causality yields synthesis
@@ -82,6 +84,9 @@ An **agent** is the entry point — a thin LLM orchestrator that manages a conve
 - [Agents: Analyst, Explorer, Advisor](docs/agents.md) — the building blocks, their tools, and the UX to build around them
 - [Graph Data Model](docs/graph.md)
 - [Scoring & Metrics](docs/scoring.md)
+- Runnable: [examples/advisor_chat.py](examples/advisor_chat.py) (console chat),
+  [notebooks/minds.ipynb](notebooks/minds.ipynb) and
+  [notebooks/seasons.ipynb](notebooks/seasons.ipynb) (building an app with `AppSpec`)
 
 ## Why a Reasoning Graph
 
@@ -124,11 +129,12 @@ Wherever the answer is a tension rather than a fact, this drops in as the reason
 
 - **Analyst** — turns raw material into structured tensions, up to grouping them into a Nexus (Case-scoped).
 - **Explorer** — takes one Nexus and works out its causal pathways and synthesis (Nexus-scoped).
-- **Advisor** — runs the whole machine silently and returns pure counsel, with no framework vocabulary exposed (Case-scoped).
+- **Advisor** — runs the whole machine silently and returns pure counsel, with no framework vocabulary exposed (Case-scoped). Its **Consultant** mode (`Advisor(mode=AdvisorMode.CONSULTANT)`) is the same head over a graph that already exists: it reads, records decisions, and never builds — the fast surface for a return visit.
 
 Analyst + Explorer are the structure-forward "graph navigator" experience; the Advisor is a chat-only product over the same graph. See [docs/agents.md](docs/agents.md) for full specs, tool lists, and the UX to build around each.
 
 ```python
+import asyncio
 from contextlib import aclosing
 
 from dialectical_framework.dialectical_reasoning import DialecticalReasoning
@@ -136,26 +142,53 @@ from dialectical_framework.settings import Settings
 from dialectical_framework.graph.nodes.case import Case
 from dialectical_framework.graph.scope_context import scope
 from dialectical_framework.agents.advisor.advisor import Advisor
-
-# Initialize once
-DialecticalReasoning.setup(Settings.from_env())
-
-# A Case owns the scope id (sid); all graph writes are sid-scoped.
-case = Case(); case.commit()
-
-with scope(case.sid):
-    advisor = Advisor(app_preamble="You are a systems thinking coach...")
-    # `aclosing` because a host that stops early must CLOSE the generator — that
-    # is what releases the provider connection and records the turn's seconds.
-    # See docs/agents.md.
-    async with aclosing(
-        advisor.chat_stream("Analyze the tension between growth and sustainability")
-    ) as events:
-        async for event in events:
-            # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
-            handle(event)
+from dialectical_framework.agents.stream_events import TextDelta
+
+
+async def main():
+    # Initialize once
+    DialecticalReasoning.setup(Settings.from_env())
+
+    # A Case owns the scope id (sid); all graph writes are sid-scoped.
+    case = Case(); case.commit()
+
+    with scope(case.sid):
+        # `principal="human"` because a real person is on the other end: it is
+        # what lets a decision they confirm be recorded as THEIR confirmation.
+        # The default attests nobody — see docs/agents.md.
+        advisor = Advisor(
+            app_preamble="You are a systems thinking coach...", principal="human"
+        )
+        # `aclosing` because a host that stops MID-TURN must CLOSE the generator
+        # — that is what releases the provider connection and records the turn's
+        # seconds. Breaking on `ResponseComplete` needs none of it: that event is
+        # yielded after the turn's closing work. See docs/agents.md.
+        async with aclosing(
+            advisor.chat_stream("Analyze the tension between growth and sustainability")
+        ) as events:
+            async for event in events:
+                # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
+                if isinstance(event, TextDelta):
+                    print(event.text, end="", flush=True)
+
+        # Once, after the last turn: the Advisor weaves a decision's pathway off
+        # the turn, and this is where that finishes. See docs/agents.md.
+        await advisor.wait_for_deferred_work()
+
+
+asyncio.run(main())
 ```
 
+Runnable versions of the above:
+
+- **[examples/advisor_chat.py](examples/advisor_chat.py)** — a console chat, and the
+  smallest program in which all five host obligations are load-bearing (`poetry run
+  python examples/advisor_chat.py`).
+- **[notebooks/minds.ipynb](notebooks/minds.ipynb)** — plugging your own domain in
+  with a single declarative `AppSpec`.
+- **[notebooks/seasons.ipynb](notebooks/seasons.ipynb)** — one `AppSpec` across every
+  agent head (Analyst, Explorer, Advisor, and the advisory toggle).
+
 ## Setup
 
 ### Requirements
@@ -166,11 +199,29 @@ with scope(case.sid):
 
 ### Install
 
+Into your own application:
+
+```bash
+pip install dialectical-framework
+```
+
+To work on the framework itself:
+
 ```bash
 poetry install
+```
+
+Either way, configuration comes from the environment:
+
+```bash
 cp .env.example .env   # then fill in the values (see .env.example for details)
 ```
 
+`DIALEXITY_DEFAULT_MODEL` is the only variable the framework itself requires (plus
+whatever credentials your provider's SDK reads). Everything else is commented out in
+`.env.example`, where each commented value **is** the code default — so the graph
+connection works as-is against Memgraph on `127.0.0.1:7687`.
+
 ### Run Tests
 
 ```bash

{dialectical_framework-1.8.1 → dialectical_framework-1.9.2}/README.md

@@ -16,7 +16,9 @@ And the synthesis is *earned*, not asserted. Where "think step by step" leaves r
 
 ## How It Works
 
-1. **Input** — text, URLs, or raw ideas from any domain
+1. **Input** — text or raw ideas from any domain (URLs, uploads and other sources
+   once you supply an [`InputResolver`](docs/graph.md#input-resolution) — the default
+   fetches nothing)
 2. **Analysis** — extract the theses, find each one's true antithesis, develop the four aspects (T+, T-, A+, A-) that say where each side helps and where it overreaches
 3. **Graph curation** — commit every insight as content-addressed, rule-validated nodes and edges — nothing is stored until it holds up
 4. **Exploration** — combine perspectives into Cycles, arrange them into Wheels, and trace the Transformations whose circular causality yields synthesis
@@ -41,6 +43,9 @@ An **agent** is the entry point — a thin LLM orchestrator that manages a conve
 - [Agents: Analyst, Explorer, Advisor](docs/agents.md) — the building blocks, their tools, and the UX to build around them
 - [Graph Data Model](docs/graph.md)
 - [Scoring & Metrics](docs/scoring.md)
+- Runnable: [examples/advisor_chat.py](examples/advisor_chat.py) (console chat),
+  [notebooks/minds.ipynb](notebooks/minds.ipynb) and
+  [notebooks/seasons.ipynb](notebooks/seasons.ipynb) (building an app with `AppSpec`)
 
 ## Why a Reasoning Graph
 
@@ -83,11 +88,12 @@ Wherever the answer is a tension rather than a fact, this drops in as the reason
 
 - **Analyst** — turns raw material into structured tensions, up to grouping them into a Nexus (Case-scoped).
 - **Explorer** — takes one Nexus and works out its causal pathways and synthesis (Nexus-scoped).
-- **Advisor** — runs the whole machine silently and returns pure counsel, with no framework vocabulary exposed (Case-scoped).
+- **Advisor** — runs the whole machine silently and returns pure counsel, with no framework vocabulary exposed (Case-scoped). Its **Consultant** mode (`Advisor(mode=AdvisorMode.CONSULTANT)`) is the same head over a graph that already exists: it reads, records decisions, and never builds — the fast surface for a return visit.
 
 Analyst + Explorer are the structure-forward "graph navigator" experience; the Advisor is a chat-only product over the same graph. See [docs/agents.md](docs/agents.md) for full specs, tool lists, and the UX to build around each.
 
 ```python
+import asyncio
 from contextlib import aclosing
 
 from dialectical_framework.dialectical_reasoning import DialecticalReasoning
@@ -95,26 +101,53 @@ from dialectical_framework.settings import Settings
 from dialectical_framework.graph.nodes.case import Case
 from dialectical_framework.graph.scope_context import scope
 from dialectical_framework.agents.advisor.advisor import Advisor
-
-# Initialize once
-DialecticalReasoning.setup(Settings.from_env())
-
-# A Case owns the scope id (sid); all graph writes are sid-scoped.
-case = Case(); case.commit()
-
-with scope(case.sid):
-    advisor = Advisor(app_preamble="You are a systems thinking coach...")
-    # `aclosing` because a host that stops early must CLOSE the generator — that
-    # is what releases the provider connection and records the turn's seconds.
-    # See docs/agents.md.
-    async with aclosing(
-        advisor.chat_stream("Analyze the tension between growth and sustainability")
-    ) as events:
-        async for event in events:
-            # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
-            handle(event)
+from dialectical_framework.agents.stream_events import TextDelta
+
+
+async def main():
+    # Initialize once
+    DialecticalReasoning.setup(Settings.from_env())
+
+    # A Case owns the scope id (sid); all graph writes are sid-scoped.
+    case = Case(); case.commit()
+
+    with scope(case.sid):
+        # `principal="human"` because a real person is on the other end: it is
+        # what lets a decision they confirm be recorded as THEIR confirmation.
+        # The default attests nobody — see docs/agents.md.
+        advisor = Advisor(
+            app_preamble="You are a systems thinking coach...", principal="human"
+        )
+        # `aclosing` because a host that stops MID-TURN must CLOSE the generator
+        # — that is what releases the provider connection and records the turn's
+        # seconds. Breaking on `ResponseComplete` needs none of it: that event is
+        # yielded after the turn's closing work. See docs/agents.md.
+        async with aclosing(
+            advisor.chat_stream("Analyze the tension between growth and sustainability")
+        ) as events:
+            async for event in events:
+                # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
+                if isinstance(event, TextDelta):
+                    print(event.text, end="", flush=True)
+
+        # Once, after the last turn: the Advisor weaves a decision's pathway off
+        # the turn, and this is where that finishes. See docs/agents.md.
+        await advisor.wait_for_deferred_work()
+
+
+asyncio.run(main())
 ```
 
+Runnable versions of the above:
+
+- **[examples/advisor_chat.py](examples/advisor_chat.py)** — a console chat, and the
+  smallest program in which all five host obligations are load-bearing (`poetry run
+  python examples/advisor_chat.py`).
+- **[notebooks/minds.ipynb](notebooks/minds.ipynb)** — plugging your own domain in
+  with a single declarative `AppSpec`.
+- **[notebooks/seasons.ipynb](notebooks/seasons.ipynb)** — one `AppSpec` across every
+  agent head (Analyst, Explorer, Advisor, and the advisory toggle).
+
 ## Setup
 
 ### Requirements
@@ -125,11 +158,29 @@ with scope(case.sid):
 
 ### Install
 
+Into your own application:
+
+```bash
+pip install dialectical-framework
+```
+
+To work on the framework itself:
+
 ```bash
 poetry install
+```
+
+Either way, configuration comes from the environment:
+
+```bash
 cp .env.example .env   # then fill in the values (see .env.example for details)
 ```
 
+`DIALEXITY_DEFAULT_MODEL` is the only variable the framework itself requires (plus
+whatever credentials your provider's SDK reads). Everything else is commented out in
+`.env.example`, where each commented value **is** the code default — so the graph
+connection works as-is against Memgraph on `127.0.0.1:7687`.
+
 ### Run Tests
 
 ```bash

{dialectical_framework-1.8.1 → dialectical_framework-1.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "1.8.1"
+version = "1.9.2"
 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"