koa-fhe

koa-fhe

Confidential coprocessor client — compute on encrypted data via Koa's FHE service.

The server never sees plaintext. Your data is encrypted locally, evaluated under Fully Homomorphic Encryption, and decrypted locally. Every query costs $0.001–$0.10 USDC via x402.

Install

pip install koa-fhe            # core (compare, add, multiply, schedule analysis)
pip install koa-fhe[ml]        # + encrypted ML inference (XGBoost workload scoring)

CLI (Agent-to-Agent)

No install needed — run ephemeral via uvx:

uvx koa-fhe health                                    # service status
uvx koa-fhe compare 85 80                             # {"greater": true, ...}
uvx koa-fhe add 500 300                               # {"value": 800, ...}
uvx koa-fhe multiply 7 13                             # {"value": 91, ...}
uvx koa-fhe verify --circuit add --queries 5          # integrity check
uvx koa-fhe --server http://remote:3410 compare 85 80 # remote server

Every command outputs JSON to stdout. Exit code 1 if integrity verification fails. Agents can call this as a subprocess — no venv, no imports, no state management.

Also works with pipx run koa-fhe or python -m koa_fhe.

Python API

import koa_fhe

client = koa_fhe.Client()  # default: localhost:3410

# Encrypted comparison — server never sees 85 or 80
result = client.compare(85, 80)
print(result.greater)  # True

# Encrypted addition
result = client.add(500, 300)
print(result.value)  # 800

# Encrypted multiplication
result = client.multiply(7, 13)
print(result.value)  # 91

API Reference

Client(server, *, payment_proof)

Method	Returns	Latency	Price
compare(a, b)	CompareResult(greater, stats)	~625ms	$0.002
add(a, b)	ArithmeticResult(value, stats)	~260ms	$0.001
multiply(a, b)	ArithmeticResult(value, stats)	~685ms	$0.002
measure_rigidity(old, new)	RigidityResult(hamming_distance, rigidity_score, severity, stats)	~3.5s	$0.05
analyze_schedule(old, new, *, constraints, alpha, beta)	ScheduleAnalysis(objective, ...)	~5s	$0.10
predict_workload(features)	WorkloadPrediction(predictions, stats)	~7s	$0.01
verify_integrity(circuit, n_queries, *, seed)	IntegrityResult(passed, queries, proofs)	varies	same as circuit
health()	ServiceHealth(status, circuits, ...)	instant	free
circuits()	dict — circuit catalog with hashes, pricing	instant	free

Warm-up & Readiness

Key generation is the slowest step (~2-30s per circuit). Use warm_up() to pre-generate keys in background threads:

client = koa_fhe.Client()
client.warm_up(["add", "threshold"])  # keygen in background

# ... do other work ...

print(client.ready)  # {"add": True, "threshold": True}
result = client.add(1, 2)  # instant — keys already ready

Key Deduplication

Evaluation keys are content-addressed (SHA-256). If you create multiple Client instances with the same circuits, the SDK detects duplicate keys on the server via HEAD /keys/{circuit}?hash=... and reuses them — no redundant uploads.

How it works

• On first call, the SDK downloads circuit specs from the server
• Keys are generated locally — the server never sees your secret key
• Key hash is checked against server — if a matching key exists, it's reused
• Otherwise, keys are uploaded (with integrity verification via X-Content-Hash)
• Inputs are encrypted locally, sent as ciphertext
• Server evaluates the FHE circuit on ciphertext
• Encrypted result returns, SDK decrypts locally

Key setup is cached per circuit. Subsequent calls skip steps 1-4. Server-side key management enforces TTL (24h default) and per-circuit caps (10 keys max).

LangChain Integration

pip install koa-fhe[langchain]

from koa_fhe.langchain import koa_tools
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

agent = initialize_agent(
    tools=koa_tools("http://your-koa-server:3410"),
    llm=ChatOpenAI(),
    agent=AgentType.OPENAI_FUNCTIONS,
)

agent.run("Is 85 greater than 80? Use encrypted comparison.")

Tools: koa_encrypted_compare, koa_encrypted_add, koa_encrypted_multiply, koa_encrypted_rigidity, koa_encrypted_schedule_analysis, koa_fhe_health.

Integrity Verification

Agents can verify that the FHE service computes correctly by interleaving trap queries — test vectors with known plaintext answers. Because FHE hides the inputs, the server cannot distinguish trap queries from real ones.

result = client.verify_integrity("add", n_queries=5, seed=42)
print(result.passed)   # True — all trap queries returned correct results
print(len(result.queries))  # 5

# If the server ever returns a wrong result:
if not result.passed:
    for proof in result.proofs:
        print(proof.circuit, proof.inputs, proof.expected, proof.actual)
        # → Submit proof to KoaIntegrity smart contract for on-chain slashing

Supported circuits: add, multiply, threshold. See contracts/KoaIntegrity.sol for the on-chain slashing mechanism.

Discovery

The FHE service exposes machine-readable metadata for agent-to-agent integration:

• OpenAPI spec: GET /openapi.yaml
• Service manifest: GET /.well-known/x402 — x402 payment info, service catalog, ERC-8004 identity
• Agent aliases: /v1/confidential/{predicate,aggregate,arithmetic,rigidity,analysis,predict}

On-chain identity: ERC-8004 Agent #21648 on Base mainnet.

Dependencies

Core (pip install koa-fhe): concrete-python + numpy. Handles compare, add, multiply, rigidity, and schedule analysis.

ML (pip install koa-fhe[ml]): adds concrete-ml for encrypted XGBoost inference. This pulls in PyTorch, scikit-learn, etc. — only install if you need predict_workload().

License

MIT