feat: Add Karma as pluggable verifiable evaluator for ERC-8183

ARCHITECTURE.md

@@ -330,6 +330,107 @@ BNBAgentError
 - **Custom Module** — extend `BNBAgentModule` and register via entry points
   to add new protocol support without modifying the SDK.
 
+## Karma Verifiable Evaluator
+
+The `bnbagent.extras.karma` package adds Karma Trust Protocol's **verifiable
+execution** as an off-chain evaluator for ERC-8183 settlement.
+
+### Integration model
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  ERC-8183 On-Chain                                         │
+│                                                            │
+│  createJob → fund → submit(deliverable)                    │
+│                         ↓                                  │
+│  ┌──────────────────────────────────────────────────┐      │
+│  │  KarmaBNBVerifier (off-chain bridge)              │      │
+│  │                                                   │      │
+│  │  1. Fetch deliverable URL from Policy events      │      │
+│  │  2. Download Karma evidence bundle + receipts     │      │
+│  │  3. POST Karma Runtime /v1/verify                │      │
+│  │  4. If APPROVE → router.settle(job_id, evidence) │      │
+│  └──────────────────────────────────────────────────┘      │
+│                         ↓                                  │
+│  settlement → COMPLETED (or REJECTED)                      │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Code Map
+
+| File | Purpose |
+|------|---------|
+| `extras/__init__.py` | Extras namespace package |
+| `extras/karma/__init__.py` | Public API: `KarmaEvaluator`, `KarmaBNBVerifier`, `KarmaEvidenceStore`, `KarmaReceiptSigner` |
+| `extras/karma/evaluator.py` | Core evaluator: verifier client, evidence encoding, receipt helpers |
+
+### Key Components
+
+- **KarmaEvaluator** — Async off-chain verifier. Sends evidence bundles to the
+  Karma Runtime and returns APPROVE/REJECT/PENDING verdicts. Works standalone
+  (no Web3 dependency).
+- **KarmaBNBVerifier** — Bridge that composes `KarmaEvaluator` with an
+  `ERC8183Client`. The single entry point `verify_and_settle(job_id)` runs
+  the full pipeline: state check → deliverable fetch → Karma verify → settle.
+- **KarmaEvidenceStore** — Thread-safe in-memory receipt cache, compatible
+  with Karma's `ReceiptStore` protocol.
+- **KarmaReceiptSigner** — EIP-191 signature wrapper for receipt digests.
+
+### Evidence Encoding
+
+Karma verification results are embedded as `evidence` bytes in
+`router.settle(job_id, evidence)`, creating a permanent on-chain audit trail:
+
+```json
+{
+  "karma": {
+    "verification_id": "vfy-abc123",
+    "verdict": "APPROVE",
+    "score": 0.98,
+    "receipt_count": 5,
+    "bundle_hash": "0x...",
+    "verified_at": "2025-01-01T00:00:00Z"
+  }
+}
+```
+
+### Design decisions
+
+1. **No new on-chain contracts.** The integration uses the existing
+   `OptimisticPolicy` + `EvaluatorRouter`. Karma acts as a pre-settlement
+   verification oracle, not a replacement for on-chain policies.
+2. **Off-chain by design.** Karma Runtime does the cryptographic heavy lifting
+   (receipt verification, Merkle reconstruction, hash consistency checks).
+   The chain only sees the result.
+3. **Pluggable.** `KarmaEvaluator` has no dependency on `ERC8183Client`.
+   Callers can use it standalone, embed it in custom scripts, or compose it
+   via `KarmaBNBVerifier`.
+4. **Auditable evidence.** The `evidence` bytes written on-chain are
+   self-describing JSON that links back to the Karma verification run.
+   Anyone can verify the claim by fetching the deliverable and re-running
+   Karma verification.
+
+### Install
+
+```bash
+pip install "bnbagent[karma]"
+```
+
+Requires `httpx ≥ 0.25` (async HTTP for Karma Runtime API calls).
+
+### Quickstart
+
+```python
+from bnbagent.extras.karma import KarmaEvaluator, KarmaBNBVerifier
+from bnbagent import ERC8183Client
+
+karma = KarmaEvaluator(runtime_url="https://api.karma.xyz", api_key="...")
+verifier = KarmaBNBVerifier(erc8183_client, karma)
+result = await verifier.verify_and_settle(job_id)
+```
+
+Full example: [`examples/karma_integration.py`](../examples/karma_integration.py)
+
 ## Dependencies
 
 | Category | Packages |

README.md

@@ -28,8 +28,11 @@ pip install "bnbagent[server]"
 # IPFS storage (HTTP pinning service backend, e.g. Pinata)
 pip install "bnbagent[ipfs]"
 
+# Karma verifiable evaluator (signed receipts + evidence bundles)
+pip install "bnbagent[karma]"
+
 # All extras
-pip install "bnbagent[server,ipfs]"
+pip install "bnbagent[server,ipfs,karma]"
 ```
 
 ## Table of Contents
@@ -42,6 +45,7 @@ pip install "bnbagent[server,ipfs]"
 - [Configuration Reference](#configuration-reference)
 - [Architecture & Components](#architecture--components)
 - [Network & Contracts](#network--contracts)
+- [Karma Verifiable Evaluator](#karma-verifiable-evaluator)
 - [Examples](#examples)
 - [Security](#security)
 - [Troubleshooting](#troubleshooting)
@@ -431,6 +435,70 @@ Payment token address is read from `commerce.paymentToken()` at runtime.
 
 ---
 
+## Karma Verifiable Evaluator
+
+> 🛡️ **Prequisite:** Install with `pip install "bnbagent[karma]"`
+
+The `bnbagent.extras.karma` package brings [Karma Trust Protocol](https://github.com/AtoB101/Karma)'s **verifiable execution** into the ERC-8183 settlement lifecycle. Instead of relying solely on the optimistic silence-approves policy, operators can run a Karma evaluator that independently verifies every tool-call receipt before settling.
+
+### What you get
+
+- **KarmaEvaluator** — Off-chain verifier that validates Karma evidence bundles and signed receipts against the Karma Runtime.
+- **KarmaBNBVerifier** — Top-level bridge that composes `KarmaEvaluator` with `ERC8183Client`. Call `verify_and_settle(job_id)` to run the full pipeline: fetch deliverable → verify → settle on-chain.
+- **KarmaEvidenceStore** — Lightweight in-memory receipt cache.
+- **Evidence encoding** — Karma verification results are embedded as `evidence` bytes in `router.settle()`, creating a permanent on-chain audit trail.
+
+### How it works
+
+```
+ERC-8183 Job (Submitted)
+       │
+       ▼
+KarmaBNBVerifier.verify_and_settle(job_id)
+       │
+       ├─ 1. Fetch deliverable URL from on-chain events
+       ├─ 2. Download Karma evidence bundle + signed receipts
+       ├─ 3. POST /v1/verify → Karma Runtime
+       ├─ 4. If APPROVE → router.settle(job_id, evidence)
+       └─ 5. On-chain evidence bytes link back to Karma verification
+```
+
+### Quick example
+
+```python
+from bnbagent import ERC8183Client, EVMWalletProvider
+from bnbagent.extras.karma import KarmaEvaluator, KarmaBNBVerifier
+
+wallet = EVMWalletProvider(password="...", private_key="0x...")
+erc8183 = ERC8183Client(wallet, network="bsc-testnet")
+
+evaluator = KarmaEvaluator(
+    runtime_url="https://api.karma.xyz",
+    api_key="karma_secret",
+)
+
+verifier = KarmaBNBVerifier(erc8183, evaluator, min_confidence=0.5)
+
+# After provider calls submit()
+result = await verifier.verify_and_settle(job_id)
+print(result["verdict"])   # APPROVE | REJECT
+print(result["tx_hash"])   # settlement tx hash (if settled)
+```
+
+Full end-to-end example: [`examples/karma_integration.py`](examples/karma_integration.py)
+
+### Architecture
+
+Karma evaluators are **pluggable** — they don't require changes to the on-chain policy contracts. They work alongside the existing `OptimisticPolicy`, acting as a pre-settlement verification oracle:
+
+- **No new contracts.** The `evidence` bytes from Karma are written to the existing `router.settle(evidence)` field.
+- **Off-chain verification.** Karma Runtime does the heavy lifting; only the result hash touches the chain.
+- **Auditable.** Anyone can decrypt the `evidence` bytes and follow the link to the Karma verification run.
+
+For more details, see [`ARCHITECTURE.md` § Karma Verifiable Evaluator](ARCHITECTURE.md#karma-verifiable-evaluator).
+
+---
+
 ## Examples
 
 | Example | Role | Description |

bnbagent/extras/__init__.py

@@ -0,0 +1,10 @@
+"""
+bnbagent extras — optional protocol integrations.
+
+Each subpackage is an independent integration that extends the BNBAgent SDK
+with third-party protocol support. Install them via pip extras:
+
+    pip install "bnbagent[karma]"   # Karma verifiable evaluator
+"""
+
+from __future__ import annotations

bnbagent/extras/karma/__init__.py

@@ -0,0 +1,53 @@
+"""
+Karma Verifiable Evaluator — BNB Chain ERC-8183 integration.
+
+Plugs Karma's signed-receipt + evidence-bundle verification into the
+ERC-8183 settlement lifecycle as a pre-submit evaluator.
+
+Key components
+--------------
+- ``KarmaEvaluator``      — verifies Karma evidence bundles before ``settle()``.
+- ``KarmaBNBVerifier``    — high-level verifier that wraps ``KarmaEvaluator``
+  and integrates with ``ERC8183Client``.
+- ``KarmaEvidenceStore``  — lightweight in-memory cache for Karma receipts.
+- ``KarmaReceiptSigner``  — EIP-191 compatible receipt signer for on-chain anchoring.
+
+Quickstart
+----------
+    from bnbagent import ERC8183Client, EVMWalletProvider
+    from bnbagent.extras.karma import KarmaEvaluator, KarmaBNBVerifier
+
+    wallet = EVMWalletProvider(password="...", private_key="0x...")
+    erc8183 = ERC8183Client(wallet, network="bsc-testnet")
+
+    evaluator = KarmaEvaluator(
+        runtime_url="https://api.karma.xyz",
+        api_key="karma_secret",
+    )
+
+    verifier = KarmaBNBVerifier(erc8183, evaluator)
+
+    # After the provider submits the deliverable, verify it with Karma:
+    result = await verifier.verify_and_settle(job_id)
+    # result contains Karma's VerificationResult + on-chain settlement tx
+
+Install
+-------
+    pip install "bnbagent[karma]"
+"""
+
+from __future__ import annotations
+
+from .evaluator import (
+    KarmaBNBVerifier,
+    KarmaEvaluator,
+    KarmaEvidenceStore,
+    KarmaReceiptSigner,
+)
+
+__all__ = [
+    "KarmaEvaluator",
+    "KarmaBNBVerifier",
+    "KarmaEvidenceStore",
+    "KarmaReceiptSigner",
+]