clervo-sdk

Dependency-free Python client for the live Clervo API. It exposes cited Search plus the complete provider-neutral AI catalog and normalized AI execution contract.

from clervo import Clervo

client = Clervo()  # https://api.clervo.dev
catalog = client.models.list()
free = next(
    model for model in catalog["data"]
    if model["clervo"]["publicSellable"]
    and model["clervo"]["billingMode"] == "free"
)
result = client.ai.execute(
    model=free["id"],
    input={
        "kind": "chat",
        "messages": [{"role": "user", "content": "Reply with ready."}],
        "responseFormat": "text",
        "stream": False,
    },
    maximum_output_tokens=16,
    idempotency_key="my-stable-request-0001",
)

The catalog carries stable canonical Clervo IDs and explicit alias contracts, capabilities, health, availability, free/paid state, pricing, and commerce metadata. client.ai.execute() accepts the normalized chat, embedding, image, speech, video, music, and virtual-try-on inputs published by OpenAPI. Canonical IDs are never silently substituted.

Paid models raise ClervoPaymentRequiredError with the exact payment challenge. The SDK never creates a wallet, signs, pays, or retries a payment automatically. Deliberately supplied payment credentials remain bound to the same idempotency key; replay sends no new authorization.

Search remains available through client.search.web() and client.search.answer(). recovery_action_for(error) returns one safe next action for known failures. Unknown settlement and timeout states prohibit retry until reconciliation.

Pass base_url only for another HTTPS deployment or loopback development. This client code is MIT licensed; use of the hosted Clervo service remains subject to its service terms.