> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consensus engine

> QWED's Consensus Engine orchestrates multiple verification engines in parallel for high-confidence results with circuit breaker patterns and weighted consensus.

The Consensus Engine orchestrates multiple verification engines for high-confidence results with fault tolerance.

<Warning>
  **Changed in v4.0.4:** Python code verification within consensus now runs exclusively through the secure Docker executor (`SecureCodeExecutor`). If the Docker sandbox is unavailable, consensus returns a `blocked_secure_execution` status and the API responds with HTTP 503.
</Warning>

## Features

* **Async parallel execution** — Run engines concurrently
* **Circuit breaker** — Auto-disable failing engines
* **Engine health monitoring** — Track reliability
* **Weighted consensus** — Consider engine reliability
* **Secure code execution** — Python engine runs through the Docker sandbox only

## Usage

```python theme={null}
from qwed_sdk import QWEDClient

client = QWEDClient(api_key="qwed_...")

result = client.verify_with_consensus(
    query="2 + 2 = 4",
    mode="maximum"  # single, high, maximum
)

print(result.final_answer)     # 4
print(result.confidence)       # 0.999
print(result.engines_used)     # 3
print(result.agreement_status) # "unanimous"
```

## Verification modes

| Mode      | Engines             | Speed  | Confidence | Docker required |
| --------- | ------------------- | ------ | ---------- | --------------- |
| `single`  | 1 (SymPy)           | ⚡ Fast | Good       | No              |
| `high`    | 2 (SymPy + Python)  | Medium | High       | Yes             |
| `maximum` | 3+ (All applicable) | Slower | Maximum    | Yes             |

<Note>
  The `high` and `maximum` modes include the Python engine, which requires the secure Docker sandbox. If Docker is unavailable, these modes return `blocked_secure_execution` instead of falling back to in-process execution.
</Note>

<Note>
  The Python engine in `high` and `maximum` modes requires Docker. If the secure Docker sandbox is unavailable, consensus verification returns HTTP 503 instead of falling back to in-process code execution.
</Note>

## Async execution

```python theme={null}
import asyncio

async def verify_many():
    results = await asyncio.gather(
        client.verify_async("2+2=4"),
        client.verify_async("3*3=9"),
        client.verify_async("sqrt(16)=4")
    )
    return results
```

## Circuit breaker

When an engine fails repeatedly, it's automatically disabled:

```python theme={null}
# Check engine health
health = client.get_engine_health()

print(health)
# {
#   "SymPy": {"state": "healthy", "failures": 0},
#   "Python": {"state": "healthy", "failures": 0},
#   "Z3": {"state": "degraded", "failures": 2}
# }

# Reset circuit breakers
client.reset_circuit_breakers()
```

## Async failure handling

When an unexpected error occurs during async engine aggregation, the Consensus Engine records the failure as a dedicated `EngineResult` entry rather than silently dropping it. This ensures that:

* The failure is visible in the `results` array returned to the caller
* Aggregate confidence scores account for the failed engine
* The error is logged via `logger.exception` for post-mortem debugging

The recorded result uses `engine_name: "consensus_orchestrator"`, `method: "async_aggregation"`, `success: false`, and includes the error message in the `error` field.

***

## Engine selection

The consensus engine automatically selects which engines to run based on the verification mode:

| Mode      | Engines selected                                    |
| --------- | --------------------------------------------------- |
| `single`  | SymPy                                               |
| `high`    | SymPy, Python                                       |
| `maximum` | SymPy, Python, Z3 (+ Stats for statistical queries) |

<Note>The fact engine is excluded from automatic engine selection. Fact verification requires external context, and including it in consensus without that context would create self-referential verification loops. If fact verification is invoked during consensus, it returns an error indicating that external context is required.</Note>

***

## Consensus calculation

The engine uses weighted voting:

| Engine | Reliability Weight |
| ------ | ------------------ |
| SymPy  | 1.00               |
| Z3     | 0.995              |
| Python | 0.99               |
| Stats  | 0.98               |

Final confidence = weighted average of agreeing engines.

### Agreement statuses

| Status                     | Meaning                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `unanimous`                | All engines returned the same answer                                                  |
| `majority`                 | More than half of the total weight agrees                                             |
| `split`                    | No clear majority among engines                                                       |
| `no_results`               | No engines returned a result                                                          |
| `blocked_secure_execution` | The Docker sandbox is unavailable and a required engine cannot run (returns HTTP 503) |