wt-runner 0.1.3__tar.gz

wt_runner-0.1.3/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## v0.1.3 — 2026-03-13
+
+- Remove direct git reference from `wt-runner[gcp]` extras to fix PyPI publishing ([#71](https://github.com/wildlife-dynamics/wt/pull/71))
+
+## v0.1.2 — 2026-03-13
+
+- Bootstrap release for prefix.dev conda channel
+
+## v0.1.1 — 2026-03-05
+
+- Fix incorrect license metadata
+
+## v0.1.0 — 2026-03-05
+
+- Initial release

wt_runner-0.1.3/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: wt-runner
+Version: 0.1.3
+Summary: FastAPI application for workflow execution using wt-invokers
+License: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.16,>=3.13
+Requires-Dist: wt-contracts<1.0.0,>=0.1.0
+Requires-Dist: wt-invokers<1.0.0,>=0.1.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: py-rattler>=0.8.0
+Requires-Dist: ruamel.yaml>=0.18.0
+Requires-Dist: opentelemetry-api>=1.0.0
+Requires-Dist: opentelemetry-sdk>=1.0.0
+Requires-Dist: obstore>=0.6.0
+Provides-Extra: gcp
+Requires-Dist: opentelemetry-sdk<2,>=1.37.0; extra == "gcp"
+Requires-Dist: opentelemetry-exporter-gcp-trace<2,>=1.9.0; extra == "gcp"
+Requires-Dist: gcloud-aio-pubsub<7,>=6.1.0; extra == "gcp"

wt_runner-0.1.3/README.md

@@ -0,0 +1,435 @@
+# wt-runner
+
+FastAPI application for executing workflows using wt-invokers.
+
+## Overview
+
+`wt-runner` is a production-ready web service that provides HTTP endpoints for executing workflows. It integrates with `wt-invokers` to support multiple execution backends (local subprocess, cloud batch, etc.) and provides comprehensive workflow management capabilities.
+
+## Features
+
+- **Workflow Execution**: Run workflows with various configurations via HTTP API
+- **Pub/Sub Integration**: Process workflow requests from Google Cloud Pub/Sub
+- **Metadata Endpoints**: Retrieve workflow schemas and metadata
+- **Format Conversion**: Convert between parameter formats (params ↔ formdata)
+- **OpenTelemetry Tracing**: Built-in distributed tracing support
+- **Multiple Invokers**: Support for different execution backends via wt-invokers
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install wt-runner
+```
+
+### With Optional Dependencies
+
+```bash
+# For GCP support (tracing, Pub/Sub, ecoscope-eda-core)
+pip install wt-runner[gcp]
+```
+
+### Development Installation
+
+```bash
+cd wt-runner
+uv sync --dev
+uv run pytest
+```
+
+## Variants
+
+`wt-runner` ships as a base package with an optional GCP variant:
+
+| Variant | Package | Adds |
+|---------|---------|------|
+| **Base** | `wt-runner` | Workflow execution, result retrieval (obstore), all endpoints except Pub/Sub |
+| **GCP** | `wt-runner-gcp` | Pub/Sub endpoint, GCP tracing, Cloud Batch deps (`wt-invokers-gcp`) |
+
+### Installing variants
+
+- **pip**: `pip install wt-runner[gcp]`
+- **conda**: `pixi add wt-runner-gcp` (metapackage that pulls in `wt-runner` + all GCP deps)
+- **Compiled workflows**: `wt-compiler compile --spec spec.yaml --variant gcp`
+
+## Usage
+
+### Starting the Server
+
+```bash
+# Basic usage
+uvicorn wt_runner.app:app
+
+# With custom host and port
+uvicorn wt_runner.app:app --host 0.0.0.0 --port 8000
+
+# With auto-reload for development
+uvicorn wt_runner.app:app --reload
+```
+
+### Using the FastAPI App in Code
+
+```python
+from wt_runner import app
+
+# The app can be imported and used with any ASGI server
+import uvicorn
+uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+## API Endpoints
+
+### Health Check
+
+```bash
+GET /
+```
+
+Returns server health status.
+
+**Response:**
+```json
+{
+  "status": "ok"
+}
+```
+
+### Run Workflow
+
+```bash
+POST /
+```
+
+Execute a workflow with specified parameters.
+
+**Query Parameters:**
+- `matchspec` (required): Rattler matchspec for the workflow package
+- `invoker_type` (optional): Type of invoker to use (default: `BlockingLocalSubprocessInvoker`)
+- `results_url` (required): URL or path for storing results
+- `workflow_run_id` (optional): Unique identifier for the workflow run
+- `timeout` (optional): Timeout in seconds
+- `docker_image_uri` (optional): Docker image URI for the workflow
+
+**Request Body:**
+```json
+{
+  "params": {
+    "key": "value"
+  },
+  "execution_mode": "sequential",
+  "mock_io": false,
+  "data_connections_env_vars": {
+    "SECRET_KEY": "secret_value"
+  },
+  "lithops_config": {
+    "lithops": {
+      "backend": "localhost",
+      "storage": "localhost"
+    }
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "result": {...},
+  "error": null,
+  "trace": null
+}
+```
+
+### Run from Pub/Sub
+
+```bash
+POST /run-from-pubsub
+```
+
+Process workflow execution requests from Google Cloud Pub/Sub messages.
+
+**Request Body:** (Pub/Sub message format)
+```json
+{
+  "message": {
+    "data": "base64-encoded-workflow-params"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "processed"
+}
+```
+
+### Get RJSF Schema
+
+```bash
+GET /rjsf?matchspec=<workflow-matchspec>
+```
+
+Retrieve the React JSON Schema Form schema for a workflow.
+
+**Response:**
+```json
+{
+  "schema": {...},
+  "uiSchema": {...}
+}
+```
+
+### Get Data Connection Property Names
+
+```bash
+GET /data-connection-property-names?matchspec=<workflow-matchspec>
+```
+
+Retrieve data connection property names for a workflow.
+
+### Convert Form Data to Params
+
+```bash
+POST /formdata-to-params?matchspec=<workflow-matchspec>
+```
+
+Convert form data format to workflow parameters.
+
+**Request Body:**
+```json
+{
+  "field1": "value1",
+  "field2": "value2"
+}
+```
+
+### Convert Params to Form Data
+
+```bash
+POST /params-to-formdata?matchspec=<workflow-matchspec>
+```
+
+Convert workflow parameters to form data format.
+
+**Request Body:**
+```json
+{
+  "param1": "value1",
+  "param2": "value2"
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+- `ECOSCOPE_WORKFLOWS_MATCHSPEC_OVERRIDE`: Override matchspec for all requests
+- `ECOSCOPE_WORKFLOWS_OTEL_EXPORTER`: OpenTelemetry exporter type (`console` or `gcp`)
+- `ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_DST`: Console exporter destination (`stdout` or `file`)
+- `ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_FILE_DST_TARGET_DIR`: Directory for trace files
+
+### OpenTelemetry Tracing
+
+Enable tracing by setting environment variables:
+
+```bash
+# Console exporter (stdout)
+export ECOSCOPE_WORKFLOWS_OTEL_EXPORTER=console
+export ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_DST=stdout
+
+# Console exporter (file)
+export ECOSCOPE_WORKFLOWS_OTEL_EXPORTER=console
+export ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_DST=file
+export ECOSCOPE_WORKFLOWS_OTEL_CONSOLE_EXPORTER_FILE_DST_TARGET_DIR=/path/to/traces
+
+# GCP Cloud Trace
+export ECOSCOPE_WORKFLOWS_OTEL_EXPORTER=gcp
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+```
+
+### Programmatic Tracing Configuration
+
+```python
+from wt_runner import configure_tracer
+
+configure_tracer(
+    name="my-service",
+    version="1.0.0",
+    exporter="console",
+    exporter_kws={}
+)
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Core tests (GCP tests skipped)
+uv sync --dev
+uv run pytest
+
+# Full tests including GCP (Pub/Sub, tracing)
+uv sync --extra gcp --dev
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=wt_runner --cov-report=term-missing
+
+# Run specific test file
+uv run pytest tests/test_app.py
+
+# Run with verbose output
+uv run pytest -v
+```
+
+### Type Checking
+
+```bash
+uv run mypy src/wt_runner
+```
+
+### Linting and Formatting
+
+```bash
+# Check code
+uv run ruff check src/wt_runner
+
+# Format code
+uv run ruff format src/wt_runner
+```
+
+## Architecture
+
+### Dependencies
+
+- **wt-invokers**: Provides workflow execution backends (required)
+- **wt-contracts**: Shared interface contracts (required)
+- **FastAPI**: Web framework for API endpoints
+- **Uvicorn**: ASGI server for running the application
+- **Rattler**: Conda package management
+- **OpenTelemetry**: Distributed tracing (optional)
+- **obstore**: Object storage for result retrieval (required)
+
+### Package Structure
+
+```
+wt-runner/
+├── src/wt_runner/
+│   ├── __init__.py       # Package exports
+│   ├── app.py            # FastAPI application
+│   ├── tracing.py        # OpenTelemetry tracing
+│   └── _version.py       # Version info (auto-generated)
+├── tests/
+│   ├── test_app.py       # Endpoint tests
+│   ├── test_tracing.py   # Tracing tests
+│   └── conftest.py       # Pytest configuration
+├── pyproject.toml        # Package metadata
+└── README.md
+```
+
+## Invoker Support
+
+The runner supports all invokers provided by `wt-invokers`:
+
+- `BlockingLocalSubprocessInvoker`: Synchronous local subprocess execution
+- `AsyncLocalSubprocessInvoker`: Asynchronous local subprocess execution
+- `CloudBatchInvoker`: Google Cloud Batch execution (requires GCP dependencies)
+
+See [wt-invokers documentation](../wt-invokers/README.md) for more details.
+
+## Error Handling
+
+The runner provides comprehensive error handling:
+
+- **400 Bad Request**: Invalid request parameters
+- **422 Unprocessable Entity**: Validation errors
+- **500 Internal Server Error**: Workflow execution failures
+- **503 Service Unavailable**: Timeout errors
+
+All errors include detailed trace information in the response.
+
+## Examples
+
+### Basic Workflow Execution
+
+```python
+import httpx
+
+response = httpx.post(
+    "http://localhost:8000/",
+    params={
+        "matchspec": "my-workflow>=1.0",
+        "results_url": "gs://bucket/results",
+    },
+    json={
+        "params": {"input": "data"},
+        "execution_mode": "sequential",
+        "mock_io": False,
+    },
+)
+
+result = response.json()
+print(result["result"])
+```
+
+### With Custom Invoker
+
+```python
+response = httpx.post(
+    "http://localhost:8000/",
+    params={
+        "matchspec": "my-workflow>=1.0",
+        "invoker_type": "AsyncLocalSubprocessInvoker",
+        "results_url": "gs://bucket/results",
+    },
+    json={
+        "params": {"input": "data"},
+        "execution_mode": "async",
+        "mock_io": False,
+    },
+)
+```
+
+### With Tracing
+
+```python
+response = httpx.post(
+    "http://localhost:8000/",
+    params={
+        "matchspec": "my-workflow>=1.0",
+        "results_url": "gs://bucket/results",
+    },
+    headers={
+        "traceparent": "00-trace-id-span-id-01",
+    },
+    json={
+        "params": {"input": "data"},
+        "execution_mode": "sequential",
+        "mock_io": False,
+    },
+)
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass: `uv run pytest`
+2. Type checking passes: `uv run mypy src/wt_runner`
+3. Code is formatted: `uv run ruff format src/wt_runner`
+4. Test coverage remains >90%
+5. All public functions have docstrings
+
+## License
+
+BSD-3-Clause
+
+## Related Packages
+
+- [wt-contracts](../wt-contracts/README.md): Shared interface contracts
+- [wt-invokers](../wt-invokers/README.md): Workflow execution backends
+- [wt-task](../wt-task/README.md): Task decorator and execution
+- [wt-compiler](../wt-compiler/README.md): Workflow compilation
+- [wt-registry](../wt-registry/README.md): Function registration

wt_runner-0.1.3/pyproject.toml

@@ -0,0 +1,149 @@
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wt-runner"
+dynamic = ["version"]
+description = "FastAPI application for workflow execution using wt-invokers"
+requires-python = ">=3.13,<3.16"
+license = { text = "BSD-3-Clause" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "wt-contracts>=0.1.0,<1.0.0",
+    "wt-invokers>=0.1.0,<1.0.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "pydantic>=2.0.0,<3.0.0",
+    "py-rattler>=0.8.0",
+    "ruamel.yaml>=0.18.0",
+    "opentelemetry-api>=1.0.0",
+    "opentelemetry-sdk>=1.0.0",
+    "obstore>=0.6.0",
+]
+
+[project.optional-dependencies]
+# Google Cloud Platform dependencies (tracing, Pub/Sub)
+# Note: ecoscope-eda-core is excluded here because PyPI forbids direct git
+# references in extras. Install it separately or use the wt-runner-gcp conda
+# metapackage which includes it.
+gcp = [
+    "opentelemetry-sdk>=1.37.0,<2",
+    "opentelemetry-exporter-gcp-trace>=1.9.0,<2",
+    "gcloud-aio-pubsub>=6.1.0,<7",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "httpx>=0.24.0",  # For FastAPI testing
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.uv.sources]
+# Development override - uses local editable packages
+# Published packages will reference PyPI version normally
+wt-contracts = { path = "../wt-contracts", editable = true }
+wt-invokers = { path = "../wt-invokers", editable = true }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+# Version comes from git tags matching this pattern
+tag_regex = "^wt-runner/v(?P<version>[0-9.]+)$"
+# Root is the git repository root
+root = ".."
+# Generate version file
+version_file = "src/wt_runner/_version.py"
+git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "wt-runner/v*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--cov=wt_runner --cov-report=term-missing"
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = [
+    "opentelemetry",
+    "opentelemetry.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["wt_runner.tracing"]
+warn_unused_ignores = false
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # Allow unused imports in __init__.py
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "fastapi.Query",
+    "fastapi.Depends",
+]
+
+# ============================================================================
+# Pixi Build Configuration (conda package building)
+# ============================================================================
+
+[tool.pixi.package]
+name = "wt-runner"
+version = "0.1.3"
+
+[tool.pixi.package.build]
+backend = { name = "pixi-build-python", version = "*", channels = ["conda-forge", "https://prefix.dev/pixi-build-backends"] }
+
+[tool.pixi.package.build.config]
+noarch = true
+
+[tool.pixi.package.host-dependencies]
+python = ">=3.13,<3.16"
+setuptools = ">=64"
+setuptools-scm = ">=8"
+pip = "*"
+
+[tool.pixi.package.run-dependencies]
+python = ">=3.13,<3.16"
+fastapi = ">=0.100.0"
+uvicorn = ">=0.20.0"
+pydantic = ">=2.0.0,<3.0.0"
+py-rattler = ">=0.8.0"
+"ruamel.yaml" = ">=0.18.0"
+opentelemetry-api = ">=1.0.0"
+opentelemetry-sdk = ">=1.0.0"
+obstore = ">=0.6.0"
+wt-contracts = ">=0.1.0,<1.0.0"
+wt-invokers = ">=0.1.0,<1.0.0"

wt_runner-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wt_runner-0.1.3/src/wt_runner/__init__.py

@@ -0,0 +1,36 @@
+"""wt-runner: FastAPI application for workflow execution.
+
+This package provides a FastAPI web service for executing workflows using
+wt-invokers. It includes endpoints for:
+- Running workflows with various configurations
+- Processing Pub/Sub messages
+- Retrieving workflow metadata and schemas
+- Converting between parameter formats
+"""
+
+from wt_runner.app import app
+from wt_runner.testing import Case, CaseRunner
+from wt_runner.tracing import (
+    TraceContextHeaders,
+    attach_context,
+    build_context_headers,
+    configure_tracer,
+)
+
+try:
+    from wt_runner._version import __version__, __version_tuple__
+except ImportError:
+    __version__ = "unknown"
+    __version_tuple__ = (0, 0, 0)
+
+__all__ = [
+    "app",
+    "Case",
+    "CaseRunner",
+    "configure_tracer",
+    "attach_context",
+    "build_context_headers",
+    "TraceContextHeaders",
+    "__version__",
+    "__version_tuple__",
+]

wt_runner-0.1.3/src/wt_runner/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.3'
+__version_tuple__ = version_tuple = (0, 1, 3)
+
+__commit_id__ = commit_id = 'g9ca3e09'