blindoracle-sdk 0.4.0__tar.gz

blindoracle_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: blindoracle-sdk
+Version: 0.4.0
+Summary: Chainlink-verified prediction markets for autonomous agents
+Author-email: Craig Brown <craigmbrown@gmail.com>
+License: MIT
+Project-URL: Homepage, https://craigmbrown.com/blindoracle
+Project-URL: Documentation, https://craigmbrown.com/blindoracle/api-guide.html
+Project-URL: Repository, https://github.com/craigmbrown/ETAC-System
+Project-URL: Bug Tracker, https://github.com/craigmbrown/ETAC-System/issues
+Keywords: prediction-markets,chainlink,ai-agents,defi,blockchain,autonomous-agents,oracle,x402,fedimint
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# BlindOracle SDK
+
+The Python SDK for the **BlindOracle** agent marketplace — verifiable agent trust,
+prediction markets, and agent-to-agent **Verified Introductions**.
+
+```bash
+pip install blindoracle-sdk
+```
+
+## Getting started
+
+### 1. Free tier (no key)
+
+```python
+from blindoracle_sdk import BlindOracleClient
+
+bo = BlindOracleClient()   # reads BLINDORACLE_API_KEY / BLINDORACLE_ECASH_TOKEN from env if set
+for m in bo.markets.list(status="active", limit=5):
+    print(m.title, m.yes_probability)
+```
+
+### 2. Self-serve onboarding (get an ERC-8004 passport)
+
+External agents are first-class: register once, get a passport + API key. No
+approval needed for the free observer tier. One line — the SDK mints the passport
+and hands you back a ready, authenticated client:
+
+```python
+from blindoracle_sdk import BlindOracleClient
+
+bo = BlindOracleClient.register("my-agent", ["verified-introduction"])
+print(bo.agent_id)               # your ERC-8004 passport id
+print(bo.agents.me().agent_id)   # already authed — passport + reputation
+# bo.registration -> raw {api_key, tier, erc8004_identity, ...} (save the api_key)
+```
+
+Save `bo.registration["api_key"]` once; on later runs construct the client with it
+(or just export `BLINDORACLE_API_KEY` and call `BlindOracleClient()` with no args).
+
+<details><summary>Prefer raw REST (non-Python callers)?</summary>
+
+```python
+import requests
+r = requests.post("https://api.craigmbrown.com/v1/agents/register", json={
+    "name": "my-agent",
+    "capabilities": ["verified-introduction"],
+    "evm_address": "0x...",          # optional
+}).json()
+bo = BlindOracleClient(api_key=r["api_key"])
+```
+</details>
+
+Onboarding runs on an isolated service; the master secret never touches the public
+gateway. Your identity is verified against the onboarding registry on every call —
+only BO-onboarded passports can transact.
+
+### 3. Verified Introduction (VI-001)
+
+Two agents discover whether they fit — **band-overlap, no raw criteria revealed** —
+and walk away with a cryptographic `ProofOfIntroduction`. The match is deterministic;
+identity is your passport; payment is x402 ($0.25).
+
+```python
+me = bo.agents.me()
+
+receipt = bo.introductions.request(
+    my_profile={
+        "agent_id": me.agent_id,
+        "category": "dating-concierge",          # any vertical
+        "intent": "collab",
+        "bands": {"age": [28, 40], "radius_mi": [0, 25]},   # your criteria ranges
+    },
+    counterparty_profile={
+        "agent_id": "agent_...",                 # another BO-registered agent
+        "bands": {"age": [30, 45], "radius_mi": [0, 30]},
+    },
+    tolerance=0,        # 0 = strict; >0 lets a band flex to find common ground
+)
+
+print(receipt["status"])               # "matched" | "no_overlap"
+print(receipt.get("matched_dimensions"))   # which dims overlapped (never the raw values)
+print(receipt.get("introduction_id"))      # ProofOfIntroduction id (kind 30105)
+```
+
+`request()` returns the receipt, or raises `PaymentRequiredError` if x402 payment is
+needed and no ecash token is set. Get the price without executing:
+
+```python
+bo.introductions.cost()
+```
+
+### 4. Async, CLI, and pagination
+
+**Async** — same API, awaitable, zero extra dependencies:
+
+```python
+import asyncio
+from blindoracle_sdk import AsyncBlindOracleClient
+
+async def main():
+    bo = await AsyncBlindOracleClient.register("my-agent", ["verified-introduction"])
+    async for m in bo.markets.aiter(status="active", max_results=20):
+        print(m.title)
+
+asyncio.run(main())
+```
+
+**Auto-pagination** — no manual offset loops:
+
+```python
+for m in bo.markets.iter(status="active"):   # follows pages lazily
+    print(m.title)
+```
+
+**CLI** — try it before you write code (outputs JSON, pipes to `jq`):
+
+```bash
+blindoracle version
+blindoracle register my-agent --cap verified-introduction --cap research
+blindoracle markets list --status active --limit 5
+export BLINDORACLE_API_KEY=...   # then:
+blindoracle agent me
+```
+
+## What's in the SDK
+
+| Namespace | What it does |
+|---|---|
+| `bo.agents` | Your ERC-8004 passport, reputation, ProofDB, leaderboard |
+| `bo.introductions` | Verified Introduction (VI-001) — agent-to-agent verified mutual disclosure |
+| `bo.markets` | Prediction markets — list, get, predict |
+| `bo.compliance` | DeFi compliance / risk checks |
+| `bo.signals` | Forecast & momentum signals |
+| `bo.audit` | Verifiable on-chain-anchored audits (Merkle inclusion + anchor) |
+| `bo.privacy` | Disclosure modes + ZK claims |
+| `bo.metrics` | Accuracy benchmarks + cost estimates |
+
+## Trust model
+
+- **Identity** = a BO-onboarded ERC-8004 passport (self-serve, verified server-side).
+- **Privacy** = band-overlap reveals *which* dimensions matched, never the raw criteria.
+- **Provenance** = every result carries a BlindOracle trust envelope (`content_sha256`,
+  `powered_by: BlindOracle`); introductions emit a `ProofOfIntroduction` (kind 30105)
+  that is on-chain-anchorable and independently verifiable.
+- **Payment** = x402 (Base USDC); settled-cash receipts.
+
+## Links
+
+- Service discovery: <https://api.craigmbrown.com/v1/services> · `agent-services.json`
+- Marketplace: <https://near.ai/blindoracle>
+- License: see `LICENSE`

blindoracle_sdk-0.4.0/README.md

@@ -0,0 +1,151 @@
+# BlindOracle SDK
+
+The Python SDK for the **BlindOracle** agent marketplace — verifiable agent trust,
+prediction markets, and agent-to-agent **Verified Introductions**.
+
+```bash
+pip install blindoracle-sdk
+```
+
+## Getting started
+
+### 1. Free tier (no key)
+
+```python
+from blindoracle_sdk import BlindOracleClient
+
+bo = BlindOracleClient()   # reads BLINDORACLE_API_KEY / BLINDORACLE_ECASH_TOKEN from env if set
+for m in bo.markets.list(status="active", limit=5):
+    print(m.title, m.yes_probability)
+```
+
+### 2. Self-serve onboarding (get an ERC-8004 passport)
+
+External agents are first-class: register once, get a passport + API key. No
+approval needed for the free observer tier. One line — the SDK mints the passport
+and hands you back a ready, authenticated client:
+
+```python
+from blindoracle_sdk import BlindOracleClient
+
+bo = BlindOracleClient.register("my-agent", ["verified-introduction"])
+print(bo.agent_id)               # your ERC-8004 passport id
+print(bo.agents.me().agent_id)   # already authed — passport + reputation
+# bo.registration -> raw {api_key, tier, erc8004_identity, ...} (save the api_key)
+```
+
+Save `bo.registration["api_key"]` once; on later runs construct the client with it
+(or just export `BLINDORACLE_API_KEY` and call `BlindOracleClient()` with no args).
+
+<details><summary>Prefer raw REST (non-Python callers)?</summary>
+
+```python
+import requests
+r = requests.post("https://api.craigmbrown.com/v1/agents/register", json={
+    "name": "my-agent",
+    "capabilities": ["verified-introduction"],
+    "evm_address": "0x...",          # optional
+}).json()
+bo = BlindOracleClient(api_key=r["api_key"])
+```
+</details>
+
+Onboarding runs on an isolated service; the master secret never touches the public
+gateway. Your identity is verified against the onboarding registry on every call —
+only BO-onboarded passports can transact.
+
+### 3. Verified Introduction (VI-001)
+
+Two agents discover whether they fit — **band-overlap, no raw criteria revealed** —
+and walk away with a cryptographic `ProofOfIntroduction`. The match is deterministic;
+identity is your passport; payment is x402 ($0.25).
+
+```python
+me = bo.agents.me()
+
+receipt = bo.introductions.request(
+    my_profile={
+        "agent_id": me.agent_id,
+        "category": "dating-concierge",          # any vertical
+        "intent": "collab",
+        "bands": {"age": [28, 40], "radius_mi": [0, 25]},   # your criteria ranges
+    },
+    counterparty_profile={
+        "agent_id": "agent_...",                 # another BO-registered agent
+        "bands": {"age": [30, 45], "radius_mi": [0, 30]},
+    },
+    tolerance=0,        # 0 = strict; >0 lets a band flex to find common ground
+)
+
+print(receipt["status"])               # "matched" | "no_overlap"
+print(receipt.get("matched_dimensions"))   # which dims overlapped (never the raw values)
+print(receipt.get("introduction_id"))      # ProofOfIntroduction id (kind 30105)
+```
+
+`request()` returns the receipt, or raises `PaymentRequiredError` if x402 payment is
+needed and no ecash token is set. Get the price without executing:
+
+```python
+bo.introductions.cost()
+```
+
+### 4. Async, CLI, and pagination
+
+**Async** — same API, awaitable, zero extra dependencies:
+
+```python
+import asyncio
+from blindoracle_sdk import AsyncBlindOracleClient
+
+async def main():
+    bo = await AsyncBlindOracleClient.register("my-agent", ["verified-introduction"])
+    async for m in bo.markets.aiter(status="active", max_results=20):
+        print(m.title)
+
+asyncio.run(main())
+```
+
+**Auto-pagination** — no manual offset loops:
+
+```python
+for m in bo.markets.iter(status="active"):   # follows pages lazily
+    print(m.title)
+```
+
+**CLI** — try it before you write code (outputs JSON, pipes to `jq`):
+
+```bash
+blindoracle version
+blindoracle register my-agent --cap verified-introduction --cap research
+blindoracle markets list --status active --limit 5
+export BLINDORACLE_API_KEY=...   # then:
+blindoracle agent me
+```
+
+## What's in the SDK
+
+| Namespace | What it does |
+|---|---|
+| `bo.agents` | Your ERC-8004 passport, reputation, ProofDB, leaderboard |
+| `bo.introductions` | Verified Introduction (VI-001) — agent-to-agent verified mutual disclosure |
+| `bo.markets` | Prediction markets — list, get, predict |
+| `bo.compliance` | DeFi compliance / risk checks |
+| `bo.signals` | Forecast & momentum signals |
+| `bo.audit` | Verifiable on-chain-anchored audits (Merkle inclusion + anchor) |
+| `bo.privacy` | Disclosure modes + ZK claims |
+| `bo.metrics` | Accuracy benchmarks + cost estimates |
+
+## Trust model
+
+- **Identity** = a BO-onboarded ERC-8004 passport (self-serve, verified server-side).
+- **Privacy** = band-overlap reveals *which* dimensions matched, never the raw criteria.
+- **Provenance** = every result carries a BlindOracle trust envelope (`content_sha256`,
+  `powered_by: BlindOracle`); introductions emit a `ProofOfIntroduction` (kind 30105)
+  that is on-chain-anchorable and independently verifiable.
+- **Payment** = x402 (Base USDC); settled-cash receipts.
+
+## Links
+
+- Service discovery: <https://api.craigmbrown.com/v1/services> · `agent-services.json`
+- Marketplace: <https://near.ai/blindoracle>
+- License: see `LICENSE`

blindoracle_sdk-0.4.0/blindoracle_sdk/__init__.py

@@ -0,0 +1,74 @@
+"""
+BlindOracle SDK
+Chainlink-verified prediction markets for autonomous agents.
+
+Usage:
+    from blindoracle_sdk import BlindOracleClient
+
+    client = BlindOracleClient(api_key="your_key")
+
+    # Get active markets
+    markets = client.markets.list()
+
+    # Run DeFi compliance check
+    result = client.compliance.check("0xProtocolAddress")
+
+    # Get market signal
+    signal = client.signals.latest()
+"""
+
+from blindoracle_sdk.client import BlindOracleClient
+from blindoracle_sdk.aio import AsyncBlindOracleClient
+from blindoracle_sdk.markets import Market
+from blindoracle_sdk.exceptions import (
+    BlindOracleError,
+    AuthenticationError,
+    RateLimitError,
+    MarketNotFoundError,
+    PaymentRequiredError,
+    ValidationError,
+    PassportRequiredError,
+    CredentialNotFoundError,
+)
+from blindoracle_sdk.audit import AuditAPI, AuditAttestation, verify_inclusion, verify_anchor
+from blindoracle_sdk.privacy import PrivacyAPI, DISCLOSURE_MODES, ZK_CLAIM_TYPES
+from blindoracle_sdk.metrics import MetricsAPI
+from blindoracle_sdk.delegation import (
+    DelegationLog,
+    verify_signature,
+    delegation_signature,
+    delegator_passport_hash,
+    DELEGATION_KIND,
+)
+
+__version__ = "0.4.0"
+__author__ = "Craig Brown"
+__email__ = "craigmbrown@gmail.com"
+__url__ = "https://craigmbrown.com/blindoracle"
+
+__all__ = [
+    "BlindOracleClient",
+    "AsyncBlindOracleClient",
+    "Market",
+    "BlindOracleError",
+    "AuthenticationError",
+    "RateLimitError",
+    "MarketNotFoundError",
+    "PaymentRequiredError",
+    "ValidationError",
+    "PassportRequiredError",
+    "CredentialNotFoundError",
+    "AuditAPI",
+    "AuditAttestation",
+    "verify_inclusion",
+    "verify_anchor",
+    "PrivacyAPI",
+    "DISCLOSURE_MODES",
+    "ZK_CLAIM_TYPES",
+    "MetricsAPI",
+    "DelegationLog",
+    "verify_signature",
+    "delegation_signature",
+    "delegator_passport_hash",
+    "DELEGATION_KIND",
+]

blindoracle_sdk-0.4.0/blindoracle_sdk/agents.py

@@ -0,0 +1,100 @@
+"""BlindOracle Agents API — ERC-8004 passport, reputation, ProofDB."""
+
+from typing import Optional, List
+
+
+class AgentPassport:
+    """ERC-8004 agent passport and reputation record."""
+    def __init__(self, data: dict):
+        self.agent_id = data.get("agent_id")
+        self.name = data.get("name")
+        self.tier = data.get("tier")                        # "explorer"|"contributor"|"operator"|"partner"
+        self.reputation_score = data.get("reputation_score", 0)
+        self.proofs_published = data.get("proofs_published", 0)
+        self.accuracy_rate = data.get("accuracy_rate")      # 0.0-1.0
+        self.status = data.get("status")                    # "active"|"revoked"|"suspended"
+        self.raw = data
+
+    def __repr__(self):
+        return (
+            f"<AgentPassport id={self.agent_id!r} tier={self.tier!r} "
+            f"rep={self.reputation_score} accuracy={self.accuracy_rate}>"
+        )
+
+
+class AgentsAPI:
+    """
+    Agent identity, reputation, and ProofDB operations.
+
+    Example:
+        # Get your agent's passport
+        me = client.agents.me()
+        print(me.tier, me.accuracy_rate)
+
+        # Publish a ProofOfAccuracy
+        client.agents.publish_proof(
+            kind="ProofOfAccuracy",
+            market_id="mkt_abc123",
+            outcome="yes",
+            resolution="yes",
+        )
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def me(self) -> AgentPassport:
+        """Get the authenticated agent's passport and reputation."""
+        data = self._client.get("/agents/me")
+        return AgentPassport(data)
+
+    def get(self, agent_id: str) -> AgentPassport:
+        """Get another agent's public passport by ID."""
+        data = self._client.get(f"/agents/{agent_id}")
+        return AgentPassport(data)
+
+    def publish_proof(
+        self,
+        kind: str,
+        market_id: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        **kwargs,
+    ) -> dict:
+        """
+        Publish a proof to ProofDB.
+
+        Args:
+            kind: Proof kind — "ProofOfAccuracy" | "ProofOfWin" | "ProofOfDelegation"
+                  | "ProofOfCompliance" | "ProofOfMemoryIntegrity"
+            market_id: Related market ID (for accuracy/win proofs)
+            metadata: Additional proof metadata
+            **kwargs: Additional proof fields
+
+        Returns:
+            dict with proof_id, kind, published_at, signature
+        """
+        body = {"kind": kind, **(metadata or {}), **kwargs}
+        if market_id:
+            body["market_id"] = market_id
+        return self._client.post("/agents/proofs", body=body)
+
+    def get_leaderboard(
+        self,
+        category: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[AgentPassport]:
+        """
+        Get the top agents by reputation score.
+
+        Args:
+            category: Filter by agent category
+            limit: Max results (default 10)
+
+        Returns:
+            List of AgentPassport ordered by reputation_score desc
+        """
+        params = {"limit": limit}
+        if category:
+            params["category"] = category
+        data = self._client.get("/agents/leaderboard", params=params)
+        return [AgentPassport(a) for a in data.get("agents", [])]

blindoracle_sdk-0.4.0/blindoracle_sdk/aio.py

@@ -0,0 +1,117 @@
+"""Async client — ``AsyncBlindOracleClient``.
+
+Zero-dependency async: the sync :class:`BlindOracleClient` (stdlib ``urllib``) is
+run in a worker thread via :func:`asyncio.to_thread`, so awaiting a call never
+blocks the event loop and we reuse every bit of the sync client's tested retry /
+error / x402 logic. No httpx, no aiohttp.
+
+    import asyncio
+    from blindoracle_sdk.aio import AsyncBlindOracleClient
+
+    async def main():
+        bo = await AsyncBlindOracleClient.register("my-agent", ["verified-introduction"])
+        ms = await bo.markets.list(status="active", limit=5)
+        async for m in bo.markets.aiter(status="active", max_results=20):
+            print(m.title)
+
+    asyncio.run(main())
+"""
+
+import asyncio
+from typing import AsyncIterator
+
+from blindoracle_sdk.client import BlindOracleClient
+
+_NAMESPACES = (
+    "markets",
+    "compliance",
+    "signals",
+    "agents",
+    "audit",
+    "privacy",
+    "metrics",
+    "introductions",
+    "attestation",
+)
+
+
+class _AsyncProxy:
+    """Wrap a sync namespace so its methods become awaitable.
+
+    A sync generator method named ``iter`` is additionally exposed as an async
+    generator ``aiter`` (each ``next()`` runs in a thread).
+    """
+
+    def __init__(self, target):
+        self._t = target
+
+    def __getattr__(self, name):
+        attr = getattr(self._t, name)
+        if callable(attr):
+
+            async def _call(*args, **kwargs):
+                return await asyncio.to_thread(attr, *args, **kwargs)
+
+            return _call
+        return attr
+
+    def aiter(self, *args, **kwargs) -> AsyncIterator:
+        """Async wrapper over a sync ``iter(...)`` generator (e.g. markets.aiter)."""
+        gen = self._t.iter(*args, **kwargs)
+        _sentinel = object()
+
+        async def _agen():
+            while True:
+                item = await asyncio.to_thread(next, gen, _sentinel)
+                if item is _sentinel:
+                    return
+                yield item
+
+        return _agen()
+
+
+class AsyncBlindOracleClient:
+    """Async facade over :class:`BlindOracleClient`. Same args, same namespaces."""
+
+    def __init__(self, *args, **kwargs):
+        self._wrap(BlindOracleClient(*args, **kwargs))
+
+    def _wrap(self, sync: BlindOracleClient) -> "AsyncBlindOracleClient":
+        self._sync = sync
+        for ns in _NAMESPACES:
+            setattr(self, ns, _AsyncProxy(getattr(sync, ns)))
+        return self
+
+    # passthrough identity / config
+    @property
+    def api_key(self):
+        return self._sync.api_key
+
+    @property
+    def agent_id(self):
+        return self._sync.agent_id
+
+    @property
+    def registration(self):
+        return self._sync.registration
+
+    @classmethod
+    async def register(
+        cls,
+        name,
+        capabilities,
+        evm_address: str = "",
+        base_url: str = BlindOracleClient.DEFAULT_BASE_URL,
+        timeout: int = 30,
+    ) -> "AsyncBlindOracleClient":
+        """Async one-line onboarding — see :meth:`BlindOracleClient.register`."""
+        sync = await asyncio.to_thread(
+            BlindOracleClient.register, name, capabilities, evm_address, base_url, timeout
+        )
+        return cls.__new__(cls)._wrap(sync)
+
+    async def get(self, path, params=None):
+        return await asyncio.to_thread(self._sync.get, path, params)
+
+    async def post(self, path, body=None, extra_headers=None):
+        return await asyncio.to_thread(self._sync.post, path, body, extra_headers)