arga-py-sdk 0.1.1__tar.gz

arga_py_sdk-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install hatchling build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

arga_py_sdk-0.1.1/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db

arga_py_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: arga-py-sdk
+Version: 0.1.1
+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
+
+```bash
+pip install arga-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")
+```
+
+## 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 |
+
+## 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).

arga_py_sdk-0.1.1/README.md

@@ -0,0 +1,122 @@
+# Arga Python SDK
+
+Typed Python client for the [Arga](https://argalabs.com) API. Supports both synchronous and asynchronous usage.
+
+## Installation
+
+```bash
+pip install arga-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")
+```
+
+## 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 |
+
+## 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).

arga_py_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arga-py-sdk"
+version = "0.1.1"
+description = "Python SDK for the Arga API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Arga Labs", email = "support@argalabs.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "httpx-sse>=0.4.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "respx"]
+
+[project.urls]
+Documentation = "https://docs.argalabs.com"
+Repository = "https://github.com/ArgaLabs/arga-python-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arga_sdk"]

arga_py_sdk-0.1.1/src/arga_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""Arga Python SDK — typed client for the Arga API."""
+
+from arga_sdk.client import Arga, AsyncArga
+from arga_sdk.exceptions import ArgaAPIError, ArgaError
+from arga_sdk.types import (
+    Run,
+    RunDetail,
+    Scenario,
+    Twin,
+    TwinInstance,
+    TwinProvisionStatus,
+)
+
+__all__ = [
+    "Arga",
+    "AsyncArga",
+    "ArgaAPIError",
+    "ArgaError",
+    "Run",
+    "RunDetail",
+    "Scenario",
+    "Twin",
+    "TwinInstance",
+    "TwinProvisionStatus",
+]

arga_py_sdk-0.1.1/src/arga_sdk/_http.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import Any, Iterator, AsyncIterator
+
+import httpx
+import httpx_sse
+
+from arga_sdk.exceptions import ArgaAPIError
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise ArgaAPIError for non-2xx responses."""
+    if response.is_success:
+        return
+    try:
+        body = response.json()
+        message = body.get("detail", body.get("message", response.text))
+    except Exception:
+        message = response.text
+    raise ArgaAPIError(
+        status_code=response.status_code,
+        message=str(message),
+        response=response,
+    )
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client wrapper around httpx."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float = 60.0) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = self._client.get(path, params=params)
+        _raise_for_status(response)
+        return response.json()
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = self._client.post(path, json=json)
+        _raise_for_status(response)
+        return response.json()
+
+    def stream_sse(self, path: str) -> Iterator[dict[str, Any]]:
+        """Stream SSE events from a GET endpoint."""
+        with httpx_sse.connect_sse(
+            self._client, "GET", path
+        ) as event_source:
+            for sse in event_source.iter_sse():
+                import json as _json
+
+                try:
+                    data = _json.loads(sse.data)
+                except (ValueError, TypeError):
+                    data = sse.data
+                yield {
+                    "event": sse.event,
+                    "data": data,
+                    "id": sse.id,
+                    "retry": sse.retry,
+                }
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client wrapper around httpx."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float = 60.0) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = await self._client.get(path, params=params)
+        _raise_for_status(response)
+        return response.json()
+
+    async def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = await self._client.post(path, json=json)
+        _raise_for_status(response)
+        return response.json()
+
+    async def stream_sse(self, path: str) -> AsyncIterator[dict[str, Any]]:
+        """Stream SSE events from a GET endpoint."""
+        async with httpx_sse.aconnect_sse(
+            self._client, "GET", path
+        ) as event_source:
+            async for sse in event_source.aiter_sse():
+                import json as _json
+
+                try:
+                    data = _json.loads(sse.data)
+                except (ValueError, TypeError):
+                    data = sse.data
+                yield {
+                    "event": sse.event,
+                    "data": data,
+                    "id": sse.id,
+                    "retry": sse.retry,
+                }
+
+    async def close(self) -> None:
+        await self._client.aclose()