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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swytchcode-runtime
-Version: 1.0.0
+Version: 1.0.2
 Summary: Thin runtime wrapper around the Swytchcode CLI
 Author: Swytchcode
 License: MIT
@@ -147,39 +147,74 @@ def create_account(input: dict) -> any:
 
 ## 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:
+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
 
-swx = Swytchcode(provider=AnthropicProvider())
-tools = swx.tools.get(toolkits=["stripe"])   # framework-native tools, full param schemas
+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(...)`
+### 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`).
+- `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
+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 |
+| 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)
 

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/README.md

@@ -129,39 +129,74 @@ def create_account(input: dict) -> any:
 
 ## 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:
+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
 
-swx = Swytchcode(provider=AnthropicProvider())
-tools = swx.tools.get(toolkits=["stripe"])   # framework-native tools, full param schemas
+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(...)`
+### 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`).
+- `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
+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 |
+| 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)
 

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swytchcode-runtime"
-version = "1.0.0"
+version = "1.0.2"
 description = "Thin runtime wrapper around the Swytchcode CLI"
 readme = "README.md"
 license = { text = "MIT" }

swytchcode_runtime-1.0.2/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.2/swytchcode_runtime/client.py

@@ -0,0 +1,243 @@
+"""High-level agentic client on top of the existing exec()."""
+
+from __future__ import annotations
+from typing import Any, Optional
+
+import re
+import hashlib
+
+from . import discover as _discover, schema as _schema, manage as _manage
+from .exec import exec_ as _exec
+from .providers.base import Provider, Tool
+
+
+MAX_TOOL_NAME_LEN = 64  # OpenAI and Anthropic strict limit
+
+
+def _make_alias(cid: str, taken: dict[str, str]) -> str:
+    base = re.sub(r"[^a-zA-Z0-9_-]", "_", cid)
+    existing = taken.get(base)
+    needs_hash = len(base) > MAX_TOOL_NAME_LEN or (existing and existing != cid)
+
+    if not needs_hash:
+        return base
+
+    h = hashlib.sha1(cid.encode("utf-8")).hexdigest()[:6]
+    keep = MAX_TOOL_NAME_LEN - 1 - len(h)
+    return base[:keep] + "_" + h
+
+
+def _toolkit_matches(toolkit: str, integration: str) -> bool:
+    """Case-insensitive match of a toolkit name against an integration string.
+
+    integration has the shape "ProjectDisplayName.library_slug@version"
+    (e.g. "GitHub.github@1.1.4"). We compare against both the project name
+    and the library slug so that ``toolkits=["github"]`` matches regardless
+    of the capitalised display name.
+    """
+    tk = toolkit.lower()
+    # Strip version: "GitHub.github@1.1.4" → "GitHub.github"
+    at_idx = integration.find("@")
+    prefix = integration[:at_idx] if at_idx != -1 else integration
+    # Split project.library: "GitHub.github" → ("GitHub", "github")
+    dot_idx = prefix.find(".")
+    if dot_idx != -1:
+        project = prefix[:dot_idx].lower()
+        lib_slug = prefix[dot_idx + 1 :].lower()
+    else:
+        project = prefix.lower()
+        lib_slug = ""
+    return tk == project or tk == lib_slug or tk == prefix.lower()
+
+
+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
+
+
+def _split_by_location(inputs: Any, flat_args: dict) -> dict:
+    """Route flat args into body/params based on LOCATION metadata from wrekenfile."""
+    body = {}
+    params = {}
+    # inputs is the raw wrekenfile list-of-single-key-dicts with LOCATION, or a JSON schema dict
+    locations = {}
+
+    if isinstance(inputs, list):
+        for item in inputs:
+            if isinstance(item, dict):
+                for name, spec in item.items():
+                    if isinstance(spec, dict):
+                        loc = str(
+                            spec.get("LOCATION", spec.get("location", "body"))
+                        ).lower()
+                        locations[name] = loc
+    elif isinstance(inputs, dict) and isinstance(inputs.get("properties"), dict):
+        for name, spec in inputs["properties"].items():
+            if isinstance(spec, dict):
+                loc = str(spec.get("LOCATION", spec.get("location", "body"))).lower()
+                locations[name] = loc
+
+    for key, val in flat_args.items():
+        loc = locations.get(key, "body")
+        if loc in ("path", "query"):
+            params[key] = val
+        else:
+            body[key] = val
+
+    result = {}
+    if body:
+        result["body"] = body
+    if params:
+        result["params"] = params
+    return result if result else {"body": flat_args}
+
+
+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] = {}
+        self._cid_to_inputs: dict[str, Any] = {}
+
+    def get(self, *, toolkits=None, tools=None, search=None):
+        # Sort canonical IDs lexicographically before alias assignment.
+        # This ensures deterministic assignment order across runs, guaranteeing the
+        # same canonical ID always receives the exact same alias (and same hash if colliding).
+        ids = sorted(self._ids(toolkits, tools, search))
+        neutral = [self._tool(cid) for cid in ids]
+        p = self._c.provider
+        return p.format_tools(neutral) if p else neutral
+
+    def execute(self, canonical_id: str, args: dict, **options) -> Any:
+        final_args = dict(args)
+
+        # 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 final_args and "params" not in final_args:
+            raw_inputs = options.pop("_raw_inputs", None)
+            if raw_inputs is not None:
+                final_args = _split_by_location(raw_inputs, final_args)
+            else:
+                final_args = {"body": final_args}
+        else:
+            options.pop("_raw_inputs", None)
+
+        # Drop empty optional fields (None/"") from body & params so values an
+        # agent over-filled don't reach the API (e.g. Stripe rejects customer="").
+        if isinstance(final_args.get("body"), (dict, list)):
+            final_args["body"] = _strip_empty(final_args["body"])
+        if isinstance(final_args.get("params"), (dict, list)):
+            final_args["params"] = _strip_empty(final_args["params"])
+        # Forward exec options (dry_run, raw, allow_raw, cwd, env) to the CLI.
+        return _exec(canonical_id, final_args, **options)
+
+    def _tool(self, cid: str) -> Tool:
+        m = _discover.info(cid)
+        if not m or not m.get("inputs"):
+            raise ValueError(
+                f"Tool discovery failed for {cid}: Invalid or missing Wrekenfile schema"
+            )
+
+        name = _make_alias(cid, self._name_to_cid)
+
+        self._name_to_cid[name] = cid
+        raw_inputs = m.get("inputs")
+        self._cid_to_inputs[cid] = raw_inputs
+        return Tool(
+            canonical_id=cid,
+            name=name,
+            description=m.get("summary") or m.get("description") or cid,
+            input_schema=_schema.simplify(raw_inputs),
+            execute=lambda args, _c=cid, _inputs=raw_inputs: self.execute(
+                _c, args, _raw_inputs=_inputs
+            ),
+        )
+
+    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:
+                    if _toolkit_matches(tk, integration):
+                        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, timeout: float | None = None
+    ) -> 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(
+                    "_", "."
+                )
+                raw_inputs = self.tools._cid_to_inputs.get(cid, {})
+                # 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", {}),
+                            _raw_inputs=raw_inputs,
+                            timeout=timeout,
+                        )
+                    )
+                    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-1.0.2}/swytchcode_runtime/exec.py

@@ -59,6 +59,7 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
     raw: bool = False,
     dry_run: bool = False,
     allow_raw: bool = False,
+    timeout: float | None = None,
 ) -> Any:
     """
     Run swytchcode exec <canonical_id> with optional JSON args on stdin.
@@ -80,6 +81,7 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
         raw: If True, use --raw and return stdout as a string.
         dry_run: If True, pass --dry-run; request details are output instead of calling the server.
         allow_raw: If True, pass --allow-raw; required for executing raw methods (kernel default is disabled).
+        timeout: Optional timeout in seconds for the subprocess.
 
     Returns:
         Parsed result (any) or raw string when raw is True.
@@ -114,8 +116,12 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
             capture_output=True,
             cwd=cwd or os.getcwd(),
             env=run_env,
-            timeout=None,
+            timeout=timeout,
         )
+    except subprocess.TimeoutExpired as e:
+        raise SwytchcodeError(
+            f"swytchcode exec timed out after {timeout} seconds", e
+        ) from e
     except FileNotFoundError as e:
         hint = (
             f"using binary at {bin_path!r}"

swytchcode_runtime-1.0.2/swytchcode_runtime/providers/__init__.py

@@ -0,0 +1,27 @@
+"""Providers for integrating Swytchcode tools into various AI frameworks."""
+
+__all__ = [
+    "AnthropicProvider",
+    "CrewAIProvider",
+    "LangGraphProvider",
+    "OpenAIAgentsProvider",
+    "VercelProvider",
+]
+
+
+def __getattr__(name):
+    """Lazy provider imports for backward compatibility."""
+    _provider_map = {
+        "AnthropicProvider": "anthropic",
+        "OpenAIAgentsProvider": "openai_agents",
+        "VercelProvider": "vercel",
+        "LangGraphProvider": "langgraph",
+        "CrewAIProvider": "crewai",
+    }
+    if name in _provider_map:
+        module_name = _provider_map[name]
+        import importlib
+
+        mod = importlib.import_module(f".{module_name}", __package__)
+        return getattr(mod, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/swytchcode_runtime/providers/base.py

@@ -6,7 +6,7 @@ the Tool itself via its `execute` closure (which runs the Swytchcode CLI): agent
 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.
+agentic/non-agentic split - execution lives on the tool, not an injected function.
 """
 
 from __future__ import annotations

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/swytchcode_runtime/providers/openai_agents.py

@@ -22,7 +22,7 @@ class OpenAIAgentsProvider(Provider):
             return await asyncio.to_thread(tool.execute, kwargs)
 
         return FunctionTool(
-            name=str(tool.name).replace(".", "_"),
+            name=str(tool.name),
             description=str(tool.description),
             params_json_schema=tool.input_schema,
             on_invoke_tool=_on_invoke,

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/swytchcode_runtime/providers/vercel.py

@@ -15,10 +15,10 @@ class VercelProvider(Provider):
 
         # 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
+        # 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.
+        # handler(**kwargs) - arguments by field name, never a positional dict.
         def _execute(**kwargs):
             return tool.execute(kwargs)
 

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/swytchcode_runtime/schema.py

@@ -36,15 +36,18 @@ def simplify(inputs: Any) -> dict:
                 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"
+                loc = str(spec.get("LOCATION", spec.get("location", ""))).lower()
+                is_required = (
+                    loc == "path"
+                    or 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
+        # 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}
@@ -61,12 +64,13 @@ def simplify(inputs: Any) -> dict:
     # 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
+        if isinstance(spec, dict):
+            loc = str(spec.get("LOCATION", spec.get("location", ""))).lower()
+            if loc == "path" and name not in required:
+                required.append(name)
+
+            if spec.get("type") == "object" and "properties" in spec:
+                spec = simplify(spec)  # recurse into nested objects
         keep[name] = spec
 
     return {

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swytchcode-runtime
-Version: 1.0.0
+Version: 1.0.2
 Summary: Thin runtime wrapper around the Swytchcode CLI
 Author: Swytchcode
 License: MIT
@@ -147,39 +147,74 @@ def create_account(input: dict) -> any:
 
 ## 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:
+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
 
-swx = Swytchcode(provider=AnthropicProvider())
-tools = swx.tools.get(toolkits=["stripe"])   # framework-native tools, full param schemas
+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(...)`
+### 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`).
+- `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
+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 |
+| 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)
 

{swytchcode_runtime-1.0.0 → swytchcode_runtime-1.0.2}/swytchcode_runtime.egg-info/SOURCES.txt

@@ -19,4 +19,6 @@ 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/providers/vercel.py
+tests/test_alias.py
+tests/test_schema_routing.py

swytchcode_runtime-1.0.2/tests/test_alias.py

@@ -0,0 +1,42 @@
+import unittest
+from swytchcode_runtime.client import Swytchcode, _make_alias
+from unittest.mock import patch
+
+
+class TestAlias(unittest.TestCase):
+    @patch("swytchcode_runtime.discover.info")
+    @patch("swytchcode_runtime.discover.search")
+    def test_deterministic_alias(self, mock_search, mock_info):
+        long_id = "google_workspace_admin_directory_users_aliases_insert_extra_padding_to_exceed_limit"
+        mock_search.return_value = [{"canonical_id": long_id}]
+        mock_info.return_value = {
+            "inputs": {"email": {"TYPE": "STRING"}},
+            "summary": "Test tool",
+        }
+
+        client = Swytchcode()
+        tools = client.tools.get(search="test")
+        self.assertEqual(len(tools), 1)
+        alias = tools[0].name
+
+        self.assertLessEqual(len(alias), 64)
+
+        # Test determinism
+        client2 = Swytchcode()
+        tools2 = client2.tools.get(search="test")
+        self.assertEqual(tools2[0].name, alias)
+
+        # Test collision
+        taken = {}
+        alias1 = _make_alias("a.b", taken)
+        taken[alias1] = "a.b"
+        alias2 = _make_alias("a_b", taken)  # Collides on sanitize
+
+        self.assertNotEqual(alias1, alias2)
+        
+        import re
+        self.assertTrue(re.search(r"_[0-9a-f]{6}$", alias2) or re.search(r"_[0-9a-f]{6}$", alias1))
+
+
+if __name__ == "__main__":
+    unittest.main()

swytchcode_runtime-1.0.2/tests/test_schema_routing.py

@@ -0,0 +1,62 @@
+import unittest
+from swytchcode_runtime.schema import simplify
+
+
+class TestSchemaRouting(unittest.TestCase):
+    def test_path_params_required(self):
+        raw_schema = [
+            {"userId": {"TYPE": "STRING", "LOCATION": "path", "DESC": "The user ID"}},
+            {"amount": {"TYPE": "INT", "LOCATION": "query"}},
+        ]
+
+        simplified = simplify(raw_schema)
+
+        # Path parameters should be required
+        self.assertIn("userId", simplified["required"])
+        self.assertEqual(simplified["properties"]["userId"]["type"], "string")
+        self.assertEqual(simplified["properties"]["amount"]["type"], "integer")
+
+    def test_json_schema_path_params_required(self):
+        raw_schema = {
+            "type": "object",
+            "properties": {
+                "owner": {"type": "string", "location": "path"},
+                "repo": {"type": "string", "location": "path"},
+                "title": {"type": "string", "location": "body"},
+            },
+        }
+        simplified = simplify(raw_schema)
+        self.assertIn("owner", simplified["required"])
+        self.assertIn("repo", simplified["required"])
+        self.assertNotIn("title", simplified["required"])
+
+    def test_split_by_location_json_schema(self):
+        from swytchcode_runtime.client import _split_by_location
+
+        raw_schema = {
+            "type": "object",
+            "properties": {
+                "owner": {"type": "string", "location": "path"},
+                "title": {"type": "string", "location": "body"},
+            },
+        }
+        args = {"owner": "swytchcode", "title": "hello"}
+        result = _split_by_location(raw_schema, args)
+        self.assertEqual(result.get("params", {}).get("owner"), "swytchcode")
+        self.assertEqual(result.get("body", {}).get("title"), "hello")
+
+    def test_split_by_location_array_wreken_shape(self):
+        from swytchcode_runtime.client import _split_by_location
+
+        raw_schema = [
+            {"owner": {"TYPE": "STRING", "LOCATION": "path"}},
+            {"title": {"TYPE": "STRING", "LOCATION": "body"}},
+        ]
+        args = {"owner": "swytchcode", "title": "hello"}
+        result = _split_by_location(raw_schema, args)
+        self.assertEqual(result.get("params", {}).get("owner"), "swytchcode")
+        self.assertEqual(result.get("body", {}).get("title"), "hello")
+
+
+if __name__ == "__main__":
+    unittest.main()

swytchcode_runtime-1.0.0/swytchcode_runtime/__init__.py

@@ -1,24 +0,0 @@
-"""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/client.py

@@ -1,133 +0,0 @@
-"""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/providers/__init__.py

@@ -1,15 +0,0 @@
-"""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",
-]