koa-fhe 0.1.3

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

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

1. On first call, the SDK downloads circuit specs from the server
2. Keys are generated locally — the server never sees your secret key
3. Key hash is checked against server — if a matching key exists, it's reused
4. Otherwise, keys are uploaded (with integrity verification via X-Content-Hash)
5. Inputs are encrypted locally, sent as ciphertext
6. Server evaluates the FHE circuit on ciphertext
7. 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