Metadata-Version: 2.4
Name: arga-py-sdk
Version: 0.1.4
Summary: Python SDK for the Arga API
Project-URL: Documentation, https://docs.argalabs.com
Project-URL: Repository, https://github.com/ArgaLabs/arga-python-sdk
Author-email: Arga Labs <support@argalabs.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Description-Content-Type: text/markdown

# Arga Python SDK

Typed Python client for the [Arga](https://argalabs.com) API. Supports both synchronous and asynchronous usage.

## Installation

Install with `uv`:

```bash
uv add arga-py-sdk
```

Or, if you're using `pip`:

```bash
pip install arga-py-sdk
```

## Quick Start

```python
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

```python
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:

```python
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/`](examples/README.md). They are the best
way to see realistic customer workflows end to end.

Before running any example, set your API key:

```bash
export ARGA_API_KEY=arga_your_api_key
```

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

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

Start with the staging validation example:

```bash
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`](examples/validate_staging_release.py): validate staging before a release
- [`examples/create_checkout_scenario.py`](examples/create_checkout_scenario.py): create a reusable checkout scenario
- [`examples/ensure_scenario_twin_urls.py`](examples/ensure_scenario_twin_urls.py): ensure stable scenario twin URLs
- [`examples/provision_checkout_twins.py`](examples/provision_checkout_twins.py): provision disposable integrations like Stripe
- [`examples/explore_staging_with_agent.py`](examples/explore_staging_with_agent.py): let Arga explore staging autonomously

See [`examples/README.md`](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

```python
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](https://docs.argalabs.com).
