Metadata-Version: 2.4
Name: verdict-engine
Version: 0.1.0
Summary: Verifiable Multi-Agent Decision Reasoning Engine
Project-URL: Homepage, https://github.com/bingdongni/verdict
Project-URL: Documentation, https://bingdongni.github.io/verdict/
Project-URL: Repository, https://github.com/bingdongni/verdict
Project-URL: Issues, https://github.com/bingdongni/verdict/issues
Project-URL: Changelog, https://github.com/bingdongni/verdict/blob/main/CHANGELOG.md
Author: bingdongni
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,audit,bayesian,decision-making,game-theory,llm,mcts,mechanism-design,multi-agent,verification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: httpx<1,>=0.27
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: litellm<2,>=1.40
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pydantic-settings<3,>=2.3
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: rich<14,>=13.7
Requires-Dist: scipy<2,>=1.13
Requires-Dist: structlog<25,>=24.1
Requires-Dist: tenacity<9,>=8.3
Requires-Dist: typer<1,>=0.12
Provides-Extra: all
Requires-Dist: fastapi<1,>=0.111; extra == 'all'
Requires-Dist: hypothesis<7,>=6.100; extra == 'all'
Requires-Dist: mcp<2,>=1.0; extra == 'all'
Requires-Dist: mkdocs-gen-files<1,>=0.5; extra == 'all'
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'all'
Requires-Dist: mkdocstrings[python]<1,>=0.25; extra == 'all'
Requires-Dist: mypy<2,>=1.10; extra == 'all'
Requires-Dist: pre-commit<4,>=3.7; extra == 'all'
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'all'
Requires-Dist: pytest-cov<6,>=5; extra == 'all'
Requires-Dist: pytest-xdist<4,>=3.5; extra == 'all'
Requires-Dist: pytest<9,>=8.2; extra == 'all'
Requires-Dist: respx<1,>=0.21; extra == 'all'
Requires-Dist: ruff<1,>=0.4; extra == 'all'
Requires-Dist: uvicorn[standard]<1,>=0.29; extra == 'all'
Requires-Dist: websockets<13,>=12; extra == 'all'
Provides-Extra: dashboard
Requires-Dist: fastapi<1,>=0.111; extra == 'dashboard'
Requires-Dist: uvicorn[standard]<1,>=0.29; extra == 'dashboard'
Requires-Dist: websockets<13,>=12; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pre-commit<4,>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
Requires-Dist: pytest-xdist<4,>=3.5; extra == 'dev'
Requires-Dist: pytest<9,>=8.2; extra == 'dev'
Requires-Dist: respx<1,>=0.21; extra == 'dev'
Requires-Dist: ruff<1,>=0.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files<1,>=0.5; extra == 'docs'
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]<1,>=0.25; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# ⚖️ Verdict

**Verifiable Multi-Agent Decision Reasoning Engine**

[![PyPI](https://img.shields.io/pypi/v/verdict-engine.svg)](https://pypi.org/project/verdict-engine/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![CI](https://github.com/bingdongni/verdict/actions/workflows/ci.yml/badge.svg)](https://github.com/bingdongni/verdict/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/verdict-engine.svg)](https://pypi.org/project/verdict-engine/)

> Formal decision science meets LLM multi-agent systems.
> The first open-source framework where AI decisions come with mathematical guarantees.

Verdict is a Python framework that brings formal decision theory — game theory, mechanism design, Bayesian inference, Monte Carlo tree search — into LLM-powered multi-agent systems. Instead of agents chatting their way to a decision, Verdict agents *deliberate* through mathematically grounded protocols, producing decisions that are **verifiable**, **auditable**, and **explainable**.

## Why Verdict?

| Framework | What it does | What's missing |
|-----------|-------------|----------------|
| AutoGen / CrewAI | Agents chat to collaborate | No formal reasoning guarantees |
| OpenClaw | AI executes tasks | No decision theory |
| MiroFish | Agents simulate social dynamics | No formal verification |
| **Verdict** | **Agents deliberate with mathematical protocols** | — |

## Quick Start

```bash
pip install verdict-engine
```

```python
import asyncio
from verdict import Decision, Objective, Option, Tribunal
from verdict.agents import BayesianReasoner, DevilsAdvocate
from verdict.protocols import StructuredDebate

decision = Decision(
    name="Cloud Provider Selection",
    options=[
        Option(name="aws", params={"cost": 0.7, "ml": 0.8}),
        Option(name="gcp", params={"cost": 0.6, "ml": 0.95}),
        Option(name="azure", params={"cost": 0.65, "ml": 0.75}),
    ],
    objectives=[
        Objective(name="cost", direction="minimize"),
        Objective(name="ml_capability", direction="maximize"),
    ],
)

tribunal = Tribunal(
    agents=[
        BayesianReasoner(model="openai/gpt-4o"),
        DevilsAdvocate(model="openai/gpt-4o"),
    ],
    protocol=StructuredDebate(max_rounds=3),
)

result = asyncio.run(tribunal.deliberate(decision))
print(result.recommendation)       # "gcp"
print(f"{result.confidence:.0%}")   # "78%"
print(result.memo.to_markdown())    # Full executive summary
```

## Key Features

### 🧠 Heterogeneous Reasoning Agents

Eight specialised agent types, each with a distinct reasoning strategy:

- **BayesianReasoner** — prior/posterior updating, expected utility maximisation
- **GameTheorist** — Nash equilibria, Shapley values, dominance analysis
- **DevilsAdvocate** — systematic contrarian stress-testing
- **AdversarialVerifier** — red-team attacks, bias detection, fallacy scanning
- **RiskAssessor** — VaR/CVaR quantification, Monte Carlo stress tests
- **CausalAnalyst** — do-calculus reasoning, confounder identification
- **DomainExpert** — RAG-enhanced domain knowledge retrieval
- **MCTSExplorer** — LLM-guided Monte Carlo tree search

### 📜 Formal Deliberation Protocols

Six mathematically grounded interaction protocols:

- **StructuredDebate** — proponent/opponent/judge triangle with evidence requirements
- **DelphiProtocol** — anonymous multi-round voting with rationale revision
- **BayesianAggregation** — logarithmic opinion pooling with expert calibration
- **NashBargaining** — multi-party interest balancing via Nash product maximisation
- **VCGMechanism** — incentive-compatible, strategy-proof aggregation
- **MajorityJudgment** — median-grade voting resistant to strategic manipulation

All protocols are composable via `ProtocolChain`.

### ✅ Decision Verification

Automated quality checks with mathematical foundations:

- **Pareto optimality** — is the recommendation on the efficient frontier?
- **Logical consistency** — does the reasoning chain contradict itself?
- **Confidence calibration** — does stated confidence match vote distribution?
- **Robustness** — would small perturbations flip the recommendation?
- **Dissent acknowledgment** — are minority views documented?

### 📋 Full Audit Trail

Every reasoning step, vote, and belief update is recorded:

```python
trail = result.audit_trail
trail.query(event_type=EventType.AGENT_REASONING, agent_id="bayesian_1")
trail.persist("audit_session.json")
```

### 📝 Decision Distillation

Compress multi-round deliberation into actionable executive memos:

```python
print(result.memo.to_markdown())
# Outputs: recommendation, key arguments, dissent, risk assessment, next steps
```

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                    verdict.Tribunal                       │
├──────────────────────────────────────────────────────────┤
│  Decision    →  Agents    →  Protocol  →  Verification   │
│  (problem)      (reason)     (deliberate)  (verify)      │
│                                             ↓            │
│                              Audit Trail + Distillation  │
└──────────────────────────────────────────────────────────┘
```

## CLI

```bash
# Run a decision from a JSON file
verdict run decision.json --model openai/gpt-4o --agents bayesian,devils_advocate

# List available agents and protocols
verdict agents
verdict protocols

# Validate a decision file
verdict validate decision.json
```

## Extensibility

Verdict is designed for extension at every layer:

```python
from verdict.agents.base import ReasoningAgent, agent_registry

@agent_registry.register("my_agent")
class MyCustomAgent(ReasoningAgent):
    agent_type = "my_agent"

    async def reason(self, decision, context):
        # Your custom reasoning logic
        ...
```

Supports custom agents, protocols, verification checks, audit exporters, and LLM middleware — all via a unified registry pattern.

## Model Support

Via [litellm](https://github.com/BerriAI/litellm), Verdict works with 100+ LLM providers:

- OpenAI (GPT-4o, o1, o3-mini)
- Anthropic (Claude Sonnet 4, Claude Opus 4)
- Google (Gemini 2.0 Flash, Gemini 2.5 Pro)
- DeepSeek (DeepSeek-Chat, DeepSeek-Reasoner)
- Local models via Ollama (Llama, Qwen, Mistral)
- Azure OpenAI, AWS Bedrock, Google Vertex AI

## Documentation

Full documentation: [bingdongni.github.io/verdict](https://bingdongni.github.io/verdict/)

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Citation

```bibtex
@software{verdict2026,
  author = {bingdongni},
  title = {Verdict: Verifiable Multi-Agent Decision Reasoning Engine},
  url = {https://github.com/bingdongni/verdict},
  year = {2026},
}
```

## License

Apache-2.0 — see [LICENSE](LICENSE) for details.
