gl-runner-sdk 0.1.0__py3-none-any.whl

gl_runner_sdk/__init__.py

@@ -0,0 +1,26 @@
+"""GL Runner SDK - Lightweight Python SDK for GL Runner API.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    - specs/GL1_core_service/lite_sdk/spec.md
+    - specs/GL1_core_service/lite_sdk/design.md
+"""
+
+from __future__ import annotations
+
+from .client import Client
+from .runnables import Runnable, RunStream
+from .runs import Runs
+from .types import RunnableRecord, RunDetailResponse, RunResponse
+
+__all__ = [
+    "Client",
+    "Runnable",
+    "RunStream",
+    "Runs",
+    "RunnableRecord",
+    "RunDetailResponse",
+    "RunResponse",
+]

gl_runner_sdk/client/__init__.py

@@ -0,0 +1,12 @@
+"""Client exports for the GL Runner SDK.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from .clients import Client
+
+__all__ = ["Client"]

gl_runner_sdk/client/clients.py

@@ -0,0 +1,82 @@
+"""Client construction for the GL Runner SDK.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..runnables.runnables import RunnableCollection
+
+
+class Client:
+    """Transport-only GL Runner client."""
+
+    def __init__(self, base_url: str, api_key: str):
+        """Initialize client.
+
+        Args:
+            base_url: Base URL of the GL Runner API.
+            api_key: API key for authentication.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+
+    @property
+    def runnables(self) -> "RunnableCollection":
+        """Return server-scoped runnable collection operations."""
+        from ..runnables.runnables import RunnableCollection
+
+        return RunnableCollection(self)
+
+    def auth_headers(
+        self,
+        *,
+        content_type: str | None = None,
+        accept: str | None = None,
+    ) -> dict[str, str]:
+        """Build standard auth headers for SDK API calls."""
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        if accept:
+            headers["Accept"] = accept
+        return headers
+
+    @staticmethod
+    def from_api_key(base_url: str, api_key: str) -> "Client":
+        """Create client from API key.
+
+        Args:
+            base_url: Base URL of the GL Runner API.
+            api_key: API key for authentication.
+
+        Returns:
+            Configured Client instance.
+        """
+        return Client(base_url=base_url, api_key=api_key)
+
+    @classmethod
+    def from_env(cls) -> "Client":
+        """Create client from environment variables.
+
+        Uses GL_RUNNER_BASE_URL and GL_RUNNER_API_KEY.
+
+        Returns:
+            Configured Client instance.
+
+        Raises:
+            ValueError: If required environment variables are missing.
+        """
+        base_url = os.environ.get("GL_RUNNER_BASE_URL", "http://localhost:4200")
+        api_key = os.environ.get("GL_RUNNER_API_KEY")
+        if not api_key:
+            raise ValueError("GL_RUNNER_API_KEY environment variable is required.")
+        return cls(base_url=base_url, api_key=api_key)

gl_runner_sdk/runnables/__init__.py

@@ -0,0 +1,12 @@
+"""Runnable operation exports for the GL Runner SDK.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from .runnables import Runnable, RunStream
+
+__all__ = ["Runnable", "RunStream"]

gl_runner_sdk/runnables/runnables.py

@@ -0,0 +1,629 @@
+"""Runnable management and execution resource.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import io
+import os
+import time
+import zipfile
+from pathlib import Path
+from typing import Any, Iterator
+import httpx
+
+from ..client import Client
+from ..runs import Runs
+from ..types import RunDetailResponse, RunResponse, RunnableRecord
+
+_DEFAULT_EXCLUDED_FILES = {
+    ".DS_Store",
+    "Thumbs.db",
+}
+_DEFAULT_ALLOWED_FILES = {
+    ".env.example",
+}
+_DEFAULT_EXCLUDED_DIRS = {
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+}
+_DEFAULT_EXCLUDED_PATTERNS = (
+    ".env",
+    ".env.*",
+    "*.pyc",
+    "*.pyo",
+    "*~",
+)
+
+
+class RunnableCollection:
+    """Server-scoped runnable collection operations."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def get(self, runnable_id: str) -> RunnableRecord:
+        """Get runnable by ID."""
+        url = f"{self._client.base_url}/v1/runnables/{runnable_id}"
+        headers = self._client.auth_headers()
+
+        resp = httpx.get(url, headers=headers, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"Get failed ({resp.status_code}): {resp.text}")
+
+        return _runnable_record_from_json(resp.json())
+
+    def list(self, limit: int = 100, offset: int = 0) -> list[RunnableRecord]:
+        """List runnables."""
+        url = f"{self._client.base_url}/v1/runnables"
+        headers = self._client.auth_headers()
+        params = {"limit": limit, "offset": offset}
+
+        resp = httpx.get(url, headers=headers, params=params, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"List failed ({resp.status_code}): {resp.text}")
+
+        return [_runnable_record_from_json(item) for item in resp.json()]
+
+    def delete(self, runnable_id: str) -> None:
+        """Delete a runnable by ID."""
+        url = f"{self._client.base_url}/v1/runnables/{runnable_id}"
+        headers = self._client.auth_headers()
+
+        resp = httpx.delete(url, headers=headers, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"Delete failed ({resp.status_code}): {resp.text}")
+
+    def get_by_key(self, key: str) -> RunnableRecord | None:
+        """Get a runnable by key."""
+        page_size = 100
+        offset = 0
+        while True:
+            runnables = self.list(limit=page_size, offset=offset)
+            if not runnables:
+                break
+            for runnable in runnables:
+                if runnable.key == key:
+                    return runnable
+            if len(runnables) < page_size:
+                break
+            offset += page_size
+        return None
+
+    def get_by_id_or_key(self, runnable_id_or_key: str) -> RunnableRecord | None:
+        """Get a runnable by ID or key. Key lookup always attempted first."""
+        runnable = self.get_by_key(runnable_id_or_key)
+        if runnable is not None:
+            return runnable
+        try:
+            return self.get(runnable_id_or_key)
+        except RuntimeError as exc:
+            if not _is_not_found_error(exc):
+                raise
+            return None
+
+
+class RunStream:
+    """Iterable wrapper that yields SSE events and provides the final result.
+
+    Returned by ``Runnable.run(stream=True)``.  Iterate to consume streaming
+    events in real time, then access ``.result`` for the completed run output.
+    """
+
+    def __init__(
+        self,
+        runnable: Runnable,
+        run_id: str,
+        deadline: float,
+        poll_interval: float,
+    ) -> None:
+        self._runnable = runnable
+        self._run_id = run_id
+        self._deadline = deadline
+        self._poll_interval = poll_interval
+        self._result: dict[str, Any] | None = None
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        for event in self._runnable.stream(self._run_id, deadline=self._deadline):
+            yield event
+        remaining = max(self._deadline - time.time(), 0.0)
+        completed = self._runnable.wait(
+            self._run_id, timeout=remaining, poll_interval=self._poll_interval
+        )
+        self._result = completed.result
+
+    @property
+    def result(self) -> dict[str, Any] | None:
+        if self._result is None:
+            raise RuntimeError("Stream not yet consumed. Iterate over RunStream before accessing .result.")
+        return self._result
+
+
+class Runnable:
+    """Runnable management and execution facade."""
+
+    def __init__(
+        self,
+        client: Client | None = None,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        key: str | None = None,
+        kind: str = "code",
+        bundle_path: str | Path | None = None,
+        version: str | None = None,
+        entrypoint: str | None = None,
+    ) -> None:
+        """Initialize Runnables.
+
+        Client is handled internally when `base_url` and `api_key` are
+        provided, or when `GL_RUNNER_BASE_URL` / `GL_RUNNER_API_KEY` env
+        vars are set.  Pass an explicit `client` to share a single transport.
+
+        Args:
+            client: Shared Client instance (optional; created from base_url/api_key otherwise).
+            base_url: Base URL of the GL Runner API.
+            api_key: API key for authentication.
+            key: Optional runnable key for public usage.
+            kind: Runnable kind.
+            bundle_path: Optional local bundle path.
+            version: Optional deployment version.
+            entrypoint: Optional entrypoint override.
+        """
+        if client is None:
+            base_url = base_url or os.environ.get("GL_RUNNER_BASE_URL", "http://localhost:4200")
+            api_key = api_key or os.environ.get("GL_RUNNER_API_KEY")
+            if not api_key:
+                raise ValueError("GL_RUNNER_API_KEY environment variable is required.")
+            client = Client(base_url=base_url, api_key=api_key)
+        self._client = client
+        self._runs = Runs(client)
+        self.key = key
+        self.kind = kind
+        self.bundle_path = Path(bundle_path) if bundle_path is not None else None
+        self.version = version
+        self.entrypoint = entrypoint
+        self._deployment: RunnableRecord | None = None
+
+    @property
+    def deployment(self) -> RunnableRecord | None:
+        """Return the tracked server deployment."""
+        return self._deployment
+
+    def _create_bundle_zip(
+        self,
+        bundle_path: Path,
+        include_sensitive_files: list[str] | tuple[str, ...] | None = None,
+    ) -> io.BytesIO:
+        """Create a ZIP archive from a bundle directory.
+
+        Args:
+            bundle_path: Path to the bundle directory.
+            include_sensitive_files: Exact bundle-relative files to include even
+                when they match the default sensitive-file denylist.
+
+        Returns:
+            BytesIO buffer containing the ZIP archive.
+        """
+        allowed_sensitive_files = _normalize_sensitive_includes(include_sensitive_files)
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zf:
+            for item in bundle_path.rglob("*"):
+                relative_path = item.relative_to(bundle_path)
+                if item.is_symlink():
+                    continue
+                if item.is_file() and not _is_excluded_bundle_path(relative_path, allowed_sensitive_files):
+                    zf.write(item, arcname=relative_path)
+        zip_buffer.seek(0)
+        return zip_buffer
+
+    def _prepare_zip_bytes(
+        self,
+        bundle_path: str | Path | None,
+        bundle_zip: bytes | io.BytesIO | None,
+        include_sensitive_files: list[str] | tuple[str, ...] | None,
+    ) -> bytes:
+        """Resolve bundle bytes from either a directory path or provided ZIP bytes."""
+        if bundle_path is not None:
+            bundle_path = Path(bundle_path)
+            if not bundle_path.exists() or not bundle_path.is_dir():
+                raise ValueError(f"Bundle path must be a directory: {bundle_path}")
+            zip_buffer = self._create_bundle_zip(bundle_path, include_sensitive_files=include_sensitive_files)
+            return zip_buffer.getvalue()
+        if bundle_zip is not None:
+            if include_sensitive_files:
+                raise ValueError("include_sensitive_files only applies when bundle_path is provided.")
+            if isinstance(bundle_zip, io.BytesIO):
+                return bundle_zip.getvalue()
+            return bundle_zip
+        raise ValueError("Either bundle_path or bundle_zip must be provided.")
+
+    def set_bundle_path(self, bundle_path: str | Path) -> "Runnable":
+        """Set the runnable bundle path on this facade."""
+        self.bundle_path = Path(bundle_path)
+        return self
+
+    def deploy(
+        self,
+        key: str | None = None,
+        kind: str | None = None,
+        bundle_zip: bytes | io.BytesIO | None = None,
+        include_sensitive_files: list[str] | tuple[str, ...] | None = None,
+        version: str | None = None,
+        entrypoint: str | None = None,
+        wait_for_active: bool = True,
+        activation_timeout: float = 120.0,
+        activation_poll_interval: float = 5.0,
+    ) -> RunnableRecord:
+        """Deploy or update a runnable.
+
+        When ``self._deployment`` is already tracked (e.g. after
+        ``load_from_id()`` or a previous ``deploy()`` call) this posts to the
+        update endpoint.  Otherwise it performs a first-time deploy.
+
+        Args:
+            key: Runnable key.
+            kind: Runnable kind (default: code).
+            bundle_zip: Pre-built ZIP archive.
+            include_sensitive_files: Explicit bundle-relative sensitive files to include.
+            version: Optional version string.
+            entrypoint: Optional entrypoint module path.
+            wait_for_active: If True (default), polls until status is no longer
+                ``deploying``.
+            activation_timeout: Max seconds to wait for activation.
+            activation_poll_interval: Seconds between activation status checks.
+
+        Returns:
+            Deployed Runnable.
+
+        Raises:
+            ValueError: If neither self.bundle_path nor bundle_zip is provided.
+            RuntimeError: If deployment fails or runnable becomes inactive.
+            TimeoutError: If activation times out.
+        """
+        if key is not None:
+            self.key = key
+        if kind is not None:
+            self.kind = kind
+        if version is not None:
+            self.version = version
+        if entrypoint is not None:
+            self.entrypoint = entrypoint
+
+        if not self.key:
+            raise ValueError("key is required to deploy a runnable.")
+        if self.kind in (None, ""):
+            self.kind = "code"
+
+        # NOTE: ordering matters — this block must execute before the auto-discovery
+        # block below; _track_deployment() updates self.version and self._deployment,
+        # which would invalidate the guard against replaying the tracked version.
+        request_version = version
+        if request_version is None:
+            request_version = self.version
+            if (self._deployment is not None and request_version == self._deployment.version):
+                request_version = None
+
+        zip_bytes = self._prepare_zip_bytes(self.bundle_path, bundle_zip, include_sensitive_files)
+
+        if self._deployment is None and self.key:
+            existing = self._client.runnables.get_by_key(self.key)
+            if existing is not None:
+                self._track_deployment(existing)
+
+        if self._deployment is not None:
+            url = f"{self._client.base_url}/v1/runnables/{self._deployment.id}:deploy"
+        else:
+            url = f"{self._client.base_url}/v1/runnables:deploy"
+
+        headers = self._client.auth_headers()
+        files = {"file": ("bundle.zip", zip_bytes, "application/zip")}
+        data: dict[str, Any] = {"key": self.key, "kind": self.kind}
+        if request_version:
+            data["version"] = request_version
+        if self.entrypoint:
+            data["entrypoint"] = self.entrypoint
+
+        resp = httpx.post(url, headers=headers, data=data, files=files, timeout=60)
+        if resp.is_error:
+            raise RuntimeError(f"Deploy failed ({resp.status_code}): {resp.text}")
+
+        runnable = _runnable_record_from_json(resp.json())
+        self._track_deployment(runnable)
+
+        if wait_for_active:
+            _wait_for_deployment_active(
+                self._client,
+                self._deployment.id,
+                activation_timeout,
+                activation_poll_interval,
+            )
+
+        return runnable
+
+    def trigger(
+        self,
+        payload: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> RunResponse:
+        """Trigger a runnable without waiting.
+
+        Args:
+            payload: Optional input payload.
+            context: Optional context data.
+
+        Returns:
+            RunResponse with run details.
+
+        Raises:
+            RuntimeError: If trigger fails.
+        """
+        runnable_id = self._tracked_deployment_id()
+        url = f"{self._client.base_url}/v1/runnables/{runnable_id}:run"
+        headers = self._client.auth_headers(content_type="application/json")
+        data: dict[str, Any] = {}
+        if payload is not None:
+            data["payload"] = payload
+        if context is not None:
+            data["context"] = context
+
+        resp = httpx.post(url, headers=headers, json=data, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"Trigger failed ({resp.status_code}): {resp.text}")
+
+        result = resp.json()
+        return RunResponse(
+            id=result["id"],
+            runnable_id=result["runnable_id"],
+            status=result["status"],
+            payload=result.get("requested_payload"),
+            context=result.get("context_metadata"),
+            result=None,
+            error=result.get("error_code"),
+            created_at=result.get("created_at"),
+            completed_at=result.get("completed_at"),
+        )
+
+    def run(
+        self,
+        payload: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        timeout: float = 120.0,
+        poll_interval: float = 2.0,
+        stream: bool = False,
+    ) -> dict[str, Any] | None | RunStream:
+        """Trigger a runnable, wait for completion, and return its result.
+
+        When ``stream=True`` returns a ``RunStream`` iterable that yields
+        raw OpenAI-compatible events and provides the final result via
+        ``.result`` after iteration.
+        """
+        run = self.trigger(payload=payload, context=context)
+        if stream:
+            return RunStream(self, run.id, time.time() + timeout, poll_interval)
+        completed = self.wait(run.id, timeout=timeout, poll_interval=poll_interval)
+        return completed.result
+
+    def wait(
+        self,
+        run_id: str,
+        timeout: float = 120.0,
+        poll_interval: float = 2.0,
+    ) -> RunDetailResponse:
+        """Wait for a run to reach a terminal status."""
+        return self._runs.wait(run_id, timeout=timeout, poll_interval=poll_interval)
+
+    def get_run(self, run_id: str) -> RunDetailResponse:
+        """Get a run by ID."""
+        return self._runs.get(run_id)
+
+    def stream(self, run_id: str, deadline: float | None = None) -> Iterator[dict[str, Any]]:
+        """Stream run events as raw OpenAI-compatible payloads."""
+        return self._runs.stream(run_id, deadline=deadline)
+
+    def events(
+        self,
+        run_id: str,
+        event_type: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Get historical events for a run."""
+        return self._runs.events(run_id, event_type=event_type, limit=limit)
+
+    @classmethod
+    def from_id(
+        cls,
+        runnable_id: str,
+        *,
+        client: Client | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> "Runnable":
+        """Construct a Runnable facade and load by ID."""
+        runnable = cls(client=client, base_url=base_url, api_key=api_key)
+        return runnable.load_from_id(runnable_id)
+
+    def load_from_id(self, runnable_id: str) -> "Runnable":
+        """Load a server deployment into this runnable facade.
+
+        Args:
+            runnable_id: ID of the runnable to track.
+
+        Returns:
+            This Runnable facade, with deployment/key/kind/version/entrypoint
+            updated from the server record.
+
+        Raises:
+            RuntimeError: If loading the runnable fails.
+        """
+        self._track_deployment(self._client.runnables.get(runnable_id))
+        return self
+
+    @classmethod
+    def from_key(
+        cls,
+        key: str,
+        *,
+        client: Client | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> "Runnable":
+        """Construct a Runnable facade and load by key."""
+        runnable = cls(client=client, base_url=base_url, api_key=api_key)
+        return runnable.load_from_key(key)
+
+    def load_from_key(self, key: str) -> "Runnable":
+        """Load a server deployment by key.
+
+        Args:
+            key: Stable user-facing key of the runnable to track.
+
+        Returns:
+            This Runnable facade, with deployment/key/kind/version/entrypoint
+            updated from the server record.
+
+        Raises:
+            RuntimeError: If no runnable is found with the given key.
+        """
+        deployment = self._client.runnables.get_by_key(key)
+        if deployment is None:
+            raise RuntimeError(f"Runnable not found: {key}")
+        self._track_deployment(deployment)
+        return self
+
+    def sync(self) -> RunnableRecord:
+        """Refresh the tracked deployment record from the server in-place.
+
+        Updates both ``_deployment`` and the facade attributes
+        (``key``, ``kind``, ``version``, ``entrypoint``) to match the
+        server state.
+
+        Returns:
+            The updated RunnableRecord fetched from the server.
+        """
+        self._track_deployment(self._client.runnables.get(self._tracked_deployment_id()))
+        return self._deployment
+
+    def delete(self) -> None:
+        """Delete the tracked runnable deployment."""
+        runnable_id = self._tracked_deployment_id()
+        self._client.runnables.delete(runnable_id)
+        self._deployment = None
+
+    def _tracked_deployment_id(self) -> str:
+        """Return the tracked deployment ID or raise a clear caller error."""
+        if self._deployment is None:
+            raise ValueError("runnable_id is required before a deployment is tracked. Call deploy() first.")
+        return self._deployment.id
+
+    def _track_deployment(self, deployment: RunnableRecord) -> None:
+        """Replace this facade's tracked deployment from a server record."""
+        self._deployment = deployment
+        self.key = deployment.key
+        self.kind = deployment.kind
+        self.version = deployment.version
+        self.entrypoint = deployment.entrypoint
+
+
+def _is_not_found_error(exc: RuntimeError) -> bool:
+    return "404" in str(exc)
+
+
+def _runnable_record_from_json(data: dict[str, Any]) -> RunnableRecord:
+    return RunnableRecord(
+        id=data["id"],
+        key=data["key"],
+        entrypoint=data["entrypoint"],
+        kind=data.get("kind", "code"),
+        version=data.get("version"),
+        status=data.get("status"),
+        metadata=data.get("metadata", {}),
+        config=data.get("config", {}),
+        created_at=data.get("created_at"),
+        updated_at=data.get("updated_at"),
+    )
+
+
+def _wait_for_deployment_active(
+    client: Client,
+    runnable_id: str,
+    timeout: float = 120.0,
+    poll_interval: float = 5.0,
+) -> None:
+    """Wait until a deployed runnable is no longer ``deploying``.
+
+    Args:
+        client: SDK Client for API calls.
+        runnable_id: ID of the deployed runnable.
+        timeout: Max seconds to wait.
+        poll_interval: Seconds between status checks.
+
+    Raises:
+        RuntimeError: If the runnable becomes ``inactive``.
+        TimeoutError: If the runnable stays ``deploying`` past the timeout.
+    """
+    deadline = time.time() + timeout
+    while True:
+        deployed = client.runnables.get(runnable_id)
+        if deployed.status == "inactive":
+            raise RuntimeError(f"Deploy failed: runnable {runnable_id} became inactive.")
+        if deployed.status == "active" and deployed.metadata.get("prefect_deployment_id"):
+            return
+        if (deployed.status not in ("deploying", "active") and deployed.status is not None):
+            return
+        if deployed.status is None:
+            import warnings
+
+            warnings.warn(
+                f"Runnable {runnable_id} returned status=None while polling for activation.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        if time.time() > deadline:
+            raise TimeoutError(
+                f"Timed out waiting for runnable {runnable_id} activation "
+                f"(last status: {deployed.status!r})."
+            )
+        time.sleep(poll_interval)
+
+
+def _normalize_sensitive_includes(include_sensitive_files: list[str] | tuple[str, ...] | None) -> set[Path]:
+    allowed: set[Path] = set()
+    for value in include_sensitive_files or ():
+        path = Path(value)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"Sensitive include must be a bundle-root filename, got: {value}")
+        if len(path.parts) != 1:
+            raise ValueError(f"Sensitive include must be a bundle-root filename (no subdirectories): {value}")
+        allowed.add(path)
+    return allowed
+
+
+def _is_excluded_bundle_path(relative_path: Path, allowed_sensitive_files: set[Path]) -> bool:
+    if relative_path in allowed_sensitive_files:
+        return False
+    if any(part in _DEFAULT_EXCLUDED_DIRS for part in relative_path.parts[:-1]):
+        return True
+    name = relative_path.name
+    if name in _DEFAULT_ALLOWED_FILES:
+        return False
+    if name in _DEFAULT_EXCLUDED_FILES:
+        return True
+    return any(fnmatch.fnmatch(name, pattern) for pattern in _DEFAULT_EXCLUDED_PATTERNS)

gl_runner_sdk/runs/__init__.py

@@ -0,0 +1,12 @@
+"""Run operation exports for the GL Runner SDK.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from .runs import Runs
+
+__all__ = ["Runs"]

gl_runner_sdk/runs/runs.py

@@ -0,0 +1,304 @@
+"""Run history and streaming resource.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Iterator
+
+import httpx
+
+from ..client import Client
+from ..types import RunDetailResponse
+
+_TERMINAL_STATUSES = {"success", "failed", "cancelled"}
+
+
+class Runs:
+    """Run status, polling, streaming, and history."""
+
+    def __init__(
+        self,
+        client: Client | None = None,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        """Initialize Runs.
+
+        Client is handled internally when `base_url` and `api_key` are
+        provided, or when `GL_RUNNER_BASE_URL` / `GL_RUNNER_API_KEY` env
+        vars are set.  Pass an explicit `client` to share a single transport.
+
+        Args:
+            client: Shared Client instance (optional; created from base_url/api_key otherwise).
+            base_url: Base URL of the GL Runner API.
+            api_key: API key for authentication.
+        """
+        if client is None:
+            base_url = base_url or os.environ.get("GL_RUNNER_BASE_URL", "http://localhost:4200")
+            api_key = api_key or os.environ.get("GL_RUNNER_API_KEY")
+            if not api_key:
+                raise ValueError("GL_RUNNER_API_KEY environment variable is required.")
+            client = Client(base_url=base_url, api_key=api_key)
+        self._client = client
+
+    def get(self, run_id: str) -> RunDetailResponse:
+        """Get a run by ID.
+
+        Args:
+            run_id: ID of the run to retrieve.
+
+        Returns:
+            RunDetailResponse with run details.
+
+        Raises:
+            RuntimeError: If the get fails.
+        """
+        url = f"{self._client.base_url}/v1/runs/{run_id}"
+        headers = self._client.auth_headers()
+
+        resp = httpx.get(url, headers=headers, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"Get run failed ({resp.status_code}): {resp.text}")
+
+        data = resp.json()
+        return RunDetailResponse(
+            id=data["run_id"],
+            runnable_id=data["runnable_id"],
+            status=data["status"],
+            payload=data.get("inputs"),
+            context=data.get("context"),
+            result=data.get("outputs"),
+            error=data.get("error"),
+            created_at=data.get("created_at"),
+            completed_at=data.get("completed_at"),
+        )
+
+    def list(
+        self,
+        runnable_key: str | None = None,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> list[RunDetailResponse]:
+        """List runs, optionally filtered by runnable.
+
+        Args:
+            runnable_key: Optional runnable key to filter by.
+            limit: Maximum number of results to return.
+            cursor: Pagination cursor from previous response.
+
+        Returns:
+            List of RunDetailResponse objects.
+
+        Raises:
+            RuntimeError: If the list fails.
+        """
+        url = f"{self._client.base_url}/v1/runs"
+        headers = self._client.auth_headers()
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        if runnable_key:
+            params["runnable_key"] = runnable_key
+
+        resp = httpx.get(url, headers=headers, params=params, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"List runs failed ({resp.status_code}): {resp.text}")
+
+        data = resp.json()
+        runs = []
+        for item in data.get("runs", []):
+            runs.append(
+                RunDetailResponse(
+                    id=item.get("run_id"),
+                    runnable_id=item.get("runnable_id"),
+                    status=item.get("status"),
+                    payload=item.get("inputs"),
+                    context=item.get("context"),
+                    result=item.get("outputs"),
+                    error=item.get("error"),
+                    created_at=item.get("created_at"),
+                    completed_at=item.get("completed_at"),
+                )
+            )
+        return runs
+
+    def cancel(self, run_id: str) -> RunDetailResponse:
+        """Cancel a running run.
+
+        Args:
+            run_id: ID of the run to cancel.
+
+        Returns:
+            RunDetailResponse with updated run details.
+
+        Raises:
+            NotImplementedError: Cancel endpoint not yet implemented in server.
+        """
+        raise NotImplementedError("Cancel endpoint not yet implemented in server")
+
+    def wait(
+        self,
+        run_id: str,
+        timeout: float = 120.0,
+        poll_interval: float = 2.0,
+    ) -> RunDetailResponse:
+        """Poll a run until it reaches a terminal server status.
+
+        This matches the canonical example flow in ``scripts/run_runnable.py``:
+        trigger the run, then poll ``GET /v1/runs/{run_id}`` until the status is
+        ``success``, ``failed``, or ``cancelled``.
+        """
+        deadline = time.time() + timeout
+        while True:
+            run = self.get(run_id)
+            if run.status in _TERMINAL_STATUSES:
+                return run
+            if time.time() > deadline:
+                raise TimeoutError("Timed out waiting for run completion")
+            time.sleep(poll_interval)
+
+    def stream(self, run_id: str, deadline: float | None = None) -> Iterator[dict[str, Any]]:
+        """Stream events from a run in real-time via SSE.
+
+        Args:
+            run_id: ID of the run to stream events from.
+            deadline: Optional wall-clock time (from time.time()) after which streaming stops.
+
+        Yields:
+            Raw OpenAI Responses API payload dicts as received from the server.
+
+        Raises:
+            RuntimeError: If the stream request fails.
+            TimeoutError: If the deadline is exceeded.
+        """
+        url = f"{self._client.base_url}/v1/runs/{run_id}/stream"
+        headers = self._client.auth_headers(accept="text/event-stream")
+
+        with httpx.stream("GET", url, headers=headers, timeout=self._stream_timeout(deadline)) as resp:
+            if resp.is_error:
+                raise RuntimeError(f"Stream failed ({resp.status_code}): {resp.text}")
+
+            yield from self._consume_sse_stream(resp, deadline)
+
+    def _stream_timeout(self, deadline: float | None) -> httpx.Timeout:
+        """Build an httpx timeout suitable for long-lived SSE streams.
+
+        When a wall-clock deadline is provided the read timeout is set to None
+        so the stream relies on the deadline checks inside
+        ``_consume_sse_stream`` rather than fixed per-read timeouts.
+        """
+        if deadline is None:
+            return httpx.Timeout(connect=30.0, read=None, write=30.0, pool=30.0)
+        remaining = max(deadline - time.time(), 1.0)
+        return httpx.Timeout(connect=min(remaining, 30.0), read=remaining, write=30.0, pool=30.0)
+
+    def _consume_sse_stream(
+        self,
+        resp: httpx.Response,
+        deadline: float | None,
+    ) -> Iterator[dict[str, Any]]:
+        """Consume an SSE stream with deadline-aware chunk reading."""
+        current_event_type: str = ""
+        remainder: bytes = b""
+
+        if deadline is not None and time.time() >= deadline:
+            raise TimeoutError("Stream deadline exceeded")
+
+        try:
+            chunks = iter(resp.iter_bytes())
+            while True:
+                if deadline is not None and time.time() >= deadline:
+                    raise TimeoutError("Stream deadline exceeded")
+                try:
+                    chunk = next(chunks)
+                except StopIteration:
+                    break
+                except httpx.ReadTimeout as exc:
+                    if deadline is not None:
+                        if time.time() >= deadline:
+                            raise TimeoutError("Stream deadline exceeded") from exc
+                        continue
+                    raise
+                if not chunk:
+                    continue
+                full = remainder + chunk
+                if b"\n" in full:
+                    last_nl = full.rfind(b"\n")
+                    remainder = full[last_nl + 1 :]
+                    ctx: dict[str, str] = {"event_type": current_event_type}
+                    yield from self._parse_sse_lines(full[: last_nl + 1], ctx, deadline)
+                    current_event_type = ctx["event_type"]
+                else:
+                    remainder = full
+        except httpx.ReadTimeout as exc:
+            if deadline is not None:
+                raise TimeoutError("Stream deadline exceeded") from exc
+            raise
+
+    def _parse_sse_lines(
+        self,
+        data: bytes,
+        ctx: dict[str, str],
+        deadline: float | None,
+    ) -> Iterator[dict[str, Any]]:
+        """Parse raw SSE lines and yield raw OpenAI payload dicts."""
+        while b"\n" in data:
+            if deadline is not None and time.time() >= deadline:
+                raise TimeoutError("Stream deadline exceeded")
+            line_bytes, data = data.split(b"\n", 1)
+            line = line_bytes.decode("utf-8", errors="replace").strip()
+            if not line:
+                continue
+            if line.startswith("event: "):
+                ctx["event_type"] = line[7:].strip()
+                continue
+            if line.startswith("data: "):
+                data_str = line[6:]
+                try:
+                    parsed = json.loads(data_str)
+                    if isinstance(parsed, dict) and parsed.get("type"):
+                        yield parsed
+                except json.JSONDecodeError:
+                    continue
+
+    def events(
+        self,
+        run_id: str,
+        event_type: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Get historical events for a run from the database.
+
+        Args:
+            run_id: ID of the run to get events for.
+            event_type: Optional event type to filter by.
+            limit: Maximum number of events to return.
+
+        Returns:
+            List of raw event dicts as returned by the server.
+
+        Raises:
+            RuntimeError: If the request fails.
+        """
+        url = f"{self._client.base_url}/v1/runs/{run_id}/events"
+        headers = self._client.auth_headers()
+        params: dict[str, Any] = {"limit": limit}
+        if event_type is not None:
+            params["event_type"] = event_type
+
+        resp = httpx.get(url, headers=headers, params=params, timeout=30)
+        if resp.is_error:
+            raise RuntimeError(f"Get events failed ({resp.status_code}): {resp.text}")
+
+        data = resp.json()
+        return data.get("events", [])

gl_runner_sdk/types/__init__.py

@@ -0,0 +1,18 @@
+"""Public type exports for the GL Runner SDK.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from .runnables import RunnableRecord
+from .runs import RunDetailResponse, RunRequest, RunResponse
+
+__all__ = [
+    "RunnableRecord",
+    "RunDetailResponse",
+    "RunRequest",
+    "RunResponse",
+]

gl_runner_sdk/types/runnables.py

@@ -0,0 +1,29 @@
+"""Runnable entity types.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RunnableRecord:
+    """Runnable entity record returned by server APIs."""
+
+    id: str
+    key: str
+    entrypoint: str
+    kind: str = "code"
+    version: str | None = None
+    status: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    config: dict[str, Any] = field(default_factory=dict)
+    created_at: str | None = None
+    updated_at: str | None = None

gl_runner_sdk/types/runs.py

@@ -0,0 +1,67 @@
+"""Run request and response types.
+
+Authors:
+    Christopher Sebastian (christophersebastian0205@gmail.com)
+
+References:
+    specs/GL1_core_service/lite_sdk/spec.md
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class RunRequest:
+    """Request type for triggering a run."""
+
+    payload: dict[str, Any] | None = None
+    context: dict[str, Any] | None = None
+
+
+@dataclass
+class RunResponse:
+    """Response from triggering a run (POST /v1/runnables/{id}:run).
+
+    Maps the server trigger RunResponse fields:
+        requested_payload  -> RunResponse.payload
+        context_metadata   -> RunResponse.context
+        error_code         -> RunResponse.error
+        result is always None (run just started)
+    """
+
+    id: str
+    runnable_id: str
+    status: str
+    payload: dict[str, Any] | None = None
+    context: dict[str, Any] | None = None
+    result: dict[str, Any] | None = None
+    error: str | None = None
+    created_at: str | None = None
+    completed_at: str | None = None
+
+
+@dataclass
+class RunDetailResponse:
+    """Response from querying a run (GET /v1/runs/{run_id} or /v1/runs).
+
+    Maps the server RunDetailResponse / RunListItem fields:
+        inputs  -> RunDetailResponse.payload
+        outputs -> RunDetailResponse.result
+        error   -> RunDetailResponse.error
+
+    Note: context is not yet returned by the detail endpoint; the field
+    is kept forward-looking for a planned server-side addition.
+    """
+
+    id: str
+    runnable_id: str
+    status: str
+    payload: dict[str, Any] | None = None
+    context: dict[str, Any] | None = None
+    result: dict[str, Any] | None = None
+    error: str | None = None
+    created_at: str | None = None
+    completed_at: str | None = None

gl_runner_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: gl-runner-sdk
+Version: 0.1.0
+Summary: GL Runner Python SDK
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: coverage>=7.11.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.14.0; extra == 'dev'

gl_runner_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gl_runner_sdk/__init__.py,sha256=v4g1An-A_UADdb1w128urMEYQD3swZ3H2oyu5d4ccIU,581
+gl_runner_sdk/client/__init__.py,sha256=WvR2fz_4ZCLj7KPPUzAhuAthlqs5RTBvHKjbkdISNsY,226
+gl_runner_sdk/client/clients.py,sha256=OXTI-kwj_9SMvpgv5e7MNGzSb1dMgb6ObJK5TsUoGOI,2330
+gl_runner_sdk/runnables/__init__.py,sha256=psqWsKlhN_ZxoqV7cD7XfdDZ7yb7z8pRBD3u07GQRn4,268
+gl_runner_sdk/runnables/runnables.py,sha256=SxvehojJslacfb4_cWrPVEkVcmaftmBT1KO4MUhV3zM,22477
+gl_runner_sdk/runs/__init__.py,sha256=DEd3s7pW2XOxrygleb0aGD8q8yOjPYE1_wzRVy2E_rI,226
+gl_runner_sdk/runs/runs.py,sha256=KcyiO6cW7L-yLDIIfH2MVwAQBt6Fc_rIfcqluqdnN9I,10757
+gl_runner_sdk/types/__init__.py,sha256=YBdDk7UNw23nJkXFJ1Z-g4B-9tJ2gfIRPmDVkyeRWJA,379
+gl_runner_sdk/types/runnables.py,sha256=RIY141y2EKUUfVTffsANnlrrXiPQc1OXN7blqUU2BSQ,668
+gl_runner_sdk/types/runs.py,sha256=0wv_cO5VzSmStZpQCZluBsbtzj1iIpmopjS9nd6Zx4U,1776
+gl_runner_sdk-0.1.0.dist-info/METADATA,sha256=2nLsJSq-rwUNKObcJBjCeE4fDiUU5YzSMKFYzk2Qz3E,295
+gl_runner_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gl_runner_sdk-0.1.0.dist-info/RECORD,,

gl_runner_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any