Action SDK

Typed inputs, outputs, context, and structured logs.

Import the authoring API from pyplines.actions:

Python

from pyplines.actions import ActionError, Context, Inputs, Outputs

Handler contract

Handlers are synchronous functions accepting a typed Inputs instance and Context, returning the declared Outputs type. Declare the handler under [project.entry-points."pyplines.action"] in pyproject.toml.

Output instances are revalidated, including constructed or mutated nested models. Serialization aliases and computed fields are supported. Captured output schemas use Pydantic serialization mode. Serializers run after validation.

Context

Context exposes invocation_id, temporary scratch_dir, and structured logging:

Python

context.log("Service restarted", level="info", service="payments", elapsed_ms=420)

Levels are debug, info, warning, and error. Custom attributes are JSON-compatible values under fields. Messages are limited to 4,096 characters, encoded fields to 8 KiB, and complete records to 16 KiB. Numeric values must be finite.

Never log secrets. There is no automatic secret redaction.

Compatibility

Stable releases within a calendar year retain backwards-compatible authoring APIs; prereleases do not carry that guarantee. Execution compatibility is governed by pyplines.action.v1.

Rebuild Action images after upgrading the SDK. Previously published images retain their embedded SDK and captured contracts.

Action CLI

Commands for authoring and publishing typed Actions.

Contracts and compatibility

Discover, pin, and validate against the machine-readable Pyplines interfaces.