dialectical-framework 1.0.0__tar.gz → 1.1.0__tar.gz

dialectical_framework-1.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.3
+Name: dialectical-framework
+Version: 1.1.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
+Author: Evaldas Taroza
+Author-email: evaldas@dialexity.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: Sociology
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Dist: boto3 (>=1.43.4,<2.0.0)
+Requires-Dist: broadcaster (>=0.3.1,<0.4.0)
+Requires-Dist: dependency-injector (>=4.48.2,<5.0.0)
+Requires-Dist: gqlalchemy (>=1.8.0,<2.0.0)
+Requires-Dist: langfuse (>=4.5.1,<5.0.0)
+Requires-Dist: mirascope[anthropic,openai,ops] (>=2.4.0,<3.0.0)
+Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Project-URL: Homepage, https://github.com/dialexity/dialectical-framework
+Project-URL: Repository, https://github.com/dialexity/dialectical-framework
+Description-Content-Type: text/markdown
+
+# Dialectical Framework
+
+A reasoning framework for AI applications that need structured dialectical analysis. It curates a graph database through LLM-guided conversation, building up thesis-antithesis-synthesis structures from any domain.
+
+The graph database **is** the state. Every interaction — extracting theses, finding oppositions, building wheels — writes semantic nodes and relationships into the graph. The framework is essentially a curation engine: an LLM orchestrator that progressively structures user input into dialectical knowledge graphs.
+
+## How It Works
+
+1. **Input** — User provides text, URLs, or ideas
+2. **Analysis** — LLM extracts theses, finds antitheses, generates aspects (T+, T-, A+, A-)
+3. **Graph curation** — Each insight is committed as nodes/relationships in the graph database
+4. **Exploration** — Perspectives are combined into Cycles, arranged into Wheels, and Transformations reveal paths toward synthesis
+
+The graph accumulates structured reasoning over time. Applications query it, visualize it, or build on it.
+
+## Architecture
+
+```
+Host Application (Chainlit, API, CLI)
+        │
+        ▼
+    Orchestrator (LLM + tools)
+        │
+        ▼
+    Graph Database (Memgraph / Neo4j)
+```
+
+The Orchestrator is the main entry point. It manages an LLM conversation with tools that read and write the graph. The host app controls persona and session identity; the framework handles reasoning and graph curation.
+
+### Core Graph Structure
+
+At the heart is the **Dialectical Wheel** — a semantic graph where nodes are statements and edges encode dialectical relationships (opposition, complementarity, transformation).
+
+| Structure | Role |
+|-----------|------|
+| **Statement** | Atomic unit of meaning |
+| **Perspective** | T/A opposition with aspects (T+, T-, A+, A-) |
+| **Cycle** | Ordered sequence of Perspectives |
+| **Wheel** | Concrete T-A arrangement implementing a Cycle |
+| **Transformation** | Action-Reflection paths between segments |
+| **Synthesis** | Emergent S+/S- from the Wheel's circular causality |
+
+Think of a Wheel as a pizza: segments are slices (T, T+, T-), Perspectives are half-pizzas (thesis + opposing antithesis), and Transitions are the cuts between slices.
+
+| Simple | Detailed |
+|--------|----------|
+| ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme.png) | ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme2.png) |
+
+## Integration
+
+The framework is designed as a drop-in reasoning engine for AI applications that need dialectical analysis — decision support, systems thinking, mediation, ethical modeling.
+
+```python
+from dialectical_framework.dialectical_reasoning import DialecticalReasoning
+from dialectical_framework.settings import Settings
+from dialectical_framework.agents.orchestrator.orchestrator import Orchestrator
+
+# Initialize once
+DialecticalReasoning.setup(Settings.from_env())
+
+# Per-session usage
+orchestrator = Orchestrator(app_preamble="You are a systems thinking coach...")
+
+async for event in orchestrator.chat_stream("Analyze the tension between growth and sustainability"):
+    # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
+    handle(event)
+```
+
+## Setup
+
+### Requirements
+
+- Python 3.11+
+- Memgraph or Neo4j
+- An LLM provider (OpenAI, Anthropic, or any LiteLLM-compatible)
+
+### Install
+
+```bash
+poetry install
+```
+
+### Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `DIALEXITY_DEFAULT_MODEL` | Model in provider/model format | `bedrock/anthropic.claude-sonnet-4-20250514-v1:0` |
+| `DIALEXITY_GRAPH_DB_VENDOR` | Graph database | `memgraph` (default) or `neo4j` |
+| `DIALEXITY_GRAPH_DB_HOST` | Database host | `127.0.0.1` |
+| `DIALEXITY_GRAPH_DB_PORT` | Database port | `7687` |
+| `DIALEXITY_THINKING_LEVEL` | Extended thinking budget | `medium`, `high`, `max` (optional) |
+
+Store in `.env` or export in your environment.
+
+### Run Tests
+
+```bash
+poetry run pytest              # All tests (LLM mocked)
+poetry run pytest -m llm       # Only LLM-path tests (mocked)
+poetry run pytest --real-llm   # Hit real LLM provider
+```
+
+## Built With
+
+- [Mirascope](https://mirascope.com/) — LLM abstraction
+- [GQLAlchemy](https://memgraph.com/docs/gqlalchemy) — Graph ORM
+- [dependency-injector](https://python-dependency-injector.ets-labs.org/) — DI container
+
+## Learn More
+
+- [Dialectical Wheels Overview](https://dialexity.com/blog/dialectical-wheels-for-systems-optimization/)
+- [Dialectical Ethics](https://dialexity.com/blog/dialectical-ethics/)
+- [Earlier Work](https://dialexity.com/blog/wp-content/uploads/2023/11/Moral-Wisdom-from-Ontology-1.pdf)
+
+## Applications
+
+- [Eye Opener](https://app.dialexity.com/aiapps/eye-opener) — Analyze text, reveal hidden assumptions
+- [Argument Inspector](https://app.dialexity.com/aiapps/argument-inspector/) — Deep-dive into case arguments for analysts and mediators
+

dialectical_framework-1.1.0/README.md

@@ -0,0 +1,118 @@
+# Dialectical Framework
+
+A reasoning framework for AI applications that need structured dialectical analysis. It curates a graph database through LLM-guided conversation, building up thesis-antithesis-synthesis structures from any domain.
+
+The graph database **is** the state. Every interaction — extracting theses, finding oppositions, building wheels — writes semantic nodes and relationships into the graph. The framework is essentially a curation engine: an LLM orchestrator that progressively structures user input into dialectical knowledge graphs.
+
+## How It Works
+
+1. **Input** — User provides text, URLs, or ideas
+2. **Analysis** — LLM extracts theses, finds antitheses, generates aspects (T+, T-, A+, A-)
+3. **Graph curation** — Each insight is committed as nodes/relationships in the graph database
+4. **Exploration** — Perspectives are combined into Cycles, arranged into Wheels, and Transformations reveal paths toward synthesis
+
+The graph accumulates structured reasoning over time. Applications query it, visualize it, or build on it.
+
+## Architecture
+
+```
+Host Application (Chainlit, API, CLI)
+        │
+        ▼
+    Orchestrator (LLM + tools)
+        │
+        ▼
+    Graph Database (Memgraph / Neo4j)
+```
+
+The Orchestrator is the main entry point. It manages an LLM conversation with tools that read and write the graph. The host app controls persona and session identity; the framework handles reasoning and graph curation.
+
+### Core Graph Structure
+
+At the heart is the **Dialectical Wheel** — a semantic graph where nodes are statements and edges encode dialectical relationships (opposition, complementarity, transformation).
+
+| Structure | Role |
+|-----------|------|
+| **Statement** | Atomic unit of meaning |
+| **Perspective** | T/A opposition with aspects (T+, T-, A+, A-) |
+| **Cycle** | Ordered sequence of Perspectives |
+| **Wheel** | Concrete T-A arrangement implementing a Cycle |
+| **Transformation** | Action-Reflection paths between segments |
+| **Synthesis** | Emergent S+/S- from the Wheel's circular causality |
+
+Think of a Wheel as a pizza: segments are slices (T, T+, T-), Perspectives are half-pizzas (thesis + opposing antithesis), and Transitions are the cuts between slices.
+
+| Simple | Detailed |
+|--------|----------|
+| ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme.png) | ![Wheel](https://raw.githubusercontent.com/dialexity/dialectical-framework/main/docs/wheel-scheme2.png) |
+
+## Integration
+
+The framework is designed as a drop-in reasoning engine for AI applications that need dialectical analysis — decision support, systems thinking, mediation, ethical modeling.
+
+```python
+from dialectical_framework.dialectical_reasoning import DialecticalReasoning
+from dialectical_framework.settings import Settings
+from dialectical_framework.agents.orchestrator.orchestrator import Orchestrator
+
+# Initialize once
+DialecticalReasoning.setup(Settings.from_env())
+
+# Per-session usage
+orchestrator = Orchestrator(app_preamble="You are a systems thinking coach...")
+
+async for event in orchestrator.chat_stream("Analyze the tension between growth and sustainability"):
+    # ThinkingDelta, TextDelta, ToolStart, ToolResult, ResponseComplete
+    handle(event)
+```
+
+## Setup
+
+### Requirements
+
+- Python 3.11+
+- Memgraph or Neo4j
+- An LLM provider (OpenAI, Anthropic, or any LiteLLM-compatible)
+
+### Install
+
+```bash
+poetry install
+```
+
+### Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `DIALEXITY_DEFAULT_MODEL` | Model in provider/model format | `bedrock/anthropic.claude-sonnet-4-20250514-v1:0` |
+| `DIALEXITY_GRAPH_DB_VENDOR` | Graph database | `memgraph` (default) or `neo4j` |
+| `DIALEXITY_GRAPH_DB_HOST` | Database host | `127.0.0.1` |
+| `DIALEXITY_GRAPH_DB_PORT` | Database port | `7687` |
+| `DIALEXITY_THINKING_LEVEL` | Extended thinking budget | `medium`, `high`, `max` (optional) |
+
+Store in `.env` or export in your environment.
+
+### Run Tests
+
+```bash
+poetry run pytest              # All tests (LLM mocked)
+poetry run pytest -m llm       # Only LLM-path tests (mocked)
+poetry run pytest --real-llm   # Hit real LLM provider
+```
+
+## Built With
+
+- [Mirascope](https://mirascope.com/) — LLM abstraction
+- [GQLAlchemy](https://memgraph.com/docs/gqlalchemy) — Graph ORM
+- [dependency-injector](https://python-dependency-injector.ets-labs.org/) — DI container
+
+## Learn More
+
+- [Dialectical Wheels Overview](https://dialexity.com/blog/dialectical-wheels-for-systems-optimization/)
+- [Dialectical Ethics](https://dialexity.com/blog/dialectical-ethics/)
+- [Earlier Work](https://dialexity.com/blog/wp-content/uploads/2023/11/Moral-Wisdom-from-Ontology-1.pdf)
+
+## Applications
+
+- [Eye Opener](https://app.dialexity.com/aiapps/eye-opener) — Analyze text, reveal hidden assumptions
+- [Argument Inspector](https://app.dialexity.com/aiapps/argument-inspector/) — Deep-dive into case arguments for analysts and mediators

{dialectical_framework-1.0.0 → dialectical_framework-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "1.0.0"
+version = "1.1.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"
@@ -56,9 +56,9 @@ boto3 = "^1.43.4"
 broadcaster = "^0.3.1"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^8.4.1"
+pytest = "^9.0.3"
 ipykernel = "^7.2.0"
-black = "^25.1.0"
+black = "^26.3.1"
 isort = "^6.0.1"
 #flake8 = "^7.1.2"
 pytest-asyncio = "^1.1.0"

dialectical_framework-1.1.0/src/dialectical_framework/agents/agent_context.py

@@ -0,0 +1,52 @@
+"""
+Agent context for the dialectical framework.
+
+Provides async-safe agent name propagation using contextvars.
+The framework sets the agent name inside chat methods; concerns read it
+for effect logging.
+
+Framework layer usage (inside Analyst/Explorer):
+    from dialectical_framework.agents.agent_context import agent_scope
+
+    with agent_scope("analyst"):
+        result = await self._conversation.submit(...)
+
+Read usage (inside ExecutionReport, EffectLogger):
+    from dialectical_framework.agents.agent_context import get_current_agent
+
+    agent = get_current_agent()  # "analyst" or None
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Optional
+
+
+_current_agent: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'current_agent', default=None
+)
+
+
+def get_current_agent() -> Optional[str]:
+    """Get the current agent name from context. Returns None if not set."""
+    return _current_agent.get()
+
+
+class _AgentContextManager:
+    def __init__(self, name: str) -> None:
+        self._name = name
+        self._token: Optional[contextvars.Token] = None
+
+    def __enter__(self) -> str:
+        self._token = _current_agent.set(self._name)
+        return self._name
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        if self._token is not None:
+            _current_agent.reset(self._token)
+
+
+def agent_scope(name: str) -> _AgentContextManager:
+    """Context manager for setting agent name within chat methods."""
+    return _AgentContextManager(name)