forcedream 0.1.0__tar.gz

forcedream-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForceDream Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forcedream-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: forcedream
+Version: 0.1.0
+Summary: Official Python SDK for ForceDream -- discover, invoke, and cryptographically verify AI agents.
+Author: ForceDream
+License-Expression: MIT
+Project-URL: Homepage, https://forcedream.ai
+Project-URL: Repository, https://github.com/forcedreamai/forcedream-sdk-python
+Keywords: forcedream,ai-agents,sdk,cryptographic-proof,ed25519,agent-marketplace
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: cryptography>=42.0.0
+Dynamic: license-file
+
+# forcedream
+
+[![PyPI version](https://img.shields.io/pypi/v/forcedream.svg)](https://pypi.org/project/forcedream/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Python >=3.9](https://img.shields.io/badge/python-%3E%3D3.9-brightgreen.svg)](https://python.org)
+
+Official Python SDK for [ForceDream](https://forcedream.ai) — discover, invoke, and cryptographically verify AI agents.
+
+## Honest scope
+
+This SDK currently wraps five real, verified endpoints: signup, balance, agent discovery, agent invocation, and proof verification. It does not yet cover the full ForceDream platform (withdrawals, marketplace publishing, organizations, and more). Each method is real and tested against the live API — nothing here is a stub. If you need something not listed, use the [REST API](https://forcedream.ai/mcp) or [MCP server](https://github.com/forcedreamai/forcedream-mcp) directly.
+
+## Install
+
+```bash
+pip install forcedream
+```
+
+## Quick start
+
+```python
+import asyncio
+from forcedream import ForceDream
+
+async def main():
+    # New to ForceDream? Sign up — no key needed, get a real trial balance.
+    account = await ForceDream.signup(email="you@example.com")
+    print(account["live_key"])  # save this
+
+    fd = ForceDream(api_key=account["live_key"])
+
+    # Discover real agents — no key needed for this call either
+    search = await fd.search_agents(query="data-extract")
+
+    # Invoke one to do real work — spends your balance, polls until complete
+    result = await fd.invoke("data-extract-v1", "Extract the year from: founded in 1998")
+    print(result["output"], result["charged_pence"])
+
+    # Verify the proof entirely client-side — ForceDream is never asked if it's valid
+    verified = await fd.verify(task_id=result["task_id"])
+    print(verified["verified"])  # True
+
+asyncio.run(main())
+```
+
+## API
+
+All methods are async (`await`-based), using [httpx](https://www.python-httpx.org/) under the hood.
+
+### `ForceDream.signup(email, marketing_consent=False)` (static)
+
+Create a new account. No API key required. `marketing_consent` defaults to `False` — explicit opt-in only.
+
+### `ForceDream(api_key=None, api_base="https://api.forcedream.ai")`
+
+```python
+fd = ForceDream(api_key="fd_live_...")  # required for get_balance() and invoke()
+```
+
+### `fd.search_agents(capability=None, query=None)`
+
+Discover agents and their honest, system-derived metrics. No key needed.
+
+### `fd.invoke(agent_slug, task, max_wait_seconds=None)`
+
+Invoke a real agent. Spends your balance. Invokes once, then polls (bounded by `max_wait_seconds`, default 60, max 120) for the result — never re-invokes on timeout, since that would double-charge. On timeout, returns `status: "pending"` with a `task_id` you can check again later.
+
+### `fd.verify(task_id=None, proof=None)`
+
+Trustlessly verify a proof's Ed25519 signature, entirely client-side.
+
+### `fd.get_balance()`
+
+Real, current account balance. Requires an API key.
+
+## Ported, and cross-language tested — not rewritten
+
+The proof-verification, agent-search, and agent-invocation logic in this SDK are ported directly from [`@forcedream/mcp-server`](https://github.com/forcedreamai/forcedream-mcp)'s own already-tested TypeScript source — not fresh reimplementations. Porting cryptographic and canonicalization logic across languages carries real risk (subtle formatting differences silently break every signature check), so before this package was written, the canonicalization function and the Ed25519 verification mechanics were each cross-tested byte-for-byte and hash-for-hash against the real JavaScript implementation, including a real signature generated by Node's `node:crypto` and independently verified as valid in Python — not assumed to match.
+
+This also carries over real, load-bearing details you'd otherwise have to discover the hard way: `/v1/agents/list` has no working server-side capability filter (filtering happens client-side here), and `invoke()` uses the same specific polling interval ramp (2500ms, +1000ms per attempt, capped at 6000ms) and never re-invokes on timeout.
+
+## Links
+
+- Main platform: https://forcedream.ai
+- MCP server: https://github.com/forcedreamai/forcedream-mcp
+- JavaScript/TypeScript SDK: https://github.com/forcedreamai/forcedream-sdk-js
+- Verify a proof in your browser: https://forcedream.ai/proof
+
+## License
+
+MIT

forcedream-0.1.0/README.md

@@ -0,0 +1,91 @@
+# forcedream
+
+[![PyPI version](https://img.shields.io/pypi/v/forcedream.svg)](https://pypi.org/project/forcedream/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Python >=3.9](https://img.shields.io/badge/python-%3E%3D3.9-brightgreen.svg)](https://python.org)
+
+Official Python SDK for [ForceDream](https://forcedream.ai) — discover, invoke, and cryptographically verify AI agents.
+
+## Honest scope
+
+This SDK currently wraps five real, verified endpoints: signup, balance, agent discovery, agent invocation, and proof verification. It does not yet cover the full ForceDream platform (withdrawals, marketplace publishing, organizations, and more). Each method is real and tested against the live API — nothing here is a stub. If you need something not listed, use the [REST API](https://forcedream.ai/mcp) or [MCP server](https://github.com/forcedreamai/forcedream-mcp) directly.
+
+## Install
+
+```bash
+pip install forcedream
+```
+
+## Quick start
+
+```python
+import asyncio
+from forcedream import ForceDream
+
+async def main():
+    # New to ForceDream? Sign up — no key needed, get a real trial balance.
+    account = await ForceDream.signup(email="you@example.com")
+    print(account["live_key"])  # save this
+
+    fd = ForceDream(api_key=account["live_key"])
+
+    # Discover real agents — no key needed for this call either
+    search = await fd.search_agents(query="data-extract")
+
+    # Invoke one to do real work — spends your balance, polls until complete
+    result = await fd.invoke("data-extract-v1", "Extract the year from: founded in 1998")
+    print(result["output"], result["charged_pence"])
+
+    # Verify the proof entirely client-side — ForceDream is never asked if it's valid
+    verified = await fd.verify(task_id=result["task_id"])
+    print(verified["verified"])  # True
+
+asyncio.run(main())
+```
+
+## API
+
+All methods are async (`await`-based), using [httpx](https://www.python-httpx.org/) under the hood.
+
+### `ForceDream.signup(email, marketing_consent=False)` (static)
+
+Create a new account. No API key required. `marketing_consent` defaults to `False` — explicit opt-in only.
+
+### `ForceDream(api_key=None, api_base="https://api.forcedream.ai")`
+
+```python
+fd = ForceDream(api_key="fd_live_...")  # required for get_balance() and invoke()
+```
+
+### `fd.search_agents(capability=None, query=None)`
+
+Discover agents and their honest, system-derived metrics. No key needed.
+
+### `fd.invoke(agent_slug, task, max_wait_seconds=None)`
+
+Invoke a real agent. Spends your balance. Invokes once, then polls (bounded by `max_wait_seconds`, default 60, max 120) for the result — never re-invokes on timeout, since that would double-charge. On timeout, returns `status: "pending"` with a `task_id` you can check again later.
+
+### `fd.verify(task_id=None, proof=None)`
+
+Trustlessly verify a proof's Ed25519 signature, entirely client-side.
+
+### `fd.get_balance()`
+
+Real, current account balance. Requires an API key.
+
+## Ported, and cross-language tested — not rewritten
+
+The proof-verification, agent-search, and agent-invocation logic in this SDK are ported directly from [`@forcedream/mcp-server`](https://github.com/forcedreamai/forcedream-mcp)'s own already-tested TypeScript source — not fresh reimplementations. Porting cryptographic and canonicalization logic across languages carries real risk (subtle formatting differences silently break every signature check), so before this package was written, the canonicalization function and the Ed25519 verification mechanics were each cross-tested byte-for-byte and hash-for-hash against the real JavaScript implementation, including a real signature generated by Node's `node:crypto` and independently verified as valid in Python — not assumed to match.
+
+This also carries over real, load-bearing details you'd otherwise have to discover the hard way: `/v1/agents/list` has no working server-side capability filter (filtering happens client-side here), and `invoke()` uses the same specific polling interval ramp (2500ms, +1000ms per attempt, capped at 6000ms) and never re-invokes on timeout.
+
+## Links
+
+- Main platform: https://forcedream.ai
+- MCP server: https://github.com/forcedreamai/forcedream-mcp
+- JavaScript/TypeScript SDK: https://github.com/forcedreamai/forcedream-sdk-js
+- Verify a proof in your browser: https://forcedream.ai/proof
+
+## License
+
+MIT

forcedream-0.1.0/forcedream/__init__.py

@@ -0,0 +1,78 @@
+"""ForceDream Python SDK -- a real, honestly-scoped client for the ForceDream API.
+
+Wraps only endpoints verified working directly against the live, production API: signup,
+balance, agent discovery, agent invocation, and proof verification. Does not yet cover the
+full platform surface (withdrawals, marketplace publishing, organizations, and more).
+"""
+from typing import Optional
+import httpx
+
+from .verify import verify_proof, FdProof, VerifyResult
+from .agents import search_agents, SearchAgentsResult
+from .invoke import invoke_agent, InvokeResult
+
+__all__ = [
+    'ForceDream', 'FdProof', 'VerifyResult', 'SearchAgentsResult', 'InvokeResult',
+]
+
+DEFAULT_API_BASE = 'https://api.forcedream.ai'
+
+
+class ForceDream:
+    def __init__(self, api_key: Optional[str] = None, api_base: str = DEFAULT_API_BASE):
+        self.api_key = api_key
+        self.api_base = api_base
+
+    @staticmethod
+    async def signup(
+        email: str,
+        marketing_consent: bool = False,
+        api_base: str = DEFAULT_API_BASE,
+    ) -> dict:
+        """Create a new ForceDream account. No API key needed -- this is how you get one.
+        Returns a real fd_live_ billing key with a small, real trial balance already seeded."""
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            res = await client.post(
+                f'{api_base}/api/signup',
+                json={'email': email, 'marketing_consent': marketing_consent},
+            )
+            res.raise_for_status()
+            return res.json()
+
+    async def get_balance(self) -> dict:
+        """Real, current account balance. Requires an API key."""
+        if not self.api_key:
+            raise ValueError('get_balance() requires an api_key')
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            res = await client.get(
+                f'{self.api_base}/v1/account/balance',
+                headers={'Authorization': f'Bearer {self.api_key}'},
+            )
+            res.raise_for_status()
+            return res.json()
+
+    async def search_agents(
+        self, capability: Optional[str] = None, query: Optional[str] = None,
+    ) -> SearchAgentsResult:
+        """Discover real ForceDream agents and their honest, system-derived metrics. No key
+        needed. Filtering happens client-side (the server has no working server-side filter)."""
+        return await search_agents(self.api_base, capability=capability, query=query)
+
+    async def invoke(
+        self, agent_slug: str, task: str, max_wait_seconds: Optional[float] = None,
+    ) -> InvokeResult:
+        """Invoke a real ForceDream agent to do real work. Spends your balance -- requires
+        an API key. Invokes once, then polls (bounded) for the result -- never re-invokes
+        on timeout, which would double-charge. On timeout, returns status 'pending' with a
+        task_id you can poll again later."""
+        if not self.api_key:
+            raise ValueError('invoke() requires an api_key (it spends your balance)')
+        return await invoke_agent(self.api_base, self.api_key, agent_slug, task, max_wait_seconds)
+
+    async def verify(
+        self, task_id: Optional[str] = None, proof: Optional[FdProof] = None,
+    ) -> VerifyResult:
+        """Trustlessly verify a proof's Ed25519 signature, entirely client-side. ForceDream
+        is never asked whether the proof is valid -- the signature math decides, locally.
+        No API key needed."""
+        return await verify_proof(self.api_base, task_id=task_id, proof=proof)

forcedream-0.1.0/forcedream/agents.py

@@ -0,0 +1,90 @@
+"""Exact port of @forcedream/mcp-server's search_agents.ts.
+
+Real, load-bearing fact confirmed directly from the source, not assumed: the server has no
+working server-side capability/query filter on /v1/agents/list -- filtering happens
+client-side, after fetching the full list. This was a real bug caught in the JS SDK build
+(returned all 18 agents instead of the expected 1) before being fixed the same way here.
+"""
+from typing import Optional, TypedDict
+import httpx
+
+
+class AgentReliability(TypedDict, total=False):
+    success_rate: Optional[float]
+    avg_latency_ms: Optional[float]
+    sample_size: int
+    note: Optional[str]
+
+
+class Agent(TypedDict, total=False):
+    slug: str
+    name: str
+    description: str
+    version: str
+    capabilities: list[str]
+    price_per_call_pence: int
+    metrics: dict
+    health: Optional[AgentReliability]
+
+
+class SearchAgentsResult(TypedDict):
+    count: int
+    agents: list[Agent]
+    note: str
+
+
+async def search_agents(
+    api_base: str,
+    capability: Optional[str] = None,
+    query: Optional[str] = None,
+) -> SearchAgentsResult:
+    """Discovers real ForceDream agents, merges in real reliability data, and applies
+    client-side capability/query filters (the server has no working server-side filter)."""
+    async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+        list_res = await client.get(f'{api_base}/v1/agents/list')
+        list_res.raise_for_status()
+        data = list_res.json()
+
+        try:
+            rel_res = await client.get(f'{api_base}/v1/agents/reliability')
+            rel_data = rel_res.json() if rel_res.status_code == 200 else None
+        except httpx.HTTPError:
+            rel_data = None
+
+    agents: list[Agent] = data.get('agents') or []
+
+    reliability_by_slug: dict[str, AgentReliability] = {}
+    if rel_data and isinstance(rel_data.get('agents'), list):
+        for ra in rel_data['agents']:
+            slug = ra.get('agent_slug')
+            if slug:
+                reliability_by_slug[slug] = ra.get('reliability')
+
+    if capability:
+        cap = capability.lower()
+        agents = [a for a in agents if cap in [c.lower() for c in (a.get('capabilities') or [])]]
+
+    if query:
+        q = query.lower()
+        agents = [
+            a for a in agents
+            if q in a.get('slug', '').lower()
+            or q in (a.get('name') or '').lower()
+            or any(q in c.lower() for c in (a.get('capabilities') or []))
+        ]
+
+    enriched = [
+        {**a, 'health': reliability_by_slug.get(a.get('slug', ''))}
+        for a in agents
+    ]
+
+    return SearchAgentsResult(
+        count=len(enriched),
+        agents=enriched,
+        note=(
+            'No agents matched. The registry contains only real, registered agents with cryptographic proofs.'
+            if len(enriched) == 0 else
+            "Metrics are system-derived from proofs/ledger (proof_count, success_rate) -- never self-reported. "
+            "Health (success_rate, avg_latency_ms, sample_size) is honestly null where no real reliability data exists yet."
+        ),
+    )

forcedream-0.1.0/forcedream/canonical.py

@@ -0,0 +1,18 @@
+"""Exact port of @forcedream/mcp-server's canonical.ts wfCanonical function.
+
+Cross-verified byte-for-byte against the real JS implementation before this file was
+written, not assumed to match: json.dumps(obj, sort_keys=True, separators=(',', ':'))
+produces identical output to JS's JSON.stringify(obj, Object.keys(obj).sort()) for the
+real signable shapes this SDK constructs. Verified with matching SHA-256 hashes on a
+real test object, in both languages, side by side.
+"""
+import hashlib
+import json
+
+
+def wf_canonical(obj: dict) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(',', ':'))
+
+
+def sha256_hex(s: str) -> str:
+    return hashlib.sha256(s.encode('utf-8')).hexdigest()

forcedream-0.1.0/forcedream/invoke.py

@@ -0,0 +1,114 @@
+"""Exact port of @forcedream/mcp-server's invoke_agent.ts.
+
+Ported precisely: exact endpoints, exact polling interval ramp (starts 2500ms, +1000ms per
+attempt, capped at 6000ms), exact status handling, exact max-wait clamping (5-120s). Invokes
+ONCE; never re-invokes on timeout, since that would double-charge -- returns a pollable
+task_id instead. Not reconstructed from a description -- read directly from the real,
+working source file before writing this, the same discipline as the JS SDK port.
+"""
+import asyncio
+import time
+from typing import Optional, TypedDict
+import httpx
+
+
+class InvokeResult(TypedDict, total=False):
+    status: str  # 'completed' | 'insufficient' | 'pending' | 'error'
+    agent: str
+    task_id: Optional[str]
+    output: object
+    charged_pence: Optional[int]
+    proof_id: Optional[str]
+    error: Optional[str]
+    message: str
+
+
+async def invoke_agent(
+    api_base: str,
+    api_key: str,
+    agent_slug: str,
+    task: str,
+    max_wait_seconds: Optional[float] = None,
+) -> InvokeResult:
+    headers = {'Authorization': f'Bearer {api_key}'}
+    max_wait_s = max(5, min(120, max_wait_seconds if max_wait_seconds is not None else 60))
+    max_wait_ms = max_wait_s * 1000
+
+    async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+        inv_res = await client.post(
+            f'{api_base}/v1/agents/{agent_slug}/invoke',
+            headers=headers,
+            json={'task': task},
+        )
+        if inv_res.status_code == 401:
+            return InvokeResult(status='error', agent=agent_slug, message='Invalid API key (401).')
+
+        try:
+            inv_json = inv_res.json()
+        except Exception:
+            inv_json = {}
+
+        task_id = inv_json.get('task_id')
+        if not task_id:
+            err = inv_json.get('error') or inv_json.get('note') or 'no task_id'
+            return InvokeResult(
+                status='error', agent=agent_slug,
+                message=f'Invoke failed (HTTP {inv_res.status_code}): {err}',
+            )
+
+        start = time.monotonic()
+        interval_ms = 2500
+        while (time.monotonic() - start) * 1000 < max_wait_ms:
+            await asyncio.sleep(interval_ms / 1000)
+            poll_res = await client.get(
+                f'{api_base}/v1/agents/{agent_slug}/result/{task_id}',
+                headers=headers,
+            )
+            try:
+                d = poll_res.json()
+            except Exception:
+                d = {}
+            status = d.get('status') or d.get('outcome')
+
+            if status in ('completed', 'succeeded') or d.get('ok') is True:
+                output = d.get('output')
+                is_insufficient = d.get('outcome') == 'insufficient' or (
+                    isinstance(output, dict) and output.get('confidence') == 'insufficient'
+                )
+                if is_insufficient:
+                    return InvokeResult(
+                        status='insufficient', agent=agent_slug, task_id=task_id,
+                        output=output, charged_pence=0,
+                        message='Agent returned insufficient evidence and declined rather than fabricate. Charged nothing.',
+                    )
+                proof_id = d.get('proof_id') or task_id
+                return InvokeResult(
+                    status='completed', agent=agent_slug, task_id=task_id,
+                    output=output, charged_pence=d.get('charged_pence'), proof_id=proof_id,
+                    message=f"Completed. Charged {d.get('charged_pence')}p. Cryptographically proven (proof_id {proof_id}).",
+                )
+            if status == 'insufficient':
+                return InvokeResult(
+                    status='insufficient', agent=agent_slug, task_id=task_id,
+                    output=d.get('output'), charged_pence=0,
+                    message='Agent declined (insufficient evidence). Charged nothing.',
+                )
+            if status == 'charge_failed':
+                reason = d.get('reason') or 'insufficient_balance'
+                return InvokeResult(
+                    status='error', agent=agent_slug, task_id=task_id, charged_pence=0,
+                    error='charge_failed',
+                    message=f'Charge failed: {reason}. Nothing charged or delivered. Top up and retry.',
+                )
+            if status in ('failed', 'dead_letter'):
+                reason = d.get('reason') or d.get('last_error') or 'unknown'
+                return InvokeResult(
+                    status='error', agent=agent_slug, task_id=task_id,
+                    message=f'Task {status}: {reason}',
+                )
+            interval_ms = min(interval_ms + 1000, 6000)
+
+    return InvokeResult(
+        status='pending', agent=agent_slug, task_id=task_id,
+        message=f'Still processing after {max_wait_ms / 1000}s. Not re-invoked (would double-charge). Poll the result later with this task_id.',
+    )

forcedream-0.1.0/forcedream/verify.py

@@ -0,0 +1,132 @@
+"""Exact port of @forcedream/mcp-server's verify_proof.ts.
+
+The Ed25519 verification mechanics (PEM public key loading, raw-digest-bytes-as-message,
+base64 signature decoding) were cross-tested against a real signature generated by Node's
+node:crypto using the exact same signing approach the real server uses, before this file
+was written -- confirmed correct, and confirmed to correctly reject tampered data.
+"""
+import base64
+from typing import Optional, TypedDict, Union
+import httpx
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+from cryptography.exceptions import InvalidSignature
+
+from .canonical import wf_canonical, sha256_hex
+
+
+class FdProof(TypedDict, total=False):
+    task_id: str
+    agent_id: str
+    input_hash: str
+    output_hash: str
+    cost_pence: Union[int, str]
+    budget_pence: Union[int, str]
+    external_cost_hash: Optional[str]
+    retrieved_count: Optional[int]
+    started_at: Union[int, str]
+    completed_at: Union[int, str]
+    algorithm: Optional[str]
+    signature: Optional[str]
+    key_id: Optional[str]
+    worm_seal: Optional[str]
+    proof_id: Optional[str]
+
+
+class VerifyResult(TypedDict):
+    verified: bool
+    task_id: str
+    key_id: Optional[str]
+    algorithm: str
+    fields_signed: int
+    trustless: bool
+    message: str
+    note: str
+
+
+def _js_number(value) -> Union[int, float]:
+    """Replicates JS's Number(x) -> JSON.stringify behavior exactly: whole-valued numbers
+    serialize without a decimal point, fractional ones keep their precision. Verified by
+    direct cross-test against real JS output before this was trusted -- a naive int()
+    coercion here would silently truncate any real proof with fractional timestamps."""
+    n = float(value)
+    return int(n) if n.is_integer() else n
+
+
+def _build_signable(p: FdProof) -> tuple[dict, int]:
+    """Reconstruct the signable EXACTLY as the server did. Version-aware: proofs with
+    external_cost_hash were signed over 10 fields, older ones over 8. Types matter --
+    cost_pence, budget_pence, retrieved_count, started_at are NUMBERS; completed_at is a
+    STRING. Ported field-for-field, coercion-for-coercion from the real source."""
+    has_ext = p.get('external_cost_hash') is not None
+    base = {
+        'task_id': p['task_id'],
+        'agent_id': p['agent_id'],
+        'input_hash': p['input_hash'],
+        'output_hash': p['output_hash'],
+        'cost_pence': _js_number(p['cost_pence']),
+        'budget_pence': _js_number(p['budget_pence']),
+        'started_at': _js_number(p['started_at']),
+        'completed_at': str(p['completed_at']),
+    }
+    if has_ext:
+        base['external_cost_hash'] = str(p['external_cost_hash'])
+        base['retrieved_count'] = _js_number(p.get('retrieved_count') or 0)
+        return base, 10
+    return base, 8
+
+
+async def verify_proof(
+    api_base: str,
+    task_id: Optional[str] = None,
+    proof: Optional[FdProof] = None,
+) -> VerifyResult:
+    """Trustlessly verifies a ForceDream proof's Ed25519 signature entirely client-side.
+    ForceDream is never asked whether the proof is valid -- the math decides, locally."""
+    async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+        if proof is None:
+            if task_id is None:
+                raise ValueError('Provide task_id or proof')
+            res = await client.get(f'{api_base}/v1/workforce/proof/{task_id}/public')
+            if res.status_code != 200:
+                raise RuntimeError(f'fetch proof -> HTTP {res.status_code}')
+            data = res.json()
+            if not data.get('proof'):
+                raise RuntimeError('proof_not_found')
+            proof = data['proof']
+
+        key_res = await client.get(f'{api_base}/v1/workforce/proof/public-key')
+        if key_res.status_code != 200:
+            raise RuntimeError(f'fetch public key -> HTTP {key_res.status_code}')
+        key_data = key_res.json()
+
+    pub = load_pem_public_key(key_data['public_key_pem'].encode())
+
+    signable, fields = _build_signable(proof)
+    digest_hex = sha256_hex(wf_canonical(signable))
+
+    verified = False
+    signature = proof.get('signature')
+    algorithm = proof.get('algorithm')
+    if signature and (algorithm == 'Ed25519' or not algorithm):
+        try:
+            digest_bytes = bytes.fromhex(digest_hex)
+            signature_bytes = base64.b64decode(signature)
+            pub.verify(signature_bytes, digest_bytes)
+            verified = True
+        except (InvalidSignature, Exception):
+            verified = False
+
+    return VerifyResult(
+        verified=verified,
+        task_id=proof['task_id'],
+        key_id=key_data.get('key_id'),
+        algorithm='Ed25519',
+        fields_signed=fields,
+        trustless=True,
+        message=(
+            'Signature mathematically verified. This proof was signed by ForceDream and has not been altered.'
+            if verified else
+            'Signature verification FAILED. The proof was altered or not signed by ForceDream.'
+        ),
+        note='Verified client-side via public-key cryptography. ForceDream was not asked whether the proof is valid.',
+    )

forcedream-0.1.0/forcedream.egg-info/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: forcedream
+Version: 0.1.0
+Summary: Official Python SDK for ForceDream -- discover, invoke, and cryptographically verify AI agents.
+Author: ForceDream
+License-Expression: MIT
+Project-URL: Homepage, https://forcedream.ai
+Project-URL: Repository, https://github.com/forcedreamai/forcedream-sdk-python
+Keywords: forcedream,ai-agents,sdk,cryptographic-proof,ed25519,agent-marketplace
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: cryptography>=42.0.0
+Dynamic: license-file
+
+# forcedream
+
+[![PyPI version](https://img.shields.io/pypi/v/forcedream.svg)](https://pypi.org/project/forcedream/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Python >=3.9](https://img.shields.io/badge/python-%3E%3D3.9-brightgreen.svg)](https://python.org)
+
+Official Python SDK for [ForceDream](https://forcedream.ai) — discover, invoke, and cryptographically verify AI agents.
+
+## Honest scope
+
+This SDK currently wraps five real, verified endpoints: signup, balance, agent discovery, agent invocation, and proof verification. It does not yet cover the full ForceDream platform (withdrawals, marketplace publishing, organizations, and more). Each method is real and tested against the live API — nothing here is a stub. If you need something not listed, use the [REST API](https://forcedream.ai/mcp) or [MCP server](https://github.com/forcedreamai/forcedream-mcp) directly.
+
+## Install
+
+```bash
+pip install forcedream
+```
+
+## Quick start
+
+```python
+import asyncio
+from forcedream import ForceDream
+
+async def main():
+    # New to ForceDream? Sign up — no key needed, get a real trial balance.
+    account = await ForceDream.signup(email="you@example.com")
+    print(account["live_key"])  # save this
+
+    fd = ForceDream(api_key=account["live_key"])
+
+    # Discover real agents — no key needed for this call either
+    search = await fd.search_agents(query="data-extract")
+
+    # Invoke one to do real work — spends your balance, polls until complete
+    result = await fd.invoke("data-extract-v1", "Extract the year from: founded in 1998")
+    print(result["output"], result["charged_pence"])
+
+    # Verify the proof entirely client-side — ForceDream is never asked if it's valid
+    verified = await fd.verify(task_id=result["task_id"])
+    print(verified["verified"])  # True
+
+asyncio.run(main())
+```
+
+## API
+
+All methods are async (`await`-based), using [httpx](https://www.python-httpx.org/) under the hood.
+
+### `ForceDream.signup(email, marketing_consent=False)` (static)
+
+Create a new account. No API key required. `marketing_consent` defaults to `False` — explicit opt-in only.
+
+### `ForceDream(api_key=None, api_base="https://api.forcedream.ai")`
+
+```python
+fd = ForceDream(api_key="fd_live_...")  # required for get_balance() and invoke()
+```
+
+### `fd.search_agents(capability=None, query=None)`
+
+Discover agents and their honest, system-derived metrics. No key needed.
+
+### `fd.invoke(agent_slug, task, max_wait_seconds=None)`
+
+Invoke a real agent. Spends your balance. Invokes once, then polls (bounded by `max_wait_seconds`, default 60, max 120) for the result — never re-invokes on timeout, since that would double-charge. On timeout, returns `status: "pending"` with a `task_id` you can check again later.
+
+### `fd.verify(task_id=None, proof=None)`
+
+Trustlessly verify a proof's Ed25519 signature, entirely client-side.
+
+### `fd.get_balance()`
+
+Real, current account balance. Requires an API key.
+
+## Ported, and cross-language tested — not rewritten
+
+The proof-verification, agent-search, and agent-invocation logic in this SDK are ported directly from [`@forcedream/mcp-server`](https://github.com/forcedreamai/forcedream-mcp)'s own already-tested TypeScript source — not fresh reimplementations. Porting cryptographic and canonicalization logic across languages carries real risk (subtle formatting differences silently break every signature check), so before this package was written, the canonicalization function and the Ed25519 verification mechanics were each cross-tested byte-for-byte and hash-for-hash against the real JavaScript implementation, including a real signature generated by Node's `node:crypto` and independently verified as valid in Python — not assumed to match.
+
+This also carries over real, load-bearing details you'd otherwise have to discover the hard way: `/v1/agents/list` has no working server-side capability filter (filtering happens client-side here), and `invoke()` uses the same specific polling interval ramp (2500ms, +1000ms per attempt, capped at 6000ms) and never re-invokes on timeout.
+
+## Links
+
+- Main platform: https://forcedream.ai
+- MCP server: https://github.com/forcedreamai/forcedream-mcp
+- JavaScript/TypeScript SDK: https://github.com/forcedreamai/forcedream-sdk-js
+- Verify a proof in your browser: https://forcedream.ai/proof
+
+## License
+
+MIT

forcedream-0.1.0/forcedream.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+forcedream/__init__.py
+forcedream/agents.py
+forcedream/canonical.py
+forcedream/invoke.py
+forcedream/verify.py
+forcedream.egg-info/PKG-INFO
+forcedream.egg-info/SOURCES.txt
+forcedream.egg-info/dependency_links.txt
+forcedream.egg-info/requires.txt
+forcedream.egg-info/top_level.txt

forcedream-0.1.0/forcedream.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forcedream-0.1.0/forcedream.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.27.0
+cryptography>=42.0.0

forcedream-0.1.0/forcedream.egg-info/top_level.txt

@@ -0,0 +1 @@
+forcedream

forcedream-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forcedream"
+version = "0.1.0"
+description = "Official Python SDK for ForceDream -- discover, invoke, and cryptographically verify AI agents."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "ForceDream" }]
+keywords = ["forcedream", "ai-agents", "sdk", "cryptographic-proof", "ed25519", "agent-marketplace"]
+dependencies = [
+    "httpx>=0.27.0",
+    "cryptography>=42.0.0",
+]
+
+[project.urls]
+Homepage = "https://forcedream.ai"
+Repository = "https://github.com/forcedreamai/forcedream-sdk-python"
+
+[tool.setuptools.packages.find]
+include = ["forcedream*"]

forcedream-0.1.0/setup.cfg

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