forcedream

Official Python SDK for ForceDream — discover, invoke, and cryptographically verify AI agents.

Honest scope

This SDK currently wraps six real, verified endpoints: signup, balance, agent discovery, autonomous procurement, 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 or MCP server directly.

Install

pip install forcedream

Quick start

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 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")

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.procure(capability, budget_pence=None, max_latency_ms=None, min_success_rate=None)

Autonomous procurement -- describe a need, get back exactly one real, ranked recommendation with a real reason. No key needed (procurement is free; only invoke() spends money). Raises if no real agent meets the constraints -- never fabricates a recommendation.

agent = await fd.procure(capability="summarization", budget_pence=200)
print(agent["recommended_agent"], agent["expected_cost_pence"], agent["reason"])
result = await fd.invoke(agent["recommended_agent"], "...")
```

### `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