21st-sdk 0.0.1__tar.gz

21st_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: 21st-sdk
+Version: 0.0.1
+Summary: Server-side Python SDK for 21st Agents
+Author: 21st.dev
+License-Expression: MIT
+Project-URL: Homepage, https://21st.dev/agents
+Keywords: ai,agent,sandbox,21st,21st.dev,sdk,python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# 21st-sdk Python
+
+Server-side Python SDK for [21st Agents](https://21st.dev/agents). Manage sandboxes, threads, and tokens programmatically.
+
+Method arguments use Python-style `snake_case`, but SDK responses keep the relay's `camelCase` field names.
+
+## Install
+
+```bash
+pip install 21st-sdk
+```
+
+## Quick Start
+
+```python
+import os
+
+from twentyfirst_sdk import AgentClient
+
+client = AgentClient(api_key=os.environ["API_KEY_21ST"])  # an_sk_...
+
+# Create a sandbox for your agent
+sandbox = client.sandboxes.create(agent="my-agent")
+
+# Create a thread
+thread = client.threads.create(sandbox_id=sandbox.id, name="Review PR #42")
+
+# Generate a short-lived token for browser clients
+token = client.tokens.create(agent="my-agent", expires_in="1h")
+print(token.expiresAt)
+```
+
+## API
+
+### `AgentClient(api_key, base_url=...)`
+
+```python
+AgentClient(
+    api_key="...",   # Your an_sk_ API key
+    base_url="...",  # Optional, default: "https://relay.an.dev"
+)
+```
+
+### `client.sandboxes`
+
+| Method | Description |
+|--------|-------------|
+| `create(agent=...)` | Create a new sandbox for an agent |
+| `get(sandbox_id)` | Get sandbox details (status, threads, agent info) |
+| `delete(sandbox_id)` | Delete a sandbox |
+| `exec(sandbox_id, command, ...)` | Run a command in a sandbox |
+| `files.write(sandbox_id, files)` | Write files into a sandbox |
+| `files.read(sandbox_id, path)` | Read a file from a sandbox |
+| `git.clone(sandbox_id, url, ...)` | Clone a repository into a sandbox |
+
+### `client.threads`
+
+| Method | Description |
+|--------|-------------|
+| `list(sandbox_id)` | List all threads in a sandbox |
+| `create(sandbox_id, name=...)` | Create a new thread |
+| `get(sandbox_id, thread_id)` | Get thread with messages |
+| `delete(sandbox_id, thread_id)` | Delete a thread |
+| `run(agent, messages, ...)` | Run a thread and return the raw streaming response |
+
+### `client.tokens`
+
+| Method | Description |
+|--------|-------------|
+| `create(agent=..., user_id=..., expires_in=...)` | Create a short-lived JWT (default: `"1h"`) |
+
+## License
+
+MIT

21st_sdk-0.0.1/README.md

@@ -0,0 +1,74 @@
+# 21st-sdk Python
+
+Server-side Python SDK for [21st Agents](https://21st.dev/agents). Manage sandboxes, threads, and tokens programmatically.
+
+Method arguments use Python-style `snake_case`, but SDK responses keep the relay's `camelCase` field names.
+
+## Install
+
+```bash
+pip install 21st-sdk
+```
+
+## Quick Start
+
+```python
+import os
+
+from twentyfirst_sdk import AgentClient
+
+client = AgentClient(api_key=os.environ["API_KEY_21ST"])  # an_sk_...
+
+# Create a sandbox for your agent
+sandbox = client.sandboxes.create(agent="my-agent")
+
+# Create a thread
+thread = client.threads.create(sandbox_id=sandbox.id, name="Review PR #42")
+
+# Generate a short-lived token for browser clients
+token = client.tokens.create(agent="my-agent", expires_in="1h")
+print(token.expiresAt)
+```
+
+## API
+
+### `AgentClient(api_key, base_url=...)`
+
+```python
+AgentClient(
+    api_key="...",   # Your an_sk_ API key
+    base_url="...",  # Optional, default: "https://relay.an.dev"
+)
+```
+
+### `client.sandboxes`
+
+| Method | Description |
+|--------|-------------|
+| `create(agent=...)` | Create a new sandbox for an agent |
+| `get(sandbox_id)` | Get sandbox details (status, threads, agent info) |
+| `delete(sandbox_id)` | Delete a sandbox |
+| `exec(sandbox_id, command, ...)` | Run a command in a sandbox |
+| `files.write(sandbox_id, files)` | Write files into a sandbox |
+| `files.read(sandbox_id, path)` | Read a file from a sandbox |
+| `git.clone(sandbox_id, url, ...)` | Clone a repository into a sandbox |
+
+### `client.threads`
+
+| Method | Description |
+|--------|-------------|
+| `list(sandbox_id)` | List all threads in a sandbox |
+| `create(sandbox_id, name=...)` | Create a new thread |
+| `get(sandbox_id, thread_id)` | Get thread with messages |
+| `delete(sandbox_id, thread_id)` | Delete a thread |
+| `run(agent, messages, ...)` | Run a thread and return the raw streaming response |
+
+### `client.tokens`
+
+| Method | Description |
+|--------|-------------|
+| `create(agent=..., user_id=..., expires_in=...)` | Create a short-lived JWT (default: `"1h"`) |
+
+## License
+
+MIT

21st_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "21st-sdk"
+version = "0.0.1"
+description = "Server-side Python SDK for 21st Agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "21st.dev" },
+]
+dependencies = [
+  "requests>=2.31.0",
+]
+keywords = [
+  "ai",
+  "agent",
+  "sandbox",
+  "21st",
+  "21st.dev",
+  "sdk",
+  "python",
+]
+
+[project.urls]
+Homepage = "https://21st.dev/agents"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

21st_sdk-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

21st_sdk-0.0.1/src/21st_sdk.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: 21st-sdk
+Version: 0.0.1
+Summary: Server-side Python SDK for 21st Agents
+Author: 21st.dev
+License-Expression: MIT
+Project-URL: Homepage, https://21st.dev/agents
+Keywords: ai,agent,sandbox,21st,21st.dev,sdk,python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# 21st-sdk Python
+
+Server-side Python SDK for [21st Agents](https://21st.dev/agents). Manage sandboxes, threads, and tokens programmatically.
+
+Method arguments use Python-style `snake_case`, but SDK responses keep the relay's `camelCase` field names.
+
+## Install
+
+```bash
+pip install 21st-sdk
+```
+
+## Quick Start
+
+```python
+import os
+
+from twentyfirst_sdk import AgentClient
+
+client = AgentClient(api_key=os.environ["API_KEY_21ST"])  # an_sk_...
+
+# Create a sandbox for your agent
+sandbox = client.sandboxes.create(agent="my-agent")
+
+# Create a thread
+thread = client.threads.create(sandbox_id=sandbox.id, name="Review PR #42")
+
+# Generate a short-lived token for browser clients
+token = client.tokens.create(agent="my-agent", expires_in="1h")
+print(token.expiresAt)
+```
+
+## API
+
+### `AgentClient(api_key, base_url=...)`
+
+```python
+AgentClient(
+    api_key="...",   # Your an_sk_ API key
+    base_url="...",  # Optional, default: "https://relay.an.dev"
+)
+```
+
+### `client.sandboxes`
+
+| Method | Description |
+|--------|-------------|
+| `create(agent=...)` | Create a new sandbox for an agent |
+| `get(sandbox_id)` | Get sandbox details (status, threads, agent info) |
+| `delete(sandbox_id)` | Delete a sandbox |
+| `exec(sandbox_id, command, ...)` | Run a command in a sandbox |
+| `files.write(sandbox_id, files)` | Write files into a sandbox |
+| `files.read(sandbox_id, path)` | Read a file from a sandbox |
+| `git.clone(sandbox_id, url, ...)` | Clone a repository into a sandbox |
+
+### `client.threads`
+
+| Method | Description |
+|--------|-------------|
+| `list(sandbox_id)` | List all threads in a sandbox |
+| `create(sandbox_id, name=...)` | Create a new thread |
+| `get(sandbox_id, thread_id)` | Get thread with messages |
+| `delete(sandbox_id, thread_id)` | Delete a thread |
+| `run(agent, messages, ...)` | Run a thread and return the raw streaming response |
+
+### `client.tokens`
+
+| Method | Description |
+|--------|-------------|
+| `create(agent=..., user_id=..., expires_in=...)` | Create a short-lived JWT (default: `"1h"`) |
+
+## License
+
+MIT

21st_sdk-0.0.1/src/21st_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/21st_sdk.egg-info/PKG-INFO
+src/21st_sdk.egg-info/SOURCES.txt
+src/21st_sdk.egg-info/dependency_links.txt
+src/21st_sdk.egg-info/requires.txt
+src/21st_sdk.egg-info/top_level.txt
+src/twentyfirst_sdk/__init__.py
+src/twentyfirst_sdk/client.py
+src/twentyfirst_sdk/types.py

21st_sdk-0.0.1/src/21st_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

21st_sdk-0.0.1/src/21st_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

21st_sdk-0.0.1/src/21st_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+twentyfirst_sdk

21st_sdk-0.0.1/src/twentyfirst_sdk/__init__.py

@@ -0,0 +1,35 @@
+from .client import DEFAULT_BASE_URL, AgentClient, AgentClientError
+from .types import (
+    APIObject,
+    ApiError,
+    ExecResult,
+    FileContent,
+    GitCloneResult,
+    RunThreadMessage,
+    RunThreadMessagePart,
+    RunThreadResult,
+    Sandbox,
+    SandboxDetail,
+    Thread,
+    ThreadSummary,
+    Token,
+)
+
+__all__ = [
+    "APIObject",
+    "DEFAULT_BASE_URL",
+    "AgentClient",
+    "AgentClientError",
+    "ApiError",
+    "ExecResult",
+    "FileContent",
+    "GitCloneResult",
+    "RunThreadMessage",
+    "RunThreadMessagePart",
+    "RunThreadResult",
+    "Sandbox",
+    "SandboxDetail",
+    "Thread",
+    "ThreadSummary",
+    "Token",
+]

21st_sdk-0.0.1/src/twentyfirst_sdk/client.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Sequence
+from urllib.parse import quote
+
+import requests
+
+from .types import APIObject, RunThreadMessage
+
+
+DEFAULT_BASE_URL = "https://relay.an.dev"
+
+
+def _to_api_object(value: Any) -> Any:
+    if isinstance(value, dict):
+        return APIObject({key: _to_api_object(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return [_to_api_object(item) for item in value]
+    return value
+
+
+class AgentClientError(Exception):
+    pass
+
+
+class AgentClient:
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+
+        self.sandboxes = SandboxesResource(self)
+        self.threads = ThreadsResource(self)
+        self.tokens = TokensResource(self)
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "AgentClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Optional[Dict[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        request_headers = {
+            "Content-Type": "application/json",
+            "Authorization": "Bearer %s" % self.api_key,
+        }
+        if headers:
+            request_headers.update(headers)
+
+        response = self._session.request(
+            method,
+            "%s%s" % (self.base_url, path),
+            json=body,
+            headers=request_headers,
+            stream=stream,
+        )
+
+        if not response.ok:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {}
+
+            error = payload.get("error") if isinstance(payload, dict) else None
+            message = None
+            if isinstance(error, dict):
+                message = error.get("message")
+
+            raise AgentClientError(message or "Request failed: %s" % response.status_code)
+
+        return response
+
+    def _fetch(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Optional[Dict[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        response = self._request(path, method=method, body=body, headers=headers)
+
+        if response.status_code == 204:
+            return None
+
+        return _to_api_object(response.json())
+
+    def _get_base_url(self) -> str:
+        return self.base_url
+
+
+class FilesResource:
+    def __init__(self, client: AgentClient):
+        self.client = client
+
+    def write(self, sandbox_id: str, files: Mapping[str, str]) -> Any:
+        return self.client._fetch(
+            "/v1/sandboxes/%s/files" % sandbox_id,
+            method="POST",
+            body={"files": dict(files)},
+        )
+
+    def read(self, sandbox_id: str, path: str) -> Any:
+        encoded_path = quote(path, safe="")
+        return self.client._fetch(
+            "/v1/sandboxes/%s/files?path=%s" % (sandbox_id, encoded_path),
+        )
+
+
+class GitResource:
+    def __init__(self, client: AgentClient):
+        self.client = client
+
+    def clone(
+        self,
+        sandbox_id: str,
+        url: str,
+        *,
+        path: Optional[str] = None,
+        token: Optional[str] = None,
+        depth: Optional[int] = None,
+    ) -> Any:
+        body: Dict[str, Any] = {"url": url}
+        if path:
+            body["path"] = path
+        if token:
+            body["token"] = token
+        if depth:
+            body["depth"] = depth
+
+        return self.client._fetch(
+            "/v1/sandboxes/%s/git/clone" % sandbox_id,
+            method="POST",
+            body=body,
+        )
+
+
+class SandboxesResource:
+    def __init__(self, client: AgentClient):
+        self.client = client
+        self.files = FilesResource(client)
+        self.git = GitResource(client)
+
+    def create(
+        self,
+        agent: str,
+        *,
+        files: Optional[Mapping[str, str]] = None,
+        envs: Optional[Mapping[str, str]] = None,
+        setup: Optional[Sequence[str]] = None,
+    ) -> Any:
+        body: Dict[str, Any] = {"agent": agent}
+        if files:
+            body["files"] = dict(files)
+        if envs:
+            body["envs"] = dict(envs)
+        if setup:
+            body["setup"] = list(setup)
+
+        return self.client._fetch("/v1/sandboxes", method="POST", body=body)
+
+    def get(self, sandbox_id: str) -> Any:
+        return self.client._fetch("/v1/sandboxes/%s" % sandbox_id)
+
+    def delete(self, sandbox_id: str) -> Any:
+        return self.client._fetch("/v1/sandboxes/%s" % sandbox_id, method="DELETE")
+
+    def exec(
+        self,
+        sandbox_id: str,
+        command: str,
+        *,
+        cwd: Optional[str] = None,
+        envs: Optional[Mapping[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> Any:
+        body: Dict[str, Any] = {"command": command}
+        if cwd:
+            body["cwd"] = cwd
+        if envs:
+            body["envs"] = dict(envs)
+        if timeout_ms:
+            body["timeoutMs"] = timeout_ms
+
+        return self.client._fetch(
+            "/v1/sandboxes/%s/exec" % sandbox_id,
+            method="POST",
+            body=body,
+        )
+
+
+class ThreadsResource:
+    def __init__(self, client: AgentClient):
+        self.client = client
+
+    def list(self, sandbox_id: str) -> Any:
+        return self.client._fetch("/v1/sandboxes/%s/threads" % sandbox_id)
+
+    def create(self, sandbox_id: str, *, name: Optional[str] = None) -> Any:
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+
+        return self.client._fetch(
+            "/v1/sandboxes/%s/threads" % sandbox_id,
+            method="POST",
+            body=body,
+        )
+
+    def get(self, sandbox_id: str, thread_id: str) -> Any:
+        return self.client._fetch(
+            "/v1/sandboxes/%s/threads/%s" % (sandbox_id, thread_id),
+        )
+
+    def delete(self, sandbox_id: str, thread_id: str) -> Any:
+        return self.client._fetch(
+            "/v1/sandboxes/%s/threads/%s" % (sandbox_id, thread_id),
+            method="DELETE",
+        )
+
+    def run(
+        self,
+        agent: str,
+        messages: Sequence[RunThreadMessage],
+        *,
+        sandbox_id: Optional[str] = None,
+        thread_id: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> Any:
+        if thread_id and not sandbox_id:
+            raise AgentClientError("threadId requires sandboxId")
+
+        if not sandbox_id:
+            sandbox_id = self.client.sandboxes.create(agent).id
+
+        if not thread_id:
+            thread_id = self.create(sandbox_id, name=name).id
+
+        encoded_agent = quote(agent, safe="")
+        response = self.client._request(
+            "/v1/chat/%s" % encoded_agent,
+            method="POST",
+            body={
+                "messages": list(messages),
+                "sandboxId": sandbox_id,
+                "threadId": thread_id,
+            },
+            stream=True,
+        )
+
+        return APIObject(
+            {
+                "sandboxId": sandbox_id,
+                "threadId": thread_id,
+                "response": response,
+                "resumeUrl": "%s/v1/chat/%s/%s/stream"
+                % (self.client._get_base_url(), encoded_agent, sandbox_id),
+            }
+        )
+
+
+class TokensResource:
+    def __init__(self, client: AgentClient):
+        self.client = client
+
+    def create(
+        self,
+        *,
+        agent: Optional[str] = None,
+        user_id: Optional[str] = None,
+        expires_in: str = "1h",
+    ) -> Any:
+        body: Dict[str, Any] = {"expiresIn": expires_in}
+
+        if agent:
+            body["agents"] = [agent]
+
+        if user_id is not None:
+            body["userId"] = user_id
+
+        return self.client._fetch("/v1/tokens", method="POST", body=body)

21st_sdk-0.0.1/src/twentyfirst_sdk/types.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, TypedDict
+
+
+class APIObject(dict):
+    """Dict with attribute-style access, similar to plain JS objects."""
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self[name] = value
+
+    def __delattr__(self, name: str) -> None:
+        try:
+            del self[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+
+class ApiError(TypedDict):
+    code: str
+    message: str
+
+
+RunThreadMessagePart = Mapping[str, Any]
+RunThreadMessage = Mapping[str, Any]
+
+Sandbox = APIObject
+SandboxDetail = APIObject
+ThreadSummary = APIObject
+RunThreadResult = APIObject
+Thread = APIObject
+Token = APIObject
+FileContent = APIObject
+ExecResult = APIObject
+GitCloneResult = APIObject