Python SDK

alive-sdk 0.1.0 is implemented as a synchronous thin client for the beta /v1 API. It is not published to PyPI yet. Python 3.13 is required. Install the wheel supplied by the maintainer:

uv pip install ./alive_sdk-0.1.0-py3-none-any.whl

The SDK depends on HTTPX. It does not install the local simulation engine, provision Supabase, refresh credentials, run Multiverse functions or connect an IDE agent automatically. A configured API must be reachable; a public-site deployment alone does not establish hosted API availability.

Discovery and validation

from alive_sdk import AliveClient
from alive_sdk.resources import reference_world, manifest

world = reference_world("rural-clinic")  # bundled; no checkout or network
print(manifest()["api_version"])

with AliveClient(base_url="http://127.0.0.1:8000") as alive:
    print(alive.models(category="process"))
    print(alive.model("alive.process.referral@1.0.0"))
    validated = alive.validate_world(world)  # API request, no execution
    print(validated["world_id"], validated["warnings"])

Public models, schemas, prompts and validation work without a token. Hosted validation is not a local engine invocation. Use the CLI for offline validation/runs.

Estimate, approve and run

For authenticated calls, supply a scoped token or a callable returning the current token. Keep credentials outside source code. Select a permitted organization; creating a project needs write scope and run creation needs run scope plus spendable credits. Use only synthetic inputs.

import os
from alive_sdk import AliveClient, idempotency_key
from alive_sdk.resources import reference_world

project_key = idempotency_key()  # persist before sending if resumable retries matter
run_key = idempotency_key()

with AliveClient(base_url=os.environ["ALIVE_API_URL"], token=os.environ["ALIVE_TOKEN"]) as alive:
    project = alive.create_project(
        "Navigator capacity experiment", key=project_key, org_id=os.environ["ALIVE_ORG_ID"]
    )
    revision = alive.save_world(project["id"], reference_world("rural-clinic"))
    estimate = alive.estimate_run(revision["world_revision_id"])
    print(estimate)  # stop here and review the estimate with the authorized user

After the user authorizes a positive credit budget, submit that same saved revision explicitly:

queued = alive.create_run(world_revision_id, budget_limit_credits=approved_budget, key=run_key)
print(queued["run_id"], queued["reserved_credits"])

The last snippet belongs inside an open client context and assumes the reviewed revision and approved budget from your application. The SDK never chooses a budget or submits a run from an estimate automatically. Persist the run id, revision id and key. For an ambiguous network failure, retry the same run body with the same key, rather than saving a new revision or creating a new key. World saves and plan creation do not currently accept idempotency keys.

Inspect and export

Poll alive.run(run_id) explicitly at a reasonable interval. queued and running are pending; succeeded, timed_out, failed and canceled are terminal. The SDK does not busy-poll.

status = alive.run(run_id)
if status["status"] in {"succeeded", "timed_out"}:
    results = alive.results(run_id)
    print(results["findings"], results["assumption_parameters"])
    comparisons = alive.compare(run_id)  # same-run stored paired variants
    page = alive.events(run_id, limit=100, offset=0)
    print(page["next_offset"], page["events_included"])
    alive.download_export(run_id, "evaluation.zip")

These snippets also use an open client context. Event pages are bounded; follow next_offset explicitly and check events_included before treating a trace as complete. Downloads use a separate unauthenticated connection to the short-lived signed URL, stream to a new file and refuse to overwrite an existing file. A failed download removes the partial file. Request a fresh link after expiry. export_link returns the URL if your own download flow is preferable.

cancel_run marks the run canceled. Queued work is not executed; an already-running in-process calculation is not forcibly interrupted and may finish its existing usage settlement. It remains canceled, rather than reappearing as successful. Process-level interruption remains planned.

Concept-only projects

Use parse_intake(project_id, external_ai_approved=…, text=…, files=…) for an approved hosted draft, or validate_intake for user-prepared JSON. Upload tuples are (filename, bytes, content_type). Review the draft before calling save_intake(project_id, intake, key=…). plan(project_id) computes eligibility. approve_plan records a supported scope, and create_review(project_id, plan_id, budget_limit_credits=…, key=…) explicitly queues a review. Poll review(review_id) and inspect context(project_id). A WorldSpec is not required here.

Errors and types

• AliveApiError: status, code, message, details, request_id from a non-2xx response. Non-JSON hosting failures use HTTP_ERROR; do not assume they are validation results.
• AliveConnectionError: the network request did not complete. A write may have reached the server; reuse its key/body and preserve identity.
• AliveProtocolError: an unexpected success body. No automatic write retry occurs.
• Filesystem/value errors remain Python exceptions (for example an existing download file).

alive_sdk.types contains generated TypedDict request/result annotations from the same OpenAPI as TypeScript. results and compare return annotated result dictionaries; other free-form responses remain dict[str, Any]. Type annotations do not validate at runtime or promote evidence grades. No API path, schema key or model reference is inferred by an LLM.

request(method, "/v1/…", json=…, params=…, data=…, files=…, key=…) covers existing operations without a named helper. See the HTTP reference for exact bodies and required scopes; errors and limits for recovery.