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

swytchcode_runtime-1.0.0/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-0.1.0 → swytchcode_runtime-1.0.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: swytchcode-runtime
-Version: 0.1.0
+Version: 1.0.0
 Summary: Thin runtime wrapper around the Swytchcode CLI
 Author: Swytchcode
 License: MIT
-Project-URL: repository, https://gitlab.com/swytchcode/py-runtime
+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
@@ -13,12 +13,18 @@ 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` binary must be installed and on your `PATH`.
+**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
 
@@ -83,6 +89,13 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 
 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:
@@ -131,3 +144,58 @@ def create_account(input: dict) -> any:
 ```
 
 **Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
+
+## Agentic workflows (framework integrations)
+
+On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools
+into the native tool objects each agent framework expects. The Swytchcode part is the same
+two lines regardless of framework:
+
+```python
+from swytchcode_runtime import Swytchcode
+from swytchcode_runtime.providers.anthropic import AnthropicProvider
+
+swx = Swytchcode(provider=AnthropicProvider())
+tools = swx.tools.get(toolkits=["stripe"])   # framework-native tools, full param schemas
+```
+
+### 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 | `providers.anthropic.AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
+| OpenAI Agents SDK | `providers.openai_agents.OpenAIAgentsProvider` | the SDK |
+| Vercel AI SDK | `providers.vercel.VercelProvider` | the SDK |
+| LangGraph | `providers.langgraph.LangGraphProvider` | the prebuilt agent |
+| CrewAI | `providers.crewai.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.0}/README.md

@@ -2,7 +2,11 @@
 
 Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
 
-**Requires:** The `swytchcode` binary must be installed and on your `PATH`.
+**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
 
@@ -67,6 +71,13 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 
 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:
@@ -115,3 +126,58 @@ def create_account(input: dict) -> any:
 ```
 
 **Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
+
+## Agentic workflows (framework integrations)
+
+On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools
+into the native tool objects each agent framework expects. The Swytchcode part is the same
+two lines regardless of framework:
+
+```python
+from swytchcode_runtime import Swytchcode
+from swytchcode_runtime.providers.anthropic import AnthropicProvider
+
+swx = Swytchcode(provider=AnthropicProvider())
+tools = swx.tools.get(toolkits=["stripe"])   # framework-native tools, full param schemas
+```
+
+### 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 | `providers.anthropic.AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
+| OpenAI Agents SDK | `providers.openai_agents.OpenAIAgentsProvider` | the SDK |
+| Vercel AI SDK | `providers.vercel.VercelProvider` | the SDK |
+| LangGraph | `providers.langgraph.LangGraphProvider` | the prebuilt agent |
+| CrewAI | `providers.crewai.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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swytchcode-runtime"
-version = "0.1.0"
+version = "1.0.0"
 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.0/swytchcode_runtime/__init__.py

@@ -0,0 +1,24 @@
+"""Thin runtime wrapper around the Swytchcode CLI."""
+
+from .errors import SwytchcodeError, is_swytchcode_error
+from .exec import exec_ as exec
+from .client import Swytchcode
+from .providers import (
+    AnthropicProvider,
+    OpenAIAgentsProvider,
+    VercelProvider,
+    LangGraphProvider,
+    CrewAIProvider,
+)
+
+__all__ = [
+    "exec",
+    "Swytchcode",
+    "SwytchcodeError",
+    "is_swytchcode_error",
+    "AnthropicProvider",
+    "OpenAIAgentsProvider",
+    "VercelProvider",
+    "LangGraphProvider",
+    "CrewAIProvider",
+]

swytchcode_runtime-1.0.0/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

swytchcode_runtime-1.0.0/swytchcode_runtime/client.py

@@ -0,0 +1,133 @@
+"""High-level agentic client on top of the existing exec()."""
+
+from __future__ import annotations
+from typing import Any, Optional
+
+from . import discover as _discover, schema as _schema, manage as _manage
+from .exec import exec_ as _exec
+from .providers.base import Provider, Tool
+
+
+def _strip_empty(obj: Any) -> Any:
+    """Recursively drop keys whose value is None or an empty string ("").
+
+    With 'expose all fields', agents often fill unused optional fields with "",
+    which APIs like Stripe reject ("empty values are an attempt to unset").
+    Only None and "" are dropped — 0, False, [], {} are preserved as meaningful.
+    """
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            if v is None or (isinstance(v, str) and v == ""):
+                continue
+            out[k] = _strip_empty(v)
+        return out
+    if isinstance(obj, list):
+        return [_strip_empty(v) for v in obj]
+    return obj
+
+
+class _Tools:
+    def __init__(self, client: "Swytchcode"):
+        self._c = client
+        # Maps a sanitized tool name (dots -> underscores) back to its canonical
+        # ID, populated as tools are built. Used to reverse names in
+        # handle_tool_calls without a lossy "_"->"." string replace.
+        self._name_to_cid: dict[str, str] = {}
+
+    def get(self, *, toolkits=None, tools=None, search=None):
+        neutral = [self._tool(cid) for cid in self._ids(toolkits, tools, search)]
+        p = self._c.provider
+        return p.format_tools(neutral) if p else neutral
+
+    def execute(self, canonical_id: str, args: dict, **options) -> Any:
+        # If args are flat (no body/params top-level keys), wrap them in body
+        # as expected by the Swytchcode CLI kernel (like in run-workflow.js)
+        if "body" not in args and "params" not in args:
+            args = {"body": args}
+        # Drop empty optional fields (None/"") from body & params so values an
+        # agent over-filled don't reach the API (e.g. Stripe rejects customer="").
+        args = dict(args)
+        if isinstance(args.get("body"), (dict, list)):
+            args["body"] = _strip_empty(args["body"])
+        if isinstance(args.get("params"), (dict, list)):
+            args["params"] = _strip_empty(args["params"])
+        # Forward exec options (dry_run, raw, allow_raw, cwd, env) to the CLI.
+        return _exec(canonical_id, args, **options)
+
+    def _tool(self, cid: str) -> Tool:
+        m = _discover.info(cid)
+        name = cid.replace(".", "_")
+        self._name_to_cid[name] = cid
+        return Tool(
+            canonical_id=cid,
+            name=name,
+            description=m.get("summary") or m.get("description") or cid,
+            input_schema=_schema.simplify(m.get("inputs")),
+            execute=lambda args, _c=cid: self.execute(_c, args),
+        )
+
+    def _ids(self, toolkits, tools, search) -> list[str]:
+        # Implementation for Phase 1: resolve against CLI local state
+        if tools:
+            return tools
+        if search:
+            # Mirror the TS runtime: resolve a natural-language search to
+            # canonical IDs via the CLI's discover/search.
+            return [
+                t["canonical_id"]
+                for t in _discover.search(search)
+                if t.get("canonical_id")
+            ]
+        if toolkits:
+            # Resolve toolkits against local tooling.json instead of global search
+            res = _manage.list_tools("tooling")
+            found = []
+            for m in res.get("methods", []):
+                integration = m.get("integration", "")
+                cid = m.get("canonical_id")
+                if not cid:
+                    continue
+                for tk in toolkits:
+                    # integration is "project.library@version"; match the project
+                    # segment exactly, not a loose substring (so "hub" != "github").
+                    if tk == integration or integration.startswith(f"{tk}."):
+                        found.append(cid)
+                        break
+            return found
+        return []
+
+
+class Swytchcode:
+    def __init__(self, provider: Optional[Provider] = None):
+        self.provider = provider
+        self.tools = _Tools(self)
+
+    def handle_tool_calls(self, response: Any) -> list[dict]:
+        """Helper to execute tools for non-agentic APIs like Anthropic."""
+        results = []
+        for block in getattr(response, "content", []):
+            if getattr(block, "type", "") == "tool_use":
+                # Reverse the sanitized name via the map built in _tool(). A plain
+                # "_"->"." replace would corrupt canonical IDs whose segments
+                # contain underscores (e.g. stripe.create_payment).
+                cid = self.tools._name_to_cid.get(block.name) or block.name.replace(
+                    "_", "."
+                )
+                # Isolate failures per block so one failing tool doesn't drop the
+                # results for the other tool_use blocks in the same turn.
+                try:
+                    content = str(self.tools.execute(cid, getattr(block, "input", {})))
+                    is_error = False
+                except Exception as e:
+                    content = f"Error executing {cid}: {e}"
+                    is_error = True
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": content,
+                        "is_error": is_error,
+                    }
+                )
+        return results

swytchcode_runtime-1.0.0/swytchcode_runtime/discover.py

@@ -0,0 +1,29 @@
+"""Find tools by intent and read their schemas."""
+
+from __future__ import annotations
+import logging
+from .cli import run_cli
+
+logger = logging.getLogger(__name__)
+
+
+def search(intent: str, *, top: int = 5) -> list[dict]:
+    res = run_cli(["discover", intent, "--top", str(top)]) or {}
+    return res.get("capabilities", [])
+
+
+def info(canonical_id: str) -> dict:
+    try:
+        result = run_cli(["info", canonical_id]) or {}
+        # CLI returns a JSON array of ToolInfo objects; unwrap the first one
+        if isinstance(result, list):
+            return result[0] if result else {}
+        return result
+    except Exception as e:
+        # Broad by design: any CLI/parse failure degrades to an empty schema
+        # rather than breaking tool discovery. Logged (not printed) so it
+        # respects the host app's logging config.
+        logger.warning(
+            "Failed to fetch info for %s (%s). Using empty schema.", canonical_id, e
+        )
+        return {"canonical_id": canonical_id, "inputs": {}}

{swytchcode_runtime-0.1.0 → swytchcode_runtime-1.0.0}/swytchcode_runtime/exec.py

@@ -2,12 +2,54 @@
 
 import json
 import os
+import shutil
 import subprocess
+import sys
 from typing import Any
 
 from .errors import SwytchcodeError
 
 
+def _resolve_bin() -> str:
+    """
+    Resolve the swytchcode binary path using the following order:
+
+    1. SWYTCHCODE_BIN env var — explicit override.
+    2. PATH lookup via shutil.which — the standard resolution.
+    3. Common install-path fallbacks for when PATH is not configured.
+    """
+    # 1. Explicit override
+    explicit = os.environ.get("SWYTCHCODE_BIN", "").strip()
+    if explicit:
+        return explicit
+
+    # 2. PATH lookup
+    found = shutil.which("swytchcode")
+    if found:
+        return found
+
+    # 3. Common install-path fallbacks
+    if sys.platform == "win32":
+        local_app_data = os.environ.get("LOCALAPPDATA", "")
+        candidates = [
+            os.path.join(
+                local_app_data, "Programs", "swytchcode", "bin", "swytchcode.exe"
+            ),
+        ]
+    else:
+        home = os.path.expanduser("~")
+        candidates = [
+            os.path.join(home, ".local", "bin", "swytchcode"),
+            "/usr/local/bin/swytchcode",
+        ]
+
+    for path in candidates:
+        if path and os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+
+    return "swytchcode"  # fall through; subprocess.run reports FileNotFoundError if still missing
+
+
 def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
     canonical_id: str,
     input: Any = None,
@@ -50,7 +92,8 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
         raise SwytchcodeError("canonical_id must be a non-empty string")
 
     flag = "--raw" if raw else "--json"
-    cmd = ["swytchcode", "exec", canonical_id, flag]
+    bin_path = _resolve_bin()
+    cmd = [bin_path, "exec", canonical_id, flag]
     if dry_run:
         cmd.append("--dry-run")
     if allow_raw:
@@ -74,7 +117,12 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
             timeout=None,
         )
     except FileNotFoundError as e:
-        raise SwytchcodeError("Failed to spawn swytchcode", e) from e
+        hint = (
+            f"using binary at {bin_path!r}"
+            if "SWYTCHCODE_BIN" in os.environ
+            else "install it with: npm install -g swytchcode (or set SWYTCHCODE_BIN=/path/to/binary)"
+        )
+        raise SwytchcodeError(f"Failed to spawn swytchcode — {hint}", e) from e
     except OSError as e:
         raise SwytchcodeError("Failed to run swytchcode", e) from e
 

swytchcode_runtime-1.0.0/swytchcode_runtime/manage.py

@@ -0,0 +1,30 @@
+"""Management commands wrapper for the SDK."""
+
+from __future__ import annotations
+from .cli import run_cli
+
+
+def add(library_or_url: str) -> dict:
+    return run_cli(["add", library_or_url]) or {}
+
+
+def list_tools(filter_arg: str = "") -> dict:
+    args = ["list", "--json"]
+    if filter_arg:
+        args.insert(1, filter_arg)
+    return run_cli(args) or {}
+
+
+def keys() -> list[dict]:
+    return run_cli(["key", "list"]) or []
+
+
+def policies() -> list[dict]:
+    return run_cli(["policy", "list"]) or []
+
+
+def search(keyword: str = "") -> dict:
+    args = ["search", "--json"]
+    if keyword:
+        args.insert(1, keyword)
+    return run_cli(args) or {}

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/__init__.py

@@ -0,0 +1,15 @@
+"""Providers for integrating Swytchcode tools into various AI frameworks."""
+
+from .anthropic import AnthropicProvider
+from .crewai import CrewAIProvider
+from .langgraph import LangGraphProvider
+from .openai_agents import OpenAIAgentsProvider
+from .vercel import VercelProvider
+
+__all__ = [
+    "AnthropicProvider",
+    "CrewAIProvider",
+    "LangGraphProvider",
+    "OpenAIAgentsProvider",
+    "VercelProvider",
+]

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/anthropic.py

@@ -0,0 +1,13 @@
+"""Anthropic Claude provider (Non-agentic / raw tool use schemas)."""
+
+from __future__ import annotations
+from .base import Provider, Tool
+
+
+class AnthropicProvider(Provider):
+    def format_tool(self, tool: Tool):
+        return {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": tool.input_schema,
+        }

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/base.py

@@ -0,0 +1,31 @@
+"""Provider base for adapting neutral Swytchcode tools to each framework.
+
+A single Provider base: `format_tool` wraps one neutral Tool into a framework's
+native tool object, and `format_tools` maps over a list. Execution is carried on
+the Tool itself via its `execute` closure (which runs the Swytchcode CLI): agentic
+frameworks (OpenAI Agents, Vercel, LangGraph, CrewAI) invoke that closure directly
+during their own loop, while non-agentic APIs (Anthropic) run it through
+`Swytchcode.handle_tool_calls`. Note this is deliberately NOT Composio's two-class
+agentic/non-agentic split — execution lives on the tool, not an injected function.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass
+class Tool:
+    canonical_id: str
+    name: str
+    description: str
+    input_schema: dict
+    execute: Callable[[dict], Any]
+
+
+class Provider:
+    def format_tool(self, tool: Tool) -> Any:
+        raise NotImplementedError
+
+    def format_tools(self, tools: list[Tool]) -> list[Any]:
+        return [self.format_tool(t) for t in tools]

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/crewai.py

@@ -0,0 +1,22 @@
+"""CrewAI provider: neutral tools -> BaseTool subclasses."""
+
+from __future__ import annotations
+from .base import Provider, Tool
+
+
+class CrewAIProvider(Provider):
+    def format_tool(self, tool: Tool):
+        from crewai.tools import BaseTool
+        from ..schema import to_pydantic_model
+
+        args_schema_cls = to_pydantic_model(tool.input_schema, tool.name + "Schema")
+
+        class DynamicCrewTool(BaseTool):
+            name: str = tool.name
+            description: str = tool.description
+            args_schema: type = args_schema_cls
+
+            def _run(self, **kwargs):
+                return tool.execute(kwargs)
+
+        return DynamicCrewTool()

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/langgraph.py

@@ -0,0 +1,17 @@
+"""LangGraph provider: neutral tools -> LangChain StructuredTool objects."""
+
+from __future__ import annotations
+from .base import Provider, Tool
+
+
+class LangGraphProvider(Provider):
+    def format_tool(self, tool: Tool):
+        from langchain_core.tools import StructuredTool
+        from ..schema import to_pydantic_model
+
+        return StructuredTool.from_function(
+            name=tool.name,
+            description=tool.description,
+            func=lambda **kwargs: tool.execute(kwargs),
+            args_schema=to_pydantic_model(tool.input_schema, tool.name + "Schema"),
+        )

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/openai_agents.py

@@ -0,0 +1,30 @@
+"""OpenAI Agents SDK provider."""
+
+from __future__ import annotations
+import asyncio
+import json
+from .base import Provider, Tool
+
+
+class OpenAIAgentsProvider(Provider):
+    def format_tool(self, tool: Tool):
+        try:
+            from agents import FunctionTool
+        except ImportError:
+            raise ImportError(
+                "Please install the OpenAI Agents SDK: pip install openai-agents"
+            )
+
+        async def _on_invoke(ctx, args: str):
+            kwargs = json.loads(args) if args else {}
+            # tool.execute drives the CLI through a blocking subprocess; offload
+            # it to a worker thread so we never stall the agent's event loop.
+            return await asyncio.to_thread(tool.execute, kwargs)
+
+        return FunctionTool(
+            name=str(tool.name).replace(".", "_"),
+            description=str(tool.description),
+            params_json_schema=tool.input_schema,
+            on_invoke_tool=_on_invoke,
+            strict_json_schema=False,
+        )

swytchcode_runtime-1.0.0/swytchcode_runtime/providers/vercel.py

@@ -0,0 +1,30 @@
+"""Vercel AI SDK provider (Python equivalent)."""
+
+from __future__ import annotations
+from .base import Provider, Tool
+
+
+class VercelProvider(Provider):
+    def format_tool(self, tool: Tool):
+        try:
+            from ai_sdk import tool as vercel_tool
+        except ImportError:
+            raise ImportError(
+                "Please install the Vercel AI SDK (requires Python 3.12+): pip install ai-sdk-python"
+            )
+
+        # The handler MUST be synchronous. ai_sdk's sync generate_text() calls the
+        # tool handler without awaiting it, so an async handler is silently never
+        # awaited — the tool never runs and the model hallucinates success. A sync
+        # handler returns a plain value that works in generate_text AND is fine for
+        # the async Tool.run path (which only awaits awaitables). Called as
+        # handler(**kwargs) — arguments by field name, never a positional dict.
+        def _execute(**kwargs):
+            return tool.execute(kwargs)
+
+        return vercel_tool(
+            name=tool.name,
+            description=tool.description,
+            parameters=tool.input_schema,
+            execute=_execute,
+        )

swytchcode_runtime-1.0.0/swytchcode_runtime/schema.py

@@ -0,0 +1,111 @@
+"""Simplify a tool's input schema for the LLM: expose all fields, mark required ones."""
+
+from __future__ import annotations
+from typing import Any, Optional
+
+
+def simplify(inputs: Any) -> dict:
+    # Handle Wrekenfile shape: a list of single-key dicts (e.g. [{"amount": {"TYPE": "INT"...}}])
+    if isinstance(inputs, list):
+        props = {}
+        required = []
+        for item in inputs:
+            if not isinstance(item, dict):
+                continue
+            for name, spec in item.items():
+                if not isinstance(spec, dict):
+                    continue
+
+                # Default to string if TYPE is missing
+                t = spec.get("TYPE", "STRING").lower()
+                if t == "int":
+                    t = "integer"
+                elif t in ("float", "number", "double"):
+                    t = "number"
+                elif t == "bool":
+                    t = "boolean"
+                elif t == "object":
+                    t = "object"
+                elif t == "any":
+                    t = "object"
+                elif t.startswith("[]"):
+                    t = "array"
+                else:
+                    t = "string"
+
+                props[name] = {"type": t, "description": spec.get("DESC", "")}
+
+                req = spec.get("REQUIRED", False)
+                is_required = req is True or (
+                    isinstance(req, str) and req.strip().lower() == "true"
+                )
+                if is_required:
+                    required.append(name)
+
+        # Composio-style rule: expose ALL fields to the model and list only the
+        # truly-required ones in `required`. A required-only approach hid optional
+        # fields — which left all-optional tools (e.g. Stripe) with an empty schema
+        # so the model called them with no arguments, and blinded the model to
+        # optional fields on tools that do have some required ones.
+        return {"type": "object", "properties": props, "required": required}
+
+    # Fallback to standard JSON Schema handling
+    if not isinstance(inputs, dict):
+        return {"type": "object", "properties": {}, "required": []}
+
+    props = inputs.get("properties") or {}
+    required = inputs.get("required") or []
+    keep = {}
+
+    # Expose all fields (same rule as the wrekenfile branch above); use the
+    # original required list only for the `required` key so optional/nested
+    # fields stay optional instead of being dropped or forced required.
+    for name, spec in props.items():
+        if (
+            isinstance(spec, dict)
+            and spec.get("type") == "object"
+            and "properties" in spec
+        ):
+            spec = simplify(spec)  # recurse into nested objects
+        keep[name] = spec
+
+    return {
+        "type": "object",
+        "properties": keep,
+        "required": [r for r in required if r in keep],
+    }
+
+
+def to_pydantic_model(schema: dict, name: str = "ArgsSchema") -> Any:
+    """Dynamically build a Pydantic model from a JSON schema for LangGraph args_schema."""
+    from pydantic import create_model
+
+    if not schema or "properties" not in schema:
+        return create_model(name)
+
+    fields = {}
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    for field_name, field_info in properties.items():
+        field_type = str
+        t = field_info.get("type")
+        if t == "integer":
+            field_type = int
+        elif t == "number":
+            field_type = float
+        elif t == "boolean":
+            field_type = bool
+        elif t == "array":
+            field_type = list
+        elif t == "object":
+            field_type = to_pydantic_model(field_info, f"{name}_{field_name}")
+
+        if field_name in required:
+            fields[field_name] = (field_type, ...)
+        else:
+            # Optional[...] so an explicit null is accepted (pydantic v2 rejects
+            # None for a bare non-optional annotation).
+            fields[field_name] = (Optional[field_type], None)
+
+    return create_model(name, **fields)

{swytchcode_runtime-0.1.0 → swytchcode_runtime-1.0.0}/swytchcode_runtime.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: swytchcode-runtime
-Version: 0.1.0
+Version: 1.0.0
 Summary: Thin runtime wrapper around the Swytchcode CLI
 Author: Swytchcode
 License: MIT
-Project-URL: repository, https://gitlab.com/swytchcode/py-runtime
+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
@@ -13,12 +13,18 @@ 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` binary must be installed and on your `PATH`.
+**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
 
@@ -83,6 +89,13 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 
 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:
@@ -131,3 +144,58 @@ def create_account(input: dict) -> any:
 ```
 
 **Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
+
+## Agentic workflows (framework integrations)
+
+On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools
+into the native tool objects each agent framework expects. The Swytchcode part is the same
+two lines regardless of framework:
+
+```python
+from swytchcode_runtime import Swytchcode
+from swytchcode_runtime.providers.anthropic import AnthropicProvider
+
+swx = Swytchcode(provider=AnthropicProvider())
+tools = swx.tools.get(toolkits=["stripe"])   # framework-native tools, full param schemas
+```
+
+### 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 | `providers.anthropic.AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
+| OpenAI Agents SDK | `providers.openai_agents.OpenAIAgentsProvider` | the SDK |
+| Vercel AI SDK | `providers.vercel.VercelProvider` | the SDK |
+| LangGraph | `providers.langgraph.LangGraphProvider` | the prebuilt agent |
+| CrewAI | `providers.crewai.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.0/swytchcode_runtime.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE.md
+README.md
+pyproject.toml
+swytchcode_runtime/__init__.py
+swytchcode_runtime/cli.py
+swytchcode_runtime/client.py
+swytchcode_runtime/discover.py
+swytchcode_runtime/errors.py
+swytchcode_runtime/exec.py
+swytchcode_runtime/manage.py
+swytchcode_runtime/schema.py
+swytchcode_runtime.egg-info/PKG-INFO
+swytchcode_runtime.egg-info/SOURCES.txt
+swytchcode_runtime.egg-info/dependency_links.txt
+swytchcode_runtime.egg-info/top_level.txt
+swytchcode_runtime/providers/__init__.py
+swytchcode_runtime/providers/anthropic.py
+swytchcode_runtime/providers/base.py
+swytchcode_runtime/providers/crewai.py
+swytchcode_runtime/providers/langgraph.py
+swytchcode_runtime/providers/openai_agents.py
+swytchcode_runtime/providers/vercel.py

swytchcode_runtime-0.1.0/swytchcode_runtime/__init__.py

@@ -1,6 +0,0 @@
-"""Thin runtime wrapper around the Swytchcode CLI."""
-
-from .errors import SwytchcodeError, is_swytchcode_error
-from .exec import exec_ as exec
-
-__all__ = ["exec", "SwytchcodeError", "is_swytchcode_error"]

swytchcode_runtime-0.1.0/swytchcode_runtime.egg-info/SOURCES.txt

@@ -1,9 +0,0 @@
-README.md
-pyproject.toml
-swytchcode_runtime/__init__.py
-swytchcode_runtime/errors.py
-swytchcode_runtime/exec.py
-swytchcode_runtime.egg-info/PKG-INFO
-swytchcode_runtime.egg-info/SOURCES.txt
-swytchcode_runtime.egg-info/dependency_links.txt
-swytchcode_runtime.egg-info/top_level.txt