server4agent 0.1.0__tar.gz

server4agent-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

server4agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Sync `Server4Agent` and async `AsyncServer4Agent` clients.
+- Resource-oriented handles: `create()`/`get()` return `Server`/`Project`/`Task`/`Build`
+  objects with scoped sub-resources (`server.tasks`, `server.files`, ...) and actions
+  (`server.exec()`, `server.deploy()`, `project.update()`).
+- `task.wait()` / `build.wait()` poll until a terminal state, with an `on_poll` callback.
+- Typed error hierarchy under `Server4AgentError` (`NotFoundError`, `RateLimitError`,
+  `APIStatusError`, ...) exposing `status`, `code`, and `request_id`.
+- Automatic retries with exponential backoff + jitter; retries are method-aware so a
+  `POST` is never retried in a way that could double-create. Configurable `timeout`
+  and `max_retries`.
+- Webhook signature verification (`verify_webhook_signature`).
+- Ships `py.typed`. Opt-in request logging via `SERVER4AGENT_LOG=debug`.

server4agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Server4Agent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

server4agent-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: server4agent
+Version: 0.1.0
+Summary: Python client for the Server4Agent REST API — sync + async, typed, with retries.
+Project-URL: Homepage, https://www.server4agent.com
+Project-URL: Documentation, https://www.server4agent.com/docs/sdks
+Project-URL: Repository, https://github.com/Server4Agent/server4agent-python
+License: MIT
+License-File: LICENSE
+Keywords: agents,mcp,sdk,server4agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# server4agent
+
+Python client for the [Server4Agent](https://www.server4agent.com) REST API —
+sync **and** async, fully typed, with automatic retries.
+
+This SDK is for the code *around* your agent — your backend, a script, a
+notebook, a webhook receiver. If your agent itself does tool-calling, point it
+at the [MCP server](https://www.server4agent.com/docs/mcp) directly; it doesn't
+need this package.
+
+## Install
+
+```bash
+pip install server4agent
+```
+
+Requires Python 3.9+. Depends only on [`httpx`](https://www.python-httpx.org/).
+
+## Quickstart
+
+```python
+from server4agent import Server4Agent
+
+client = Server4Agent()  # reads SERVER4AGENT_API_KEY from the environment
+
+# create() returns a handle you can act on directly
+server = client.servers.create(tier="small")
+
+# kick off a build and block until it's live
+build = server.builds.start("a FastAPI todo API with a web UI").wait()
+print(build.url)
+
+# run a command right on the server
+print(server.exec("ls -la"))
+```
+
+`api_key` can also be passed explicitly: `Server4Agent(api_key="sk_live_...")`.
+Use it as a context manager to close the connection pool:
+
+```python
+with Server4Agent() as client:
+    ...
+```
+
+## Async
+
+The async client mirrors the sync one method-for-method:
+
+```python
+import asyncio
+from server4agent import AsyncServer4Agent
+
+async def main():
+    async with AsyncServer4Agent() as client:
+        server = await client.servers.create(tier="small")
+        task = await server.tasks.create("Scrape today's HN front page to JSON.")
+        await task.wait()
+        print(task.status, task.result)
+
+asyncio.run(main())
+```
+
+## Handles
+
+`create()` and `get()` return rich handles — data records you can also act on:
+
+```python
+server = client.servers.get("srv_abc")
+server.tasks.create("...")          # sub-resources are scoped to the server
+server.files.write("app.py", "...")
+server.deploy()
+server.refresh()                    # re-fetch in place
+
+project = client.projects.get("prj_xyz")
+project.update(visibility="public")
+```
+
+`task.wait()` / `build.wait()` poll until a terminal state; both accept
+`poll_interval` and `timeout` (seconds).
+
+## Errors
+
+Every failure is a subclass of `Server4AgentError`, so you can catch broadly or
+narrowly:
+
+```python
+from server4agent import NotFoundError, RateLimitError, APIStatusError
+
+try:
+    client.servers.get("srv_missing")
+except NotFoundError:
+    ...                              # 404
+except RateLimitError as e:
+    ...                              # 429 (already retried; quote e.request_id to support)
+except APIStatusError as e:
+    print(e.status, e.code, e.message, e.request_id)
+```
+
+Retryable failures (429, 5xx, network blips) are retried automatically with
+exponential backoff. Tune it per client:
+
+```python
+Server4Agent(timeout=30.0, max_retries=4)
+```
+
+## Verifying webhooks
+
+```python
+import os
+from server4agent import verify_webhook_signature
+
+# request.data must be the raw body — parse it as JSON only after verifying.
+ok = verify_webhook_signature(
+    secret=os.environ["SERVER4AGENT_WEBHOOK_SECRET"],
+    body=request.data.decode("utf-8"),
+    header=request.headers.get("Server4Agent-Signature"),
+)
+if not ok:
+    return "invalid signature", 401
+```
+
+## API surface
+
+`servers`, `projects`, `templates`, `tasks`, `builds`, `files`, `keys`,
+`webhooks` — see the [REST API docs](https://www.server4agent.com/docs/api) for
+the endpoints each method wraps.
+
+Server-side only: this SDK holds your `sk_live_` key. Never embed it in a
+notebook or script you share.

server4agent-0.1.0/README.md

@@ -0,0 +1,129 @@
+# server4agent
+
+Python client for the [Server4Agent](https://www.server4agent.com) REST API —
+sync **and** async, fully typed, with automatic retries.
+
+This SDK is for the code *around* your agent — your backend, a script, a
+notebook, a webhook receiver. If your agent itself does tool-calling, point it
+at the [MCP server](https://www.server4agent.com/docs/mcp) directly; it doesn't
+need this package.
+
+## Install
+
+```bash
+pip install server4agent
+```
+
+Requires Python 3.9+. Depends only on [`httpx`](https://www.python-httpx.org/).
+
+## Quickstart
+
+```python
+from server4agent import Server4Agent
+
+client = Server4Agent()  # reads SERVER4AGENT_API_KEY from the environment
+
+# create() returns a handle you can act on directly
+server = client.servers.create(tier="small")
+
+# kick off a build and block until it's live
+build = server.builds.start("a FastAPI todo API with a web UI").wait()
+print(build.url)
+
+# run a command right on the server
+print(server.exec("ls -la"))
+```
+
+`api_key` can also be passed explicitly: `Server4Agent(api_key="sk_live_...")`.
+Use it as a context manager to close the connection pool:
+
+```python
+with Server4Agent() as client:
+    ...
+```
+
+## Async
+
+The async client mirrors the sync one method-for-method:
+
+```python
+import asyncio
+from server4agent import AsyncServer4Agent
+
+async def main():
+    async with AsyncServer4Agent() as client:
+        server = await client.servers.create(tier="small")
+        task = await server.tasks.create("Scrape today's HN front page to JSON.")
+        await task.wait()
+        print(task.status, task.result)
+
+asyncio.run(main())
+```
+
+## Handles
+
+`create()` and `get()` return rich handles — data records you can also act on:
+
+```python
+server = client.servers.get("srv_abc")
+server.tasks.create("...")          # sub-resources are scoped to the server
+server.files.write("app.py", "...")
+server.deploy()
+server.refresh()                    # re-fetch in place
+
+project = client.projects.get("prj_xyz")
+project.update(visibility="public")
+```
+
+`task.wait()` / `build.wait()` poll until a terminal state; both accept
+`poll_interval` and `timeout` (seconds).
+
+## Errors
+
+Every failure is a subclass of `Server4AgentError`, so you can catch broadly or
+narrowly:
+
+```python
+from server4agent import NotFoundError, RateLimitError, APIStatusError
+
+try:
+    client.servers.get("srv_missing")
+except NotFoundError:
+    ...                              # 404
+except RateLimitError as e:
+    ...                              # 429 (already retried; quote e.request_id to support)
+except APIStatusError as e:
+    print(e.status, e.code, e.message, e.request_id)
+```
+
+Retryable failures (429, 5xx, network blips) are retried automatically with
+exponential backoff. Tune it per client:
+
+```python
+Server4Agent(timeout=30.0, max_retries=4)
+```
+
+## Verifying webhooks
+
+```python
+import os
+from server4agent import verify_webhook_signature
+
+# request.data must be the raw body — parse it as JSON only after verifying.
+ok = verify_webhook_signature(
+    secret=os.environ["SERVER4AGENT_WEBHOOK_SECRET"],
+    body=request.data.decode("utf-8"),
+    header=request.headers.get("Server4Agent-Signature"),
+)
+if not ok:
+    return "invalid signature", 401
+```
+
+## API surface
+
+`servers`, `projects`, `templates`, `tasks`, `builds`, `files`, `keys`,
+`webhooks` — see the [REST API docs](https://www.server4agent.com/docs/api) for
+the endpoints each method wraps.
+
+Server-side only: this SDK holds your `sk_live_` key. Never embed it in a
+notebook or script you share.

server4agent-0.1.0/SECURITY.md

@@ -0,0 +1,24 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security issues **privately** — do not open a public issue or PR.
+
+- Use GitHub's private vulnerability reporting on this repo (**Security → Report a
+  vulnerability**), or
+- email **security@server4agent.com**.
+
+We aim to acknowledge reports within 3 business days.
+
+## Handling your API key
+
+This SDK holds an `sk_live_` key and is meant for **server-side** use only.
+
+- Never embed it in a shared notebook or script, and never commit it to source
+  control. Prefer the `SERVER4AGENT_API_KEY` environment variable.
+- Rotate a key immediately if it may have been exposed (`client.keys.revoke(id)`).
+
+## Supported versions
+
+Only the latest published `0.x` release receives security fixes while the SDK
+is pre-1.0.

server4agent-0.1.0/examples/async_quickstart.py

@@ -0,0 +1,19 @@
+"""Give the on-server agent a goal and await the result, using the async client.
+
+    SERVER4AGENT_API_KEY=sk_live_... python async_quickstart.py
+"""
+import asyncio
+
+from server4agent import AsyncServer4Agent
+
+
+async def main() -> None:
+    async with AsyncServer4Agent() as client:
+        server = await client.servers.create(tier="small")
+        task = await server.tasks.create("Summarize today's top HN posts into summary.md")
+        await task.wait(on_poll=lambda t: print("task:", t.status))
+        print(task.result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

server4agent-0.1.0/examples/quickstart.py

@@ -0,0 +1,19 @@
+"""Provision a server, have the agent build an app, and print the live URL.
+
+    SERVER4AGENT_API_KEY=sk_live_... python quickstart.py
+"""
+from server4agent import Server4Agent
+
+
+def main() -> None:
+    with Server4Agent() as client:
+        server = client.servers.create(tier="small")
+        print(f"server {server.id} ({server.status})")
+
+        build = server.builds.start("a FastAPI todo API with a small web UI")
+        build.wait(on_poll=lambda b: print(f"  build: {b.status}"))
+        print("live at", build.url)
+
+
+if __name__ == "__main__":
+    main()

server4agent-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "server4agent"
+description = "Python client for the Server4Agent REST API — sync + async, typed, with retries."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["server4agent", "sdk", "agents", "mcp"]
+dynamic = ["version"]
+dependencies = [
+    "httpx>=0.24,<1",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://www.server4agent.com"
+Documentation = "https://www.server4agent.com/docs/sdks"
+Repository = "https://github.com/Server4Agent/server4agent-python"
+
+[tool.hatch.version]
+path = "server4agent/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["server4agent"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

server4agent-0.1.0/server4agent/__init__.py

@@ -0,0 +1,79 @@
+from ._async.client import AsyncServer4Agent
+from ._async.client import (
+    AsyncBuild,
+    AsyncProject,
+    AsyncServer,
+    AsyncTask,
+)
+from ._models import (
+    ApiKey,
+    BuildStep,
+    CreatedApiKey,
+    CreatedWebhook,
+    Deployment,
+    ExecResult,
+    ProjectTemplate,
+    ProjectTemplateDefaults,
+    WEBHOOK_EVENTS,
+    Webhook,
+)
+from ._sync.client import Build, Project, Server, Server4Agent, Task
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    Server4AgentError,
+    UnprocessableEntityError,
+)
+from .webhooks import verify_webhook_signature
+
+__all__ = [
+    # clients
+    "Server4Agent",
+    "AsyncServer4Agent",
+    # sync handles
+    "Server",
+    "Project",
+    "Task",
+    "Build",
+    # async handles
+    "AsyncServer",
+    "AsyncProject",
+    "AsyncTask",
+    "AsyncBuild",
+    # data types
+    "ApiKey",
+    "CreatedApiKey",
+    "Webhook",
+    "CreatedWebhook",
+    "Deployment",
+    "ExecResult",
+    "BuildStep",
+    "ProjectTemplate",
+    "ProjectTemplateDefaults",
+    "WEBHOOK_EVENTS",
+    # errors
+    "Server4AgentError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    # webhooks
+    "verify_webhook_signature",
+    "__version__",
+]