Consensus engine

​

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

​

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

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

​

Execution deadlines and partial results

• One aggregate budget, not per-engine stacking. All selected engines share the same 30-second wall clock. Sequential per-engine waits cannot accumulate beyond it.
• Timed-out engines become explicit BLOCKED results. An engine that misses the deadline is recorded in verification_chain as a BLOCKED EngineResult with the timeout in its error field (for example, "Engine timed out after 30s"). The failure is also recorded with the circuit breaker.
• Circuit-open engines are recorded too. An engine skipped because its circuit breaker is open appears as a BLOCKED result rather than being silently dropped.
• Partial results still aggregate. Engines that finished within the deadline contribute normally. The consensus verdict is computed from the results that arrived, with the fail-closed status propagation rules applied — a BLOCKED engine result caps the consensus at UNVERIFIABLE.
• Off the event loop. Engine execution runs in a dedicated per-call executor, so a slow consensus request degrades only itself, not other API traffic.

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

for engine in result.verification_chain:
    if engine.status == "BLOCKED" and "timed out" in (engine.error or ""):
        print(f"{engine.engine_name} missed the 30s deadline")

​

Async failure handling

• 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

​

Secure execution gates

​

Single-expression gate on translated math

• The expression must parse with ast.parse(..., mode="eval"). Multi-statement input, semicolon chains, assignments, imports, and multi-line newline smuggling all fail by construction.
• Expressions longer than 500 characters are rejected before parsing, so deeply nested adversarial input never reaches the parser.
• The existing character-set and denylist checks remain as defense in depth.

​

Module-indirection blocklist on executed code

• Imports of OS, process, and reflection modules (os, sys, subprocess, socket, posix, nt, importlib, ctypes, builtins, and network clients) are blocked wherever the module name appears in the import path, including from ... import os as safe aliasing.
• Attribute chains are blocked when any segment names a dangerous module, so package-internal re-exports (reaching the OS module through pandas or numpy internals) are caught even though the chain is rooted at an innocuous alias.
• OS-primitive calls (system, popen, import_module, the exec*/spawn* families, fork) are blocked as bare names and as attribute targets, which also stops importlib.import_module("os")-style indirection.

​

Engine selection

​

Consensus calculation

​

Agreement statuses

​

Status propagation

• All engines return BLOCKED → the consensus result is BLOCKED.
• Any single engine returns BLOCKED (but not all) → the consensus result is capped at UNVERIFIABLE (fail-closed — a partial block prevents VERIFIED).
• Any engine returns UNVERIFIABLE → the consensus result is UNVERIFIABLE.
• Only unanimous VERIFIED engine outcomes can produce a VERIFIED consensus.
• Math-query translation failures fail closed — the engine raises rather than fabricating a numeric answer from a regex or decimal guess.

​

Sub-engine status contract

​

ConsensusResult

​

.to_diagnostic_result()

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

dr = result.to_diagnostic_result()

dr.is_verified          # True only if consensus was VERIFIED
dr.proof_ref            # sha256:... bound to result.verified_evidence
dr.developer_fields     # {'agreement_status': 'unanimous', 'confidence': 0.99, 'engines_used': 2}