fystash

Python SDK for the Fystash public API. Catalog operations are generated from the same operation catalog as TypeScript. Ergonomic handles (Revision, Branch, Plan, Run, Evidence) live in a handwritten layer above that transport (ADR-0091). This package is not a second CLI.

Install

pip install fystash

Configure

Set environment variables, or pass them explicitly. The SDK does not read ~/.fystash/credentials.json unless you call Fystash.from_cli_context().

FYSTASH_API_URL       default https://api.fystash.ai/v1
FYSTASH_ACCESS_TOKEN
FYSTASH_PROJECT_ID

from fystash import Fystash

fystash = Fystash.from_env()
# or: Fystash.connect(api_url=..., access_token=..., project_id=...)

Quickstart

fystash = Fystash.from_env()

revision = fystash.environments.compile_file("environment.yaml")

branch = fystash.branches.create(
    revision=revision.id,
    name="dev"
)

plan = fystash.runs.plan(
    revision=revision.id,
    branch=branch.id
)

run = plan.apply()

run.wait_ready()
run.exec(["pytest", "-q"])
evidence = run.evidence.list()
run.stop()

plan.apply() submits the digest stored on that Plan object. Retrying apply() on the same handle reuses one idempotency key; constructing a new Plan starts a new intent.

run.exec(argv) maps to catalog execProcess with component=workspace and actor=agent unless overridden. It never invokes a local shell.

Errors

Failures keep the canonical envelope code. Convenience classes (AuthenticationError, PermissionError, CapabilityUnavailableError, ApprovalRequiredError, ConflictError, TimeoutError) wrap that envelope.

License

Apache-2.0