Apagea Python SDK

The apagea distribution provides the typed Action runtime for Python >=3.14,<3.15. Releases publish exact SDK runtime dependency requirements so ordinary Action locks capture a compatible SDK dependency set. Action-specific dependencies may be added when compatible with those requirements. 0.1.0.dev0 identifies the embedded development SDK.

from pydantic import SecretStr
from apagea.actions import Context, Inputs, Outputs

class Request(Inputs):
    message: str

class Settings(Context):
    api_token: SecretStr

class Result(Outputs):
    message: str

def handler(inputs: Request, context: Settings) -> Result:
    context.log.info("Processing request")
    return Result(message=inputs.message)

Declare the handler in [project.entry-points."apagea.action"]. The Go CLI discovers/builds the interface in a uv-managed environment through this SDK. Context model fields describe deployment-scoped Context requirements; invocation identity, scratch space, logging, and artifact staging are runtime facilities excluded from that schema.

Logger methods are debug, info, warn, error, and exception, with no aliases. Records are bounded and thread-safe. Wrapped secret values are recursively masked, and known secret strings are redacted on a best-effort basis. Unwrapping/transformation is not tracked as taint. Do not write secrets to logs. Sensitive Context disables detailed local exception diagnostics; secret wrappers in public results retain Pydantic's masking. Remote protected outputs are sealed to the server, encrypted at rest, and exposed through separately authorized evidence endpoints.

apagea.fields supplies Pydantic-compatible TextInput, NumberInput, Text, Table, LineChart, and Download helpers. Capture validates component field references and emits versioned metadata plus explicit field order. External clients can render these contracts; apagea.blocks is the preferred output-authoring surface, with Metric, MetricValue, Status, TimeSeries, Table, Text, and Download. Existing output helpers remain compatible. The server returns ordinary fields as JSON without prescribing rendering.

context.artifacts.add stages bounded files from scratch space. Local limits are 16 files, 16 MiB per file, and 64 MiB total. Use the CLI's --artifacts to retain them after execution. Remote artifacts are retained by the server and downloaded through authenticated endpoints.

A handler explicitly annotated -> None may complete without returning domain data. Its wire output is an empty object. A non-None return fails validation. A numeric field can use Metric(format="compact"); a MetricValue field can additionally return value, previous, and comparison for a comparative metric. Logger methods remain unchanged and have no aliases.

uv run --project apagea-sdk python -m unittest discover -s apagea-sdk/tests

See authoring contract and working example.

Helpful failures

Use ActionError(message, code="action_failed", *, hint="") for text intended for the person running the tool. Keep credentials and sensitive data out of all three public fields. Known secrets are additionally redacted by the SDK and server.

raise ActionError(
    "GitHub rejected the configured credential.",
    "github_authentication_failed",
    hint="Ask a Namespace administrator to update the credential.",
) from error

Deployed failures automatically capture a protected exception chain and stack locations, including when Context contains secrets. These are sealed to the server and accessible only through separately authorized, audited diagnostic reads. Unexpected exception messages stay in that protected record. Local diagnostic behavior is unchanged. See invocation diagnostics for collection limits and security boundaries.

Native Actions use the runner account's host networking. Do not set [tool.apagea].network_required; this removed declaration did not enforce access. Virtual environments isolate dependencies, not network or filesystem permissions.