zambo-sdk 0.1.0__tar.gz

zambo_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: zambo-sdk
+Version: 0.1.0
+Summary: Zambo Python client — 100+ MCP tools, verifiable receipt for every call, no API key
+Author: Brennan Zambo
+License: MIT
+Project-URL: Homepage, https://zambo.dev
+Project-URL: Documentation, https://zambo.dev/docs
+Keywords: zambo,mcp,ai-tools,agents,receipts
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# zambo-sdk
+
+Thin Python client for [Zambo](https://zambo.dev) — the trust layer for AI work. 100+ native MCP tools, a verifiable receipt for every call. Free 20 calls/tool/day, no account, no API key. Zero dependencies.
+
+> **Name note:** the distribution name is pending final pick (`zambo-sdk`, `zambo-dev`, `zambo-api`, `pyzambo`, `zambodotdev`, `zambopy` are all free on PyPI). The import package is `zambo_sdk` regardless.
+
+## Install
+
+```bash
+pip install zambo-sdk
+```
+
+## Quickstart
+
+```python
+from zambo_sdk import Client, verify_receipt
+
+z = Client()
+
+# 1. Call a tool — plain JSON-RPC, no API key
+result = z.call("live_price", {"symbol": "BTC"})
+print(result.text)
+print("receipt:", result.receipt_id)
+print("audit:  ", result.audit_url)
+
+# 2. Route any goal through the universal entry point
+job = z.universal("audit https://example.com for AI discoverability", session="demo-1")
+print(job.text)
+
+# 3. Search the full 100+ tool catalog
+found = z.search("generate QR code")
+print(found.text)
+
+# 4. Verify a receipt client-side (recomputes the sha256 locally)
+v = verify_receipt(result.receipt_id)
+print("verified:", v.verified, v.checks)
+```
+
+## API
+
+- `Client().call(tool, arguments)` → `CallResult` (`.text`, `.receipt_id`, `.audit_url`, `.receipt`)
+- `Client().list_tools()` → list of tool descriptors
+- `Client().search(query)` → search the full catalog via `capability_search`
+- `Client().universal(goal, session=None)` → multi-step jobs via `zambo_universal`
+- `get_receipt(receipt_id)` → full receipt JSON
+- `verify_receipt(receipt_id)` → `Verification` (`.verified`, `.checks`, `.audit_url`)
+
+`verify_receipt` checks three things: the receipt exists, the server marks it `verified`, and — recomputed locally so the server can't fake it — `sha256(canonical_bytes) == output_hash`, plus the presence of the anchor record.
+
+## Notes
+
+- Endpoint: `https://zambo.dev/api/mcp` (JSON-RPC 2.0 over HTTPS, `streamable_http`-compatible).
+- Receipts: `https://zambo.dev/api/receipt/<uuid>` (JSON), audit page `https://zambo.dev/run/<uuid>`.
+- Need more than 20 calls/tool/day? The $1.49/24h Day Pass is at [zambo.dev](https://zambo.dev).

zambo_sdk-0.1.0/README.md

@@ -0,0 +1,54 @@
+# zambo-sdk
+
+Thin Python client for [Zambo](https://zambo.dev) — the trust layer for AI work. 100+ native MCP tools, a verifiable receipt for every call. Free 20 calls/tool/day, no account, no API key. Zero dependencies.
+
+> **Name note:** the distribution name is pending final pick (`zambo-sdk`, `zambo-dev`, `zambo-api`, `pyzambo`, `zambodotdev`, `zambopy` are all free on PyPI). The import package is `zambo_sdk` regardless.
+
+## Install
+
+```bash
+pip install zambo-sdk
+```
+
+## Quickstart
+
+```python
+from zambo_sdk import Client, verify_receipt
+
+z = Client()
+
+# 1. Call a tool — plain JSON-RPC, no API key
+result = z.call("live_price", {"symbol": "BTC"})
+print(result.text)
+print("receipt:", result.receipt_id)
+print("audit:  ", result.audit_url)
+
+# 2. Route any goal through the universal entry point
+job = z.universal("audit https://example.com for AI discoverability", session="demo-1")
+print(job.text)
+
+# 3. Search the full 100+ tool catalog
+found = z.search("generate QR code")
+print(found.text)
+
+# 4. Verify a receipt client-side (recomputes the sha256 locally)
+v = verify_receipt(result.receipt_id)
+print("verified:", v.verified, v.checks)
+```
+
+## API
+
+- `Client().call(tool, arguments)` → `CallResult` (`.text`, `.receipt_id`, `.audit_url`, `.receipt`)
+- `Client().list_tools()` → list of tool descriptors
+- `Client().search(query)` → search the full catalog via `capability_search`
+- `Client().universal(goal, session=None)` → multi-step jobs via `zambo_universal`
+- `get_receipt(receipt_id)` → full receipt JSON
+- `verify_receipt(receipt_id)` → `Verification` (`.verified`, `.checks`, `.audit_url`)
+
+`verify_receipt` checks three things: the receipt exists, the server marks it `verified`, and — recomputed locally so the server can't fake it — `sha256(canonical_bytes) == output_hash`, plus the presence of the anchor record.
+
+## Notes
+
+- Endpoint: `https://zambo.dev/api/mcp` (JSON-RPC 2.0 over HTTPS, `streamable_http`-compatible).
+- Receipts: `https://zambo.dev/api/receipt/<uuid>` (JSON), audit page `https://zambo.dev/run/<uuid>`.
+- Need more than 20 calls/tool/day? The $1.49/24h Day Pass is at [zambo.dev](https://zambo.dev).

zambo_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zambo-sdk"  # Brennan-approved distribution name (2026-09-20). "zambo" is his CLI package.
+version = "0.1.0"
+description = "Zambo Python client — 100+ MCP tools, verifiable receipt for every call, no API key"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Brennan Zambo" }]
+keywords = ["zambo", "mcp", "ai-tools", "agents", "receipts"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://zambo.dev"
+Documentation = "https://zambo.dev/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]

zambo_sdk-0.1.0/setup.cfg

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

zambo_sdk-0.1.0/src/zambo_sdk/__init__.py

@@ -0,0 +1,30 @@
+"""zambo_sdk — thin Python client for zambo.dev.
+
+Zambo (https://zambo.dev) is the trust layer for AI work: 100+ native MCP
+tools over plain JSON-RPC, a verifiable receipt for every call. Free
+20 calls/tool/day, no account, no API key. $1.49/24h Day Pass.
+
+This is the whole client: call tools, fetch receipts, verify receipts.
+No dependencies beyond the standard library.
+"""
+
+from zambo_sdk.client import (
+    ZAMBO_API_URL,
+    CallResult,
+    Client,
+    ReceiptNotFound,
+    Verification,
+    get_receipt,
+    verify_receipt,
+)
+
+__all__ = [
+    "ZAMBO_API_URL",
+    "CallResult",
+    "Client",
+    "ReceiptNotFound",
+    "Verification",
+    "get_receipt",
+    "verify_receipt",
+]
+__version__ = "0.1.0"

zambo_sdk-0.1.0/src/zambo_sdk/client.py

@@ -0,0 +1,202 @@
+"""Thin, dependency-free client for the Zambo MCP endpoint.
+
+Contract (verified live against https://zambo.dev/api/mcp):
+- POST JSON-RPC 2.0, no auth, no session.
+- ``tools/list`` -> {"tools": [...]}
+- ``tools/call`` {"name", "arguments"} -> {"content": [...], "_receipt": {...}}
+- Server answers JSON or SSE (``data: {...}`` lines); transport flakes are
+  retried, JSON-RPC errors are never retried.
+- Receipt JSON: GET https://zambo.dev/api/receipt/<uuid> (Accept: application/json)
+- Human audit page: https://zambo.dev/run/<uuid>
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.client as _http_client
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+ZAMBO_API_URL = "https://zambo.dev/api/mcp"
+ZAMBO_RECEIPT_API = "https://zambo.dev/api/receipt/{receipt_id}"
+ZAMBO_AUDIT_URL = "https://zambo.dev/run/{receipt_id}"
+
+_JSON_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json, text/event-stream",
+}
+
+_TRANSIENT = (
+    _http_client.IncompleteRead,
+    _http_client.RemoteDisconnected,
+    _http_client.BadStatusLine,
+    ConnectionResetError,
+    BrokenPipeError,
+    TimeoutError,
+)
+
+
+class ZamboError(Exception):
+    """A JSON-RPC error returned by the Zambo server."""
+
+
+class ReceiptNotFound(ZamboError):
+    """No receipt exists for the given id."""
+
+
+@dataclass
+class CallResult:
+    """The outcome of one tool call."""
+
+    tool: str
+    text: str
+    receipt_id: Optional[str] = None
+    audit_url: Optional[str] = None
+    receipt: Dict[str, Any] = field(default_factory=dict)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.receipt.get("status") == "success" if self.receipt else True
+
+
+@dataclass
+class Verification:
+    """Client-side verification of a Zambo receipt."""
+
+    receipt_id: str
+    verified: bool
+    checks: Dict[str, bool]
+    audit_url: str
+    receipt: Dict[str, Any] = field(default_factory=dict)
+
+
+def _post_json_rpc(method: str, params: Dict[str, Any], attempts: int = 6) -> Dict[str, Any]:
+    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
+    last: Optional[Exception] = None
+    for n in range(attempts):
+        try:
+            req = urllib.request.Request(ZAMBO_API_URL, data=body, headers=_JSON_HEADERS, method="POST")
+            with urllib.request.urlopen(req, timeout=60) as resp:
+                raw = resp.read().decode().strip()
+            break
+        except _TRANSIENT as e:
+            last = e
+            time.sleep(0.6 * (n + 1))
+    else:
+        raise ZamboError(f"Transport failed after {attempts} attempts: {type(last).__name__}: {last}")
+
+    if raw.startswith("{"):
+        payload = json.loads(raw)
+    else:  # SSE: data: {...} lines
+        payload = None
+        for line in raw.splitlines():
+            if line.startswith("data:"):
+                try:
+                    payload = json.loads(line[5:].strip())
+                    break
+                except json.JSONDecodeError:
+                    continue
+    if payload is None:
+        raise ZamboError(f"Unparseable response: {raw[:200]}")
+    if "error" in payload:
+        raise ZamboError(json.dumps(payload["error"]))
+    return payload["result"]
+
+
+def _get_json(url: str, attempts: int = 4) -> Dict[str, Any]:
+    last: Optional[Exception] = None
+    for n in range(attempts):
+        try:
+            req = urllib.request.Request(url, headers={"Accept": "application/json"}, method="GET")
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise ReceiptNotFound(f"No receipt found: {url}")
+            raise ZamboError(f"HTTP {e.code} fetching {url}")
+        except _TRANSIENT as e:
+            last = e
+            time.sleep(0.6 * (n + 1))
+    raise ZamboError(f"Transport failed after {attempts} attempts: {type(last).__name__}: {last}")
+
+
+class Client:
+    """Minimal Zambo client. No API key, no account — free 20 calls/tool/day."""
+
+    def call(self, tool: str, arguments: Optional[Dict[str, Any]] = None) -> CallResult:
+        """Call a Zambo tool. Returns text + the verifiable receipt."""
+        result = _post_json_rpc("tools/call", {"name": tool, "arguments": arguments or {}})
+        text = "\n".join(
+            b.get("text", "") for b in result.get("content", []) if b.get("type") == "text"
+        )
+        receipt = result.get("_receipt", {}) or {}
+        rid = receipt.get("id")
+        return CallResult(
+            tool=tool,
+            text=text,
+            receipt_id=rid,
+            audit_url=ZAMBO_AUDIT_URL.format(receipt_id=rid) if rid else None,
+            receipt=receipt,
+            raw=result,
+        )
+
+    def list_tools(self) -> List[Dict[str, Any]]:
+        """List the tools on the main MCP surface."""
+        return _post_json_rpc("tools/list", {}).get("tools", [])
+
+    def search(self, query: str) -> CallResult:
+        """Search the full 100+ tool catalog."""
+        return self.call("capability_search", {"query": query})
+
+    def universal(self, goal: str, session: Optional[str] = None) -> CallResult:
+        """Route any goal through zambo_universal (the main entry point)."""
+        args: Dict[str, Any] = {"goal": goal}
+        if session:
+            args["session"] = session
+        return self.call("zambo_universal", args)
+
+
+def get_receipt(receipt_id: str) -> Dict[str, Any]:
+    """Fetch the full receipt JSON for a receipt id."""
+    return _get_json(ZAMBO_RECEIPT_API.format(receipt_id=receipt_id))
+
+
+def verify_receipt(receipt_id: str) -> Verification:
+    """Verify a Zambo receipt client-side.
+
+    Checks:
+    - the receipt exists and the server marks it ``verified``
+    - sha256 of the canonical bytes matches the claimed ``output_hash``
+      (recomputed locally — the server cannot fake this)
+    - an anchor record is present
+    """
+    receipt = get_receipt(receipt_id)
+    checks: Dict[str, bool] = {}
+
+    checks["exists"] = bool(receipt.get("id"))
+    checks["server_marks_verified"] = receipt.get("verification_status") == "verified"
+
+    claimed = receipt.get("output_hash", "")
+    canonical_b64 = receipt.get("canonical_bytes", "")
+    try:
+        digest = "sha256:" + hashlib.sha256(base64.b64decode(canonical_b64)).hexdigest()
+        checks["output_hash_matches"] = bool(claimed) and digest == claimed
+    except Exception:
+        checks["output_hash_matches"] = False
+
+    checks["anchor_present"] = bool((receipt.get("anchor") or {}).get("event_id"))
+
+    verified = all(checks.values())
+    return Verification(
+        receipt_id=receipt_id,
+        verified=verified,
+        checks=checks,
+        audit_url=ZAMBO_AUDIT_URL.format(receipt_id=receipt_id),
+        receipt=receipt,
+    )

zambo_sdk-0.1.0/src/zambo_sdk.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: zambo-sdk
+Version: 0.1.0
+Summary: Zambo Python client — 100+ MCP tools, verifiable receipt for every call, no API key
+Author: Brennan Zambo
+License: MIT
+Project-URL: Homepage, https://zambo.dev
+Project-URL: Documentation, https://zambo.dev/docs
+Keywords: zambo,mcp,ai-tools,agents,receipts
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# zambo-sdk
+
+Thin Python client for [Zambo](https://zambo.dev) — the trust layer for AI work. 100+ native MCP tools, a verifiable receipt for every call. Free 20 calls/tool/day, no account, no API key. Zero dependencies.
+
+> **Name note:** the distribution name is pending final pick (`zambo-sdk`, `zambo-dev`, `zambo-api`, `pyzambo`, `zambodotdev`, `zambopy` are all free on PyPI). The import package is `zambo_sdk` regardless.
+
+## Install
+
+```bash
+pip install zambo-sdk
+```
+
+## Quickstart
+
+```python
+from zambo_sdk import Client, verify_receipt
+
+z = Client()
+
+# 1. Call a tool — plain JSON-RPC, no API key
+result = z.call("live_price", {"symbol": "BTC"})
+print(result.text)
+print("receipt:", result.receipt_id)
+print("audit:  ", result.audit_url)
+
+# 2. Route any goal through the universal entry point
+job = z.universal("audit https://example.com for AI discoverability", session="demo-1")
+print(job.text)
+
+# 3. Search the full 100+ tool catalog
+found = z.search("generate QR code")
+print(found.text)
+
+# 4. Verify a receipt client-side (recomputes the sha256 locally)
+v = verify_receipt(result.receipt_id)
+print("verified:", v.verified, v.checks)
+```
+
+## API
+
+- `Client().call(tool, arguments)` → `CallResult` (`.text`, `.receipt_id`, `.audit_url`, `.receipt`)
+- `Client().list_tools()` → list of tool descriptors
+- `Client().search(query)` → search the full catalog via `capability_search`
+- `Client().universal(goal, session=None)` → multi-step jobs via `zambo_universal`
+- `get_receipt(receipt_id)` → full receipt JSON
+- `verify_receipt(receipt_id)` → `Verification` (`.verified`, `.checks`, `.audit_url`)
+
+`verify_receipt` checks three things: the receipt exists, the server marks it `verified`, and — recomputed locally so the server can't fake it — `sha256(canonical_bytes) == output_hash`, plus the presence of the anchor record.
+
+## Notes
+
+- Endpoint: `https://zambo.dev/api/mcp` (JSON-RPC 2.0 over HTTPS, `streamable_http`-compatible).
+- Receipts: `https://zambo.dev/api/receipt/<uuid>` (JSON), audit page `https://zambo.dev/run/<uuid>`.
+- Need more than 20 calls/tool/day? The $1.49/24h Day Pass is at [zambo.dev](https://zambo.dev).

zambo_sdk-0.1.0/src/zambo_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+src/zambo_sdk/__init__.py
+src/zambo_sdk/client.py
+src/zambo_sdk.egg-info/PKG-INFO
+src/zambo_sdk.egg-info/SOURCES.txt
+src/zambo_sdk.egg-info/dependency_links.txt
+src/zambo_sdk.egg-info/top_level.txt

zambo_sdk-0.1.0/src/zambo_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zambo_sdk-0.1.0/src/zambo_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+zambo_sdk