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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. swytchcode_runtime-1.1.1/PKG-INFO +292 -0
  2. swytchcode_runtime-1.1.1/README.md +274 -0
  3. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/pyproject.toml +1 -1
  4. swytchcode_runtime-1.1.1/swytchcode_runtime/__init__.py +32 -0
  5. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/cli.py +3 -1
  6. swytchcode_runtime-1.1.1/swytchcode_runtime/client.py +244 -0
  7. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/discover.py +3 -1
  8. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/errors.py +10 -1
  9. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/exec.py +41 -3
  10. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/manage.py +1 -0
  11. swytchcode_runtime-1.1.1/swytchcode_runtime/prompts.py +19 -0
  12. swytchcode_runtime-1.1.1/swytchcode_runtime/providers/__init__.py +27 -0
  13. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/anthropic.py +1 -0
  14. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/base.py +6 -3
  15. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/crewai.py +2 -0
  16. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/langgraph.py +2 -0
  17. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/openai_agents.py +3 -1
  18. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/vercel.py +3 -2
  19. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/schema.py +19 -16
  20. swytchcode_runtime-1.1.1/swytchcode_runtime.egg-info/PKG-INFO +292 -0
  21. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime.egg-info/SOURCES.txt +6 -1
  22. swytchcode_runtime-1.1.1/tests/test_alias.py +42 -0
  23. swytchcode_runtime-1.1.1/tests/test_exec_errors.py +36 -0
  24. swytchcode_runtime-1.1.1/tests/test_prompts.py +21 -0
  25. swytchcode_runtime-1.1.1/tests/test_schema_routing.py +62 -0
  26. swytchcode_runtime-1.0.0/PKG-INFO +0 -201
  27. swytchcode_runtime-1.0.0/README.md +0 -183
  28. swytchcode_runtime-1.0.0/swytchcode_runtime/__init__.py +0 -24
  29. swytchcode_runtime-1.0.0/swytchcode_runtime/client.py +0 -133
  30. swytchcode_runtime-1.0.0/swytchcode_runtime/providers/__init__.py +0 -15
  31. swytchcode_runtime-1.0.0/swytchcode_runtime.egg-info/PKG-INFO +0 -201
  32. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/LICENSE.md +0 -0
  33. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/setup.cfg +0 -0
  34. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime.egg-info/dependency_links.txt +0 -0
  35. {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime.egg-info/top_level.txt +0 -0
@@ -0,0 +1,292 @@
1
+ Metadata-Version: 2.4
2
+ Name: swytchcode-runtime
3
+ Version: 1.1.1
4
+ Summary: Thin runtime wrapper around the Swytchcode CLI
5
+ Author: Swytchcode
6
+ License: MIT
7
+ Project-URL: repository, https://github.com/swytchcodehq/runtime-py
8
+ Keywords: swytchcode,cli,runtime,exec
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE.md
17
+ Dynamic: license-file
18
+
19
+ # swytchcode-runtime (Python)
20
+
21
+ Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
22
+
23
+ **Requires:** The `swytchcode` CLI must be installed. The binary is located automatically - no configuration needed in most environments. Resolution order:
24
+
25
+ 1. `SWYTCHCODE_BIN` env var - explicit override.
26
+ 2. `$PATH` lookup via `shutil.which` - the standard system resolution.
27
+ 3. Common install paths - `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ pip install swytchcode-runtime
33
+ ```
34
+
35
+ Or from the repo:
36
+
37
+ ```bash
38
+ pip install /path/to/runtime-libraries/python-runtime
39
+ ```
40
+
41
+ ## Use
42
+
43
+ ### JSON mode (default)
44
+
45
+ ```python
46
+ from swytchcode_runtime import exec
47
+
48
+ result = exec("api.account.create", {"email": "test@example.com"})
49
+ # result is parsed JSON (any)
50
+ ```
51
+
52
+ Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
53
+
54
+ **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:
55
+ - **body** - Request body (dict).
56
+ - **params** - Query/path params (e.g. `{"id": "cluster-123"}`).
57
+ - **Authorization** - Auth header value (e.g. `"Bearer token123"`).
58
+ - **headers** - Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
59
+ - Other top-level keys are passed as query params.
60
+
61
+ Example with body, params, and headers:
62
+
63
+ ```python
64
+ exec("api.cluster.get", {
65
+ "params": {"id": "cluster-123"},
66
+ "Authorization": "Bearer token123",
67
+ "headers": {"X-Request-Id": "abc-123"},
68
+ })
69
+ ```
70
+
71
+ ### Raw mode
72
+
73
+ Get stdout as a string instead of parsing JSON:
74
+
75
+ ```python
76
+ from swytchcode_runtime import exec
77
+
78
+ output = exec("api.report.export", {"id": "123"}, raw=True)
79
+ # output is the raw stdout string
80
+ ```
81
+
82
+ ### Options
83
+
84
+ - **cwd** - Working directory for the process (default: current directory).
85
+ - **env** - Extra environment variables (merged with `os.environ`).
86
+ - **raw** - If `True`, use `--raw` and return stdout as a string.
87
+ - **dry_run** - If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
88
+ - **allow_raw** - If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
89
+
90
+ This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
91
+
92
+ ### Environment variables
93
+
94
+ This runtime itself needs no environment configuration to run - all auth lives in the CLI's own session (`swytchcode login`, stored under `~/.swytchcode/`) or in `.swytchcode/` in your project. The variables below are for the rarer cases where you need to override that:
95
+
96
+ | Variable | Description |
97
+ |----------|-------------|
98
+ | `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). |
99
+ | `SWYTCHCODE_TOKEN` | Service-token auth for headless environments (CI, servers) where an interactive `swytchcode login` isn't possible. Not needed for local development once you've run `swytchcode login`. |
100
+
101
+ ### Error handling
102
+
103
+ Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
104
+
105
+ ```python
106
+ from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
107
+
108
+ try:
109
+ exec("api.account.create", {"email": "test@example.com"})
110
+ except Exception as e:
111
+ if is_swytchcode_error(e):
112
+ print(e.message, e.cause)
113
+ raise
114
+ ```
115
+
116
+ On a non-zero exit the CLI writes a classified JSON error to stderr; `exec()` parses it into a clean `.message` and a structured `.details` dict (`category`, `retryable`, `suggested_action`, `docs_url`) instead of leaving you to parse the raw JSON yourself:
117
+
118
+ ```python
119
+ except SwytchcodeError as e:
120
+ if e.details and e.details.get("category") == "auth":
121
+ print(e.details.get("suggested_action"))
122
+ ```
123
+
124
+ ## What this library is
125
+
126
+ - A thin process wrapper over the Swytchcode shell.
127
+ - A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
128
+ - A convenience for developers and IDE agents.
129
+
130
+ ## What this library is not
131
+
132
+ - An HTTP SDK or API client.
133
+ - A replacement for the shell. All authority stays in the Swytchcode CLI.
134
+
135
+ This library **must not** and **does not**:
136
+
137
+ - Read `.swytchcode/*` or parse `tooling.json`.
138
+ - Validate schemas or add retries/timeouts.
139
+ - Call the registry or embed auth logic.
140
+
141
+ It is a pipe, not a brain.
142
+
143
+ ## For Cursor / IDE agents
144
+
145
+ Generate code that uses this runtime instead of subprocess boilerplate.
146
+
147
+ **Preferred:**
148
+
149
+ ```python
150
+ from swytchcode_runtime import exec
151
+
152
+ def create_account(input: dict) -> any:
153
+ return exec("api.account.create", input)
154
+ ```
155
+
156
+ **Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
157
+
158
+ ## Agentic workflows (framework integrations)
159
+
160
+ For full, production-ready examples across all major frameworks, check out the [Swytchcode Examples Repository](https://github.com/swytchcodehq/swytchcode-examples).
161
+
162
+ On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects.
163
+
164
+ ### Tool-use guidance - `TOOL_USE_INSTRUCTIONS`
165
+
166
+ Without an explicit nudge, models can be conservative about side-effecting actions (starring a repo, sending a payment, creating an issue) - they'll describe what they *would* do instead of actually calling the tool. `TOOL_USE_INSTRUCTIONS` is a short, framework-agnostic string that fixes this; concatenate it into whatever your provider calls its system prompt / instructions. It's scoped to only the tools this library provides, so it's safe to combine with instructions for other, unrelated tools in the same system prompt:
167
+
168
+ ```python
169
+ from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
170
+
171
+ system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
172
+ ```
173
+
174
+ ### Quickstart: Anthropic SDK
175
+
176
+ Here is a clean example of building a simple agent using the Anthropic SDK. It stars the [Swytchcode Examples repo](https://github.com/swytchcodehq/swytchcode-examples) on GitHub - a genuine OAuth-connected action (not just an API key passed on the request), so the setup below covers the real one-time flow: installing the CLI, logging in, and connecting a GitHub account.
177
+
178
+ **One-time setup** (run once per machine/project):
179
+
180
+ ```bash
181
+ # 1. Install the CLI (macOS/Linux; see https://cli.swytchcode.com for other platforms)
182
+ curl -fsSL https://cli.swytchcode.com/install.sh | sh
183
+
184
+ # 2. Scaffold .swytchcode/ + tooling.json in your project
185
+ swytchcode init
186
+
187
+ # 3. Log in (opens a browser; creates your Swytchcode session)
188
+ swytchcode login
189
+
190
+ # 4. Fetch the GitHub integration
191
+ swytchcode get github
192
+
193
+ # 5. Enable the "star a repo" tool - the trust boundary for what this project can call
194
+ swytchcode add user.starred.update
195
+
196
+ # 6. Connect your GitHub account (opens a browser for the OAuth flow)
197
+ swytchcode auth connect github
198
+ ```
199
+
200
+ Then add your Anthropic key to a `.env` file in your project root (used by `python-dotenv` below):
201
+
202
+ ```bash
203
+ # .env
204
+ ANTHROPIC_API_KEY=sk-ant-...
205
+ ```
206
+
207
+ **Installation:**
208
+ ```bash
209
+ pip install swytchcode-runtime anthropic python-dotenv
210
+ ```
211
+ *(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.)*
212
+
213
+ **Example:**
214
+ ```python
215
+ import os
216
+ from dotenv import load_dotenv
217
+ import anthropic
218
+ from swytchcode_runtime import Swytchcode, TOOL_USE_INSTRUCTIONS
219
+ from swytchcode_runtime.providers.anthropic import AnthropicProvider
220
+
221
+ load_dotenv() # Loads .env automatically
222
+
223
+ def run_agent():
224
+ client = anthropic.Anthropic()
225
+
226
+ # 1. Initialize Swytchcode with the Anthropic provider
227
+ swx = Swytchcode(provider=AnthropicProvider())
228
+
229
+ # 2. Fetch the tools you want your agent to use (e.g., GitHub tools)
230
+ tools = swx.tools.get(toolkits=["github"])
231
+
232
+ # 3. Build the system prompt: your own instructions plus TOOL_USE_INSTRUCTIONS,
233
+ # which tells Claude to call the tool directly for action requests instead of
234
+ # just describing what it would do
235
+ system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
236
+
237
+ response = client.messages.create(
238
+ model="claude-3-5-sonnet-latest",
239
+ max_tokens=1024,
240
+ system=system,
241
+ tools=tools,
242
+ messages=[{"role": "user", "content": "Star the swytchcodehq/swytchcode-examples repo on GitHub for me."}],
243
+ )
244
+
245
+ # 4. Run any tool calls Claude made and send the results back
246
+ results = swx.handle_tool_calls(response)
247
+ print(results)
248
+
249
+ if __name__ == "__main__":
250
+ run_agent()
251
+ ```
252
+
253
+ ### Selecting tools - `swx.tools.get(...)`
254
+
255
+ Pass exactly one selector; IDs resolve against your local Swytchcode state and remote search:
256
+
257
+ - `toolkits=["stripe"]` - every enabled tool whose integration matches a toolkit.
258
+ - `tools=["charges.charge.create"]` - explicit canonical IDs.
259
+ - `search="refund a charge"` - natural-language discovery (via `swytchcode discover`).
260
+
261
+ Each returned tool carries a **full input schema** - every field is surfaced to the model, with
262
+ only the truly-required ones marked `required` - and an `execute` callback that runs `swytchcode
263
+ exec` for you (empty optional values are stripped before the call so APIs like Stripe don't reject them).
264
+
265
+ ### Supported providers
266
+
267
+ | Framework | Import | Who runs the tool loop |
268
+ |-----------|--------|------------------------|
269
+ | Anthropic Claude | `from swytchcode_runtime.providers.anthropic import AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
270
+ | OpenAI Agents SDK | `from swytchcode_runtime.providers.openai_agents import OpenAIAgentsProvider` | the SDK |
271
+ | Vercel AI SDK | `from swytchcode_runtime.providers.vercel import VercelProvider` | the SDK |
272
+ | LangGraph | `from swytchcode_runtime.providers.langgraph import LangGraphProvider` | the prebuilt agent |
273
+ | CrewAI | `from swytchcode_runtime.providers.crewai import CrewAIProvider` | the crew |
274
+
275
+ ### Non-agentic APIs (Anthropic Messages)
276
+
277
+ When you run the tool loop yourself, `handle_tool_calls` executes each `tool_use` block and
278
+ returns the `tool_result` blocks to send back:
279
+
280
+ ```python
281
+ import anthropic
282
+ client = anthropic.Anthropic()
283
+ msg = client.messages.create(
284
+ model="claude-sonnet-5", max_tokens=1024, tools=tools,
285
+ messages=[{"role": "user", "content": "Refund charge ch_123 for $20"}],
286
+ )
287
+ results = swx.handle_tool_calls(msg) # runs the tool calls, returns tool_result blocks
288
+ ```
289
+
290
+ One runnable file per framework lives in `sdk-examples/`. Install the matching framework SDK
291
+ (`pip install openai-agents` / `anthropic` / `ai` / `langgraph` / `crewai`) alongside the
292
+ `swytchcode` CLI.
@@ -0,0 +1,274 @@
1
+ # swytchcode-runtime (Python)
2
+
3
+ Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
4
+
5
+ **Requires:** The `swytchcode` CLI must be installed. The binary is located automatically - no configuration needed in most environments. Resolution order:
6
+
7
+ 1. `SWYTCHCODE_BIN` env var - explicit override.
8
+ 2. `$PATH` lookup via `shutil.which` - the standard system resolution.
9
+ 3. Common install paths - `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pip install swytchcode-runtime
15
+ ```
16
+
17
+ Or from the repo:
18
+
19
+ ```bash
20
+ pip install /path/to/runtime-libraries/python-runtime
21
+ ```
22
+
23
+ ## Use
24
+
25
+ ### JSON mode (default)
26
+
27
+ ```python
28
+ from swytchcode_runtime import exec
29
+
30
+ result = exec("api.account.create", {"email": "test@example.com"})
31
+ # result is parsed JSON (any)
32
+ ```
33
+
34
+ Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
35
+
36
+ **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:
37
+ - **body** - Request body (dict).
38
+ - **params** - Query/path params (e.g. `{"id": "cluster-123"}`).
39
+ - **Authorization** - Auth header value (e.g. `"Bearer token123"`).
40
+ - **headers** - Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
41
+ - Other top-level keys are passed as query params.
42
+
43
+ Example with body, params, and headers:
44
+
45
+ ```python
46
+ exec("api.cluster.get", {
47
+ "params": {"id": "cluster-123"},
48
+ "Authorization": "Bearer token123",
49
+ "headers": {"X-Request-Id": "abc-123"},
50
+ })
51
+ ```
52
+
53
+ ### Raw mode
54
+
55
+ Get stdout as a string instead of parsing JSON:
56
+
57
+ ```python
58
+ from swytchcode_runtime import exec
59
+
60
+ output = exec("api.report.export", {"id": "123"}, raw=True)
61
+ # output is the raw stdout string
62
+ ```
63
+
64
+ ### Options
65
+
66
+ - **cwd** - Working directory for the process (default: current directory).
67
+ - **env** - Extra environment variables (merged with `os.environ`).
68
+ - **raw** - If `True`, use `--raw` and return stdout as a string.
69
+ - **dry_run** - If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
70
+ - **allow_raw** - If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
71
+
72
+ This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
73
+
74
+ ### Environment variables
75
+
76
+ This runtime itself needs no environment configuration to run - all auth lives in the CLI's own session (`swytchcode login`, stored under `~/.swytchcode/`) or in `.swytchcode/` in your project. The variables below are for the rarer cases where you need to override that:
77
+
78
+ | Variable | Description |
79
+ |----------|-------------|
80
+ | `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). |
81
+ | `SWYTCHCODE_TOKEN` | Service-token auth for headless environments (CI, servers) where an interactive `swytchcode login` isn't possible. Not needed for local development once you've run `swytchcode login`. |
82
+
83
+ ### Error handling
84
+
85
+ Failures raise `SwytchcodeError` (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:
86
+
87
+ ```python
88
+ from swytchcode_runtime import exec, SwytchcodeError, is_swytchcode_error
89
+
90
+ try:
91
+ exec("api.account.create", {"email": "test@example.com"})
92
+ except Exception as e:
93
+ if is_swytchcode_error(e):
94
+ print(e.message, e.cause)
95
+ raise
96
+ ```
97
+
98
+ On a non-zero exit the CLI writes a classified JSON error to stderr; `exec()` parses it into a clean `.message` and a structured `.details` dict (`category`, `retryable`, `suggested_action`, `docs_url`) instead of leaving you to parse the raw JSON yourself:
99
+
100
+ ```python
101
+ except SwytchcodeError as e:
102
+ if e.details and e.details.get("category") == "auth":
103
+ print(e.details.get("suggested_action"))
104
+ ```
105
+
106
+ ## What this library is
107
+
108
+ - A thin process wrapper over the Swytchcode shell.
109
+ - A stable call surface: `exec(canonical_id, input=None, *, cwd=..., env=..., raw=...)`.
110
+ - A convenience for developers and IDE agents.
111
+
112
+ ## What this library is not
113
+
114
+ - An HTTP SDK or API client.
115
+ - A replacement for the shell. All authority stays in the Swytchcode CLI.
116
+
117
+ This library **must not** and **does not**:
118
+
119
+ - Read `.swytchcode/*` or parse `tooling.json`.
120
+ - Validate schemas or add retries/timeouts.
121
+ - Call the registry or embed auth logic.
122
+
123
+ It is a pipe, not a brain.
124
+
125
+ ## For Cursor / IDE agents
126
+
127
+ Generate code that uses this runtime instead of subprocess boilerplate.
128
+
129
+ **Preferred:**
130
+
131
+ ```python
132
+ from swytchcode_runtime import exec
133
+
134
+ def create_account(input: dict) -> any:
135
+ return exec("api.account.create", input)
136
+ ```
137
+
138
+ **Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.
139
+
140
+ ## Agentic workflows (framework integrations)
141
+
142
+ For full, production-ready examples across all major frameworks, check out the [Swytchcode Examples Repository](https://github.com/swytchcodehq/swytchcode-examples).
143
+
144
+ On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects.
145
+
146
+ ### Tool-use guidance - `TOOL_USE_INSTRUCTIONS`
147
+
148
+ Without an explicit nudge, models can be conservative about side-effecting actions (starring a repo, sending a payment, creating an issue) - they'll describe what they *would* do instead of actually calling the tool. `TOOL_USE_INSTRUCTIONS` is a short, framework-agnostic string that fixes this; concatenate it into whatever your provider calls its system prompt / instructions. It's scoped to only the tools this library provides, so it's safe to combine with instructions for other, unrelated tools in the same system prompt:
149
+
150
+ ```python
151
+ from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
152
+
153
+ system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
154
+ ```
155
+
156
+ ### Quickstart: Anthropic SDK
157
+
158
+ Here is a clean example of building a simple agent using the Anthropic SDK. It stars the [Swytchcode Examples repo](https://github.com/swytchcodehq/swytchcode-examples) on GitHub - a genuine OAuth-connected action (not just an API key passed on the request), so the setup below covers the real one-time flow: installing the CLI, logging in, and connecting a GitHub account.
159
+
160
+ **One-time setup** (run once per machine/project):
161
+
162
+ ```bash
163
+ # 1. Install the CLI (macOS/Linux; see https://cli.swytchcode.com for other platforms)
164
+ curl -fsSL https://cli.swytchcode.com/install.sh | sh
165
+
166
+ # 2. Scaffold .swytchcode/ + tooling.json in your project
167
+ swytchcode init
168
+
169
+ # 3. Log in (opens a browser; creates your Swytchcode session)
170
+ swytchcode login
171
+
172
+ # 4. Fetch the GitHub integration
173
+ swytchcode get github
174
+
175
+ # 5. Enable the "star a repo" tool - the trust boundary for what this project can call
176
+ swytchcode add user.starred.update
177
+
178
+ # 6. Connect your GitHub account (opens a browser for the OAuth flow)
179
+ swytchcode auth connect github
180
+ ```
181
+
182
+ Then add your Anthropic key to a `.env` file in your project root (used by `python-dotenv` below):
183
+
184
+ ```bash
185
+ # .env
186
+ ANTHROPIC_API_KEY=sk-ant-...
187
+ ```
188
+
189
+ **Installation:**
190
+ ```bash
191
+ pip install swytchcode-runtime anthropic python-dotenv
192
+ ```
193
+ *(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.)*
194
+
195
+ **Example:**
196
+ ```python
197
+ import os
198
+ from dotenv import load_dotenv
199
+ import anthropic
200
+ from swytchcode_runtime import Swytchcode, TOOL_USE_INSTRUCTIONS
201
+ from swytchcode_runtime.providers.anthropic import AnthropicProvider
202
+
203
+ load_dotenv() # Loads .env automatically
204
+
205
+ def run_agent():
206
+ client = anthropic.Anthropic()
207
+
208
+ # 1. Initialize Swytchcode with the Anthropic provider
209
+ swx = Swytchcode(provider=AnthropicProvider())
210
+
211
+ # 2. Fetch the tools you want your agent to use (e.g., GitHub tools)
212
+ tools = swx.tools.get(toolkits=["github"])
213
+
214
+ # 3. Build the system prompt: your own instructions plus TOOL_USE_INSTRUCTIONS,
215
+ # which tells Claude to call the tool directly for action requests instead of
216
+ # just describing what it would do
217
+ system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
218
+
219
+ response = client.messages.create(
220
+ model="claude-3-5-sonnet-latest",
221
+ max_tokens=1024,
222
+ system=system,
223
+ tools=tools,
224
+ messages=[{"role": "user", "content": "Star the swytchcodehq/swytchcode-examples repo on GitHub for me."}],
225
+ )
226
+
227
+ # 4. Run any tool calls Claude made and send the results back
228
+ results = swx.handle_tool_calls(response)
229
+ print(results)
230
+
231
+ if __name__ == "__main__":
232
+ run_agent()
233
+ ```
234
+
235
+ ### Selecting tools - `swx.tools.get(...)`
236
+
237
+ Pass exactly one selector; IDs resolve against your local Swytchcode state and remote search:
238
+
239
+ - `toolkits=["stripe"]` - every enabled tool whose integration matches a toolkit.
240
+ - `tools=["charges.charge.create"]` - explicit canonical IDs.
241
+ - `search="refund a charge"` - natural-language discovery (via `swytchcode discover`).
242
+
243
+ Each returned tool carries a **full input schema** - every field is surfaced to the model, with
244
+ only the truly-required ones marked `required` - and an `execute` callback that runs `swytchcode
245
+ exec` for you (empty optional values are stripped before the call so APIs like Stripe don't reject them).
246
+
247
+ ### Supported providers
248
+
249
+ | Framework | Import | Who runs the tool loop |
250
+ |-----------|--------|------------------------|
251
+ | Anthropic Claude | `from swytchcode_runtime.providers.anthropic import AnthropicProvider` | you (Messages API + `swx.handle_tool_calls`) |
252
+ | OpenAI Agents SDK | `from swytchcode_runtime.providers.openai_agents import OpenAIAgentsProvider` | the SDK |
253
+ | Vercel AI SDK | `from swytchcode_runtime.providers.vercel import VercelProvider` | the SDK |
254
+ | LangGraph | `from swytchcode_runtime.providers.langgraph import LangGraphProvider` | the prebuilt agent |
255
+ | CrewAI | `from swytchcode_runtime.providers.crewai import CrewAIProvider` | the crew |
256
+
257
+ ### Non-agentic APIs (Anthropic Messages)
258
+
259
+ When you run the tool loop yourself, `handle_tool_calls` executes each `tool_use` block and
260
+ returns the `tool_result` blocks to send back:
261
+
262
+ ```python
263
+ import anthropic
264
+ client = anthropic.Anthropic()
265
+ msg = client.messages.create(
266
+ model="claude-sonnet-5", max_tokens=1024, tools=tools,
267
+ messages=[{"role": "user", "content": "Refund charge ch_123 for $20"}],
268
+ )
269
+ results = swx.handle_tool_calls(msg) # runs the tool calls, returns tool_result blocks
270
+ ```
271
+
272
+ One runnable file per framework lives in `sdk-examples/`. Install the matching framework SDK
273
+ (`pip install openai-agents` / `anthropic` / `ai` / `langgraph` / `crewai`) alongside the
274
+ `swytchcode` CLI.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "swytchcode-runtime"
7
- version = "1.0.0"
7
+ version = "1.1.1"
8
8
  description = "Thin runtime wrapper around the Swytchcode CLI"
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -0,0 +1,32 @@
1
+ """Thin runtime wrapper around the Swytchcode CLI."""
2
+
3
+ from .client import Swytchcode
4
+ from .errors import SwytchcodeError, is_swytchcode_error
5
+ from .exec import exec_ as exec
6
+ from .prompts import TOOL_USE_INSTRUCTIONS
7
+
8
+ __all__ = [
9
+ "TOOL_USE_INSTRUCTIONS",
10
+ "Swytchcode",
11
+ "SwytchcodeError",
12
+ "exec",
13
+ "is_swytchcode_error",
14
+ ]
15
+
16
+
17
+ def __getattr__(name):
18
+ """Lazy provider imports for backward compatibility."""
19
+ _provider_map = {
20
+ "AnthropicProvider": ("providers.anthropic", "AnthropicProvider"),
21
+ "OpenAIAgentsProvider": ("providers.openai_agents", "OpenAIAgentsProvider"),
22
+ "VercelProvider": ("providers.vercel", "VercelProvider"),
23
+ "LangGraphProvider": ("providers.langgraph", "LangGraphProvider"),
24
+ "CrewAIProvider": ("providers.crewai", "CrewAIProvider"),
25
+ }
26
+ if name in _provider_map:
27
+ module_path, attr = _provider_map[name]
28
+ import importlib
29
+
30
+ mod = importlib.import_module(f".{module_path}", __package__)
31
+ return getattr(mod, attr)
32
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -1,13 +1,14 @@
1
1
  """Run a swytchcode CLI subcommand with --json and parse the output."""
2
2
 
3
3
  from __future__ import annotations
4
+
4
5
  import json
5
6
  import os
6
7
  import subprocess
7
8
  from typing import Any
8
9
 
9
- from .exec import _resolve_bin
10
10
  from .errors import SwytchcodeError
11
+ from .exec import _resolve_bin
11
12
 
12
13
 
13
14
  def run_cli(
@@ -32,6 +33,7 @@ def run_cli(
32
33
  cwd=cwd or os.getcwd(),
33
34
  env=run_env,
34
35
  timeout=timeout,
36
+ check=False,
35
37
  )
36
38
  except FileNotFoundError as e:
37
39
  raise SwytchcodeError(