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