arga-py-sdk 0.1.4

Python SDK for the Arga API

Arga Python SDK

Typed Python client for the Arga API. Supports both synchronous and asynchronous usage.

Installation

Install with uv:

uv add arga-py-sdk

Or, if you're using pip:

pip install arga-py-sdk

Quick Start

from arga_sdk import Arga

client = Arga(api_key="arga_...")

# Create a URL run with service twins
run = client.runs.create_url_run(
    url="https://staging.myapp.com",
    twins=["stripe", "slack"],
)
print(run.run_id, run.status)

# Poll until the run completes
detail = client.runs.wait(run.run_id, timeout=300)
print(detail.status, detail.results_json)

# Stream live results
for event in client.runs.stream_results(run.run_id):
    print(event)

# Cancel a run
client.runs.cancel(run.run_id)

Async Usage

import asyncio
from arga_sdk import AsyncArga

async def main():
    client = AsyncArga(api_key="arga_...")

    run = await client.runs.create_url_run(url="https://staging.myapp.com")

    # Stream results
    async for event in client.runs.stream_results(run.run_id):
        print(event)

    # Wait for completion
    detail = await client.runs.wait(run.run_id)
    print(detail.status)

    await client.close()

asyncio.run(main())

Context Manager

Both clients support context managers to ensure proper cleanup:

with Arga(api_key="arga_...") as client:
    run = client.runs.create_url_run(url="https://staging.myapp.com")

async with AsyncArga(api_key="arga_...") as client:
    run = await client.runs.create_url_run(url="https://staging.myapp.com")

Examples

Runnable examples live in examples/. They are the best way to see realistic customer workflows end to end.

Before running any example, set your API key:

export ARGA_API_KEY=arga_your_api_key

If you need a non-default API environment, you can also set:

export ARGA_BASE_URL=https://app.argalabs.com

Start with the staging validation example:

uv run python examples/validate_staging_release.py

Each example is a small workflow script with an editable config block near the top of the file. Open the file, adjust the business-specific values, then run it with uv.

Choose an example based on the customer job you want to model:

• examples/validate_staging_release.py: validate staging before a release
• examples/create_checkout_scenario.py: create a reusable checkout scenario
• examples/ensure_scenario_twin_urls.py: ensure stable scenario twin URLs
• examples/provision_checkout_twins.py: provision disposable integrations like Stripe
• examples/explore_staging_with_agent.py: let Arga explore staging autonomously

See examples/README.md for exact commands, required edits, and expected output for each example.

Available Methods

Runs

Method	Description
client.runs.create_url_run(url, ...)	Test a live URL with browser validation
client.runs.create_pr_run(repo, ...)	Validate code changes from a PR or branch
client.runs.create_agent_run(...)	Deploy an autonomous agent for exploration
client.runs.get(run_id)	Get full run details
client.runs.stream_results(run_id)	Stream SSE result events
client.runs.cancel(run_id)	Cancel a running run
client.runs.wait(run_id, ...)	Poll until terminal status

Twins

Method	Description
client.twins.list()	List available service twins
client.twins.provision(twins, ...)	Provision twin instances
client.twins.get_status(run_id)	Get provisioning status
client.twins.extend(run_id, ...)	Extend twin TTL

Scenarios

Method	Description
client.scenarios.create(name, ...)	Create a test scenario
client.scenarios.list(...)	List scenarios (with optional filters)
client.scenarios.get(scenario_id)	Get a scenario by ID
client.scenarios.ensure_twin_environment(scenario_id, ...)	Create or return permanent twin URLs for a scenario
client.scenarios.get_twin_environment(scenario_id)	Get permanent twin environment status and URLs
client.scenarios.reseed_twin_environment(scenario_id)	Reseed a permanent twin environment from the scenario
client.scenarios.delete_twin_environment(scenario_id)	Tear down a permanent twin environment
client.scenarios.list_twin_environments()	List permanent scenario twin environments

Error Handling

from arga_sdk import Arga, ArgaAPIError, ArgaError

client = Arga(api_key="arga_...")

try:
    run = client.runs.get("nonexistent-id")
except ArgaAPIError as e:
    print(e.status_code)  # e.g. 404
    print(e.message)
except ArgaError as e:
    print(e.message)

Documentation

Full API documentation is available at docs.argalabs.com.