voke 0.1.0__tar.gz

voke-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# Node
+node_modules/
+frontend/dist/
+.cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Secrets
+*.pem
+*.key
+macvm-infra
+id_rsa*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+.pytest_cache/
+coverage/
+.coverage
+htmlcov/
+
+# Build artifacts
+cli/voke
+action/dist/
+mcp/dist/
+frontend/
+# Frontend dist is built in CI

voke-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: voke
+Version: 0.1.0
+Summary: Python SDK for Voke — serverless macOS compute on Apple Silicon
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: crewai
+Requires-Dist: crewai-tools>=0.1; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# voke
+
+Python SDK for [Voke](https://voke.run) -- serverless macOS compute on Apple Silicon. Run scripts on ephemeral macOS VMs with one function call.
+
+## Install
+
+```bash
+pip install voke                 # core SDK
+pip install voke[langchain]      # + LangChain integration
+pip install voke[crewai]         # + CrewAI integration
+```
+
+## Quick start
+
+### Sync
+
+```python
+from voke import Voke
+
+client = Voke()  # reads VOKE_API_KEY from env
+result = client.jobs.create(script="uname -m && sw_vers").wait()
+
+print(result.exit_code)  # 0
+print(result.stdout)     # arm64\nProductName: macOS\n...
+```
+
+### Async
+
+```python
+import asyncio
+from voke import AsyncVoke
+
+async def main():
+    client = AsyncVoke()
+    job = await client.jobs.create(script="uname -m")
+    result = await job.async_wait()
+    print(result.stdout)
+    await client.close()
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `Voke(api_key=None, base_url="https://api.voke.run")`
+
+Create a sync client. If `api_key` is not provided, reads `VOKE_API_KEY` from environment.
+
+### `client.jobs.create(script, *, image="base", timeout=600, env=None, webhook_url=None) -> Job`
+
+Submit a script. Returns a `Job` object immediately (status will be "queued").
+
+### `client.jobs.get(job_id) -> Job`
+
+Fetch a job by ID.
+
+### `client.jobs.list(*, limit=20, offset=0, status=None) -> JobList`
+
+List your jobs, newest first.
+
+### `client.jobs.cancel(job_id) -> Job`
+
+Cancel a queued job.
+
+### `job.wait(poll_interval=1.5, timeout=None) -> Job`
+
+Poll until the job reaches a terminal state (completed/failed/cancelled).
+
+### `client.images() -> dict[str, ImageInfo]`
+
+List available macOS images.
+
+### `client.usage() -> UsageResponse`
+
+Get current month's usage.
+
+## Images
+
+| Image | Description |
+|-------|-------------|
+| `base` | Clean macOS Sonoma 14.8 with dev tools |
+| `xcode16` | base + Xcode 16, Swift 6, CocoaPods, Fastlane |
+
+## Error handling
+
+```python
+from voke.errors import VokeError, AuthenticationError, RateLimitError
+
+try:
+    client.jobs.create(script="echo hello")
+except AuthenticationError:
+    print("Bad API key")
+except RateLimitError:
+    print("Too many requests")
+except VokeError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## LangChain
+
+```python
+from voke.tools.langchain import VokeRunTool
+
+tool = VokeRunTool()  # reads VOKE_API_KEY from env
+
+# Use with an agent
+from langchain.agents import AgentExecutor
+agent = AgentExecutor(tools=[tool], ...)
+
+# Or call directly
+result = tool.invoke({"script": "sw_vers", "image": "base"})
+```
+
+## CrewAI
+
+```python
+from voke.tools.crewai import VokeTool
+from crewai import Agent
+
+macos_tool = VokeTool()
+
+agent = Agent(
+    role="macOS Engineer",
+    tools=[macos_tool],
+    ...
+)
+```

voke-0.1.0/README.md

@@ -0,0 +1,127 @@
+# voke
+
+Python SDK for [Voke](https://voke.run) -- serverless macOS compute on Apple Silicon. Run scripts on ephemeral macOS VMs with one function call.
+
+## Install
+
+```bash
+pip install voke                 # core SDK
+pip install voke[langchain]      # + LangChain integration
+pip install voke[crewai]         # + CrewAI integration
+```
+
+## Quick start
+
+### Sync
+
+```python
+from voke import Voke
+
+client = Voke()  # reads VOKE_API_KEY from env
+result = client.jobs.create(script="uname -m && sw_vers").wait()
+
+print(result.exit_code)  # 0
+print(result.stdout)     # arm64\nProductName: macOS\n...
+```
+
+### Async
+
+```python
+import asyncio
+from voke import AsyncVoke
+
+async def main():
+    client = AsyncVoke()
+    job = await client.jobs.create(script="uname -m")
+    result = await job.async_wait()
+    print(result.stdout)
+    await client.close()
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `Voke(api_key=None, base_url="https://api.voke.run")`
+
+Create a sync client. If `api_key` is not provided, reads `VOKE_API_KEY` from environment.
+
+### `client.jobs.create(script, *, image="base", timeout=600, env=None, webhook_url=None) -> Job`
+
+Submit a script. Returns a `Job` object immediately (status will be "queued").
+
+### `client.jobs.get(job_id) -> Job`
+
+Fetch a job by ID.
+
+### `client.jobs.list(*, limit=20, offset=0, status=None) -> JobList`
+
+List your jobs, newest first.
+
+### `client.jobs.cancel(job_id) -> Job`
+
+Cancel a queued job.
+
+### `job.wait(poll_interval=1.5, timeout=None) -> Job`
+
+Poll until the job reaches a terminal state (completed/failed/cancelled).
+
+### `client.images() -> dict[str, ImageInfo]`
+
+List available macOS images.
+
+### `client.usage() -> UsageResponse`
+
+Get current month's usage.
+
+## Images
+
+| Image | Description |
+|-------|-------------|
+| `base` | Clean macOS Sonoma 14.8 with dev tools |
+| `xcode16` | base + Xcode 16, Swift 6, CocoaPods, Fastlane |
+
+## Error handling
+
+```python
+from voke.errors import VokeError, AuthenticationError, RateLimitError
+
+try:
+    client.jobs.create(script="echo hello")
+except AuthenticationError:
+    print("Bad API key")
+except RateLimitError:
+    print("Too many requests")
+except VokeError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## LangChain
+
+```python
+from voke.tools.langchain import VokeRunTool
+
+tool = VokeRunTool()  # reads VOKE_API_KEY from env
+
+# Use with an agent
+from langchain.agents import AgentExecutor
+agent = AgentExecutor(tools=[tool], ...)
+
+# Or call directly
+result = tool.invoke({"script": "sw_vers", "image": "base"})
+```
+
+## CrewAI
+
+```python
+from voke.tools.crewai import VokeTool
+from crewai import Agent
+
+macos_tool = VokeTool()
+
+agent = Agent(
+    role="macOS Engineer",
+    tools=[macos_tool],
+    ...
+)
+```

voke-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "voke"
+version = "0.1.0"
+description = "Python SDK for Voke — serverless macOS compute on Apple Silicon"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai-tools>=0.1"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voke"]

voke-0.1.0/src/voke/__init__.py

@@ -0,0 +1,28 @@
+"""Voke Python SDK — serverless macOS compute on Apple Silicon."""
+
+from voke.client import Voke, AsyncVoke
+from voke.models import Job, JobSummary, JobList, ImageInfo, UsageResponse
+from voke.errors import (
+    VokeError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+)
+
+__all__ = [
+    "Voke",
+    "AsyncVoke",
+    "Job",
+    "JobSummary",
+    "JobList",
+    "ImageInfo",
+    "UsageResponse",
+    "VokeError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"

voke-0.1.0/src/voke/client.py

@@ -0,0 +1,328 @@
+"""Voke API client — sync and async."""
+
+from __future__ import annotations
+
+import os
+import time
+import asyncio
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from voke.errors import raise_for_status
+from voke.models import Job, JobList, ImageInfo, UsageResponse
+
+TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled", "timeout"})
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+
+class _SyncJobsResource:
+    """jobs.create / .get / .list / .cancel"""
+
+    def __init__(self, client: "Voke"):
+        self._c = client
+
+    def create(
+        self,
+        script: str,
+        *,
+        image: str = "base",
+        timeout: int = 600,
+        env: Optional[Dict[str, str]] = None,
+        labels: Optional[Dict[str, str]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> Job:
+        body: Dict[str, Any] = {"script": script, "image": image, "timeout": timeout}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if labels:
+            body["labels"] = labels
+        # Env vars: prepend exports to script
+        if env:
+            exports = "\n".join(f'export {k}={_shell_quote(v)}' for k, v in env.items())
+            body["script"] = f"{exports}\n{script}"
+        resp = self._c._request("POST", "/v1/jobs", json=body)
+        return Job.model_validate(resp)._bind(self._c)
+
+    def get(self, job_id: str) -> Job:
+        resp = self._c._request("GET", f"/v1/jobs/{job_id}")
+        return Job.model_validate(resp)._bind(self._c)
+
+    def list(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        status: Optional[str] = None,
+    ) -> JobList:
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        resp = self._c._request("GET", "/v1/jobs", params=params)
+        return JobList.model_validate(resp)
+
+    def cancel(self, job_id: str) -> Job:
+        resp = self._c._request("DELETE", f"/v1/jobs/{job_id}")
+        return Job.model_validate(resp)._bind(self._c)
+
+
+class Voke:
+    """Synchronous Voke API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.voke.run",
+        *,
+        http_client: Optional[httpx.Client] = None,
+    ):
+        self.api_key = api_key or os.environ.get("VOKE_API_KEY", "")
+        self.base_url = base_url.rstrip("/")
+        self._http = http_client or httpx.Client(timeout=30.0)
+        self.jobs = _SyncJobsResource(self)
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+        }
+
+    def _request(
+        self, method: str, path: str, *, json: Any = None, params: Any = None
+    ) -> Any:
+        max_attempts = 3
+        for attempt in range(max_attempts):
+            try:
+                resp = self._http.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    headers=self._headers(),
+                    json=json,
+                    params=params,
+                )
+            except httpx.TransportError:
+                if attempt >= max_attempts - 1:
+                    raise
+                time.sleep(0.5 * 2**attempt)
+                continue
+
+            if resp.status_code == 429:
+                if attempt >= max_attempts - 1:
+                    body = resp.json() if resp.content else {}
+                    raise_for_status(resp.status_code, body)
+                retry_after = resp.headers.get("Retry-After")
+                wait = float(retry_after) if retry_after else 2.0
+                time.sleep(wait)
+                continue
+
+            if resp.status_code >= 500:
+                if attempt >= max_attempts - 1:
+                    body = resp.json() if resp.content else {}
+                    raise_for_status(resp.status_code, body)
+                time.sleep(0.5 * 2**attempt)
+                continue
+
+            body = resp.json() if resp.content else {}
+            raise_for_status(resp.status_code, body)
+            return body
+
+        # Unreachable, but satisfies type checker
+        raise RuntimeError("Exhausted retries")
+
+    def _poll_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 1.5,
+        timeout: Optional[float] = None,
+    ) -> Job:
+        deadline = time.time() + timeout if timeout else None
+        while True:
+            job = self.jobs.get(job_id)
+            if job.is_terminal:
+                return job
+            if deadline and time.time() >= deadline:
+                raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
+            time.sleep(poll_interval)
+
+    def images(self) -> Dict[str, ImageInfo]:
+        resp = self._request("GET", "/v1/images")
+        return {k: ImageInfo.model_validate(v) for k, v in resp.items()}
+
+    def usage(self) -> UsageResponse:
+        resp = self._request("GET", "/v1/auth/usage")
+        return UsageResponse.model_validate(resp)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Voke":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+
+class _AsyncJobsResource:
+    """Async jobs.create / .get / .list / .cancel"""
+
+    def __init__(self, client: "AsyncVoke"):
+        self._c = client
+
+    async def create(
+        self,
+        script: str,
+        *,
+        image: str = "base",
+        timeout: int = 600,
+        env: Optional[Dict[str, str]] = None,
+        labels: Optional[Dict[str, str]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> Job:
+        body: Dict[str, Any] = {"script": script, "image": image, "timeout": timeout}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if labels:
+            body["labels"] = labels
+        if env:
+            exports = "\n".join(f'export {k}={_shell_quote(v)}' for k, v in env.items())
+            body["script"] = f"{exports}\n{script}"
+        resp = await self._c._request("POST", "/v1/jobs", json=body)
+        return Job.model_validate(resp)._bind(self._c)
+
+    async def get(self, job_id: str) -> Job:
+        resp = await self._c._request("GET", f"/v1/jobs/{job_id}")
+        return Job.model_validate(resp)._bind(self._c)
+
+    async def list(
+        self,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        status: Optional[str] = None,
+    ) -> JobList:
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        resp = await self._c._request("GET", "/v1/jobs", params=params)
+        return JobList.model_validate(resp)
+
+    async def cancel(self, job_id: str) -> Job:
+        resp = await self._c._request("DELETE", f"/v1/jobs/{job_id}")
+        return Job.model_validate(resp)._bind(self._c)
+
+
+class AsyncVoke:
+    """Asynchronous Voke API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.voke.run",
+        *,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        self.api_key = api_key or os.environ.get("VOKE_API_KEY", "")
+        self.base_url = base_url.rstrip("/")
+        self._http = http_client or httpx.AsyncClient(timeout=30.0)
+        self.jobs = _AsyncJobsResource(self)
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+        }
+
+    async def _request(
+        self, method: str, path: str, *, json: Any = None, params: Any = None
+    ) -> Any:
+        max_attempts = 3
+        for attempt in range(max_attempts):
+            try:
+                resp = await self._http.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    headers=self._headers(),
+                    json=json,
+                    params=params,
+                )
+            except httpx.TransportError:
+                if attempt >= max_attempts - 1:
+                    raise
+                await asyncio.sleep(0.5 * 2**attempt)
+                continue
+
+            if resp.status_code == 429:
+                if attempt >= max_attempts - 1:
+                    body = resp.json() if resp.content else {}
+                    raise_for_status(resp.status_code, body)
+                retry_after = resp.headers.get("Retry-After")
+                wait = float(retry_after) if retry_after else 2.0
+                await asyncio.sleep(wait)
+                continue
+
+            if resp.status_code >= 500:
+                if attempt >= max_attempts - 1:
+                    body = resp.json() if resp.content else {}
+                    raise_for_status(resp.status_code, body)
+                await asyncio.sleep(0.5 * 2**attempt)
+                continue
+
+            body = resp.json() if resp.content else {}
+            raise_for_status(resp.status_code, body)
+            return body
+
+        # Unreachable, but satisfies type checker
+        raise RuntimeError("Exhausted retries")
+
+    async def _poll_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 1.5,
+        timeout: Optional[float] = None,
+    ) -> Job:
+        deadline = time.time() + timeout if timeout else None
+        while True:
+            job = await self.jobs.get(job_id)
+            if job.is_terminal:
+                return job
+            if deadline and time.time() >= deadline:
+                raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
+            await asyncio.sleep(poll_interval)
+
+    async def images(self) -> Dict[str, ImageInfo]:
+        resp = await self._request("GET", "/v1/images")
+        return {k: ImageInfo.model_validate(v) for k, v in resp.items()}
+
+    async def usage(self) -> UsageResponse:
+        resp = await self._request("GET", "/v1/auth/usage")
+        return UsageResponse.model_validate(resp)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncVoke":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _shell_quote(s: str) -> str:
+    """Simple shell quoting for env var values."""
+    return "'" + s.replace("'", "'\\''") + "'"