Metadata-Version: 2.4
Name: apagea
Version: 2026.10.1rc2
Summary: Official APAGEA Python SDK and typed Action runtime
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: pydantic==2.12.5
Requires-Dist: packaging==25.0
Requires-Dist: cryptography<47,>=46

# Apagea Python SDK

The `apagea` distribution provides the typed Action runtime, extracted and adapted from Pyplines. Initial development version: `0.1.0.dev0` (unpublished).

```python
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 Docker 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.

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

See [authoring contract](../design/AUTHORING.md) and [working example](../examples/README.md).

## 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.

```python
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](../design/DIAGNOSTICS.md) for collection limits and security boundaries.
