server4agent 0.1.0__tar.gz → 0.9.0__tar.gz

server4agent-0.9.0/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+## 0.9.0
+
+Tuning runs are removed. The API no longer has the `/tuning/sessions`
+endpoints, so neither client calls them. This is a breaking change.
+
+- `client.tuning` is gone from both clients, with `list()`, `start()`, `get()`
+  and `report()`, and so are the `TuningSession` and `AsyncTuningSession`
+  handles and the `TuningStart` and `TuningStatus` types.
+- `WEBHOOK_EVENTS` no longer lists `tuning.started` or `tuning.completed`, and
+  `webhooks.create()` with either is refused as an unknown event. Nothing
+  sends them any more. A webhook created before they were retired may still
+  have them stored; `webhooks.list()` leaves them off its `events`.
+
+## 0.8.0
+
+Projects can put their URL behind a password.
+
+- `ProjectAccess` gains `"password"`: a visitor to the project's URL is asked
+  for a password the owner set, and gets in without any account. A project
+  read from the API can now report it, so code that branches on `access`
+  should handle the new value.
+- `projects.create()` and `project.update()` (sync and async, and the flat
+  `client.projects.update(project_id, ...)`) take `access_password`. It is
+  required when switching to `access="password"` unless a password is already
+  set, and refused with any other access. Sent on its own to a password
+  project, it changes the password and signs out everyone who used the old
+  one. Switching to another access discards it. It is at least 4 characters
+  (a 4 digit code works), stored encrypted, and never returned by the API.
+
+## 0.7.0
+
+The client now covers every operation in the REST API. Everything below is
+additive: code written against 0.6.0 keeps working unchanged.
+
+New:
+
+- Secrets, the environment variables injected into agent runs and bring-up.
+  `client.secrets.list()`, `set(key, value, description=None)` and
+  `delete(secret_id)` manage the account's secrets; `server.secrets` and
+  `project.secrets` (or `client.secrets.list_for_server()` /
+  `set_for_server()` / `list_for_project()` / `set_for_project()`) list and
+  bind them where they apply. Values are write-only: a `Secret` carries the
+  key, a note, a masked hint and its bindings, never the value.
+- `server.logs(project_id=None, lines=None)`, `project.logs()` and
+  `client.servers.logs(server_id, ...)` return the log-file tails a server's
+  background processes write, or `None` before any were reported. When the
+  server cannot be read live the API answers with its last saved copy, so
+  check `LogsSnapshot.updated_at` before reading a tail as current.
+- `project.start(command, name=None)` starts the project's app as a
+  background process on its routed port and keeps it running across restarts.
+  It returns an `AppStart` saying whether the app answered. When the app exits
+  instead, the `ConflictError` it raises carries the app's last output in
+  `err.body["log_tail"]`.
+- `project.init(proceed=None)` starts bring-up for a project seeded from code,
+  or resumes one paused waiting for secrets.
+- `project.export(ttl_seconds=None)` packs a project into one portable file
+  and returns a link to it, and `server.projects.import_bundle(bundle,
+  name=None)` recreates a project from that file, here or on another
+  deployment. `bundle` is the file's bytes or a base64 string. The result
+  lists the environment variables still to set in `missing_env`, because a
+  bundle carries their names and never their values.
+- `client.tuning` starts, lists, reads and reports tuning runs, which fix an
+  agent from an evaluation platform's report. A `TuningSession` has `wait()`,
+  like a task or a build: reading a session is what advances it, so polling
+  is how it reaches `reported` or `failed`.
+- `client.me()` returns the account the key acts on, its spend and budget this
+  period (`usage.blocked` says whether new tasks are refused), and how many
+  servers, projects and keys it has.
+- `APIStatusError.body` is the whole JSON error response, for details beyond
+  the message, such as why a file write was refused (`reason`).
+
+Catching up with the API:
+
+- `server.deploy()` takes `project_id`, and `project.deploy()` deploys that
+  project. A server with several projects used to refuse every deploy from
+  this client with a 400, because there was no way to say which one. Deploy
+  now only puts a project online once something in it is listening, and
+  raises `ConflictError` when nothing is. It still returns the URL as a `str`,
+  which now also carries `.status` (`"live"`, or `"publishing"` when the URL
+  had not answered yet) and `.project_id`.
+- `server.deployments()` raised `TypeError` on every call once the API began
+  returning each deployment's `project_id`. `Deployment.project_id` reads it.
+- `webhooks.create(url)` without `events` sent `"events": null`, which the API
+  refuses. It now leaves the field out, which subscribes to every event.
+  `WEBHOOK_EVENTS` adds `quota.egress_cap_reached`, `tuning.started` and
+  `tuning.completed`.
+- `server.exec()` takes `project_id`, to run inside that project's folder.
+- `tasks.create()` takes `project_id`, and `follow_up_of` to continue an
+  earlier task's conversation. A task now reads `project_id`, `log` (the live
+  progress note), `change` (what the run committed) and `usage` (tokens, turns
+  and cost); one created as a follow-up also reads `follow_up_of` and
+  `resumed`.
+- `servers.create()` and `projects.create()` take `secrets`, bound server-wide
+  or to the project. `projects.create()` also takes `source` (a template, a git
+  repository or an uploaded archive) and `auto_init`.
+- Projects read `source`, `init_phase` and `run_plan`, plus `init_run_id` on
+  the handle that started a bring-up. `project.update()` takes `run_plan`.
+- `files.get_download_url()` also returns the file's `path`.
+- Templates read `source_kind`, and a build step's status can be `"failed"`.
+- `ProjectAccess` and `ProjectVisibility` are exported from the package, as
+  0.4.0 said they were.
+- `examples/preview_env.py` builds the branch in the project's own folder,
+  starts the app with `project.start()` and puts it online with
+  `project.deploy()`. It used to build at the server root, so the project URL
+  it printed never had anything behind it.
+
+## 0.6.0
+
+- `server.kind` on every server handle: `"standard"` for a headless box,
+  `"browser"` for one with a screen and a browser on it. The field was already
+  set at creation but no read path returned it, so a browser server was
+  indistinguishable from a headless one once you had it. A server from an API
+  that predates the field reads as `"standard"`.
+- `kind` is accepted by `servers.create()` on both the sync and async clients,
+  which is what provisions a browser box. It needs a plan that allows the
+  medium tier, and costs more to run.
+
+## 0.5.0
+
+- Requires Python 3.11 or newer. 3.9 is past end of life and 3.10 reaches it in
+  October 2026, so the floor now sits on the oldest release that still gets
+  upstream fixes. The client itself is unchanged: on 3.11 and newer, 0.5.0
+  behaves exactly as 0.4.0 did.
+
+## 0.4.0
+
+- `project.access` and the `access` keyword on `projects.create()` and
+  `project.update()`. `"public"` is anyone with the link, which is what every
+  project did before and stays the default. `"team"` puts the project's URL
+  behind a Server4Agent sign-in, so only people in the account that owns it can
+  open it. A project from an API that predates the field reads as `"public"`.
+- `ProjectAccess` is exported alongside `ProjectVisibility`. The two are
+  separate on purpose: `visibility` decides whether the URL serves at all,
+  `access` decides who gets through once it does.
+
+## 0.3.0
+
+- `task.message_type`: `"user"` for a task you created, `"system"` for one the
+  platform started for you (a project imported from git brings itself up this
+  way). A system task's `goal` is a short summary of the run, not the
+  instructions its agent was given. Tasks from an API that predates the field
+  read as `"user"`.
+
+## 0.2.0
+
+- `files.get_download_url(server_id, path, ttl_seconds=None)` — mint a
+  signed, expiring link anyone can use to download one workspace file, no
+  API key required to fetch it.
+- `files.read_binary(server_id, path)` and `files.write(server_id, path,
+  content)` — read/write binary files (e.g. a generated `.xlsx`) without
+  corrupting bytes; `write` now also accepts `bytes` alongside `str`.
+
+## 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.9.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.5
+Name: server4agent
+Version: 0.9.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: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+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.11+. 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")
+# Ask visitors for a password before the URL opens. No account needed to get in.
+project.update(access="password", access_password="a long shared passphrase")
+```
+
+Binary files (e.g. a generated `.xlsx`) round-trip through `write`/`read_binary`
+without corruption, and `get_download_url` mints a shareable, expiring link:
+
+```python
+server.files.write("report.xlsx", xlsx_bytes)          # bytes -> base64 on the wire
+data = server.files.read_binary("report.xlsx")         # decoded back to bytes
+
+link = server.files.get_download_url("report.xlsx", ttl_seconds=3600)
+print(link["url"], link["expires_at"])
+```
+
+`server.kind` says what sort of box you are holding: `"standard"` is headless,
+`"browser"` has a screen with a browser on it, for sites an agent has to drive
+rather than fetch. It is orthogonal to `tier`, and a nickname proves nothing, so
+read the field rather than the name:
+
+```python
+server = client.servers.create(tier="medium", kind="browser")
+with_screens = [s for s in client.servers.list() if s.kind == "browser"]
+```
+
+`task.wait()` / `build.wait()` poll until a terminal state; both accept
+`poll_interval` and `timeout` (seconds).
+
+Not every task in a server's list is one you sent. `task.message_type` is
+`"system"` for runs the platform starts for you, such as the bring-up of a
+project imported from git, and `"user"` for your own. A system task's `goal` is
+a summary of what the run does, not the instructions its agent was given:
+
+```python
+mine = [t for t in server.tasks.list() if t.message_type == "user"]
+```
+
+`project_id` runs a task in one project's folder, and `follow_up_of` continues
+an earlier task's conversation, e.g. to answer one that is `awaiting_input`:
+
+```python
+task = server.tasks.create("Add a dark mode toggle", project_id=project.id)
+reply = server.tasks.create("Use the system setting by default", follow_up_of=task.id)
+```
+
+## Starting and deploying an app
+
+`project.start()` runs the app as a background process with `PORT` set to the
+project's routed port, keeps it running across restarts, and says whether it
+answered. `deploy()` then makes the project public once something is listening:
+
+```python
+from server4agent import ConflictError
+
+try:
+    started = project.start("node server.js")
+    print(started.status, started.listening)       # "running" True
+except ConflictError as e:
+    print(e.body.get("log_tail"))                   # the app's last output
+
+url = project.deploy()                              # or server.deploy(project_id=...)
+print(url, url.status)                              # "live", or "publishing" if not answering yet
+```
+
+`server.logs(project_id=None, lines=None)` (or `project.logs()`) returns the
+log-file tails of the server's background processes, or `None` before any
+were reported. When the server cannot be read live the API answers with its
+last saved copy, so check `updated_at` before trusting a tail as current:
+
+```python
+snap = project.logs(lines=50)
+if snap:
+    print(snap.updated_at)
+    for f in snap.files:
+        print(f.path, f.tail)
+```
+
+## Secrets
+
+Secrets are environment variables injected into agent runs and bring-up.
+Values are write-only: reads return the key, a note, a masked hint and where it
+is bound, never the value.
+
+```python
+from server4agent import SecretInput
+
+client.secrets.set("STRIPE_KEY", "sk_test_...", description="test mode")
+server.secrets.set([{"key": "DATABASE_URL", "value": "postgres://..."}])   # every project on the server
+project.secrets.set([SecretInput("SENTRY_DSN", "https://...")])            # this project only
+print([s.key for s in project.secrets.list()])
+```
+
+`servers.create()` and `projects.create()` also take `secrets=[...]`, so a
+project seeded from git can come up without stopping to ask for them:
+
+```python
+project = server.projects.create(
+    source={"kind": "git", "git_url": "https://github.com/northstar/app"},
+    secrets=[{"key": "DATABASE_URL", "value": "postgres://..."}],
+)
+print(project.init_phase, project.init_run_id)      # bring-up starts on its own
+project.init(proceed=True)                          # resume one waiting on secrets
+```
+
+## Moving a project
+
+`export()` packs a project into one file behind a time-limited link, and
+`import_bundle()` recreates it on any server, here or on another deployment.
+A bundle carries the names of the environment variables it needs, never their
+values:
+
+```python
+import httpx
+
+bundle = project.export(ttl_seconds=3600)
+data = httpx.get(bundle.url).content
+
+result = other_server.projects.import_bundle(data, name="landing-copy")
+print(result.project.id, result.missing_env)        # set these before the app can run
+```
+
+## Account and budget
+
+```python
+me = client.me()
+print(me.account["plan"], me.usage.spend_usd, me.usage.hard_limit_usd)
+if me.usage.blocked:
+    print("new tasks are refused:", me.usage.reason)
+```
+
+## 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
+```
+
+## Examples
+
+Runnable scripts in [`examples/`](examples/):
+
+| File | What it shows |
+| --- | --- |
+| [`quickstart.py`](examples/quickstart.py) | Provision a server, build an app, print the live URL. |
+| [`async_quickstart.py`](examples/async_quickstart.py) | The same flow on the async client. |
+| [`exec_and_files.py`](examples/exec_and_files.py) | Write a file, install a dependency, and run it on the durable workspace. |
+| [`await_input.py`](examples/await_input.py) | Handle a task that pauses to ask a question (`awaiting_input`). |
+| [`preview_env.py`](examples/preview_env.py) | Ephemeral per-PR preview URL for CI. |
+| [`webhook_receiver.py`](examples/webhook_receiver.py) | Verify webhook signatures in a Flask handler. |
+
+## API surface
+
+`servers`, `projects`, `templates`, `tasks`, `builds`, `files`, `secrets`,
+`keys`, `webhooks`, and `client.me()`. Every REST operation has a
+method on both clients; see the
+[REST API docs](https://www.server4agent.com/docs/api) for the endpoints each
+one wraps.
+
+Server-side only: this SDK holds your `sk_live_` key. Never embed it in a
+notebook or script you share.