Code Template

GLLM Tools sandbox template builder module.

Exposes the provider-agnostic BaseTemplateBuilder interface and the shared models. Concrete provider builders are imported directly from their modules (e.g. code_template.e2b_template_builder) so that importing this package does not pull in every provider SDK.

RegistryAuth = Annotated[BasicAuth | AwsAuth | GcpAuth, Field(discriminator='type')] module-attribute

Discriminated union of registry credential styles, keyed on the type tag.

Each variant carries exactly its own fields (no not-applicable leftovers) and is validated on construction (e.g. AwsAuth requires region).

AwsAuth

Bases: BaseModel

AWS ECR auth via IAM credentials.

E2B exchanges these for a registry token server-side; other backends translate to a basic login client-side.

Attributes:

Name	Type	Description
type	Literal['aws']	Discriminator tag.
access_key_id	str	AWS access key ID (identifier, not secret).
secret_access_key	SecretStr	AWS secret access key. Redacted in repr/logs; reveal at the SDK boundary via reveal_secret_key().
region	str	ECR region.

reveal_secret_key()

Return the secret access key in plain text (use only at the SDK boundary).

BaseTemplateBuilder

Bases: ABC

Provider-agnostic, build-time companion to BaseSandbox.

Implementations produce a reusable template reference for one sandbox provider. The interface is uniform; the mechanism is delegated to each provider. supports_build makes the asymmetry explicit so callers can branch up front instead of relying on methods that silently do nothing.

provider abstractmethod property

The backend this builder targets; stamped into every TemplateRef.

Returns:

Name	Type	Description
SandboxProvider	SandboxProvider	The provider identifier.

Raises:

Type	Description
NotImplementedError	If the property is not implemented in the subclass.

supports_build abstractmethod property

Whether this provider can build templates.

Returns:

Name	Type	Description
bool	bool	True if build() produces a reusable reference (E2B,
	bool	OpenSandbox); False if the provider has no template mechanism (Bedrock).

Raises:

Type	Description
NotImplementedError	If the property is not implemented in the subclass.

build(spec) abstractmethod

Produce or refresh the template described by spec.

Providers that cannot build return a result with status=UNSUPPORTED and template_ref=None rather than raising.

Parameters:

Name	Type	Description	Default
spec	TemplateSpec	Provider-neutral build inputs.	required

Returns:

Name	Type	Description
TemplateBuildResult	TemplateBuildResult	The structured build outcome.

Raises:

Type	Description
NotImplementedError	If the method is not implemented in the subclass.

ensure(spec)

Idempotently ensure the template exists. Never raises.

Flow

1. Fast path: if not force_rebuild and a usable reference resolves, return SKIPPED.
2. Otherwise build(spec).
3. If the build failed (non-forced) but a usable reference now resolves, treat it as SKIPPED (a concurrent builder may have won the race).

Any exception is caught and returned as FAILED so the runtime can fall back to a default sandbox rather than crashing.

Parameters:

Name	Type	Description	Default
spec	TemplateSpec	Provider-neutral build inputs.	required

Returns:

Name	Type	Description
TemplateBuildResult	TemplateBuildResult	The structured outcome (template_ref is
	TemplateBuildResult	None only for FAILED/UNSUPPORTED).

is_usable(template_id) abstractmethod

Whether a usable template resolves for template_id.

"Usable" means it can back a sandbox creation — for E2B the alias exists with at least one tag; for OpenSandbox a Ready snapshot of that name exists.

Parameters:

Name	Type	Description	Default
template_id	str	The template handle to check.	required

Returns:

Name	Type	Description
bool	bool	True if the template is usable for sandbox creation.

Raises:

Type	Description
NotImplementedError	If the method is not implemented in the subclass.

BasicAuth

Bases: BaseModel

Username/password auth (Docker Hub, GHCR, Harbor, any registry with basic auth).

The only mode OpenSandbox supports natively.

Attributes:

Name	Type	Description
type	Literal['basic']	Discriminator tag.
username	str	Registry username (identifier, not secret).
password	SecretStr	Registry password or token. Redacted in repr/logs; reveal at the SDK boundary via reveal_password().

reveal_password()

Return the password in plain text (use only at the SDK boundary).

GcpAuth

Bases: BaseModel

GCP Artifact/Container Registry auth via a service-account JSON.

E2B handles the exchange server-side; other backends translate to a basic login.

Attributes:

Name	Type	Description
type	Literal['gcp']	Discriminator tag.
service_account_json	SecretStr	Service-account credentials, given as either the JSON content or a filesystem path to the JSON file. Redacted in repr/logs; use resolved_service_account_json() to get the content uniformly regardless of which form was provided.

resolved_service_account_json()

Return the service-account JSON content, reading a file if a path was given.

Returns:

Name	Type	Description
str	str	The JSON content (the value verbatim when it is not a readable path).

SandboxProvider

Bases: str, Enum

Sandbox backend that produced (or would produce) a template reference.

A str enum so it serializes as a plain value ("e2b") across service boundaries and compares to plain strings.

Attributes:

Name	Type	Description
E2B		E2B backend (reference is an alias).
OPENSANDBOX		OpenSandbox backend (reference is a snapshot name).
BEDROCK		Bedrock AgentCore (no template; never emits a reference).

TemplateBuildResult

Bases: BaseModel

Structured, provider-agnostic result of a template build/ensure.

Attributes:

Name	Type	Description
status	TemplateBuildStatus	Outcome of the operation.
template_ref	TemplateRef | None	Self-describing reference to pass to the sandbox-creating service. None for FAILED or UNSUPPORTED.
detail	str	Human-readable note (why skipped / unsupported / error head).
stage	Stage | None	The failing stage for a FAILED result (typically Stage.TEMPLATE_BUILD), so callers get a structured category instead of a bare detail string. None for non-failure outcomes.
logs	str	Build output captured for debugging, when available.

TemplateBuildStatus

Bases: Enum

Outcome of a template build/ensure operation.

Attributes:

Name	Type	Description
SUCCESS		The template was built and is ready.
SKIPPED		The template was already usable; no rebuild was needed.
UNSUPPORTED		The provider cannot build templates.
FAILED		A build was attempted and failed.

TemplateRef

Bases: BaseModel

Self-describing, serializable reference to a built template.

Produced by a build-time TemplateBuilder and consumed by a (possibly separate) sandbox-creating service. It carries the provider so the consumer can dispatch to the right create() without the original TemplateSpec or builder. Being a plain model, it survives a DB row / message-queue hop between services.

Attributes:

Name	Type	Description
provider	SandboxProvider	Which backend produced the reference.
value	str	The provider-native reference — an E2B alias name or an OpenSandbox snapshot name (the stable template_id handle, resolved to a concrete snapshot id at create time). Never a raw snapshot id.

TemplateSpec

Bases: BaseModel

Provider-neutral inputs for building a sandbox template.

The standard input is a container image registry reference (image + optional registry_auth); each builder resolves it to a provider-native reference (E2B alias, OpenSandbox snapshot/image, ...). packages are baked in on top when the provider supports it.

Attributes:

Name	Type	Description
template_id	str	Stable handle for the template (E2B alias name / OpenSandbox snapshot name).
image	str | None	Container image registry reference to build from (e.g. "python:3.12" or "123.dkr.ecr.us-west-2.amazonaws.com/img:tag"). This is the standard, preferred input.
registry_auth	RegistryAuth | None	Credentials for pulling image from a private registry. None for public images.
packages	list[str] | None	pip packages to bake in. Treated as trusted (the caller pre-validates). If None/empty, no install step runs.
start_cmd	str | None	Command the sandbox runs at boot (E2B/OpenSandbox do not run the image ENTRYPOINT). When image is set and this is None, the builder defaults to the code-interpreter start command (E2B start command / OpenSandbox DEFAULT_CI_ENTRYPOINT). Ignored by Bedrock.
ready_cmd	str | None	E2B-only — shell readiness check paired with start_cmd; defaults to waiting on the code-interpreter port. Ignored by OpenSandbox/Bedrock.
cpu_count	int | None	E2B-only — whole CPU cores baked into the template. E2B fixes sandbox size at build time (its create API takes no resource field), so this is the only way to size an E2B sandbox. Its API types this as an integer with a minimum of 1, so fractional CPU is not expressible. None uses DEFAULT_SANDBOX_CPU_COUNT. Ignored by OpenSandbox/Bedrock, which size sandboxes at creation instead.
memory_mb	int | None	E2B-only — template memory in MiB (despite the name, E2B's memoryMB is MiB), minimum 128. None uses DEFAULT_SANDBOX_MEMORY_MB. Ignored by OpenSandbox/Bedrock.
base_template	str | None	DEPRECATED — use image. Legacy base to build from (E2B base alias / OpenSandbox base image). Kept for backward compatibility; will be removed.
dockerfile	str | None	DEPRECATED — use image. Legacy Dockerfile path/content (honored by E2B, ignored by OpenSandbox). Kept for backward compatibility; will be removed.
force_rebuild	bool	Rebuild even if the template already exists.