Scaffold subfork Python API client and package checks

Author: rsgalloway

.github/workflows/tests.yml

@@ -0,0 +1,19 @@
+name: Test and package
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.10', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install '.[dev]'
+      - run: python -m pytest
+      - run: python -m build
+      - run: python -m twine check dist/*

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.env
+.env.*
+build/
+dist/
+*.egg-info/

README.md

@@ -1 +1,100 @@
-hello world
+# subfork
+
+Python API client for Subfork graph authoring, publication and execution.
+**Alpha scaffold; not yet published to PyPI.** Distribution and import name: `subfork`.
+BYO workers belong in the separate worker package, not this client.
+
+## Development install
+
+Requires Python 3.10+.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+A package license must be selected before the first public release. CI builds and
+checks distributions but does not publish them.
+
+## Usage
+
+Create an API key under Account → API keys on a deployment with API-key support.
+Set `SUBFORK_API_KEY` in your process environment; never put it in source files,
+URLs, graph definitions, notebooks committed to git, or agent transcripts.
+
+```python
+from subfork import Subfork
+
+with Subfork() as client:  # Reads SUBFORK_API_KEY; defaults to https://subfork.com
+    nodes = client.nodes.list(include_all_versions=True)
+    graphs = client.graphs.list()
+```
+
+For a local deployment:
+
+```python
+with Subfork(base_url="http://subfork.localhost") as client:
+    nodes = client.nodes.list()
+```
+
+`base_url` is an origin, without `/api/v1`. HTTPS is required except for loopback
+and `.localhost` hosts. Credentials are sent in the Authorization bearer header.
+Redirects are not followed. Use a context manager or call `client.close()`.
+
+## Author, publish, execute
+
+The following deliberately creates and publishes a public graph and consumes
+execution quota. Grant read/write/run/publish scopes only when needed.
+Responses are dictionaries preserving the server's JSON shape.
+
+```python
+from subfork import Subfork
+
+name = "Python greeting"
+definition = {
+    "name": name,
+    "nodes": [{
+        "node_instance_id": "hello", "node_id": "n_text_value",
+        "node_version": "1.0.0", "title": "Hello",
+        "params": {"text": "Hello from Python"},
+    }],
+    "edges": [],
+    "graph_outputs": {"text": {"node_instance_id": "hello", "output_name": "text"}},
+}
+with Subfork() as client:
+    client.graphs.validate(definition)
+    graph = client.graphs.create(name=name, definition=definition)
+    client.graphs.publish(graph["id"], version="v1")
+    execution = client.graphs.execute(graph["id"], version="v1")
+    result = client.executions.wait(execution["id"], timeout=120)
+    print(result["status"], result.get("outputs"))
+```
+
+Discover published blocks with `graphs.published()` and retrieve their exact
+interfaces with `graphs.published_version(graph_id, version)`. Compose their
+returned node IDs with `composite_graph` parameters and explicit pinned versions.
+`graphs.interface(graph_id)` previews the server-inferred interface.
+`graphs.update()` replaces the submitted draft fields, including description;
+pass the description to preserve it. Existing server ownership and quotas apply.
+
+## Errors and limits
+
+Catch `AuthenticationError`, `PermissionDeniedError`, `ValidationError`,
+`RateLimitError`, or the base `APIError`; HTTP errors expose `status_code` and
+`retry_after`. Messages intentionally do not echo raw response bodies or secrets.
+`TransportError` means the outcome of a write may be unknown. There are no automatic
+retries: inspect remote state before retrying create, publish or execute operations.
+
+`executions.wait()` polls until a terminal status and returns failed executions
+as results too. `ExecutionTimeout` does **not** cancel the remote execution;
+use `executions.cancel(id)` explicitly. Polling uses a monotonic deadline and caps
+individual HTTP timeout settings by remaining time. HTTPX timeouts apply per I/O
+phase, not a strict wall-clock deadline for the entire network exchange.
+
+The first scaffold is synchronous. Async support, rich response models, artifact
+streaming, idempotent write retries and worker support are not included. Mock HTTP
+tests do not certify any particular server deployment.

pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "subfork"
+version = "0.1.0a1"
+description = "Python API client for Subfork graph authoring and execution"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.28,<1"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<10", "build>=1,<2", "twine>=6,<7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+subfork = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

src/subfork/__init__.py

@@ -0,0 +1,8 @@
+"""Subfork's Python API client. BYO worker support is a separate distribution."""
+from .client import Subfork
+from .errors import APIError, AuthenticationError, ExecutionTimeout, InvalidResponseError, NotFoundError, PermissionDeniedError, RateLimitError, SubforkError, TransportError, ValidationError
+
+__version__ = '0.1.0a1'
+__all__ = ['Subfork', 'SubforkError', 'APIError', 'AuthenticationError', 'PermissionDeniedError',
+           'NotFoundError', 'ValidationError', 'RateLimitError', 'TransportError',
+           'InvalidResponseError', 'ExecutionTimeout']

src/subfork/client.py

@@ -0,0 +1,61 @@
+"""Synchronous, explicitly closed HTTP client. No automatic write retries."""
+from __future__ import annotations
+
+import math
+import os
+from typing import Any
+
+import httpx
+
+from .errors import APIError, AuthenticationError, InvalidResponseError, NotFoundError, PermissionDeniedError, RateLimitError, TransportError, ValidationError
+from .resources import Executions, Graphs, Nodes
+
+
+class Subfork:
+    def __init__(self, api_key: str | None = None, *, base_url: str = 'https://subfork.com',
+                 timeout: float = 30, transport: httpx.BaseTransport | None = None):
+        key = os.environ.get('SUBFORK_API_KEY') if api_key is None else api_key
+        if not key or any(char.isspace() for char in key):
+            raise ValueError('Provide an API key or set SUBFORK_API_KEY; keys cannot contain whitespace.')
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError('timeout must be a positive finite number.')
+        origin = httpx.URL(base_url)
+        if not origin.host or origin.userinfo or origin.query or origin.fragment or origin.path not in {'', '/'}:
+            raise ValueError('base_url must be an origin without credentials, path, query or fragment.')
+        if origin.scheme != 'https' and not (origin.scheme == 'http' and (origin.host in {'localhost', '127.0.0.1', '::1'} or origin.host.endswith('.localhost'))):
+            raise ValueError('Use HTTPS; HTTP is allowed only for localhost.')
+        self.timeout = timeout
+        self._client = httpx.Client(base_url=str(origin).rstrip('/') + '/api/v1/', timeout=timeout,
+                                    headers={'Authorization': 'Bearer ' + key, 'Accept': 'application/json'},
+                                    follow_redirects=False, transport=transport)
+        self.nodes = Nodes(self)
+        self.graphs = Graphs(self)
+        self.executions = Executions(self)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._client.request(method, path.lstrip('/'), **kwargs)
+        except httpx.TransportError:
+            raise TransportError('API request could not be completed; inspect remote state before retrying a write.') from None
+        if not response.is_success:
+            errors = {401: AuthenticationError, 403: PermissionDeniedError, 404: NotFoundError,
+                      422: ValidationError, 429: RateLimitError}
+            # Fixed messages avoid reflecting secrets from an untrusted response.
+            raise errors.get(response.status_code, APIError)(
+                'Subfork API returned HTTP %s.' % response.status_code, status_code=response.status_code,
+                retry_after=response.headers.get('retry-after'))
+        if response.status_code == 204:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            raise InvalidResponseError('API returned invalid JSON.') from None
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Subfork:
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()

src/subfork/errors.py

@@ -0,0 +1,48 @@
+"""Public client errors; credentials and raw responses are never attached."""
+
+
+class SubforkError(Exception):
+    """Base class for client errors."""
+
+
+class TransportError(SubforkError):
+    """The request could not be completed; a write's outcome may be unknown."""
+
+
+class APIError(SubforkError):
+    def __init__(self, message: str, *, status_code: int, retry_after: str | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.retry_after = retry_after
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ValidationError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class InvalidResponseError(SubforkError):
+    pass
+
+
+class ExecutionTimeout(SubforkError):
+    """Polling expired. The remote execution was not cancelled."""
+
+    def __init__(self, execution_id: str):
+        super().__init__("Execution polling timed out; the remote execution may still be running.")
+        self.execution_id = execution_id

src/subfork/py.typed

@@ -0,0 +1,95 @@
+"""Small resource wrappers over the existing versioned HTTP API."""
+from __future__ import annotations
+
+import math
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from .errors import ExecutionTimeout
+
+if TYPE_CHECKING:
+    from .client import Subfork
+
+
+def segment(value: str) -> str:
+    if not value or value in {'.', '..'}:
+        raise ValueError('Resource identifiers must be non-empty and cannot be dot segments.')
+    return quote(value, safe='')
+
+
+class Resource:
+    def __init__(self, client: Subfork):
+        self._client = client
+
+
+class Nodes(Resource):
+    def list(self, *, include_all_versions: bool = False) -> list[dict[str, Any]]:
+        return self._client._request('GET', '/nodes', params={'include_all_versions': include_all_versions})
+
+    def get(self, node_id: str) -> dict[str, Any]:
+        return self._client._request('GET', '/nodes/' + segment(node_id))
+
+
+class Graphs(Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._client._request('GET', '/graphs')
+
+    def get(self, graph_id: str) -> dict[str, Any]:
+        return self._client._request('GET', '/graphs/' + segment(graph_id))
+
+    def validate(self, definition: dict[str, Any], *, name: str | None = None) -> dict[str, Any]:
+        return self._client._request('POST', '/graphs/validate', json={
+            'name': name if name is not None else definition.get('name', 'Untitled Graph'), 'definition': definition})
+
+    def create(self, *, name: str, definition: dict[str, Any], description: str = '', tags: list[str] | None = None) -> dict[str, Any]:
+        return self._client._request('POST', '/graphs', json={
+            'name': name, 'description': description, 'definition': definition, 'tags': tags or []})
+
+    def update(self, graph_id: str, *, name: str, definition: dict[str, Any], description: str = '') -> dict[str, Any]:
+        return self._client._request('PUT', '/graphs/' + segment(graph_id), json={
+            'name': name, 'description': description, 'definition': definition})
+
+    def published(self) -> list[dict[str, Any]]:
+        return self._client._request('GET', '/graphs/published')
+
+    def versions(self, graph_id: str) -> list[dict[str, Any]]:
+        return self._client._request('GET', '/graphs/' + segment(graph_id) + '/versions')
+
+    def published_version(self, graph_id: str, version: str) -> dict[str, Any]:
+        return self._client._request('GET', '/graphs/published/' + segment(graph_id) + '/versions/' + segment(version))
+
+    def interface(self, graph_id: str) -> dict[str, Any]:
+        return self._client._request('GET', '/graphs/' + segment(graph_id) + '/interface-preview')
+
+    def publish(self, graph_id: str, *, version: str, interface: dict[str, Any] | None = None, comment: str = '') -> dict[str, Any]:
+        payload: dict[str, Any] = {'version': version, 'comment': comment}
+        if interface is not None:
+            payload['interface'] = interface
+        return self._client._request('POST', '/graphs/' + segment(graph_id) + '/versions', json=payload)
+
+    def execute(self, graph_id: str, *, version: str = 'draft', inputs: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._request('POST', '/graphs/' + segment(graph_id) + '/execute',
+                                     params={'version': version}, json={'inputs': inputs or {}})
+
+
+class Executions(Resource):
+    def get(self, execution_id: str) -> dict[str, Any]:
+        return self._client._request('GET', '/executions/' + segment(execution_id))
+
+    def cancel(self, execution_id: str) -> dict[str, Any]:
+        return self._client._request('POST', '/executions/' + segment(execution_id) + '/cancel')
+
+    def wait(self, execution_id: str, *, timeout: float = 120, poll_interval: float = 2) -> dict[str, Any]:
+        if not math.isfinite(timeout) or timeout <= 0 or not math.isfinite(poll_interval) or poll_interval <= 0:
+            raise ValueError('timeout and poll_interval must be positive finite numbers.')
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise ExecutionTimeout(execution_id)
+            result = self._client._request('GET', '/executions/' + segment(execution_id),
+                                          timeout=min(self._client.timeout, remaining))
+            if result['status'] in {'completed', 'failed', 'canceled', 'cancelled', 'outcome_unknown'}:
+                return result
+            time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))