Python SDK

The official Python SDK for QWED.

Installation

pip install qwed

Quick start

from qwed_sdk import QWEDClient

client = QWEDClient(api_key="qwed_your_key")

# Basic verification
result = client.verify("Is 2+2=4?")
print(result.verified)  # True
print(result.status)    # "VERIFIED"

As of v5.0.0, the status field may return INCONCLUSIVE, BLOCKED, or UNKNOWN in addition to VERIFIED and ERROR. Natural-language math queries return INCONCLUSIVE when the inner engine succeeds, because the LLM translation step is non-deterministic. See the trust boundary documentation for details.

Async client

from qwed_sdk import QWEDAsyncClient
import asyncio

async def main():
    async with QWEDAsyncClient(api_key="qwed_...") as client:
        result = await client.verify("2+2=4")
        print(result.verified)

asyncio.run(main())

Methods

verify(query)

Auto-detect and verify any claim.

result = client.verify("What is 15% of 200?")

verify_math(expression)

Verify mathematical expressions.

result = client.verify_math("x**2 + 2*x + 1 = (x+1)**2")

verify_logic(query)

Verify logical constraints (QWED-Logic DSL).

result = client.verify_logic("(AND (GT x 5) (LT y 10))")
print(result.model)  # {"x": 6, "y": 9}

verify_code(code, language)

Check code for security vulnerabilities.

result = client.verify_code(code, language="python")
for vuln in result.vulnerabilities:
    print(f"{vuln.severity}: {vuln.message}")

verify_sql(query, schema_ddl, dialect)

Validate SQL queries against a schema.

result = client.verify_sql(
    query="SELECT * FROM users WHERE id = 1",
    schema_ddl="CREATE TABLE users (id INT, name TEXT)",
    dialect="postgresql"
)

verify_fact(claim, context)

New in v4.0.0

Verify factual claims against a provided context. Includes client-side PII pre-check.

result = client.verify_fact(
    claim="The company was founded in 2020",
    context="Acme Corp was established in 2020 in San Francisco."
)
print(result.status)       # "UNVERIFIABLE" (heuristic support is advisory-only)
print(result.is_verified)  # False

verify_fact fails closed when the QWED service can’t complete the check. If the client can’t connect (httpx.ConnectError) or the request times out (httpx.TimeoutException), it returns status="UNVERIFIABLE" and is_verified=False. It doesn’t raise. The local PII pre-check still runs first, but it is not a fact check, so passing it never produces VERIFIED.

result = client.verify_fact(claim=claim, context=context)

if result.status == "UNVERIFIABLE":
    # Service unreachable, timed out, or the claim could not be proven.
    # Don't treat the claim as true. Retry, escalate, or reject.
    # Completed checks expose "agent_message"; offline/timeout failures expose
    # "message". Read both safely so neither path raises KeyError.
    print(result.result.get("agent_message") or result.result.get("message") or "Verification unavailable.")
    reject(claim)
elif result.status == "BLOCKED":
    reject(claim)

Earlier SDK versions returned status="VERIFIED" and is_verified=True when the service was unreachable, after running only the local PII scan. If your code relied on that offline pass, it now receives UNVERIFIABLE.

verify_stats(query, file_path)

New in v4.0.0

Verify statistical claims against CSV data.

result = client.verify_stats(
    query="The average salary is above 50000",
    file_path="data.csv"
)

verify_consensus(query, mode, min_confidence)

New in v4.0.0

Multi-engine consensus verification.

result = client.verify_consensus(
    query="The square root of 144 is 12",
    mode="high",
    min_confidence=0.8
)
print(result.verified)     # True
print(result.confidence)   # 0.95

Parameter	Type	Default	Description
`query`	str	—	Claim to verify
`mode`	str	`"single"`	`single`, `high`, or `maximum`
`min_confidence`	float	`0.8`	Minimum confidence threshold

verify_image(image_path, claim)

New in v4.0.0

Verify claims about image content.

result = client.verify_image(
    image_path="photo.jpg",
    claim="This image contains a cat"
)

verify_batch(items)

Verify multiple items at once. The response is a BatchResult whose items are per-item records — for math items the verdict is a DiagnosticResult nested under each item’s result, so check result.status and result.proof_ref per item rather than relying on an aggregate.

response = client.verify_batch([
    {"query": "2+2=4", "type": "math"},
    {"query": "x + x", "type": "math"},
])

for item in response.items:
    result = item.result or {}
    if result.get("status") == "VERIFIED" and result.get("proof_ref"):
        # Authoritative — admissible for control flow
        print("verified:", result.get("agent_message"), result.get("proof_ref"))
    else:
        # UNVERIFIABLE or BLOCKED — must reject
        print("rejected:", result.get("status"), result.get("agent_message"))

For math items, supply equality claims (e.g., "x + x = 2*x") to receive proof results. Bare expressions without an = return status: "UNVERIFIABLE" with the simplified form in developer_fields.simplified — they are never reported as verified. The legacy is_valid flag is preserved inside developer_fields.is_valid for backward compatibility.

Verification Context

New in v7.1.0

The SDK exposes Verification Context v1.0 — the standardized JSON record of a verification — as client methods, re-exported types, and a to_verification_context() method on the verifier classes.

Client methods

All three methods are available on both QWEDClient and QWEDAsyncClient and call the corresponding Verification Context endpoints.

create_verification_context_from_diagnostic(diagnostic, query, verifier)

Create a schema-valid Verification Context document from a DiagnosticResult dict. Optional keyword arguments: verifier_version and attestation_token. A VERIFIED diagnostic without a valid attestation token fails closed to BLOCKED (fail-closed).

document = client.create_verification_context_from_diagnostic(
    diagnostic={
        "status": "VERIFIED",
        "agent_message": "Identity verified",
        "developer_fields": {"is_valid": True},
        "proof_ref": "sha256:9f2c…",
    },
    query="x**2 + 2*x + 1 = (x+1)**2",
    verifier="MathVerifier",
    attestation_token=token,
)
print(document["verdict"])                             # "VERIFIED"
print(document["context"]["decision"]["admission"])    # "ADMIT"

validate_verification_context(document)

Validate a document against the v1.0 JSON Schema.

result = client.validate_verification_context(document)
print(result["valid"])  # True or False

resolve_verification_context(document)

Resolve the document’s proof_ref evidence commitment.

result = client.resolve_verification_context(document)
print(result["resolved"])  # True only if the stored proof_ref matches

Re-exported types and helpers

qwed_sdk re-exports the Verification Context v1.0 model, so you can build, validate, and resolve documents locally without an API round trip:

from qwed_sdk import (
    # Enums and model types
    Verdict,
    Admission,
    VerificationContext,
    VerificationContextDocument,
    VerificationContextValidationError,
    Formalization,
    VerifiedObject,
    Interpretation,
    Proof,
    Evidence,
    Decision,
    # proof_ref helpers
    compute_document_proof_ref,
    resolve_document_proof_ref,
    compute_context_proof_ref,
    resolve_context_proof_ref,
    # Schema validation helpers
    validate_document,
    is_valid_document,
)

# Validate a document dict (raises VerificationContextValidationError on failure)
validate_document(document)

# Boolean variant
if is_valid_document(document):
    ...

# Recompute and check the evidence commitment locally
assert resolve_document_proof_ref(document)

compute_document_proof_ref(document) derives the canonical sha256:<64-hex> commitment for a document.
resolve_document_proof_ref(document) returns True only when the document is VERIFIED, schema-valid, and the stored proof_ref matches the re-derived commitment. Everything else returns False (fail-closed).

to_verification_context() on verifiers

Every verification engine that defines to_verification_context() maps its DiagnosticResult to a Verification Context document: the Code, Consensus, DSL Logic, Fact, Graph Fact, Image, Logic, Reasoning, Schema, SQL, Stats, and Symbolic verifier classes, plus the BatchFactVerifier and MultiVLMVerifier helpers. Math and the secure code executor do not define the method — pass their DiagnosticResult to create_verification_context_from_diagnostic() instead:

# Verifiers that define the method — convert the DiagnosticResult they return
diagnostic = sql_verifier.verify_sql(query="SELECT id, total FROM orders WHERE customer_id = 42")
document = sql_verifier.to_verification_context(
    diagnostic, query="SELECT id, total FROM orders WHERE customer_id = 42"
)
document.validate()
print(document.to_dict()["verdict"])

# Math and the secure code executor have no such method — pass their
# DiagnosticResult dict to the client instead
document = client.create_verification_context_from_diagnostic(
    diagnostic={
        "status": "VERIFIED",
        "agent_message": "Identity verified",
        "developer_fields": {"is_valid": True},
        "proof_ref": "sha256:9f2c…",
    },
    query="x**2 + 2*x + 1 = (x+1)**2",
    verifier="MathVerifier",
    attestation_token=token,
)

The mapping preserves the fail-closed invariants: VERIFIED documents carry a sha256 proof_ref, while UNVERIFIABLE and BLOCKED documents carry proof_ref: null with admission DENY.

Verification cache

qwed_sdk.cache.VerificationCache is the persistent SQLite-backed cache for verification results. It reduces LLM cost on repeated queries. Cache entries are context-bound. A hit requires an exact match of both the normalized query and the trust-bound CacheContext. A mismatch on any context dimension is a deterministic miss. The cache never falls back to a query-only match. This prevents cross-provider, cross-model, cross-policy, and cross-tenant replay of VERIFIED results.

`CacheContext`

Every get() and set() call requires a CacheContext. All fields participate in the cache key.

Field	Type	Required	Description
`provider`	`str`	yes	Provider or API endpoint identifier (e.g., `"openai"`).
`model`	`str`	yes	Model or deployment name (e.g., `"gpt-4o"`).
`policy_version`	`str`	yes	Verifier policy version string (e.g., `"v1"`).
`tenant_id`	`Optional[str]`	no	Tenant or session scope identifier.
`env_fingerprint`	`Optional[str]`	no	Environment or configuration fingerprint for extra binding.

Usage

from qwed_sdk.cache import CacheContext, VerificationCache

cache = VerificationCache()  # defaults to ~/.qwed/cache, TTL 24h

ctx = CacheContext(
    provider="openai",
    model="gpt-4o",
    policy_version="v1",
    tenant_id="tenant-alpha",
)

# Cache miss on first call
result = cache.get("Is 2+2=4?", ctx)         # None

# Populate the cache for this (query, context) pair
cache.set("Is 2+2=4?", {"verified": True, "value": 4}, ctx)

# Same query, same context → hit
cache.get("Is 2+2=4?", ctx)                  # {"verified": True, "value": 4}

# Same query, different provider → deterministic miss
ctx_other = CacheContext(provider="anthropic", model="claude-opus-4-5", policy_version="v1")
cache.get("Is 2+2=4?", ctx_other)            # None

Miss conditions

cache.get(query, context) returns None when any of the following holds:

No entry exists for this (query, context) pair.
The stored entry has expired (TTL, default 24 hours).
The stored context fingerprint does not match context (replay guard).
The entry uses the legacy v1 schema. The cache never returns legacy rows.

Constructor options

VerificationCache(cache_dir: Optional[str] = None, ttl: int = 86400)

cache_dir — Directory for the SQLite database. Defaults to ~/.qwed/cache.
ttl — Time-to-live in seconds. Defaults to 24 hours.

get() and set() require a CacheContext argument as of the May 17, 2026 release. Calls that omit the context raise TypeError. See the changelog entry for migration details.

CLI

# Verify
qwed verify "2+2=4"

# Verify logic
qwed verify-logic "(AND (GT x 5) (LT y 10))"

# Verify code file
qwed verify-code -f script.py

# Batch verify
qwed batch -f queries.json

# Verification Context v1.0 utilities (v7.1.0)
qwed context validate document.json
qwed context resolve document.json
qwed context from-diagnostic --diagnostic-file diag.json \
  --query "x + x = 2*x" --verifier MathVerifier

See the CLI reference for details on the qwed context command group.

Verification cache

qwed_sdk.cache provides a context-bound SQLite cache for verification results. A cache hit requires an exact match of both the normalized query and the trust-bound CacheContext. Any mismatch on a context dimension yields a deterministic miss — the cache never crosses trust boundaries. The cache also ignores legacy entries that lack a context fingerprint.

from qwed_sdk.cache import CacheContext, VerificationCache

ctx = CacheContext(
    provider="openai",
    model="gpt-4o",
    policy_version="v1",
    tenant_id="tenant-alpha",       # optional
    env_fingerprint="sha256-...",   # optional
)

cache = VerificationCache()

cache.get("2+2", ctx)              # None (miss)
cache.set("2+2", {"verified": True}, ctx)
cache.get("2+2", ctx)              # {"verified": True}

# Different provider — deterministic miss (replay prevention)
ctx2 = CacheContext(provider="claude", model="claude-opus-4-5", policy_version="v1")
cache.get("2+2", ctx2)             # None

`CacheContext`

Trust-bound context dimensions required for every cache operation. All fields participate in the cache key; omitting or changing any field causes a deterministic cache miss.

str

required

Provider or API endpoint identifier (for example, "openai", "claude").

str

required

Model or deployment name (for example, "gpt-4o").

str

required

Verifier policy version string (for example, "v1").

Optional[str]

default:"None"

Tenant or session scope identifier. Use to prevent cross-tenant replay.

Optional[str]

default:"None"

Environment or config fingerprint for additional binding.

`VerificationCache(cache_dir=None, ttl=86400)`

Optional[str]

default:"~/.qwed/cache"

Directory for the SQLite cache database.

int

default:"86400"

Time-to-live in seconds (default: 24 hours). get() treats entries older than ttl as a miss and deletes them on access.

The cache caps total entries at MAX_ENTRIES = 1000. When set() grows the table past the cap, set() evicts the least-recently-accessed entries.

`get(query, context)`

Return the cached result for (query, context), or None on miss. get() returns None when:

No entry exists for the (query, context) pair.
The entry has expired (older than ttl).
The stored context fingerprint does not match context (defence-in-depth replay guard).

str

required

The verification query string. Normalized (lowercased, whitespace-collapsed) before hashing.

CacheContext

required

Trust-bound context that must match exactly. Omitting this argument raises TypeError.

Optional[Dict[str, Any]]

The cached result dict, or None on any miss.

`set(query, result, context)`

Store a verification result bound to (query, context). The composite primary key (key, context_fingerprint) keeps identical queries under different contexts as independent entries.

str

required

The verification query string.

Dict[str, Any]

required

Verification result to cache. set() serializes this dict as JSON.

CacheContext

required

Trust-bound context to bind this entry to.

`clear()`

Remove all cached entries and reset stats.

`get_stats()`

Return a CacheStats dataclass with hits, misses, total_entries, cache_size_bytes, and a hit_rate property.

`print_stats()`

Print a formatted summary of cache statistics to stdout. Uses ANSI colors when colorama is installed.

Breaking change (Issue #187). get() and set() now require a CacheContext argument. Calls like cache.get("2+2") or cache.set("2+2", result) raise TypeError. The on-disk schema is cache_v2 with composite PRIMARY KEY (key, context_fingerprint). The cache never returns entries from the legacy v1 cache table.

Guards

The SDK includes security guards for protecting AI agent pipelines:

from qwed_sdk.guards import (
    RAGGuard,
    ExfiltrationGuard,
    MCPPoisonGuard,
    SelfInitiatedCoTGuard,
    SovereigntyGuard,
    SystemGuard,
    ConfigGuard,
)

# Prevent RAG hallucinations from wrong document chunks
rag_guard = RAGGuard(max_drm_rate="1/10")
result = rag_guard.verify_retrieval_context(
    target_document_id="contract_v2",
    retrieved_chunks=chunks
)

# Block data exfiltration to unauthorized endpoints
exfil_guard = ExfiltrationGuard(allowed_endpoints=["https://api.openai.com"])
result = exfil_guard.verify_outbound_call(
    destination_url=url,
    payload=data
)

# Detect poisoned MCP tool definitions
mcp_guard = MCPPoisonGuard()
result = mcp_guard.verify_tool_definition(tool_schema)

# Block dangerous shell commands (v4.0.0)
sys_guard = SystemGuard()
result = sys_guard.verify_shell_command("rm -rf /")

# Detect plaintext secrets in config (v4.0.0)
cfg_guard = ConfigGuard()
result = cfg_guard.verify_config_safety(config_data)

See the SDK Guards reference for complete documentation.

Environment variables

Variable	Description
`QWED_API_KEY`	API key
`QWED_BASE_URL`	API base URL

API Reference

SDKs

Installation

Quick start

Async client

Methods

verify(query)

verify_math(expression)

verify_logic(query)

verify_code(code, language)

verify_sql(query, schema_ddl, dialect)

verify_fact(claim, context)

verify_stats(query, file_path)

verify_consensus(query, mode, min_confidence)

verify_image(image_path, claim)

verify_batch(items)

Verification Context

Client methods

create_verification_context_from_diagnostic(diagnostic, query, verifier)

validate_verification_context(document)

resolve_verification_context(document)

Re-exported types and helpers

to_verification_context() on verifiers

Verification cache

`CacheContext`

Usage

Miss conditions

Constructor options

CLI

Verification cache

`CacheContext`

`VerificationCache(cache_dir=None, ttl=86400)`

`get(query, context)`

`set(query, result, context)`

`clear()`

`get_stats()`

`print_stats()`

Guards

Environment variables

​Installation

​Quick start

​Async client

​Methods

​verify(query)

​verify_math(expression)

​verify_logic(query)

​verify_code(code, language)

​verify_sql(query, schema_ddl, dialect)

​verify_fact(claim, context)

​verify_stats(query, file_path)

​verify_consensus(query, mode, min_confidence)

​verify_image(image_path, claim)

​verify_batch(items)

​Verification Context

​Client methods

​create_verification_context_from_diagnostic(diagnostic, query, verifier)

​validate_verification_context(document)

​resolve_verification_context(document)

​Re-exported types and helpers

​to_verification_context() on verifiers

​Verification cache

​CacheContext

​Usage

​Miss conditions

​Constructor options

​CLI

​Verification cache

​CacheContext

​VerificationCache(cache_dir=None, ttl=86400)

​get(query, context)

​set(query, result, context)

​clear()

​get_stats()

​print_stats()

​Guards

​Environment variables

Installation

Quick start

Async client

Methods

verify(query)

verify_math(expression)

verify_logic(query)

verify_code(code, language)

verify_sql(query, schema_ddl, dialect)

verify_fact(claim, context)

verify_stats(query, file_path)

verify_consensus(query, mode, min_confidence)

verify_image(image_path, claim)

verify_batch(items)

Verification Context

Client methods

create_verification_context_from_diagnostic(diagnostic, query, verifier)

validate_verification_context(document)

resolve_verification_context(document)

Re-exported types and helpers

to_verification_context() on verifiers

Verification cache

`CacheContext`

Usage

Miss conditions

Constructor options

CLI

Verification cache

`CacheContext`

`VerificationCache(cache_dir=None, ttl=86400)`

`get(query, context)`

`set(query, result, context)`

`clear()`

`get_stats()`

`print_stats()`

Guards

Environment variables