dialectical-framework 1.8.0__tar.gz → 1.9.1__tar.gz

{dialectical_framework-1.8.0 → dialectical_framework-1.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.8.0
+Version: 1.9.1
 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
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 
 # Dialectical Framework
 
-**Make an LLM reason in oppositions, not averages.**
+**Dialectical AI: Achieving Objectivity and Synthesis in LLM Reasoning via Structured Tension Graphs**
 
 Ask a model a hard question and it tends to collapse the tension into one confident answer — or hedge with a bland "on one hand… on the other." This framework does neither. For every thesis it generates a genuine antithesis, maps precisely where each side overreaches (T-, A-) and where it constructively balances the other (T+, A+), and drives the pair toward a **synthesis** — not a compromise, but a new quality that emerges from their circular causality and that neither pole held alone.
 
@@ -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
 
@@ -129,24 +134,60 @@ Wherever the answer is a tension rather than a fact, this drops in as the reason
 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
 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
+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())
+```
 
-# Initialize once
-DialecticalReasoning.setup(Settings.from_env())
-
-# A Case owns the scope id (sid); all graph writes are sid-scoped.
-case = Case(); case.commit()
+Runnable versions of the above:
 
-with scope(case.sid):
-    advisor = Advisor(app_preamble="You are a systems thinking coach...")
-    async for event in advisor.chat_stream("Analyze the tension between growth and sustainability"):
-        # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
-        handle(event)
-```
+- **[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 counsel toggle).
 
 ## Setup
 
@@ -158,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
@@ -185,3 +244,4 @@ The methods for applying dialectical reasoning with AI are patented. The MIT
 License does not grant patent rights beyond a limited grant for use of this
 software as distributed — see [PATENTS](https://github.com/dialexity/dialectical-framework/blob/main/PATENTS) for the patent terms and
 [dialexity.com/patents](https://dialexity.com/patents) for the patent listing.
+

{dialectical_framework-1.8.0 → dialectical_framework-1.9.1}/README.md

@@ -1,6 +1,6 @@
 # Dialectical Framework
 
-**Make an LLM reason in oppositions, not averages.**
+**Dialectical AI: Achieving Objectivity and Synthesis in LLM Reasoning via Structured Tension Graphs**
 
 Ask a model a hard question and it tends to collapse the tension into one confident answer — or hedge with a bland "on one hand… on the other." This framework does neither. For every thesis it generates a genuine antithesis, maps precisely where each side overreaches (T-, A-) and where it constructively balances the other (T+, A+), and drives the pair toward a **synthesis** — not a compromise, but a new quality that emerges from their circular causality and that neither pole held alone.
 
@@ -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
 
@@ -88,24 +93,60 @@ Wherever the answer is a tension rather than a fact, this drops in as the reason
 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
 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
+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())
+```
 
-# Initialize once
-DialecticalReasoning.setup(Settings.from_env())
-
-# A Case owns the scope id (sid); all graph writes are sid-scoped.
-case = Case(); case.commit()
+Runnable versions of the above:
 
-with scope(case.sid):
-    advisor = Advisor(app_preamble="You are a systems thinking coach...")
-    async for event in advisor.chat_stream("Analyze the tension between growth and sustainability"):
-        # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
-        handle(event)
-```
+- **[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 counsel toggle).
 
 ## Setup
 
@@ -117,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
@@ -143,4 +202,4 @@ The source code is licensed under the [MIT License](https://github.com/dialexity
 The methods for applying dialectical reasoning with AI are patented. The MIT
 License does not grant patent rights beyond a limited grant for use of this
 software as distributed — see [PATENTS](https://github.com/dialexity/dialectical-framework/blob/main/PATENTS) for the patent terms and
-[dialexity.com/patents](https://dialexity.com/patents) for the patent listing.
+[dialexity.com/patents](https://dialexity.com/patents) for the patent listing.

{dialectical_framework-1.8.0 → dialectical_framework-1.9.1}/pyproject.toml

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