vxsdk 0.1.0__py3-none-any.whl

vxsdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: vxsdk
+Version: 0.1.0
+Summary: Python SDK for the vxcloud / VxCloud platform — provision infrastructure, deploy applications, and manage running services from your terminal or CI pipeline.
+Author-email: vxcloud <engineering@vxcloud.io>
+License: Apache-2.0
+Project-URL: Homepage, https://vxcloud.io
+Project-URL: Documentation, https://vxcloud.io/docs/sdks
+Project-URL: Repository, https://github.com/vxcloud/platform
+Project-URL: Issues, https://github.com/vxcloud/platform/issues
+Project-URL: Changelog, https://github.com/vxcloud/platform/blob/main/services/sdk/python/CHANGELOG.md
+Keywords: vxcloud,vxcloud,vxcli,infrastructure,iac,deploy,ssh,docker,kubernetes,ai-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: httpx>=0.25; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: httpx>=0.25; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+
+# vxsdk (Python, preview)
+
+Single-file, stdlib-only Python port of [`../`](..) — the Go SDK.
+
+Same wire contract, same auth model (API key + auto-refresh on 401),
+same resource layout. Use this from Python scripts, Jupyter notebooks,
+data pipelines, or any internal Python service that needs to talk to
+the vxcloud platform.
+
+```
+services/sdk/python/
+├── vxsdk.py           sync SDK — stdlib only, drop-in
+├── vxsdk_async.py     async SDK — same API, requires httpx
+├── deploy_app.py      runnable sync demo (container or stack)
+├── deploy_async.py    runnable async demo (3 deploys in parallel)
+└── README.md          this file
+```
+
+## Two flavors
+
+| Flavor | Module | Dependency | When to use |
+|---|---|---|---|
+| **Sync** | `vxsdk` | stdlib only | Scripts, notebooks, single-shot operations, simple migrations from `vxcli` |
+| **Async** | `vxsdk_async` | `httpx` (`pip install httpx`) | FastAPI / aiohttp services, concurrent fan-out (multi-host deploys, batch installs), high-throughput integration |
+
+Same class hierarchy, same method signatures, same auth model. Switching
+is essentially `vxsdk.Client` → `vxsdk_async.AsyncClient` plus
+`async`/`await`.
+
+## Why a parallel Python implementation?
+
+Python and Go don't share runtimes. The Go SDK is the right answer for
+Go services and customers; this Python file is the right answer for
+Python customers. Both are wrappers over the same FastAPI HTTP surface,
+so the JSON wire is identical and they can be regenerated from a single
+OpenAPI spec when the platform team enables one.
+
+For now, both are hand-written and kept in sync by review.
+
+## Installation
+
+```bash
+# PyPI (canonical name)
+pip install vxsdk
+pip install vxsdk[async]      # adds httpx for vxsdk_async
+
+# PyPI (brand-name alias — same code, just `import vxcloud`)
+pip install vxcloud
+pip install vxcloud[async]
+
+# Drop-in (no install, stdlib-only)
+cp services/sdk/python/vxsdk.py /path/to/your/project/
+```
+
+Stdlib only for the sync flavor — no extra deps. Tested on Python 3.9+.
+
+## Entry-point styles
+
+All four below resolve to the same class object — pick the name you and
+your team prefer. There is no behavior difference:
+
+```python
+import vxsdk
+
+c = vxsdk.Client.load_from_vxcli()      # canonical
+c = vxsdk.VxCloud.load_from_vxcli()     # PascalCase brand (matches TS SDK)
+c = vxsdk.vxcloud.load_from_vxcli()     # lowercase brand
+
+# Or via the alias package:
+import vxcloud
+c = vxcloud.Client.load_from_vxcli()
+c = vxcloud.load_from_vxcli()            # module-level convenience
+```
+
+## Quick start
+
+```python
+import vxsdk
+
+# Reads ~/.vxcloud/credentials.json (the file `vxcli auth login` writes)
+c = vxsdk.Client.load_from_vxcli()
+
+# Or with explicit credentials
+# c = vxsdk.Client(api_key="xc_dev_...", username="alice")
+
+# Provision a VM — `c.cloud.vm.provision(...)` mirrors the TypeScript SDK.
+# (The legacy flat `c.cloud.create_vm(...)` also still works.)
+vm = c.cloud.vm.provision(
+    name="api-vm", cloud="aws", region="us-east-1",
+    instance_type="t3.small", key_pair_name="AWSPRODKEY2",
+)
+print(vm["public_ip"])
+
+# Deploy FastAPI onto the new VM
+sess = c.deploy.fastapi(
+    path="./", entry="app.app:app",
+    requirements="requirements.txt",
+    app_port=8000, http_port=80, app_name="studio-backend",
+    host=vm["public_ip"], ssh_user="ubuntu",
+    key_pair_name="AWSPRODKEY1.PEM",
+)
+print(sess["session_id"])
+
+# Deploy a Docker container onto a VM
+result = c.deploy.container(
+    host="54.197.71.181", ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
+    image="grafana/grafana:latest",
+    name="grafana", ports=["3000:3000"],
+    restart_policy="unless-stopped",
+)
+print(result["session_id"], result.get("status"))
+
+# Deploy a language stack from a public git repo
+result = c.deploy.stack(
+    "golang",
+    host="54.197.71.181", ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
+    repo_url="https://github.com/joelwembo/va-sample-golang.git", branch="main",
+    git_provider="github", app_name="va-sample-golang",
+    http_port="80", app_port="8080", go_version="1.22",
+)
+
+# Run a custom shell script over SSH
+result = c.install.script(
+    host="54.197.71.181", ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
+    script="#!/bin/bash\necho hello\n",
+    script_name="hello.sh",
+)
+
+# CI/CD
+for p in c.cicd.pipelines.list():
+    print(p["id"], p["name"], p.get("repository_url"))
+
+build = c.cicd.pipelines.trigger(pipeline_id="abc...", branch="main")
+
+# Marketplace
+agents = c.marketplace.agents.list()
+result = c.marketplace.agents.deploy(
+    "golang_url_status_agent",
+    host="54.197.71.181", ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
+    http_port="8094",
+)
+
+# Cloud provisioning (real AWS resources)
+result = c.cloud.create_s3_bucket("my-bucket-001", region="us-east-1")
+result = c.cloud.create_iam_policy("my-policy-001",
+                                    policy_document={"Version": "2012-10-17", "Statement": [...]})
+```
+
+## Resource map
+
+| Path | Method | Backend endpoint |
+|---|---|---|
+| `c.cicd.pipelines.list/show/trigger` | GET/GET/POST | `/api/v2/cicd/pipelines/...` |
+| `c.cicd.builds.show` | GET | `/api/v2/cicd/builds/{id}` |
+| `c.sessions.list` | GET | `/api/v3/sessions/list` |
+| `c.install.script` | POST multipart | `/api/v2/tenant/install/script` |
+| `c.install.compose` | POST multipart | `/api/v2/tenant/provision/docker-compose/custom` |
+| `c.deploy.container` | POST multipart | `/api/v2/tenant/container/deploy` |
+| `c.deploy.stack(kind)` | POST multipart | `/api/v2/infrastructure/services/<kind>/deploy` |
+| `c.marketplace.agents.list/show/deploy` | GET/GET/POST | `/api/v2/marketplace/agents/...` |
+| `c.marketplace.models.list/show` | GET/GET | `/api/v2/marketplace/models/...` |
+| `c.marketplace.solutions.list/show/provision` | GET/GET/POST | `/api/v2/marketplace/templates`, `/provision` |
+| `c.cloud.create_s3_bucket` | POST | `/api/v2/tenant/provision/storage` |
+| `c.cloud.create_iam_policy/role/keypair` | POST | `/api/v2/tenant/provision/security` |
+| `c.cloud.create_vm` *(legacy)* | POST | `/api/v2/tenant/provision/vm` |
+| `c.cloud.vm.provision/status/action` | POST | `/api/v2/tenant/provision/vm`, `/provision/vm/{status,action}` |
+| `c.cloud.create_vpc` | POST | `/api/v2/tenant/provision/networks` |
+| `c.cloud.create_kubernetes_cluster` | POST | `/api/v2/tenant/provision/kubernetes` |
+| `c.cloud.list_kubernetes_clusters` | GET | `/api/v2/tenant/kubernetes/clusters` |
+| `c.cloud.kubernetes_cluster_details` | POST | `/api/v2/tenant/kubernetes/cluster/details` |
+| `c.cloud.create_serverless_function` | POST | `/api/v2/tenant/provision/serverless` |
+| `c.metaldb.test_connection/provision` | POST | `/api/v2/tenant/metaldb/...` |
+| `c.nodes.list/default/set_default` | GET/POST | `/api/v1/auth/nodes/` (control plane) |
+| `c.workspace.delete_workspace` | DELETE | `/api/v2/setup/workspace` |
+| `c.marketplace.models.deploy` | POST | `/api/v2/marketplace/models/deploy` |
+| `c.agentcontrol.{summary,fine_tuning,training,knowledge,datasets,agents,github}` | GET/POST | `/api/v2/agentcontrol/...` (X-Tenant-ID header) |
+| `c.vxcomputer.info/run/classify/audit_verify` | GET/POST | `/api/v2/vxcomputer/...` |
+| `c.workflow.list/create/validate/execute/export` | GET/POST | `/api/v2/workflow/...` |
+| `c.vxchrono.create_goal/schedule/launch_run` | POST | `/api/v2/vxchrono/...` |
+| `c.robotic.list_robots/register_robot/send_command` | GET/POST | `/api/v2/robotic/...` |
+
+Async parity: `vxsdk_async.AsyncClient` exposes the same modules,
+including `c.vxcomputer`, `c.workflow`, `c.vxchrono`, and `c.robotic`.
+
+## Errors
+
+```python
+try:
+    c.cicd.pipelines.list()
+except vxsdk.VxAuthError as e:        # 401/403
+    ...
+except vxsdk.VxValidationError as e:  # 400/422
+    ...
+except vxsdk.VxRateLimitError as e:   # 429 — e.retry_after
+    ...
+except vxsdk.VxNotFoundError as e:    # 404
+    ...
+except vxsdk.VxServerError as e:      # 5xx
+    ...
+except vxsdk.VxNetworkError as e:     # transport
+    ...
+except vxsdk.VxError as e:            # base, anything else
+    ...
+```
+
+The SDK retries `VxNetworkError`, `VxServerError`, and `VxRateLimitError`
+up to 3 times with exponential backoff. Auth errors and validation errors
+are surfaced immediately — retrying them as-is would not succeed.
+
+On `401`, the SDK calls `POST /api/v1/auth/developer/keys/login` once
+with the configured API key, replays the original request, and only
+surfaces the error if the refresh itself fails. Application code should
+not see token expiration.
+
+## Run the sync deploy program
+
+```bash
+cd services/sdk/python
+python3 deploy_app.py                                  # whoami container on inst3:8085
+python3 deploy_app.py --image redis:7 --name r --ports 6380:6379
+python3 deploy_app.py --mode stack --kind golang \
+    --repo-url https://github.com/joelwembo/va-sample-golang.git
+```
+
+Default: deploys `traefik/whoami:latest` to inst3:8085 and polls until it
+returns HTTP 200. See `python3 deploy_app.py --help` for flags.
+
+## Run the async demo
+
+```bash
+pip install httpx
+python3 deploy_async.py
+```
+
+Drops three redis containers onto a single host **in parallel** via
+`asyncio.gather()`. Verified live: 3 deploys in 22.8s wall clock vs.
+~57s sequential — a 2.5× speedup, and a 3× win at higher fan-out.
+
+```python
+import asyncio, vxsdk_async as vx
+
+async def main():
+    async with await vx.AsyncClient.load_from_vxcli() as c:
+        results = await asyncio.gather(
+            c.deploy.container(host=h1, ssh_user="ubuntu", key_pair_name=K, image="redis:7", ports=["6381:6379"], name="r1"),
+            c.deploy.container(host=h2, ssh_user="ubuntu", key_pair_name=K, image="redis:7", ports=["6381:6379"], name="r2"),
+            c.deploy.container(host=h3, ssh_user="ubuntu", key_pair_name=K, image="redis:7", ports=["6381:6379"], name="r3"),
+        )
+
+asyncio.run(main())
+```

vxsdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+vxsdk.py,sha256=yilLgPuNa_ZKlM_4c5Lt7CZxR-p5LNO2wERXpPMzFHI,173181
+vxsdk_async.py,sha256=T22EH3ZgmVp1DGto8P-AQlT3RXB06lfju5sFvPK49Ho,67226
+vxsdk-0.1.0.dist-info/METADATA,sha256=V4a2oT-lGCSKt3QdQUvmI9prKg547rh1UztZYOMR9D4,11879
+vxsdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vxsdk-0.1.0.dist-info/top_level.txt,sha256=YrtNolpWp2PjA8nQAuFcpz54y74UglCTigafE_hWqhM,18
+vxsdk-0.1.0.dist-info/RECORD,,

vxsdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vxsdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+vxsdk
+vxsdk_async