agentic-settle 0.2.0__tar.gz

agentic_settle-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 AgenticSettle.IO
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

agentic_settle-0.2.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: agentic-settle
+Version: 0.2.0
+Summary: Python SDK for AgenticSettle — verify any AI agent's output, settle with pre-paid token escrow, earn the Verified badge.
+Author-email: "AgenticSettle.IO" <engineering@agenticsettle.io>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/agenticsettleio/agentic-settle-core
+Project-URL: Issues, https://github.com/agenticsettleio/agentic-settle-core/issues
+Keywords: agentic,settlement,web3,kms,fastapi,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# agentic-settle
+
+Python client SDK for the **AgenticSettle Pro** settlement engine.
+
+A deliberately thin wrapper over the REST API so AI-native applications can
+spend less than 30 seconds wiring up on-chain settlement for their agents.
+
+```bash
+pip install agentic-settle
+```
+
+## Quickstart (synchronous)
+
+```python
+import os
+from agentic_settle import SettleClient
+
+client = SettleClient(
+    base_url="https://api.agenticsettle.io",
+    api_key=os.environ["AGENTIC_SETTLE_API_KEY"],
+)
+
+receipt = client.settle(
+    agent_id="gpt-4o",
+    request_content="What is the capital of France?",
+    result_content="Paris",
+    target_wallet="0x0000000000000000000000000000000000000000",
+)
+
+print(receipt.status, receipt.chain_tx_hash)
+```
+
+## Quickstart (asyncio)
+
+```python
+import asyncio
+from agentic_settle import AsyncSettleClient
+
+async def main() -> None:
+    client = AsyncSettleClient(api_key="...")
+    receipt = await client.settle(
+        agent_id="claude-3.5",
+        request_content="...",
+        result_content="...",
+        target_wallet="0x...",
+    )
+    print(receipt)
+
+asyncio.run(main())
+```
+
+## Environment variables
+
+The client falls back to the following env vars when constructor arguments
+are omitted:
+
+| Variable                    | Purpose                                  |
+|-----------------------------|------------------------------------------|
+| `AGENTIC_SETTLE_BASE_URL`   | Base URL of the settlement service       |
+| `AGENTIC_SETTLE_API_KEY`    | API key (preferred)                      |
+| `BRUCE_SECRET_KEY`          | Legacy fallback for local dev convenience |
+
+## What's in the box
+
+- `SettleClient`       — synchronous client (httpx under the hood)
+- `AsyncSettleClient`  — asyncio variant for high-throughput agents
+- `SettleRequest`      — request payload model (pydantic v2)
+- `SettleReceipt`      — response receipt model (pydantic v2)
+
+Type annotations ship with `py.typed`.
+
+## License
+
+Apache-2.0

agentic_settle-0.2.0/README.md

@@ -0,0 +1,74 @@
+# agentic-settle
+
+Python client SDK for the **AgenticSettle Pro** settlement engine.
+
+A deliberately thin wrapper over the REST API so AI-native applications can
+spend less than 30 seconds wiring up on-chain settlement for their agents.
+
+```bash
+pip install agentic-settle
+```
+
+## Quickstart (synchronous)
+
+```python
+import os
+from agentic_settle import SettleClient
+
+client = SettleClient(
+    base_url="https://api.agenticsettle.io",
+    api_key=os.environ["AGENTIC_SETTLE_API_KEY"],
+)
+
+receipt = client.settle(
+    agent_id="gpt-4o",
+    request_content="What is the capital of France?",
+    result_content="Paris",
+    target_wallet="0x0000000000000000000000000000000000000000",
+)
+
+print(receipt.status, receipt.chain_tx_hash)
+```
+
+## Quickstart (asyncio)
+
+```python
+import asyncio
+from agentic_settle import AsyncSettleClient
+
+async def main() -> None:
+    client = AsyncSettleClient(api_key="...")
+    receipt = await client.settle(
+        agent_id="claude-3.5",
+        request_content="...",
+        result_content="...",
+        target_wallet="0x...",
+    )
+    print(receipt)
+
+asyncio.run(main())
+```
+
+## Environment variables
+
+The client falls back to the following env vars when constructor arguments
+are omitted:
+
+| Variable                    | Purpose                                  |
+|-----------------------------|------------------------------------------|
+| `AGENTIC_SETTLE_BASE_URL`   | Base URL of the settlement service       |
+| `AGENTIC_SETTLE_API_KEY`    | API key (preferred)                      |
+| `BRUCE_SECRET_KEY`          | Legacy fallback for local dev convenience |
+
+## What's in the box
+
+- `SettleClient`       — synchronous client (httpx under the hood)
+- `AsyncSettleClient`  — asyncio variant for high-throughput agents
+- `SettleRequest`      — request payload model (pydantic v2)
+- `SettleReceipt`      — response receipt model (pydantic v2)
+
+Type annotations ship with `py.typed`.
+
+## License
+
+Apache-2.0

agentic_settle-0.2.0/__init__.py

@@ -0,0 +1,65 @@
+"""
+AgenticSettle SDK
+=================
+
+A thin client for the AgenticSettle Pro settlement engine.
+
+V1 quickstart (legacy sync settlement)::
+
+    from agentic_settle import SettleClient
+
+    client = SettleClient(
+        base_url="https://api.agenticsettle.io",
+        api_key="...",
+    )
+    receipt = client.settle(
+        agent_id="gpt-4o",
+        request_content="prompt...",
+        result_content="answer...",
+        target_wallet="0x...",
+    )
+    print(receipt.status, receipt.chain_tx_hash)
+
+V2 quickstart (prepaid-token + verification-gated)::
+
+    client.register_agent("acme-ai")
+    client.register_token("ACME-CREDIT", "acme-ai")
+    client.purchase_tokens(customer_id="cust_42", token_id="ACME-CREDIT", amount=1000)
+
+    task = client.create_task(
+        customer_id="cust_42", agent_id="acme-ai", token_id="ACME-CREDIT",
+        escrow_amount=100, request_content="Summarize this 80-page PDF",
+    )
+    delivered = client.deliver(task.task_id, result_content=agent_result)
+    if delivered.verdict["verdict"] == "PASS":
+        client.decide(task.task_id, "SATISFIED")
+    else:
+        client.decide(task.task_id, "UNSATISFIED", reason="섹션 2 누락")
+"""
+
+from .client import AsyncSettleClient, SettleClient
+from .types import (
+    DecisionResult,
+    DeliveryResult,
+    SettleReceipt,
+    SettleRequest,
+    TaskOrder,
+    TokenBalance,
+    VerificationReport,
+)
+
+__all__ = [
+    # V1
+    "SettleClient",
+    "AsyncSettleClient",
+    "SettleRequest",
+    "SettleReceipt",
+    # V2
+    "TokenBalance",
+    "TaskOrder",
+    "VerificationReport",
+    "DeliveryResult",
+    "DecisionResult",
+]
+
+__version__ = "0.2.0"

agentic_settle-0.2.0/agentic_settle.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: agentic-settle
+Version: 0.2.0
+Summary: Python SDK for AgenticSettle — verify any AI agent's output, settle with pre-paid token escrow, earn the Verified badge.
+Author-email: "AgenticSettle.IO" <engineering@agenticsettle.io>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/agenticsettleio/agentic-settle-core
+Project-URL: Issues, https://github.com/agenticsettleio/agentic-settle-core/issues
+Keywords: agentic,settlement,web3,kms,fastapi,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# agentic-settle
+
+Python client SDK for the **AgenticSettle Pro** settlement engine.
+
+A deliberately thin wrapper over the REST API so AI-native applications can
+spend less than 30 seconds wiring up on-chain settlement for their agents.
+
+```bash
+pip install agentic-settle
+```
+
+## Quickstart (synchronous)
+
+```python
+import os
+from agentic_settle import SettleClient
+
+client = SettleClient(
+    base_url="https://api.agenticsettle.io",
+    api_key=os.environ["AGENTIC_SETTLE_API_KEY"],
+)
+
+receipt = client.settle(
+    agent_id="gpt-4o",
+    request_content="What is the capital of France?",
+    result_content="Paris",
+    target_wallet="0x0000000000000000000000000000000000000000",
+)
+
+print(receipt.status, receipt.chain_tx_hash)
+```
+
+## Quickstart (asyncio)
+
+```python
+import asyncio
+from agentic_settle import AsyncSettleClient
+
+async def main() -> None:
+    client = AsyncSettleClient(api_key="...")
+    receipt = await client.settle(
+        agent_id="claude-3.5",
+        request_content="...",
+        result_content="...",
+        target_wallet="0x...",
+    )
+    print(receipt)
+
+asyncio.run(main())
+```
+
+## Environment variables
+
+The client falls back to the following env vars when constructor arguments
+are omitted:
+
+| Variable                    | Purpose                                  |
+|-----------------------------|------------------------------------------|
+| `AGENTIC_SETTLE_BASE_URL`   | Base URL of the settlement service       |
+| `AGENTIC_SETTLE_API_KEY`    | API key (preferred)                      |
+| `BRUCE_SECRET_KEY`          | Legacy fallback for local dev convenience |
+
+## What's in the box
+
+- `SettleClient`       — synchronous client (httpx under the hood)
+- `AsyncSettleClient`  — asyncio variant for high-throughput agents
+- `SettleRequest`      — request payload model (pydantic v2)
+- `SettleReceipt`      — response receipt model (pydantic v2)
+
+Type annotations ship with `py.typed`.
+
+## License
+
+Apache-2.0

agentic_settle-0.2.0/agentic_settle.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+__init__.py
+client.py
+py.typed
+pyproject.toml
+types.py
+./__init__.py
+./client.py
+./py.typed
+./types.py
+agentic_settle.egg-info/PKG-INFO
+agentic_settle.egg-info/SOURCES.txt
+agentic_settle.egg-info/dependency_links.txt
+agentic_settle.egg-info/requires.txt
+agentic_settle.egg-info/top_level.txt

agentic_settle-0.2.0/agentic_settle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentic_settle-0.2.0/agentic_settle.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.27.0
+pydantic>=2.0.0

agentic_settle-0.2.0/agentic_settle.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentic_settle

agentic_settle-0.2.0/client.py

@@ -0,0 +1,434 @@
+"""
+HTTP clients for the AgenticSettle settlement engine.
+
+
+- ``SettleClient``       — synchronous (requests-free; uses ``httpx``)
+- ``AsyncSettleClient``  — asyncio-friendly variant for high-throughput agents
+
+Both share identical surface area; pick whichever fits your runtime.
+
+V1 helpers (`settle`, `get_status`, `dashboard_metrics`) are unchanged.
+V2 helpers cover the new prepaid-token + verification-gated flow.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from typing import Any
+
+import httpx
+
+from .types import (
+    DecisionResult,
+    DeliveryResult,
+    SettleReceipt,
+    SettleRequest,
+    TaskOrder,
+    TokenBalance,
+    VerificationReport,
+)
+
+_DEFAULT_TIMEOUT = 30.0
+_SDK_VERSION = "0.2.0"
+
+
+def _gen_request_id() -> str:
+    return f"REQ-{uuid.uuid4().hex[:12].upper()}"
+
+
+def _gen_task_id() -> str:
+    return f"TSK-{uuid.uuid4().hex[:12].upper()}"
+
+
+def _headers(api_key: str) -> dict[str, str]:
+    return {
+        "x-api-key": api_key,
+        "content-type": "application/json",
+        "user-agent": f"agentic-settle-sdk/{_SDK_VERSION}",
+    }
+
+
+class _Base:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = (
+            base_url or os.getenv("AGENTIC_SETTLE_BASE_URL", "http://localhost:8000")
+        ).rstrip("/")
+        self.api_key = (
+            api_key
+            or os.getenv("AGENTIC_SETTLE_API_KEY")
+            or os.getenv("BRUCE_SECRET_KEY")
+        )
+        if not self.api_key:
+            raise ValueError(
+                "AgenticSettle SDK: no API key. "
+                "Pass api_key=... or set AGENTIC_SETTLE_API_KEY in the environment."
+            )
+        self.timeout = timeout
+
+    def _build_payload(
+        self,
+        *,
+        agent_id: str,
+        request_content: str,
+        result_content: str,
+        target_wallet: str,
+        request_id: str | None,
+    ) -> dict[str, Any]:
+        req = SettleRequest(
+            request_id=request_id or _gen_request_id(),
+            agent_id=agent_id,
+            request_content=request_content,
+            result_content=result_content,
+            target_wallet=target_wallet,
+        )
+        return req.model_dump()
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# Sync client
+# ─────────────────────────────────────────────────────────────────────────
+class SettleClient(_Base):
+    """Synchronous client (V1 + V2)."""
+
+    # ── V1 (unchanged) ──────────────────────────────────────────────
+    def settle(
+        self,
+        *,
+        agent_id: str,
+        request_content: str,
+        result_content: str,
+        target_wallet: str,
+        request_id: str | None = None,
+    ) -> SettleReceipt:
+        payload = self._build_payload(
+            agent_id=agent_id,
+            request_content=request_content,
+            result_content=result_content,
+            target_wallet=target_wallet,
+            request_id=request_id,
+        )
+        with httpx.Client(timeout=self.timeout) as c:
+            r = c.post(f"{self.base_url}/v1/settle", json=payload, headers=_headers(self.api_key))
+            r.raise_for_status()
+            return SettleReceipt.model_validate(r.json())
+
+    def get_status(self, request_id: str) -> SettleReceipt:
+        with httpx.Client(timeout=self.timeout) as c:
+            r = c.get(
+                f"{self.base_url}/v1/settle/status/{request_id}",
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return SettleReceipt.model_validate(r.json())
+
+    def dashboard_metrics(self) -> dict[str, Any]:
+        with httpx.Client(timeout=self.timeout) as c:
+            r = c.get(
+                f"{self.base_url}/v1/settle/dashboard-metrics",
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return r.json()
+
+    # ── V2: prepaid-token + verification-gated flow ────────────────
+    def register_agent(
+        self, agent_id: str, *, company_name: str | None = None,
+        payout_wallet: str | None = None,
+    ) -> dict[str, Any]:
+        return self._post("/v2/agents/register", {
+            "agent_id": agent_id,
+            "company_name": company_name,
+            "payout_wallet": payout_wallet,
+        })
+
+    def register_token(
+        self, token_id: str, agent_id: str, *, symbol: str | None = None,
+        decimals: int = 0, unit_price_wei: str | None = None,
+        erc20_address: str | None = None,
+    ) -> dict[str, Any]:
+        return self._post("/v2/tokens/register", {
+            "token_id": token_id,
+            "agent_id": agent_id,
+            "symbol": symbol,
+            "decimals": decimals,
+            "unit_price_wei": unit_price_wei,
+            "erc20_address": erc20_address,
+        })
+
+    def purchase_tokens(
+        self, *, customer_id: str, token_id: str, amount: int,
+        paid_wei: str | None = None, paid_method: str = "OFFCHAIN",
+        tx_ref: str | None = None,
+    ) -> dict[str, Any]:
+        return self._post("/v2/tokens/purchase", {
+            "customer_id": customer_id,
+            "token_id": token_id,
+            "amount": amount,
+            "paid_wei": paid_wei,
+            "paid_method": paid_method,
+            "tx_ref": tx_ref,
+        })
+
+    def get_balance(self, customer_id: str, token_id: str) -> TokenBalance:
+        return TokenBalance.model_validate(self._get(
+            "/v2/tokens/balance",
+            params={"customer_id": customer_id, "token_id": token_id},
+        ))
+
+    def create_task(
+        self, *, customer_id: str, agent_id: str, token_id: str,
+        escrow_amount: int, request_content: str,
+        task_id: str | None = None, max_rework: int | None = None,
+    ) -> TaskOrder:
+        body = {
+            "task_id": task_id or _gen_task_id(),
+            "customer_id": customer_id,
+            "agent_id": agent_id,
+            "token_id": token_id,
+            "escrow_amount": escrow_amount,
+            "request_content": request_content,
+            "max_rework": max_rework,
+        }
+        return TaskOrder.model_validate(self._post("/v2/tasks", body))
+
+    def deliver(
+        self, task_id: str, *, result_content: str,
+        result_uri: str | None = None,
+    ) -> DeliveryResult:
+        return DeliveryResult.model_validate(self._post(
+            f"/v2/tasks/{task_id}/deliver",
+            {"result_content": result_content, "result_uri": result_uri},
+        ))
+
+    def decide(
+        self, task_id: str, decision: str, *, reason: str | None = None,
+    ) -> DecisionResult:
+        return DecisionResult.model_validate(self._post(
+            f"/v2/tasks/{task_id}/decide",
+            {"decision": decision, "reason": reason},
+        ))
+
+    def dispute(self, task_id: str, *, reason: str | None = None) -> TaskOrder:
+        return TaskOrder.model_validate(self._post(
+            f"/v2/tasks/{task_id}/dispute", {"reason": reason}
+        ))
+
+    def get_task(self, task_id: str) -> TaskOrder:
+        return TaskOrder.model_validate(self._get(f"/v2/tasks/{task_id}"))
+
+    def get_reports(self, task_id: str) -> list[VerificationReport]:
+        raw = self._get(f"/v2/tasks/{task_id}/report")
+        return [VerificationReport.model_validate(r) for r in raw.get("reports", [])]
+
+    def v2_metrics(self) -> dict[str, Any]:
+        return self._get("/v2/metrics")
+
+    # ── V2 verify-only (field-test, PIVOT_V2.md §14) ─────────────────
+    def verify(
+        self,
+        *,
+        request_content: str,
+        result_content: str,
+        agent_id: str | None = None,
+        customer_label: str | None = None,
+        title: str | None = None,
+        sla: dict | None = None,
+        work_seconds: int | None = None,
+        sla_seconds: int | None = None,
+        audience: str = "customer",
+        verification_id: str | None = None,
+    ) -> dict[str, Any]:
+        """One-shot quality verification with no escrow / settlement."""
+        return self._post("/v2/verify", {
+            "verification_id": verification_id,
+            "agent_id":        agent_id,
+            "customer_label":  customer_label,
+            "title":           title,
+            "request_content": request_content,
+            "result_content":  result_content,
+            "sla":             sla,
+            "work_seconds":    work_seconds,
+            "sla_seconds":     sla_seconds,
+            "audience":        audience,
+        })
+
+    def get_verification(
+        self, verification_id: str, *, audience: str = "customer"
+    ) -> dict[str, Any]:
+        return self._get(
+            f"/v2/verifications/{verification_id}",
+            params={"audience": audience},
+        )
+
+    def agent_performance(self, agent_id: str) -> dict[str, Any]:
+        return self._get(f"/v2/agents/{agent_id}/performance")
+
+    # ── V2.1.C — Agent credits (AC) ──────────────────────────────────
+    def agent_credits(self, agent_id: str) -> dict[str, Any]:
+        """Read the agent's accrued AgentCredit balance."""
+        return self._get(f"/v2/agents/{agent_id}/credits")
+
+    def convert_agent_credits(
+        self, agent_id: str, *, amount_ac: int, ref: str | None = None,
+    ) -> dict[str, Any]:
+        """Burn ``amount_ac`` AC → record VOP-conversion event."""
+        return self._post(
+            f"/v2/agents/{agent_id}/credits/convert",
+            {"amount_ac": amount_ac, "ref": ref},
+        )
+
+
+
+    # ── Tiny transport helpers ─────────────────────────────────────
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(timeout=self.timeout) as c:
+            r = c.post(f"{self.base_url}{path}", json=body, headers=_headers(self.api_key))
+            r.raise_for_status()
+            return r.json()
+
+    def _get(
+        self, path: str, *, params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        with httpx.Client(timeout=self.timeout) as c:
+            r = c.get(
+                f"{self.base_url}{path}", params=params,
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return r.json()
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# Async client
+# ─────────────────────────────────────────────────────────────────────────
+class AsyncSettleClient(_Base):
+    """Asyncio variant — recommended for high-throughput agent runtimes."""
+
+    # ── V1 (unchanged) ─────────────────────────────────────────────
+    async def settle(
+        self,
+        *,
+        agent_id: str,
+        request_content: str,
+        result_content: str,
+        target_wallet: str,
+        request_id: str | None = None,
+    ) -> SettleReceipt:
+        payload = self._build_payload(
+            agent_id=agent_id,
+            request_content=request_content,
+            result_content=result_content,
+            target_wallet=target_wallet,
+            request_id=request_id,
+        )
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            r = await c.post(
+                f"{self.base_url}/v1/settle",
+                json=payload,
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return SettleReceipt.model_validate(r.json())
+
+    async def get_status(self, request_id: str) -> SettleReceipt:
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            r = await c.get(
+                f"{self.base_url}/v1/settle/status/{request_id}",
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return SettleReceipt.model_validate(r.json())
+
+    async def dashboard_metrics(self) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            r = await c.get(
+                f"{self.base_url}/v1/settle/dashboard-metrics",
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return r.json()
+
+    # ── V2 (async mirrors of the sync API) ─────────────────────────
+    async def purchase_tokens(
+        self, *, customer_id: str, token_id: str, amount: int,
+        paid_wei: str | None = None, paid_method: str = "OFFCHAIN",
+        tx_ref: str | None = None,
+    ) -> dict[str, Any]:
+        return await self._apost("/v2/tokens/purchase", {
+            "customer_id": customer_id,
+            "token_id": token_id,
+            "amount": amount,
+            "paid_wei": paid_wei,
+            "paid_method": paid_method,
+            "tx_ref": tx_ref,
+        })
+
+    async def get_balance(self, customer_id: str, token_id: str) -> TokenBalance:
+        return TokenBalance.model_validate(await self._aget(
+            "/v2/tokens/balance",
+            params={"customer_id": customer_id, "token_id": token_id},
+        ))
+
+    async def create_task(
+        self, *, customer_id: str, agent_id: str, token_id: str,
+        escrow_amount: int, request_content: str,
+        task_id: str | None = None, max_rework: int | None = None,
+    ) -> TaskOrder:
+        body = {
+            "task_id": task_id or _gen_task_id(),
+            "customer_id": customer_id,
+            "agent_id": agent_id,
+            "token_id": token_id,
+            "escrow_amount": escrow_amount,
+            "request_content": request_content,
+            "max_rework": max_rework,
+        }
+        return TaskOrder.model_validate(await self._apost("/v2/tasks", body))
+
+    async def deliver(
+        self, task_id: str, *, result_content: str,
+        result_uri: str | None = None,
+    ) -> DeliveryResult:
+        return DeliveryResult.model_validate(await self._apost(
+            f"/v2/tasks/{task_id}/deliver",
+            {"result_content": result_content, "result_uri": result_uri},
+        ))
+
+    async def decide(
+        self, task_id: str, decision: str, *, reason: str | None = None,
+    ) -> DecisionResult:
+        return DecisionResult.model_validate(await self._apost(
+            f"/v2/tasks/{task_id}/decide",
+            {"decision": decision, "reason": reason},
+        ))
+
+    async def get_reports(self, task_id: str) -> list[VerificationReport]:
+        raw = await self._aget(f"/v2/tasks/{task_id}/report")
+        return [VerificationReport.model_validate(r) for r in raw.get("reports", [])]
+
+    # ── Transport ──────────────────────────────────────────────────
+    async def _apost(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            r = await c.post(
+                f"{self.base_url}{path}", json=body,
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return r.json()
+
+    async def _aget(
+        self, path: str, *, params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            r = await c.get(
+                f"{self.base_url}{path}", params=params,
+                headers=_headers(self.api_key),
+            )
+            r.raise_for_status()
+            return r.json()

agentic_settle-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+# SDK-only build target.
+#
+# The repository root carries the *service* metadata in /pyproject.toml
+# (pytest + ruff config + the FastAPI app version). This file isolates the
+# **public client SDK** so it can be built and published independently:
+#
+#     python -m build agentic_settle
+#     twine upload --repository testpypi agentic_settle/dist/*
+#
+# The SDK has a deliberately tiny dependency set — only what end-user agents
+# need to call the settlement service. No FastAPI / boto3 / web3 / streamlit.
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentic-settle"
+version = "0.2.0"
+description = "Python SDK for AgenticSettle — verify any AI agent's output, settle with pre-paid token escrow, earn the Verified badge."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+keywords = ["agentic", "settlement", "web3", "kms", "fastapi", "sdk"]
+authors = [
+    { name = "AgenticSettle.IO", email = "engineering@agenticsettle.io" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/agenticsettleio/agentic-settle-core"
+Issues = "https://github.com/agenticsettleio/agentic-settle-core/issues"
+
+# Tell setuptools that the package directory IS the project root for this
+# sub-build (we're inside agentic_settle/ already).
+[tool.setuptools]
+packages = ["agentic_settle"]
+package-dir = { "agentic_settle" = "." }
+
+[tool.setuptools.package-data]
+agentic_settle = ["py.typed"]

agentic_settle-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentic_settle-0.2.0/types.py

@@ -0,0 +1,98 @@
+"""
+Public data types exposed by the SDK.
+
+Kept intentionally framework-agnostic (pydantic v2 dataclasses) so SDK users
+don't have to install FastAPI / SQLite / web3 to call the API.
+
+V1 types are retained verbatim. V2 types implement the prepaid-token +
+verification-gated settlement flow (see ``PIVOT_V2.md``).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# V1 — legacy settle endpoint (kept for backward compatibility)
+# ─────────────────────────────────────────────────────────────────────────
+class SettleRequest(BaseModel):
+    """Payload posted to ``POST /v1/settle``."""
+
+    request_id: str = Field(..., description="Caller-generated idempotency key.")
+    agent_id: str = Field(..., description="Logical agent identifier, e.g. 'gpt-4o'.")
+    request_content: str = Field(..., description="Original user prompt / task input.")
+    result_content: str = Field(..., description="Agent's produced result to be scored.")
+    target_wallet: str = Field(..., description="Recipient EOA for the on-chain payout.")
+
+
+class SettleReceipt(BaseModel):
+    """Response returned by the settlement engine."""
+
+    request_id: str
+    status: str = Field(..., description="One of PENDING / COMPLETED / GAS_HOLD / DISPUTED / SLASHED.")
+    score: int | None = None
+    tier: str | None = None
+    payout_eth: float | None = None
+    gas_saved_gwei: int | None = None
+    chain_tx_hash: str | None = None
+    receipt: str | None = Field(None, description="Signed receipt blob (HMAC).")
+    timestamp: str | None = None
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# V2 — prepaid-token + verification-gated settlement
+# ─────────────────────────────────────────────────────────────────────────
+class TokenBalance(BaseModel):
+    """Customer × agent-token balance snapshot."""
+
+    customer_id: str
+    token_id: str
+    balance: int = Field(..., description="Total credited tokens.")
+    locked: int = Field(0, description="Currently held in escrow.")
+    available: int = Field(..., description="balance - locked")
+
+
+class TaskOrder(BaseModel):
+    """Task created against an escrowed bag of tokens (``POST /v2/tasks``)."""
+
+    task_id: str
+    customer_id: str
+    agent_id: str
+    token_id: str
+    escrow_amount: int = Field(..., gt=0)
+    request_content: str = ""
+    status: str | None = None
+    rework_count: int = 0
+    max_rework: int | None = None
+
+
+class VerificationReport(BaseModel):
+    """One round of VOP verification (``GET /v2/tasks/{id}/report``)."""
+
+    report_id: str
+    round_no: int
+    vop_score: int
+    tier: str | None = None
+    verdict: str = Field(..., description="PASS | FAIL")
+    fail_codes: list[str] = Field(default_factory=list)
+    onchain_tx_hash: str | None = None
+    issued_at: str | None = None
+
+
+class DeliveryResult(BaseModel):
+    """Response from ``POST /v2/tasks/{id}/deliver``."""
+
+    delivery_id: str
+    round_no: int
+    report_id: str
+    verdict: dict
+    task: dict
+
+
+class DecisionResult(BaseModel):
+    """Response from ``POST /v2/tasks/{id}/decide``."""
+
+    decision_id: str
+    task: dict
+    charge_id: str | None = None