Owned Vast.ai Python SDK Lifecycles
Overview
Use the highest-level client that preserves the required control. Keep resource identity and cleanup ownership explicit, normalize provider response variants at one boundary, and never hide a billable instance behind an unbounded retry.
Prerequisites
- Chosen high-level, synchronous, asynchronous, or Serverless client surface
- Typed internal model for offers, instances, terminal states, and provider errors
- Idempotency, timeout, test-double, and cleanup design
Instructions
Step 1: Select one client boundary
Use VastAI for broad CLI-equivalent operations, SyncClient for typed synchronous instance control, AsyncClient inside an async context, or Serverless for endpoint inference.
Step 2: Normalize responses once
Map provider dictionaries and error shapes into a small internal result type. Preserve offer ID, contract ID, status, price, and raw error code for diagnosis.
Step 3: Separate plan from mutation
Search and score offers without creating resources. Require an approved plan object before calling create, update, destroy, or credit operations.
Step 4: Own the lifecycle
Persist the returned instance ID immediately, apply a monotonic deadline, classify terminal failure states, and place destroy or handoff in an explicit finalizer.
Step 5: Test failure boundaries
Cover 401, 403, 429, malformed responses, create-without-ID, readiness timeout, and cleanup failure using local fakes.
Step 6: Expose a redacted receipt
Return normalized decisions and state transitions; never return the API key or full environment.
Authentication
Construct clients from VAST_API_KEY or the approved local configuration. Do not pass keys as literals, serialize client objects, or let provider credentials cross into workload payloads.
Tool Discipline
Use Read and Grep to inspect manifests, configuration, provider output, and existing tests before proposing a mutation. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not create, update, destroy, or fund Vast.ai resources without explicit operator approval.
Output
- Client-selection decision and typed adapter contract
- Bounded lifecycle implementation with local failure tests
- Redacted mutation and cleanup receipt
Return client type, package version, plan identity, provider resource IDs, terminal outcome, and cleanup owner.
Examples
An async job runner uses AsyncClient as a context manager, records instance.id before waiting, cancels on its deadline, and destroys the instance in a tested finalizer.
Error Handling
| Failure | Response |
|---|---|
| Create succeeds without a usable ID | Stop follow-on work, reconcile instances from the account, and avoid a blind second create. |
| Response shape changes | Fail at the adapter boundary and retain the redacted raw response for review. |
| 429 occurs | Use bounded client retry and reduce polling; do not multiply retries at every layer. |
| Finalizer cannot destroy | Persist the resource ID and page the billing owner. |