helm-runtime-sdk 1.0.0rc1__py3-none-any.whl

helm_runtime_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""helmstudio's runtime SDK for Python: a client for the platform API.
+
+    from helm_runtime_sdk import from_env
+    helm = from_env()
+    asset = helm.assets.adopt({"path": out, "kind": "video"})
+    helm.gallery.add({"kind": "video", "asset_id": asset["id"], "params": {"seed": 42}})
+
+Standard library only. Method names match the Go and Node clients
+(docs/design/04-packages.md §4). _generated.py is generated by api/gen; the rest
+is written by hand. Sync only for now; the embedded provider for Python is
+decided with the Python studios (docs/decisions.md M4 Q3, Q25).
+"""
+
+import os
+
+from ._generated import API_VERSION, Client
+from ._transport import Event, HelmError, RawResponse, Transport
+
+__all__ = ["API_VERSION", "Client", "Event", "HelmError", "RawResponse", "Transport", "from_env", "remote"]
+
+
+def remote(base: str, token: str) -> Client:
+    """A client for the API at base, e.g. http://127.0.0.1:8700/api/v1."""
+    return Client(Transport(base, token))
+
+
+def from_env() -> Client:
+    """The remote client when HELM_API is set, as helmstudio and helm dev do."""
+    api = os.environ.get("HELM_API")
+    if not api:
+        raise HelmError(0, "no_provider", "HELM_API is not set; run under helmstudio or helm dev")
+    token = os.environ.get("HELM_TOKEN")
+    if not token:
+        raise HelmError(0, "no_token", "HELM_API is set but HELM_TOKEN is not; a studio with no capabilities gets no token")
+    return remote(api, token)

helm_runtime_sdk/_generated.py

@@ -0,0 +1,308 @@
+# Code generated by api/gen from api/openapi.yaml. DO NOT EDIT.
+"""Generated groups of the helmstudio runtime SDK. Import from helm_runtime_sdk."""
+
+from typing import Any, Dict, Optional, Sequence
+
+from ._transport import Transport, quote
+
+API_VERSION = "1.0.0"
+
+
+class MeGroup:
+    """The me group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def get(self) -> Any:
+        """Who the token belongs to, what it may do, and how much quota is left. (GET /me)"""
+        return self._t.request("GET", "/me", query={}, headers={}, expect="json")
+
+class EventsGroup:
+    """The events group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def subscribe(self, *, last_event_id: Optional[Any] = None) -> Any:
+        """Server-sent events for the calling studio. (GET /events)"""
+        return self._t.request("GET", "/events", query={}, headers={"Last-Event-ID": last_event_id}, expect="sse")
+
+class KVGroup:
+    """The kv group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(self, ns: str, *, prefix: Optional[Any] = None, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """List keys in a namespace, with sizes and modified times. No values. (GET /kv/{ns})"""
+        return self._t.request("GET", "/kv/" + quote(ns), query={"prefix": prefix, "limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def get(self, ns: str, key: str) -> Any:
+        """Read one document. (GET /kv/{ns}/{key})"""
+        return self._t.request("GET", "/kv/" + quote(ns) + "/" + quote(key), query={}, headers={}, expect="json")
+
+    def put(self, ns: str, key: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any:
+        """Create or replace a document. (PUT /kv/{ns}/{key})"""
+        return self._t.request("PUT", "/kv/" + quote(ns) + "/" + quote(key), query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/json")
+
+    def patch(self, ns: str, key: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any:
+        """Apply a JSON merge patch (RFC 7396) to an existing document. (PATCH /kv/{ns}/{key})"""
+        return self._t.request("PATCH", "/kv/" + quote(ns) + "/" + quote(key), query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/merge-patch+json")
+
+    def delete(self, ns: str, key: str, *, if_match: Optional[Any] = None) -> Any:
+        """Remove a document. (DELETE /kv/{ns}/{key})"""
+        return self._t.request("DELETE", "/kv/" + quote(ns) + "/" + quote(key), query={}, headers={"If-Match": if_match}, expect="empty")
+
+class SessionsGroup:
+    """The sessions group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(self, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """The calling studio's sessions, most recently opened first. (GET /sessions)"""
+        return self._t.request("GET", "/sessions", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def create(self, body: Dict[str, Any]) -> Any:
+        """Create a session. (POST /sessions)"""
+        return self._t.request("POST", "/sessions", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def get(self, id: str) -> Any:
+        """One session. A deleted session, or another studio's, is 404. (GET /sessions/{id})"""
+        return self._t.request("GET", "/sessions/" + quote(id), query={}, headers={}, expect="json")
+
+    def update(self, id: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any:
+        """Rename, or merge changes into the state document. (PATCH /sessions/{id})"""
+        return self._t.request("PATCH", "/sessions/" + quote(id), query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/merge-patch+json")
+
+    def delete(self, id: str, *, if_match: Optional[Any] = None) -> Any:
+        """Soft-delete. Its name becomes free; items keep their session_id. (DELETE /sessions/{id})"""
+        return self._t.request("DELETE", "/sessions/" + quote(id), query={}, headers={"If-Match": if_match}, expect="empty")
+
+    def duplicate(self, id: str, body: Dict[str, Any]) -> Any:
+        """Copy a session's state under a new name. The copy has never been opened. (POST /sessions/{id}:duplicate)"""
+        return self._t.request("POST", "/sessions/" + quote(id) + ":duplicate", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def activate(self, id: str) -> Any:
+        """Set opened_at to now. Changes neither the state nor the etag, nor any process. (POST /sessions/{id}:activate)"""
+        return self._t.request("POST", "/sessions/" + quote(id) + ":activate", query={}, headers={}, expect="empty")
+
+class RecordsGroup:
+    """The records group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def query(self, collection: str, *, where: Optional[Sequence[str]] = None, order: Optional[Any] = None, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """Query a collection with the closed filter language. Never SQL. (GET /records/{collection})"""
+        return self._t.request("GET", "/records/" + quote(collection), query={"where": where, "order": order, "limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def insert(self, collection: str, body: Dict[str, Any]) -> Any:
+        """Insert a document; returns its id and etag. (POST /records/{collection})"""
+        return self._t.request("POST", "/records/" + quote(collection), query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def get(self, collection: str, id: str) -> Any:
+        """One record. Deleted, in another collection, or another studio's is 404. (GET /records/{collection}/{id})"""
+        return self._t.request("GET", "/records/" + quote(collection) + "/" + quote(id), query={}, headers={}, expect="json")
+
+    def replace(self, collection: str, id: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any:
+        """Replace a document. If-Match on the etag; 409 on conflict. (PUT /records/{collection}/{id})"""
+        return self._t.request("PUT", "/records/" + quote(collection) + "/" + quote(id), query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/json")
+
+    def patch(self, collection: str, id: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any:
+        """Apply a JSON merge patch (RFC 7396). If-Match on the etag; 409 on conflict. (PATCH /records/{collection}/{id})"""
+        return self._t.request("PATCH", "/records/" + quote(collection) + "/" + quote(id), query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/merge-patch+json")
+
+    def delete(self, collection: str, id: str, *, if_match: Optional[Any] = None) -> Any:
+        """Soft-delete, so an undo is possible and a sync never sees a gap. (DELETE /records/{collection}/{id})"""
+        return self._t.request("DELETE", "/records/" + quote(collection) + "/" + quote(id), query={}, headers={"If-Match": if_match}, expect="empty")
+
+class AssetsGroup:
+    """The assets group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def upload(self, body: bytes, content_type: str, *, kind: Any, filename: Optional[Any] = None, pinned: Optional[Any] = None, width: Optional[Any] = None, height: Optional[Any] = None, duration_s: Optional[Any] = None, fps: Optional[Any] = None) -> Any:
+        """Upload bytes. Idempotent on content. (POST /assets)"""
+        return self._t.request("POST", "/assets", query={"kind": kind, "filename": filename, "pinned": pinned, "width": width, "height": height, "duration_s": duration_s, "fps": fps}, headers={}, expect="json", raw_body=body, content_type=content_type)
+
+    def adopt(self, body: Dict[str, Any]) -> Any:
+        """Adopt a file from the stage or data directory by hardlink — no copy, no HTTP body. (POST /assets:adopt)"""
+        return self._t.request("POST", "/assets:adopt", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def read(self, id: str, *, range: Optional[Any] = None) -> Any:
+        """The asset's bytes, with Range. (GET /assets/{id})"""
+        return self._t.request("GET", "/assets/" + quote(id), query={}, headers={"Range": range}, expect="raw")
+
+    def thumb(self, id: str, *, w: Optional[Any] = None) -> Any:
+        """A thumbnail, generated once and cached. (GET /assets/{id}/thumb)"""
+        return self._t.request("GET", "/assets/" + quote(id) + "/thumb", query={"w": w}, headers={}, expect="raw")
+
+    def lineage(self, id: str, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """Downstream provenance — every item ever made from this asset, recursively. (GET /assets/{id}/lineage)"""
+        return self._t.request("GET", "/assets/" + quote(id) + "/lineage", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+class GalleryGroup:
+    """The gallery group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def add(self, body: Dict[str, Any]) -> Any:
+        """Record an output with its params, inputs, tags and session. One call per generation. (POST /gallery/items)"""
+        return self._t.request("POST", "/gallery/items", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def query(self, *, scope: Optional[Any] = None, studio: Optional[Any] = None, kind: Optional[Any] = None, tag: Optional[Sequence[str]] = None, session_id: Optional[Any] = None, starred: Optional[Any] = None, asset_id: Optional[Any] = None, since: Optional[Any] = None, until: Optional[Any] = None, q: Optional[Any] = None, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """Query items, scoped to the caller unless scope=all. (GET /gallery/items)"""
+        return self._t.request("GET", "/gallery/items", query={"scope": scope, "studio": studio, "kind": kind, "tag": tag, "session_id": session_id, "starred": starred, "asset_id": asset_id, "since": since, "until": until, "q": q, "limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def get(self, id: str) -> Any:
+        """One item. Another studio's without gallery.read_all, or a deleted one, is 404. (GET /gallery/items/{id})"""
+        return self._t.request("GET", "/gallery/items/" + quote(id), query={}, headers={}, expect="json")
+
+    def update(self, id: str, body: Dict[str, Any]) -> Any:
+        """Star, tag or rename one of the caller's own items. (PATCH /gallery/items/{id})"""
+        return self._t.request("PATCH", "/gallery/items/" + quote(id), query={}, headers={}, expect="json", json_body=body, content_type="application/merge-patch+json")
+
+    def delete(self, id: str) -> Any:
+        """Soft-delete one of the caller's own items. (DELETE /gallery/items/{id})"""
+        return self._t.request("DELETE", "/gallery/items/" + quote(id), query={}, headers={}, expect="empty")
+
+    def lineage(self, id: str, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """Upstream provenance — the items whose outputs this item was made from, recursively. (GET /gallery/items/{id}/lineage)"""
+        return self._t.request("GET", "/gallery/items/" + quote(id) + "/lineage", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+class HandoffGroup:
+    """The handoff group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def send(self, body: Dict[str, Any]) -> Any:
+        """Put an item in another studio's inbox. (POST /handoff)"""
+        return self._t.request("POST", "/handoff", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+class InboxGroup:
+    """The inbox group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(self, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """Handoffs to the caller not yet consumed, oldest first. (GET /inbox)"""
+        return self._t.request("GET", "/inbox", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def consume(self, id: str) -> Any:
+        """Mark an entry handled. Idempotent. (POST /inbox/{id}:consume)"""
+        return self._t.request("POST", "/inbox/" + quote(id) + ":consume", query={}, headers={}, expect="empty")
+
+class JobsGroup:
+    """The jobs group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(self, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """The calling studio's jobs, of every kind, newest first. (GET /jobs)"""
+        return self._t.request("GET", "/jobs", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def create(self, body: Dict[str, Any]) -> Any:
+        """Report a long-running piece of the studio's own work as a task job. (POST /jobs)"""
+        return self._t.request("POST", "/jobs", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def get(self, id: str) -> Any:
+        """One of the calling studio's jobs. Another studio's is 404. (GET /jobs/{id})"""
+        return self._t.request("GET", "/jobs/" + quote(id), query={}, headers={}, expect="json")
+
+    def update(self, id: str, body: Dict[str, Any]) -> Any:
+        """Report progress on, or finish, a task job the calling studio created. (PATCH /jobs/{id})"""
+        return self._t.request("PATCH", "/jobs/" + quote(id), query={}, headers={}, expect="json", json_body=body, content_type="application/merge-patch+json")
+
+    def cancel(self, id: str) -> Any:
+        """Ask for one of the calling studio's task jobs to be cancelled. (POST /jobs/{id}:cancel)"""
+        return self._t.request("POST", "/jobs/" + quote(id) + ":cancel", query={}, headers={}, expect="empty")
+
+    def logs(self, id: str) -> Any:
+        """One of the calling studio's job logs as server-sent events, from the start, then live until the job finishes. (GET /jobs/{id}/logs)"""
+        return self._t.request("GET", "/jobs/" + quote(id) + "/logs", query={}, headers={}, expect="sse")
+
+    def append_log(self, id: str, body: Dict[str, Any]) -> Any:
+        """Append lines to a running task job's log. (POST /jobs/{id}/logs)"""
+        return self._t.request("POST", "/jobs/" + quote(id) + "/logs", query={}, headers={}, expect="empty", json_body=body, content_type="application/json")
+
+class TimelineGroup:
+    """The timeline group."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(self, body: Dict[str, Any]) -> Any:
+        """Create a sequence from clips, or from whole tracks. (POST /timeline)"""
+        return self._t.request("POST", "/timeline", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def list(self, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """The sequences the caller may read, newest first. (GET /timeline)"""
+        return self._t.request("GET", "/timeline", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def get(self, id: str) -> Any:
+        """One sequence. One the caller may not read is 404. (GET /timeline/{id})"""
+        return self._t.request("GET", "/timeline/" + quote(id), query={}, headers={}, expect="json")
+
+    def update(self, id: str, body: Dict[str, Any], *, if_match: Any) -> Any:
+        """Edit a sequence. Every edit is a revision. (PATCH /timeline/{id})"""
+        return self._t.request("PATCH", "/timeline/" + quote(id), query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/merge-patch+json")
+
+    def delete(self, id: str, *, if_match: Optional[Any] = None) -> Any:
+        """Delete a sequence. Its exports and their lineage stay. (DELETE /timeline/{id})"""
+        return self._t.request("DELETE", "/timeline/" + quote(id), query={}, headers={"If-Match": if_match}, expect="empty")
+
+    def revisions(self, id: str, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """The sequence's earlier revisions, newest first. (GET /timeline/{id}/revisions)"""
+        return self._t.request("GET", "/timeline/" + quote(id) + "/revisions", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def revert(self, id: str, body: Dict[str, Any], *, if_match: Any) -> Any:
+        """Write an earlier revision back as the newest one. (POST /timeline/{id}:revert)"""
+        return self._t.request("POST", "/timeline/" + quote(id) + ":revert", query={}, headers={"If-Match": if_match}, expect="json", json_body=body, content_type="application/json")
+
+    def append(self, body: Dict[str, Any]) -> Any:
+        """Add one asset to the end of a track, without stealing focus. (POST /timeline:append)"""
+        return self._t.request("POST", "/timeline:append", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def open(self, id: str) -> Any:
+        """Ask the framework to show its editor on this sequence. (POST /timeline/{id}:open)"""
+        return self._t.request("POST", "/timeline/" + quote(id) + ":open", query={}, headers={}, expect="json")
+
+    def plan(self, id: str, *, preset: Optional[Any] = None) -> Any:
+        """Which path an export would take, and why. (GET /timeline/{id}:plan)"""
+        return self._t.request("GET", "/timeline/" + quote(id) + ":plan", query={"preset": preset}, headers={}, expect="json")
+
+    def export(self, id: str, body: Dict[str, Any]) -> Any:
+        """Export the sequence. Answers with the job that renders it. (POST /timeline/{id}:export)"""
+        return self._t.request("POST", "/timeline/" + quote(id) + ":export", query={}, headers={}, expect="json", json_body=body, content_type="application/json")
+
+    def exports(self, id: str, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any:
+        """The sequence's export jobs, newest first. (GET /timeline/{id}/exports)"""
+        return self._t.request("GET", "/timeline/" + quote(id) + "/exports", query={"limit": limit, "cursor": cursor}, headers={}, expect="json")
+
+    def cancel_export(self, id: str, job: str) -> Any:
+        """Stop a running export and leave nothing behind. (POST /timeline/{id}/exports/{job}:cancel)"""
+        return self._t.request("POST", "/timeline/" + quote(id) + "/exports/" + quote(job) + ":cancel", query={}, headers={}, expect="empty")
+
+
+class Client:
+    """One attribute per API group, the same names as the Go and Node clients."""
+
+    def __init__(self, transport: Transport) -> None:
+        self.me = MeGroup(transport)
+        self.events = EventsGroup(transport)
+        self.kv = KVGroup(transport)
+        self.sessions = SessionsGroup(transport)
+        self.records = RecordsGroup(transport)
+        self.assets = AssetsGroup(transport)
+        self.gallery = GalleryGroup(transport)
+        self.handoff = HandoffGroup(transport)
+        self.inbox = InboxGroup(transport)
+        self.jobs = JobsGroup(transport)
+        self.timeline = TimelineGroup(transport)

helm_runtime_sdk/_transport.py

@@ -0,0 +1,148 @@
+"""HTTP transport for the helmstudio runtime SDK. Standard library only."""
+
+import datetime
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterator, Optional
+
+
+def quote(value: str) -> str:
+    """Escape one path segment."""
+    return urllib.parse.quote(str(value), safe=":")
+
+
+# The one typed error shape across languages (docs/design/04-packages.md §4).
+KINDS = {
+    400: "Invalid", 413: "Invalid", 416: "Invalid", 422: "Invalid",
+    401: "Unauthenticated",
+    403: "Forbidden", 421: "Forbidden",
+    404: "NotFound", 410: "NotFound",
+    409: "Conflict",
+    429: "QuotaExceeded", 507: "QuotaExceeded",
+    501: "Unsupported",
+    503: "Unavailable",
+}
+
+
+class HelmError(Exception):
+    """Every refusal: status, stable code, message and details."""
+
+    def __init__(self, status: int, code: str, message: str, details: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__("%s (%d): %s" % (code, status, message))
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    @property
+    def kind(self) -> str:
+        if self.status == 0:
+            return "Unavailable"
+        return KINDS.get(self.status, "Internal")
+
+
+class RawResponse:
+    """An asset's bytes or a thumbnail."""
+
+    def __init__(self, response: Any) -> None:
+        self.status = response.status
+        self.headers = dict(response.headers.items())
+        self._response = response
+
+    def read(self) -> bytes:
+        try:
+            return self._response.read()
+        finally:
+            self._response.close()
+
+
+class Event:
+    def __init__(self, event_id: str, name: str, data: str) -> None:
+        self.id = event_id
+        self.name = name
+        self.data = data
+
+    def json(self) -> Any:
+        return json.loads(self.data) if self.data else None
+
+
+def _events(response: Any) -> Iterator[Event]:
+    event_id, name, data = "", "", []
+    try:
+        for raw in response:
+            line = raw.decode("utf-8").rstrip("\r\n")
+            if line == "":
+                if name or data:
+                    yield Event(event_id, name, "\n".join(data))
+                event_id, name, data = "", "", []
+            elif line.startswith(":"):
+                continue
+            elif line.startswith("id:"):
+                event_id = line[3:].strip()
+            elif line.startswith("event:"):
+                name = line[6:].strip()
+            elif line.startswith("data:"):
+                data.append(line[5:].lstrip(" "))
+    finally:
+        response.close()
+
+
+def _value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, datetime.datetime):
+        return v.isoformat()
+    return str(v)
+
+
+class Transport:
+    def __init__(self, base: str, token: str, timeout: float = 60.0) -> None:
+        self.base = base.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    def request(self, method: str, path: str, query: Dict[str, Any], headers: Dict[str, Any], expect: str,
+                json_body: Any = None, raw_body: Optional[bytes] = None, content_type: Optional[str] = None) -> Any:
+        pairs = []
+        for k, v in query.items():
+            if v is None:
+                continue
+            if isinstance(v, (list, tuple)):
+                pairs.extend((k, _value(x)) for x in v)
+            else:
+                pairs.append((k, _value(v)))
+        url = self.base + path + ("?" + urllib.parse.urlencode(pairs) if pairs else "")
+        body = None
+        if json_body is not None:
+            body = json.dumps(json_body).encode("utf-8")
+        elif raw_body is not None:
+            body = raw_body
+        req = urllib.request.Request(url, data=body, method=method)
+        req.add_header("Authorization", "Bearer " + self.token)
+        if content_type:
+            req.add_header("Content-Type", content_type)
+        for k, v in headers.items():
+            if v is not None:
+                req.add_header(k, _value(v))
+        try:
+            response = urllib.request.urlopen(req, timeout=None if expect == "sse" else self.timeout)
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            try:
+                doc = json.loads(raw)
+                raise HelmError(e.code, doc.get("error", "unexpected_response"), doc.get("message", ""), doc.get("details")) from None
+            except ValueError:
+                raise HelmError(e.code, "unexpected_response", raw.decode("utf-8", "replace")) from None
+        except urllib.error.URLError as e:
+            raise HelmError(0, "unavailable", str(e.reason)) from None
+        if expect == "sse":
+            return _events(response)
+        if expect == "raw":
+            return RawResponse(response)
+        with response:
+            raw = response.read()
+        if expect == "json":
+            return json.loads(raw)
+        return None

helm_runtime_sdk/proxy.py

@@ -0,0 +1,259 @@
+"""The same-origin proxy a studio mounts at /helm/, so its page never holds a token.
+
+Standard library only. It behaves exactly as the Go and Node runtime SDKs'
+proxies do (docs/decisions.md M6 Q10; test/conformance holds all three to it):
+
+- ``/helm/api/v1/<studio-api path>`` is forwarded to ``HELM_API`` with
+  ``HELM_TOKEN`` added. Only the studio API and the theme stream; a launcher
+  path is 404 and never reaches the daemon.
+- ``/helm/sdk/v1/<file>`` (GET and HEAD) is forwarded to ``HELM_SDK_BASE``
+  without a token.
+- ``/helm/accent.css`` is the studio's hue for each theme.
+
+The page's own Authorization, cookies, Origin and Referer are never forwarded,
+and the daemon's Set-Cookie never comes back.
+
+For a stdlib ``http.server`` studio::
+
+    from helm_runtime_sdk.proxy import Proxy
+    proxy = Proxy.from_env()
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            if proxy.handle_http(self):
+                return
+            ...
+
+For a WSGI studio, mount ``proxy.wsgi`` under ``/helm``.
+"""
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from typing import Dict, Iterable, Iterator, List, Optional, Tuple
+
+PREFIX = "/helm/"
+
+# First path segments under /api/v1/ that are forwarded: every studio-api
+# operation's, and the theme stream's.
+STUDIO_SEGMENTS = frozenset(
+    [
+        "me", "events", "kv", "sessions", "records", "assets", "assets:adopt", "gallery",
+        "handoff", "inbox", "jobs", "theme", "timeline", "timeline:append",
+    ]
+)
+
+REQUEST_HEADERS = ["Accept", "Content-Type", "Range", "If-Range", "If-Match", "If-None-Match", "Last-Event-ID"]
+RESPONSE_HEADERS = ["Content-Type", "Content-Length", "Content-Range", "Accept-Ranges", "ETag", "Last-Modified", "Cache-Control", "Content-Disposition", "Allow"]
+METHODS = frozenset(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"])
+
+_HEX = re.compile(r"^#[0-9a-fA-F]{6}$")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):  # never follow: forward as is
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+Response = Tuple[int, List[Tuple[str, str]], Iterable[bytes]]
+
+
+def _luminance(hex_colour: str) -> float:
+    out = []
+    for i in range(3):
+        c = int(hex_colour[1 + 2 * i : 3 + 2 * i], 16) / 255
+        out.append(c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4)
+    return 0.2126 * out[0] + 0.7152 * out[1] + 0.0722 * out[2]
+
+
+def _on(hex_colour: str) -> str:
+    lum = _luminance(hex_colour)
+    dark = (lum + 0.05) / (_luminance("#1a1400") + 0.05)
+    white = 1.05 / (lum + 0.05)
+    return "#1a1400" if dark >= white else "#ffffff"
+
+
+def accent_css(dark: str, light: str) -> Optional[str]:
+    """/helm/accent.css for a hue pair, or None unless both are #rrggbb."""
+    if not dark or not light or not _HEX.match(dark) or not _HEX.match(light):
+        return None
+    dark, light = dark.lower(), light.lower()
+
+    def block(h: str) -> str:
+        return "--helm-studio-accent: " + h + "; --helm-on-studio-accent: " + _on(h) + ";"
+
+    return (
+        ":root { " + block(dark) + " }\n"
+        + "@media (prefers-color-scheme: light) { :root:not([data-theme]) { " + block(light) + " } }\n"
+        + ':root[data-theme="light"] { ' + block(light) + " }\n"
+    )
+
+
+def safe_path(path: str) -> bool:
+    """Refuse dot segments, empty segments and encoded slashes, backslashes or dots."""
+    lower = path.lower()
+    if "%2f" in lower or "%5c" in lower or "%2e" in lower or "\\" in path:
+        return False
+    segs = path.lstrip("/").split("/")
+    for i, s in enumerate(segs):
+        if s in (".", "..") or (s == "" and i != len(segs) - 1):
+            return False
+    return True
+
+
+def _error(status: int, code: str, message: str) -> Response:
+    body = json.dumps({"error": code, "message": message}).encode() + b"\n"
+    return status, [("Content-Type", "application/json"), ("X-Content-Type-Options", "nosniff")], [body]
+
+
+def _not_found() -> Response:
+    return _error(404, "not_found", "the helm proxy forwards only the studio API, the theme stream, the SDK files and accent.css")
+
+
+class Proxy:
+    def __init__(self, api: str = "", token: str = "", sdk_base: str = "", accent_dark: str = "", accent_light: str = "") -> None:
+        self.api = api.rstrip("/")
+        self.token = token
+        self.sdk_base = sdk_base.rstrip("/")
+        self.accent_dark = accent_dark
+        self.accent_light = accent_light
+
+    @classmethod
+    def from_env(cls, env: Optional[Dict[str, str]] = None) -> "Proxy":
+        e = os.environ if env is None else env
+        return cls(e.get("HELM_API", ""), e.get("HELM_TOKEN", ""), e.get("HELM_SDK_BASE", ""),
+                   e.get("HELM_ACCENT_DARK", ""), e.get("HELM_ACCENT_LIGHT", ""))
+
+    def respond(self, method: str, raw_path: str, query: str, headers: Dict[str, str], body: Optional[bytes]) -> Response:
+        """Answer one request. raw_path is the escaped path, starting /helm/."""
+        if not raw_path.startswith(PREFIX):
+            return _not_found()
+        rest = raw_path[len(PREFIX) - 1 :]
+        if not safe_path(rest):
+            return _not_found()
+        if rest == "/accent.css":
+            css = accent_css(self.accent_dark, self.accent_light)
+            if css is None or method not in ("GET", "HEAD"):
+                return _not_found()
+            payload = [] if method == "HEAD" else [css.encode()]
+            return 200, [("Content-Type", "text/css; charset=utf-8"), ("Cache-Control", "no-cache"), ("X-Content-Type-Options", "nosniff")], payload
+        if rest.startswith("/api/v1/"):
+            sub = rest[len("/api/v1/") :]
+            first = sub.split("/", 1)[0]
+            if not self.api or first not in STUDIO_SEGMENTS:
+                return _not_found()
+            return self._forward(method, self.api + "/" + sub, query, headers, body, self.token)
+        if rest.startswith("/sdk/v1/"):
+            if not self.sdk_base or method not in ("GET", "HEAD"):
+                return _not_found()
+            return self._forward(method, self.sdk_base + "/" + rest[len("/sdk/v1/") :], query, headers, None, "")
+        return _not_found()
+
+    def _forward(self, method: str, target: str, query: str, headers: Dict[str, str], body: Optional[bytes], token: str) -> Response:
+        if method not in METHODS:
+            return _error(405, "method_not_allowed", method + " is not forwarded")
+        if query:
+            target += "?" + query
+        lower = {k.lower(): v for k, v in headers.items()}
+        out = {}
+        for h in REQUEST_HEADERS:
+            if h.lower() in lower:
+                out[h] = lower[h.lower()]
+        if token:
+            out["Authorization"] = "Bearer " + token
+        data = body if method not in ("GET", "HEAD") else None
+        if method in ("POST", "PUT", "PATCH") and data is None:
+            data = b""
+        req = urllib.request.Request(target, data=data, method=method, headers=out)
+        try:
+            res = _opener.open(req)
+        except urllib.error.HTTPError as e:
+            res = e
+        except (urllib.error.URLError, OSError):
+            # Never the error text: it can carry the upstream URL.
+            return _error(503, "unavailable", "helmstudio did not answer")
+        status = res.status if hasattr(res, "status") else res.code
+        resp_headers = [("X-Content-Type-Options", "nosniff")]
+        for h in RESPONSE_HEADERS:
+            for v in res.headers.get_all(h) or []:
+                resp_headers.append((h, v))
+        if method == "HEAD":
+            res.close()
+            return status, resp_headers, []
+        return status, resp_headers, _chunks(res)
+
+    def wsgi(self, environ, start_response):
+        """A WSGI application for everything under /helm/."""
+        raw = environ.get("RAW_URI") or environ.get("REQUEST_URI") or ""
+        raw = raw.split("?", 1)[0] if raw else (environ.get("SCRIPT_NAME", "") + environ.get("PATH_INFO", ""))
+        headers = {k[5:].replace("_", "-").title(): v for k, v in environ.items() if k.startswith("HTTP_")}
+        if environ.get("CONTENT_TYPE"):
+            headers["Content-Type"] = environ["CONTENT_TYPE"]
+        length = int(environ.get("CONTENT_LENGTH") or 0)
+        body = environ["wsgi.input"].read(length) if length else None
+        status, hdrs, payload = self.respond(environ.get("REQUEST_METHOD", "GET"), raw, environ.get("QUERY_STRING", ""), headers, body)
+        start_response("%d %s" % (status, _reason(status)), hdrs)
+        return payload
+
+    def handle_http(self, handler) -> bool:
+        """Serve a request on a http.server.BaseHTTPRequestHandler if it is under /helm/.
+
+        Returns False, having written nothing, for any other path.
+        """
+        path, _, query = handler.path.partition("?")
+        if not path.startswith(PREFIX):
+            return False
+        length = int(handler.headers.get("Content-Length") or 0)
+        body = handler.rfile.read(length) if length else None
+        status, hdrs, payload = self.respond(handler.command, path, query, dict(handler.headers.items()), body)
+        if isinstance(payload, list):
+            # Fully known: say how long it is, so a kept-alive connection ends the response.
+            data = b"".join(payload)
+            payload = [data]
+            if handler.command != "HEAD":
+                hdrs = [(k, v) for k, v in hdrs if k != "Content-Length"] + [("Content-Length", str(len(data)))]
+            elif not any(k == "Content-Length" for k, _ in hdrs):
+                hdrs = hdrs + [("Content-Length", "0")]
+        elif not any(k == "Content-Length" for k, _ in hdrs):
+            # A stream of unknown length ends when the connection closes.
+            handler.close_connection = True
+            hdrs = hdrs + [("Connection", "close")]
+        handler.send_response(status)
+        for k, v in hdrs:
+            handler.send_header(k, v)
+        handler.end_headers()
+        try:
+            for chunk in payload:
+                handler.wfile.write(chunk)
+                handler.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+        finally:
+            close = getattr(payload, "close", None)
+            if close:
+                close()
+        return True
+
+
+def _chunks(res) -> Iterator[bytes]:
+    try:
+        while True:
+            chunk = res.read1(65536) if hasattr(res, "read1") else res.read(65536)
+            if not chunk:
+                return
+            yield chunk
+    finally:
+        res.close()
+
+
+def _reason(status: int) -> str:
+    from http import HTTPStatus
+
+    try:
+        return HTTPStatus(status).phrase
+    except ValueError:
+        return ""

helm_runtime_sdk-1.0.0rc1.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: helm-runtime-sdk
+Version: 1.0.0rc1
+Summary: helmstudio's runtime SDK: a client for the platform API
+Author: Janishar Ali
+License: MIT
+Project-URL: Documentation, https://helmstudio.in/docs/
+Project-URL: Repository, https://github.com/janishar/helmstudio
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# helm-runtime-sdk
+
+helmstudio's runtime SDK for Python: the client a studio uses to reach the
+platform API — keep its files in the library, record what it makes in the
+gallery with the parameters and inputs that made it, keep sessions and
+settings, hand clips to the timeline — and the same-origin proxy that lets its
+page use the API and helm-css without holding a token.
+
+    pip install --pre helm-runtime-sdk
+
+It uses the standard library only, and needs Python 3.9 or newer.
+
+A studio built with it runs under helmstudio, or on its own under `helm dev`,
+which set `HELM_API` and `HELM_TOKEN` for it:
+
+    from helm_runtime_sdk import from_env
+
+    helm = from_env()
+    asset = helm.assets.adopt({"path": path, "kind": "image"})
+    helm.gallery.add({"kind": "image", "asset_id": asset["id"], "params": {"prompt": prompt}})
+
+The proxy is `helm_runtime_sdk.proxy`.
+
+The documentation — the quickstart, the guides, and every call in Python, Go
+and JavaScript — is at https://helmstudio.in/docs/.

helm_runtime_sdk-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,9 @@
+helm_runtime_sdk/__init__.py,sha256=v_jl-6Ma5_8F9tbEQVUG6JPGyfyzdnPsE0FlMJH1I7I,1448
+helm_runtime_sdk/_generated.py,sha256=96boCcxXRU3ymssgm42bQf-f6cX3lSE-_o1wz_pGhlk,19454
+helm_runtime_sdk/_transport.py,sha256=fJ4jWtrQ5Of2qqeXFNqiPfk6dmJL2uQjQlarMqFXkYg,4972
+helm_runtime_sdk/proxy.py,sha256=WpQFGSrjdKHJrVDNmzxsviyKl-9J7sTAsj9vqijzxPU,10710
+helm_runtime_sdk-1.0.0rc1.dist-info/licenses/LICENSE,sha256=Pi8mZuoS8vyZDHm7Fbh-abXjQcZz3W4TdhezZR6rHPw,1069
+helm_runtime_sdk-1.0.0rc1.dist-info/METADATA,sha256=MplKl5LZiTGbbZY2qwii2dXdCRcnYA7RMIeAynDpcvw,1587
+helm_runtime_sdk-1.0.0rc1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+helm_runtime_sdk-1.0.0rc1.dist-info/top_level.txt,sha256=b7WyuDEvqDmJgoqpUw9S4TVGgCfQdfBMkass5UY1IH8,17
+helm_runtime_sdk-1.0.0rc1.dist-info/RECORD,,

helm_runtime_sdk-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

helm_runtime_sdk-1.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janishar Ali
+
+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.

helm_runtime_sdk-1.0.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+helm_runtime_sdk