gl-runner-sdk 0.1.0__tar.gz

gl_runner_sdk-0.1.0/.env.example

@@ -0,0 +1,3 @@
+# GL Runner SDK local environment
+GL_RUNNER_BASE_URL=http://localhost:4200
+GL_RUNNER_API_KEY=glr_replace_me

gl_runner_sdk-0.1.0/.env.test.example

@@ -0,0 +1,3 @@
+# Copy to .env.test for local integration tests.
+GL_RUNNER_BASE_URL=http://localhost:4200
+GL_RUNNER_API_KEY=glr_replace_me

gl_runner_sdk-0.1.0/.gitconfig

@@ -0,0 +1,7 @@
+[user]
+	name = catapa-infra
+	email = sre@catapa.com
+[url "https://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:x-oauth-basic@github.com/"]
+	insteadOf = https://github.com/
+[url "https://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@github.com"]
+	insteadOf = ssh://git@github.com

gl_runner_sdk-0.1.0/.gitignore

@@ -0,0 +1,164 @@
+# Created by https://www.gitignore.io/api/python
+# Edit at https://www.gitignore.io/?templates=python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+jars/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don’t work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.idea
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# End of https://www.gitignore.io/api/python
+
+build/*
+test/data/demand_forecaster/save_model.model
+condaenv.t1e302om.requirements.txt
+
+*.env
+!build.ci.env
+*.aes
+
+# local IDE stuffs
+.idea/*
+.DS_Store
+data/
+db/
+embeddings_model/
+logs/
+tokenizer/
+
+#vs code stuffs
+.vscode/*
+!.vscode/extensions.json
+
+#specific files
+libs/documentation/scripts/docs_generated/*
+libs/documentation/docs/gllm*
+libs/documentation/docs/index.rst
+libs/documentation/docs/conf.py
+libs/documentation/docs/_summary/
+libs/documentation/docs/_build/
+
+**/.local_files/*
+**/.local/*
+*.pyi
+setup.cfg
+setup.py
+*.xml
+*cache
+*.key
+!cache/
+!hybrid_cache/
+!vector_cache/
+!data_store_cache/
+
+/.playwright-mcp/
+/reviews/
+/.worktrees/
+/.tmp/
+/.agents/local/
+fix_plan_*.md
+
+deployment/helm-values/values.glchatdemo.secret.yaml
+deployment/helm-values/values.glchatdev.secret.yaml
+deployment/helm-values/values.glchatprod.secret.yaml

gl_runner_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,157 @@
+# GL Runner Python SDK
+
+Lightweight Python SDK for interacting with GL Runner API.
+
+## Installation
+
+```bash
+pip install -e python/gl-runner-sdk
+```
+
+## Quick Start
+
+```python
+from gl_runner_sdk import Runnable
+
+runnable = Runnable(
+    base_url="https://runner.example.com",
+    api_key="glr_...",
+    key="hello-world",
+    bundle_path="./examples/bundles/hello-world",
+)
+
+# Deploy a runnable
+deployment = runnable.deploy()
+print(deployment.id)
+
+# Run waits by default and returns the completed result
+result = runnable.run(payload={"question": "status"})
+print(result)
+
+# Trigger returns a run record without waiting
+run = runnable.trigger(payload={"question": "status"})
+print(run.id)
+```
+
+## Blank Folder Quickstart
+
+1. Create a new folder and install:
+
+```bash
+mkdir lite-sdk-quickstart && cd lite-sdk-quickstart
+python3 -m venv .venv
+source .venv/bin/activate
+pip install gl-runner-sdk python-dotenv
+```
+
+2. Set API variables:
+
+```bash
+export GL_RUNNER_BASE_URL="http://localhost:4200"
+export GL_RUNNER_API_KEY="glr_..."
+```
+
+3. Create files:
+
+```text
+lite-sdk-quickstart/
+  deploy_and_run.py
+  bundles/
+    hello-world/
+      runnables.yaml
+      entrypoint.py
+```
+
+`bundles/hello-world/runnables.yaml`:
+
+```yaml
+entrypoint: entrypoint.py:handler
+kind: code
+```
+
+`bundles/hello-world/entrypoint.py`:
+
+```python
+def handler(payload=None, context=None):
+    payload = payload or {}
+    return {"ok": True, "echo": payload}
+```
+
+`deploy_and_run.py`:
+
+```python
+from gl_runner_sdk import Runnable
+
+runnable = Runnable(
+    key="hello-world",
+    bundle_path="./bundles/hello-world",
+)
+
+deployment = runnable.deploy()
+result = runnable.run(payload={"message": "hello"})
+print("deployment_id=", deployment.id)
+print("result=", result)
+```
+
+4. Run:
+
+```bash
+python deploy_and_run.py
+```
+
+Expected output includes a deployment id and a result similar to
+`{"ok": True, "echo": {"message": "hello"}}`.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GL_RUNNER_API_KEY` | required | API key for authentication |
+| `GL_RUNNER_BASE_URL` | `http://localhost:4200` | Base URL |
+
+The SDK client reads `GL_RUNNER_BASE_URL` and `GL_RUNNER_API_KEY` from your
+local environment for API access.
+
+Bundle packaging excludes `.env`, `.env.*`, caches, virtualenvs, build outputs,
+and VCS metadata by default. If a trusted local bundle must carry a runtime
+`.env`, opt in explicitly with `include_sensitive_files=[".env"]` or
+`gl-runner deploy --include-sensitive-file .env`.
+
+Deployed runnable code only sees variables provided by the runner environment,
+or files explicitly packaged into the bundle.
+
+Troubleshooting:
+- `401/403`: verify `GL_RUNNER_API_KEY`.
+- connection errors: verify `GL_RUNNER_BASE_URL` and server availability.
+- `Bundle manifest is required`: ensure `runnables.yaml` exists in bundle root.
+- runnable cannot read `.env`: include it explicitly or set variables on runner.
+
+## Tests
+
+```bash
+python -m pytest
+```
+
+Integration tests auto-skip unless they can reach `GL_RUNNER_BASE_URL` and
+`GL_RUNNER_API_KEY` is configured.
+
+## Scripts
+
+```bash
+# Deploy
+python ./scripts/deploy.py --bundle-path ./bundle --key hello
+
+# Run
+python ./scripts/run.py --runnable-id <id> --payload '{"key":"value"}'
+
+# Wait
+python ./scripts/run.py --runnable-id <id> --wait
+
+# List
+python ./scripts/list.py runnables
+```
+
+## Example Bundles
+
+Deployable bundles from the original `python/gl-runner/examples` tree now live
+under `examples/bundles/`.

gl_runner_sdk-0.1.0/build.ci.github.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -e
+
+REPORT_PATH=build/reports
+
+rm -rf dist build *.egg-info
+mkdir -p "$REPORT_PATH"
+
+cd "$(dirname "$0")"
+
+export HOME=${HOME:-$(pwd)}
+export REPORT_PATH
+
+if [[ "${CI}" == "true" ]]; then
+  git config --unset credential.helper || :
+  git config --global user.name "catapa-infra"
+  git config --global user.email "sre@catapa.com"
+  git config --global url."https://${GH_TOKEN}:x-oauth-basic@github.com/".insteadOf "https://github.com/"
+  git config --global url."https://${GH_TOKEN}@github.com".insteadOf "ssh://git@github.com"
+  git branch -m temp-branch 2>/dev/null || echo "Note: Could not rename branch, continuing..."
+fi
+
+function build {
+  echo "Installing SDK dependencies..."
+  uv sync --extra dev --frozen
+}
+
+function run_code_style_check {
+  echo "Running code style check with ruff..."
+  uv run ruff check . --exclude=.venv,build,dist,.local,.cache,__pycache__
+}
+
+function run_tests {
+  echo "Running SDK tests and generating coverage report..."
+  uv run python -m coverage run -m pytest
+  test_exit_code=$?
+
+  if [[ $test_exit_code -ne 0 ]]; then
+    echo "ERROR: Tests failed with exit code $test_exit_code"
+    exit $test_exit_code
+  fi
+
+  uv run python -m coverage report -m -i --skip-empty
+  uv run python -m coverage xml -i -o "$REPORT_PATH/gl-runner-sdk.xml"
+
+  if [[ -f "$REPORT_PATH/gl-runner-sdk.xml" ]]; then
+    echo "SUCCESS: Coverage report generated at $REPORT_PATH/gl-runner-sdk.xml"
+  else
+    echo "ERROR: Coverage report file was not created!"
+    exit 1
+  fi
+}
+
+function build_package {
+  echo "Building SDK package..."
+  uv build
+}
+
+build
+
+if [[ "${CI}" == "true" ]]; then
+  run_code_style_check
+  run_tests
+  build_package
+fi
+
+echo "Build and test completed successfully!"

gl_runner_sdk-0.1.0/docs-planning/manual-publish-checklist-premium.md

@@ -0,0 +1,126 @@
+# GL Runner Manual Publish Checklist (Premium)
+
+This is the operational source of truth for:
+
+- sidebar order in GitBook,
+- target slug mapping under `https://gdplabs.gitbook.io/sdk/gl-runner/...`,
+- phased publishing sequence.
+
+Authoring source in repo:
+
+- `python/gl-runner-sdk/gitbook/`
+
+Standardization policy applied:
+
+- UX-first onboarding order is used for GL Runner:
+  `Overview` -> `Prerequisites` -> `Getting Started` -> `Guides` -> `Tutorials` -> `Resources`.
+- Required sections are present: Introduction (Overview), Prerequisites, Getting Started.
+- Topics are organized into: `Getting Started`, `Guides`,
+  `Prerequisites`, `Tutorials`, `Resources`.
+- `Cookbook` is published at the root level (`gl-runner-cookbook.md`), not nested under `guides/`.
+
+## 0) One-time setup in GitBook (GL SDK space)
+
+1. Create a top-level page/collection: `GL Runner`.
+1. Set top-level slug: `gl-runner`.
+1. Create top-level children in this exact order:
+   - `introduction-to-gl-runner`
+   - `prerequisites`
+   - `getting-started`
+   - `guides`
+   - `tutorials`
+   - `resources`
+1. Under `resources`, create child pages and collections in this order:
+   - `runtime-environment`
+   - `glossary`
+   - `reference`
+   - `reference/rest-api`
+
+## 1) Publish order (recommended)
+
+Ship in waves for navigability and lower risk.
+
+### Wave A: Required baseline
+
+- `introduction-to-gl-runner.md` -> `gl-runner/introduction-to-gl-runner`
+- `prerequisites.md` -> `gl-runner/prerequisites`
+- `getting-started/README.md` -> `gl-runner/getting-started/README`
+
+### Wave B: Guides
+
+- `guides/README.md` -> `gl-runner/guides/README`
+- `guides/bundle-format.md` -> `gl-runner/guides/bundle-format`
+- `guides/building-runnables.md` -> `gl-runner/guides/building-runnables`
+- `guides/deploy-runnables.md` -> `gl-runner/guides/deploy-runnables`
+- `guides/run-and-wait.md` -> `gl-runner/guides/run-and-wait`
+- `guides/streaming-and-history.md` -> `gl-runner/guides/streaming-and-history`
+- `guides/update-runnables.md` -> `gl-runner/guides/update-runnables`
+- `gl-runner-cookbook.md` -> `gl-runner/gl-runner-cookbook`
+
+### Wave C: Tutorials
+
+- `tutorials/README.md` -> `gl-runner/tutorials/README`
+- `tutorials/hello-world.md` -> `gl-runner/tutorials/hello-world`
+- `tutorials/math-sum.md` -> `gl-runner/tutorials/math-sum`
+- `tutorials/simple-de.md` -> `gl-runner/tutorials/simple-de`
+- `tutorials/custom-de.md` -> `gl-runner/tutorials/custom-de`
+- `tutorials/stateful-runnables.md` -> `gl-runner/tutorials/stateful-runnables`
+
+### Wave D: Resources
+
+- `resources/README.md` -> `gl-runner/resources/README`
+- `resources/runtime-environment.md` -> `gl-runner/resources/runtime-environment`
+- `resources/glossary.md` -> `gl-runner/resources/glossary`
+- `resources/reference/README.md` -> `gl-runner/resources/reference/README`
+- `resources/reference/python-sdk.md` -> `gl-runner/resources/reference/python-sdk`
+- `resources/reference/rest-api/README.md` -> `gl-runner/resources/reference/rest-api/README`
+- `resources/reference/rest-api/runnables.md` -> `gl-runner/resources/reference/rest-api/runnables`
+- `resources/reference/rest-api/runs.md` -> `gl-runner/resources/reference/rest-api/runs`
+- `resources/reference/rest-api/schemas.md` -> `gl-runner/resources/reference/rest-api/schemas`
+- (no rest-api/index.md — use rest-api/README as entry)
+
+## 2) Policy guardrails during publishing
+
+1. Default to Agent-first examples and workflows.
+1. Keep `Client` examples only for legacy/advanced admin workflows.
+1. Keep REST details in `resources/reference/rest-api/*`; avoid deep REST walkthroughs in guides.
+1. Move long advanced examples to cookbook links when page readability degrades.
+1. Keep internal links under `https://gdplabs.gitbook.io/sdk/gl-runner/...`.
+1. Avoid GitBook block macros in source markdown (for example `{% stepper %}` / `{% step %}`), because manual copy-paste mode may render them as plain text. Use numbered headings/lists instead.
+
+## 3) QA before each publish wave
+
+- Exactly one in-content H1 in source markdown, as the first line, matching the page title in GitBook navigation.
+- Internal links resolve to current target slugs.
+- Code fences and GitBook hints render properly.
+- Terminology is consistent (Agent-first, CLI in Guides, REST reference-only).
+- Sidebar order matches this checklist.
+
+## 4) Drift control
+
+If a hotfix is made directly in GitBook UI, mirror it back into
+`python/gl-runner-sdk/gitbook/` immediately.
+
+## 5) Team sync process
+
+Use the **`gitbook_sync`** skill (located at `.agents/skills/gitbook_sync/`):
+
+```bash
+# 1. Dry-run to preview changes
+python .agents/skills/gitbook_sync/scripts/sync_from_checklist.py
+
+# 2. Apply sync (copies files to gl-sdk)
+python .agents/skills/gitbook_sync/scripts/sync_from_checklist.py --apply
+
+# 3. Commit and push in gl-sdk repo
+cd /path/to/gl-sdk
+git add gitbook/gl-runner gitbook/SUMMARY.md
+git commit -m "docs: sync GL Runner pages"
+git push origin docs/gitbook-sync
+
+# 4. Wait 1-2 minutes, then verify live
+# https://gdplabs.gitbook.io/sdk/gl-runner/overview
+```
+
+**Note:** This checklist is the source of truth for page mappings. The skill
+reads it automatically to determine which files to sync.

gl_runner_sdk-0.1.0/examples/.env.example

@@ -0,0 +1,7 @@
+# GL Runner SDK — copy this file to .env and fill in your values
+
+# Base URL of your GL Runner instance (local or remote)
+GL_RUNNER_BASE_URL=http://localhost:4200
+
+# API key issued by GL Runner (starts with glr_)
+GL_RUNNER_API_KEY=glr_...

gl_runner_sdk-0.1.0/examples/01_hello_world.py

@@ -0,0 +1,38 @@
+"""Hello World — deploy and run the hello-world bundle.
+
+Authors:
+    Immanuel Rhesa (immanuel.rhesa@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from gl_runner_sdk import Runnable
+
+load_dotenv()
+
+
+def main() -> None:
+    """Deploy the hello-world bundle and run it with a sample payload."""
+    runnable = Runnable(
+        base_url=os.environ["GL_RUNNER_BASE_URL"],
+        api_key=os.environ["GL_RUNNER_API_KEY"],
+        key="hello-world",
+        bundle_path="./bundles/hello-world",
+    )
+
+    print("Deploying hello-world...")
+    deployment = runnable.deploy()
+    print(f"Deployed: {deployment.id}")
+
+    print("Running hello-world...")
+    result = runnable.run(payload={"name": "GL Runner"})
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    main()

gl_runner_sdk-0.1.0/examples/02_math_sum.py

@@ -0,0 +1,38 @@
+"""Math Sum — deploy and run the math-sum bundle.
+
+Authors:
+    Immanuel Rhesa (immanuel.rhesa@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from gl_runner_sdk import Runnable
+
+load_dotenv()
+
+
+def main() -> None:
+    """Deploy the math-sum bundle and run it with a list of numbers."""
+    runnable = Runnable(
+        base_url=os.environ["GL_RUNNER_BASE_URL"],
+        api_key=os.environ["GL_RUNNER_API_KEY"],
+        key="math-sum",
+        bundle_path="./bundles/math-sum",
+    )
+
+    print("Deploying math-sum...")
+    deployment = runnable.deploy()
+    print(f"Deployed: {deployment.id}")
+
+    print("Running math-sum with [1, 2, 3, 4, 5]...")
+    result = runnable.run(payload={"numbers": [1, 2, 3, 4, 5]})
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    main()

gl_runner_sdk-0.1.0/examples/03_simple_de.py

@@ -0,0 +1,44 @@
+"""Simple Digital Employee — deploy and run the simple-de bundle.
+
+Authors:
+    Immanuel Rhesa (immanuel.rhesa@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from gl_runner_sdk import Runnable
+
+load_dotenv()
+
+
+def main() -> None:
+    """Deploy the simple-de bundle and invoke the Digital Employee with a message.
+
+    The bundle's .env is included in the deployment so the Digital Employee
+    can access the Google Mail MCP credentials at runtime.
+    """
+    runnable = Runnable(
+        base_url=os.environ["GL_RUNNER_BASE_URL"],
+        api_key=os.environ["GL_RUNNER_API_KEY"],
+        key="simple-de",
+        bundle_path="./bundles/simple-de",
+    )
+
+    print("Deploying simple-de...")
+    deployment = runnable.deploy(include_sensitive_files=[".env"])
+    print(f"Deployed: {deployment.id}")
+
+    print("Running simple-de...")
+    result = runnable.run(
+        payload={"message": "Send a welcome email to the new team member."}
+    )
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    main()