swytchcode-runtime 0.1.0__tar.gz → 1.0.1__tar.gz

swytchcode_runtime-1.0.1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Swytchcode Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swytchcode_runtime-1.0.1/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: swytchcode-runtime
+Version: 1.0.1
+Summary: Thin runtime wrapper around the Swytchcode CLI
+Author: Swytchcode
+License: MIT
+Project-URL: repository, https://github.com/swytchcodehq/runtime-py
+Keywords: swytchcode,cli,runtime,exec
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+# swytchcode-runtime (Python)
+
+Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
+
+**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically — no configuration needed in most environments. Resolution order:
+
+1. `SWYTCHCODE_BIN` env var — explicit override.
+2. `$PATH` lookup via `shutil.which` — the standard system resolution.
+3. Common install paths — `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
+
+## Install
+
+```bash
+pip install swytchcode-runtime
+```
+
+Or from the repo:
+
+```bash
+pip install /path/to/runtime-libraries/python-runtime
+```
+
+## Use
+
+### JSON mode (default)
+
+```python
+from swytchcode_runtime import exec
+
+result = exec("api.account.create", {"email": "test@example.com"})
+# result is parsed JSON (any)
+```
+
+Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
+
+**Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
+- **body** — Request body (dict).
+- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
+- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- Other top-level keys are passed as query params.
+
+Example with body, params, and headers:
+
+```python
+exec("api.cluster.get", {
+    "params": {"id": "cluster-123"},
+    "Authorization": "Bearer token123",
+    "headers": {"X-Request-Id": "abc-123"},
+})
+```
+
+### Raw mode
+
+Get stdout as a string instead of parsing JSON:
+
+```python
+from swytchcode_runtime import exec
+
+output = exec("api.report.export", {"id": "123"}, raw=True)
+# output is the raw stdout string
+```
+
+### Options
+
+- **cwd** – Working directory for the process (default: current directory).
+- **env** – Extra environment variables (merged with `os.environ`).
+- **raw** – If `True`, use `--raw` and return stdout as a string.
+- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+
+This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `SWYTCHCODE_BIN` | Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or virtualised environments). |
+| `SWYTCHCODE_TOKEN` | Auth token passed to the CLI via the process environment. |
+
+### Error handling
+
+Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
+
+```python
+from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
+
+try:
+    exec("api.account.create", {"email": "test@example.com"})
+except Exception as e:
+    if is_swytchcode_error(e):
+        print(e.message, e.cause)
+    raise
+```
+
+## What this library is
+
+- A thin process wrapper over the Swytchcode shell.
+- A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
+- A convenience for developers and IDE agents.
+
+## What this library is not
+
+- An HTTP SDK or API client.
+- A replacement for the shell. All authority stays in the Swytchcode CLI.
+
+This library **must not** and **does not**:
+
+- Read `.swytchcode/*` or parse `tooling.json`.
+- Validate schemas or add retries/timeouts.
+- Call the registry or embed auth logic.
+
+It is a pipe, not a brain.
+
+## For Cursor / IDE agents
+
+Generate code that uses this runtime instead of subprocess boilerplate.
+
+**Preferred:**
+
+```python
+from swytchcode_runtime import exec
+
+def create_account(input: dict) -> any:
+    return exec("api.account.create", input)
+```
+
+**Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
+
+## Agentic workflows (framework integrations)
+
+For full, production-ready examples across all major frameworks, check out the [Swytchcode Examples Repository](https://github.com/swytchcodehq/swytchcode-examples).
+
+On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects. 
+
+### Quickstart: Anthropic SDK
+
+Here is a clean example of building a simple agent using the Anthropic SDK. We use `python-dotenv` to load environment variables (like `ANTHROPIC_API_KEY`).
+
+**Installation:**
+```bash
+pip install swytchcode-runtime anthropic python-dotenv
+```
+*(Note: You only need to install the SDK for the framework you are actually using. You **do not** need to install `openai-agents` or `langchain` if you are only using Anthropic. The `swytchcode-runtime` isolates these dependencies via lazy loading.)*
+
+**Example:**
+```python
+import os
+from dotenv import load_dotenv
+import anthropic
+from swytchcode_runtime import Swytchcode
+from swytchcode_runtime.providers.anthropic import AnthropicProvider
+
+load_dotenv()  # Loads .env automatically
+
+def run_agent():
+    client = anthropic.Anthropic()
+    
+    # 1. Initialize Swytchcode with the Anthropic provider
+    swx = Swytchcode(provider=AnthropicProvider())
+    
+    # 2. Fetch the tools you want your agent to use (e.g., Stripe tools)
+    tools = swx.tools.get(toolkits=["stripe"])
+
+    # 3. Pass them to Claude
+    response = client.messages.create(
+        model="claude-3-5-sonnet-latest",
+        max_tokens=1024,
+        tools=tools,
+        messages=[{"role": "user", "content": "Refund charge ch_123 for $20."}],
+    )
+
+    print(response)
+
+if __name__ == "__main__":
+    run_agent()
+```
+
+### Selecting tools - `swx.tools.get(...)`
+
+Pass exactly one selector; IDs resolve against your local Swytchcode state and remote search:
+
+- `toolkits=["stripe"]` - every enabled tool whose integration matches a toolkit.
+- `tools=["charges.charge.create"]` - explicit canonical IDs.
+- `search="refund a charge"` - natural-language discovery (via `swytchcode discover`).
+
+Each returned tool carries a **full input schema** - every field is surfaced to the model, with
+only the truly-required ones marked `required` - and an `execute` callback that runs `swytchcode
+exec` for you (empty optional values are stripped before the call so APIs like Stripe don't reject them).
+
+### Supported providers
+
+| Framework | Import | Who runs the tool loop |
+|-----------|--------|------------------------|
+| Anthropic Claude | `from swytchcode_runtime.providers.anthropic import AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
+| OpenAI Agents SDK | `from swytchcode_runtime.providers.openai_agents import OpenAIAgentsProvider` | the SDK |
+| Vercel AI SDK | `from swytchcode_runtime.providers.vercel import VercelProvider` | the SDK |
+| LangGraph | `from swytchcode_runtime.providers.langgraph import LangGraphProvider` | the prebuilt agent |
+| CrewAI | `from swytchcode_runtime.providers.crewai import CrewAIProvider` | the crew |
+
+### Non-agentic APIs (Anthropic Messages)
+
+When you run the tool loop yourself, `handle_tool_calls` executes each `tool_use` block and
+returns the `tool_result` blocks to send back:
+
+```python
+import anthropic
+client = anthropic.Anthropic()
+msg = client.messages.create(
+    model="claude-sonnet-5", max_tokens=1024, tools=tools,
+    messages=[{"role": "user", "content": "Refund charge ch_123 for $20"}],
+)
+results = swx.handle_tool_calls(msg)   # runs the tool calls, returns tool_result blocks
+```
+
+One runnable file per framework lives in `sdk-examples/`. Install the matching framework SDK
+(`pip install openai-agents` / `anthropic` / `ai` / `langgraph` / `crewai`) alongside the
+`swytchcode` CLI.

swytchcode_runtime-1.0.1/README.md

@@ -0,0 +1,218 @@
+# swytchcode-runtime (Python)
+
+Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
+
+**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically — no configuration needed in most environments. Resolution order:
+
+1. `SWYTCHCODE_BIN` env var — explicit override.
+2. `$PATH` lookup via `shutil.which` — the standard system resolution.
+3. Common install paths — `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
+
+## Install
+
+```bash
+pip install swytchcode-runtime
+```
+
+Or from the repo:
+
+```bash
+pip install /path/to/runtime-libraries/python-runtime
+```
+
+## Use
+
+### JSON mode (default)
+
+```python
+from swytchcode_runtime import exec
+
+result = exec("api.account.create", {"email": "test@example.com"})
+# result is parsed JSON (any)
+```
+
+Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
+
+**Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
+- **body** — Request body (dict).
+- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
+- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- Other top-level keys are passed as query params.
+
+Example with body, params, and headers:
+
+```python
+exec("api.cluster.get", {
+    "params": {"id": "cluster-123"},
+    "Authorization": "Bearer token123",
+    "headers": {"X-Request-Id": "abc-123"},
+})
+```
+
+### Raw mode
+
+Get stdout as a string instead of parsing JSON:
+
+```python
+from swytchcode_runtime import exec
+
+output = exec("api.report.export", {"id": "123"}, raw=True)
+# output is the raw stdout string
+```
+
+### Options
+
+- **cwd** – Working directory for the process (default: current directory).
+- **env** – Extra environment variables (merged with `os.environ`).
+- **raw** – If `True`, use `--raw` and return stdout as a string.
+- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+
+This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `SWYTCHCODE_BIN` | Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or virtualised environments). |
+| `SWYTCHCODE_TOKEN` | Auth token passed to the CLI via the process environment. |
+
+### Error handling
+
+Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
+
+```python
+from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
+
+try:
+    exec("api.account.create", {"email": "test@example.com"})
+except Exception as e:
+    if is_swytchcode_error(e):
+        print(e.message, e.cause)
+    raise
+```
+
+## What this library is
+
+- A thin process wrapper over the Swytchcode shell.
+- A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
+- A convenience for developers and IDE agents.
+
+## What this library is not
+
+- An HTTP SDK or API client.
+- A replacement for the shell. All authority stays in the Swytchcode CLI.
+
+This library **must not** and **does not**:
+
+- Read `.swytchcode/*` or parse `tooling.json`.
+- Validate schemas or add retries/timeouts.
+- Call the registry or embed auth logic.
+
+It is a pipe, not a brain.
+
+## For Cursor / IDE agents
+
+Generate code that uses this runtime instead of subprocess boilerplate.
+
+**Preferred:**
+
+```python
+from swytchcode_runtime import exec
+
+def create_account(input: dict) -> any:
+    return exec("api.account.create", input)
+```
+
+**Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
+
+## Agentic workflows (framework integrations)
+
+For full, production-ready examples across all major frameworks, check out the [Swytchcode Examples Repository](https://github.com/swytchcodehq/swytchcode-examples).
+
+On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects. 
+
+### Quickstart: Anthropic SDK
+
+Here is a clean example of building a simple agent using the Anthropic SDK. We use `python-dotenv` to load environment variables (like `ANTHROPIC_API_KEY`).
+
+**Installation:**
+```bash
+pip install swytchcode-runtime anthropic python-dotenv
+```
+*(Note: You only need to install the SDK for the framework you are actually using. You **do not** need to install `openai-agents` or `langchain` if you are only using Anthropic. The `swytchcode-runtime` isolates these dependencies via lazy loading.)*
+
+**Example:**
+```python
+import os
+from dotenv import load_dotenv
+import anthropic
+from swytchcode_runtime import Swytchcode
+from swytchcode_runtime.providers.anthropic import AnthropicProvider
+
+load_dotenv()  # Loads .env automatically
+
+def run_agent():
+    client = anthropic.Anthropic()
+    
+    # 1. Initialize Swytchcode with the Anthropic provider
+    swx = Swytchcode(provider=AnthropicProvider())
+    
+    # 2. Fetch the tools you want your agent to use (e.g., Stripe tools)
+    tools = swx.tools.get(toolkits=["stripe"])
+
+    # 3. Pass them to Claude
+    response = client.messages.create(
+        model="claude-3-5-sonnet-latest",
+        max_tokens=1024,
+        tools=tools,
+        messages=[{"role": "user", "content": "Refund charge ch_123 for $20."}],
+    )
+
+    print(response)
+
+if __name__ == "__main__":
+    run_agent()
+```
+
+### Selecting tools - `swx.tools.get(...)`
+
+Pass exactly one selector; IDs resolve against your local Swytchcode state and remote search:
+
+- `toolkits=["stripe"]` - every enabled tool whose integration matches a toolkit.
+- `tools=["charges.charge.create"]` - explicit canonical IDs.
+- `search="refund a charge"` - natural-language discovery (via `swytchcode discover`).
+
+Each returned tool carries a **full input schema** - every field is surfaced to the model, with
+only the truly-required ones marked `required` - and an `execute` callback that runs `swytchcode
+exec` for you (empty optional values are stripped before the call so APIs like Stripe don't reject them).
+
+### Supported providers
+
+| Framework | Import | Who runs the tool loop |
+|-----------|--------|------------------------|
+| Anthropic Claude | `from swytchcode_runtime.providers.anthropic import AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
+| OpenAI Agents SDK | `from swytchcode_runtime.providers.openai_agents import OpenAIAgentsProvider` | the SDK |
+| Vercel AI SDK | `from swytchcode_runtime.providers.vercel import VercelProvider` | the SDK |
+| LangGraph | `from swytchcode_runtime.providers.langgraph import LangGraphProvider` | the prebuilt agent |
+| CrewAI | `from swytchcode_runtime.providers.crewai import CrewAIProvider` | the crew |
+
+### Non-agentic APIs (Anthropic Messages)
+
+When you run the tool loop yourself, `handle_tool_calls` executes each `tool_use` block and
+returns the `tool_result` blocks to send back:
+
+```python
+import anthropic
+client = anthropic.Anthropic()
+msg = client.messages.create(
+    model="claude-sonnet-5", max_tokens=1024, tools=tools,
+    messages=[{"role": "user", "content": "Refund charge ch_123 for $20"}],
+)
+results = swx.handle_tool_calls(msg)   # runs the tool calls, returns tool_result blocks
+```
+
+One runnable file per framework lives in `sdk-examples/`. Install the matching framework SDK
+(`pip install openai-agents` / `anthropic` / `ai` / `langgraph` / `crewai`) alongside the
+`swytchcode` CLI.

{swytchcode_runtime-0.1.0 → swytchcode_runtime-1.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swytchcode-runtime"
-version = "0.1.0"
+version = "1.0.1"
 description = "Thin runtime wrapper around the Swytchcode CLI"
 readme = "README.md"
 license = { text = "MIT" }
@@ -20,7 +20,7 @@ classifiers = [
 ]
 
 [project.urls]
-repository = "https://gitlab.com/swytchcode/py-runtime"
+repository = "https://github.com/swytchcodehq/runtime-py"
 
 [tool.setuptools.packages.find]
 where = ["."]

swytchcode_runtime-1.0.1/swytchcode_runtime/__init__.py

@@ -0,0 +1,30 @@
+"""Thin runtime wrapper around the Swytchcode CLI."""
+
+from .errors import SwytchcodeError, is_swytchcode_error
+from .exec import exec_ as exec
+from .client import Swytchcode
+
+__all__ = [
+    "exec",
+    "Swytchcode",
+    "SwytchcodeError",
+    "is_swytchcode_error",
+]
+
+
+def __getattr__(name):
+    """Lazy provider imports for backward compatibility."""
+    _provider_map = {
+        "AnthropicProvider": ("providers.anthropic", "AnthropicProvider"),
+        "OpenAIAgentsProvider": ("providers.openai_agents", "OpenAIAgentsProvider"),
+        "VercelProvider": ("providers.vercel", "VercelProvider"),
+        "LangGraphProvider": ("providers.langgraph", "LangGraphProvider"),
+        "CrewAIProvider": ("providers.crewai", "CrewAIProvider"),
+    }
+    if name in _provider_map:
+        module_path, attr = _provider_map[name]
+        import importlib
+
+        mod = importlib.import_module(f".{module_path}", __package__)
+        return getattr(mod, attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

swytchcode_runtime-1.0.1/swytchcode_runtime/cli.py

@@ -0,0 +1,58 @@
+"""Run a swytchcode CLI subcommand with --json and parse the output."""
+
+from __future__ import annotations
+import json
+import os
+import subprocess
+from typing import Any
+
+from .exec import _resolve_bin
+from .errors import SwytchcodeError
+
+
+def run_cli(
+    args: list[str],
+    *,
+    cwd: str | None = None,
+    env: dict | None = None,
+    timeout: float | None = 60,
+) -> Any:
+    cmd = [_resolve_bin(), *args]
+    if "--json" not in args:
+        cmd.append("--json")
+
+    run_env = os.environ.copy()
+    if env:
+        run_env.update(env)
+
+    try:
+        r = subprocess.run(
+            cmd,
+            capture_output=True,
+            cwd=cwd or os.getcwd(),
+            env=run_env,
+            timeout=timeout,
+        )
+    except FileNotFoundError as e:
+        raise SwytchcodeError(
+            "Failed to spawn swytchcode; is the CLI installed?", e
+        ) from e
+    except subprocess.TimeoutExpired as e:
+        raise SwytchcodeError(
+            f"swytchcode command timed out after {timeout}s", e
+        ) from e
+
+    if r.returncode != 0:
+        raise SwytchcodeError(
+            r.stderr.decode("utf-8", "replace").strip() or "command failed",
+            r.returncode,
+        )
+
+    out = r.stdout.decode("utf-8", "replace").strip()
+    if not out:
+        return None
+
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as e:
+        raise SwytchcodeError("Invalid JSON from swytchcode", out) from e