Consensus engine

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

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.

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

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

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.

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.

Async execution

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:

# 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)

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.

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)

Overview

Core Engines

Analysis Engines

Specialized Engines

Features

Usage

Verification modes

Async execution

Circuit breaker

Async failure handling

Engine selection

Consensus calculation

Agreement statuses

​Features

​Usage

​Verification modes

​Async execution

​Circuit breaker

​Async failure handling

​Engine selection

​Consensus calculation

​Agreement statuses

Features

Usage

Verification modes

Async execution

Circuit breaker

Async failure handling

Engine selection

Consensus calculation

Agreement statuses