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.
- swytchcode_runtime-1.1.1/PKG-INFO +292 -0
- swytchcode_runtime-1.1.1/README.md +274 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/pyproject.toml +1 -1
- swytchcode_runtime-1.1.1/swytchcode_runtime/__init__.py +32 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/cli.py +3 -1
- swytchcode_runtime-1.1.1/swytchcode_runtime/client.py +244 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/discover.py +3 -1
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/errors.py +10 -1
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/exec.py +41 -3
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/manage.py +1 -0
- swytchcode_runtime-1.1.1/swytchcode_runtime/prompts.py +19 -0
- swytchcode_runtime-1.1.1/swytchcode_runtime/providers/__init__.py +27 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/anthropic.py +1 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/base.py +6 -3
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/crewai.py +2 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/langgraph.py +2 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/openai_agents.py +3 -1
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/providers/vercel.py +3 -2
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime/schema.py +19 -16
- swytchcode_runtime-1.1.1/swytchcode_runtime.egg-info/PKG-INFO +292 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime.egg-info/SOURCES.txt +6 -1
- swytchcode_runtime-1.1.1/tests/test_alias.py +42 -0
- swytchcode_runtime-1.1.1/tests/test_exec_errors.py +36 -0
- swytchcode_runtime-1.1.1/tests/test_prompts.py +21 -0
- swytchcode_runtime-1.1.1/tests/test_schema_routing.py +62 -0
- swytchcode_runtime-1.0.0/PKG-INFO +0 -201
- swytchcode_runtime-1.0.0/README.md +0 -183
- swytchcode_runtime-1.0.0/swytchcode_runtime/__init__.py +0 -24
- swytchcode_runtime-1.0.0/swytchcode_runtime/client.py +0 -133
- swytchcode_runtime-1.0.0/swytchcode_runtime/providers/__init__.py +0 -15
- swytchcode_runtime-1.0.0/swytchcode_runtime.egg-info/PKG-INFO +0 -201
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/LICENSE.md +0 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/setup.cfg +0 -0
- {swytchcode_runtime-1.0.0 → swytchcode_runtime-1.1.1}/swytchcode_runtime.egg-info/dependency_links.txt +0 -0
- {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.
|
|
@@ -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(
|