Metadata-Version: 2.3
Name: dialectical-framework
Version: 1.1.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
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

