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
