Execution contracts - Nebius Token Factory documentation

See Customize the SDK for hook ordering, ownership, and implementation obligations. RunRequest describes one command. Executor contracts let adapters use a custom backend. Public command values and execution contracts for integrations.

`class RunRequest`

class contree_sdk.execution.RunRequest(*, command, shell, args, env, cwd, stdin, stdin_open, files, timeout, disposable, truncate_output_at, preserve_env, hostname, uid, gid, resources_limits, networking)

Command configuration passed through the session’s public extension hooks. Use dataclasses.replace to change a request. Arguments and environment are copied at construction. File sources and stdin remain caller-owned. Exactly one of command and shell must be supplied. Results are saved by default; use disposable=True to leave session history unchanged.

Attributes

str | None

tuple[str, ...]

Mapping[str, str] | None

str | None

bool

float | timedelta | None

bool

int | None

bool

str | None

int | None

InstanceResourcesLimits | None

InstanceNetworking | None

str

float | None

`class OperationContext`

class contree_sdk.execution.OperationContext(request, session_id, image_uuid, parent_id, branch, files, attachments, detached, node_id, created_at, position_version, session_cwd, session_env)

The effective request and history position captured before remote execution.

Attributes

RunRequest

RunRequest

str

str | None

tuple[str, ...]

tuple[StagedFile, ...]

tuple[StagedFile, …]

bool

str

float

int

str | None

Mapping[str, str]

`class SyncExecutor`

class contree_sdk.execution.SyncExecutor()

Execution and file access required by synchronous framework adapters. Implementations own their lifecycle. Adapters do not close executors. Successful execution returns the client’s InstanceResult, including nonzero exit codes. read_file returns exact bytes or raises a client API exception.

Attributes

str

Methods

`execute()`

@abstractmethod
def execute(request) -> InstanceResult

required

InstanceResult

`read_file()`

@abstractmethod
def read_file(path) -> bytes

required

bytes

`write_file()`

def write_file(path, content) -> None

Write bytes to an absolute path, creating its parent directories.Returns after the write is applied to the executor’s filesystem. It does not merely stage a file or upload a blob. Persistence follows execute(). The default runs mkdir and cat through execute() with binary stdin. Override this method to use another file-transfer mechanism. An override must coordinate with the executor’s commands and snapshot lifecycle.Invalid paths raise ValueError; a failed write raises FileWriteError. Transport errors, timeouts, and cancellation propagate unchanged.

required

None

`class AsyncExecutor`

class contree_sdk.execution.AsyncExecutor()

Native asynchronous execution and file access for framework adapters.

Attributes

str

Methods

`execute()`

def execute(request) -> InstanceResult

required

InstanceResult

`read_file()`

def read_file(path) -> bytes

required

bytes

`write_file()`

async def write_file(path, content) -> None

Write bytes with the same contract as SyncExecutor.write_file.The default awaits execute() with binary stdin. Override with native async file transfer, coordinating with commands and snapshot lifecycle. Returns after application, not after staging or blob upload. Invalid paths raise ValueError; a failed write raises FileWriteError. Transport errors, timeouts, and cancellation propagate unchanged.

required

None

Public lifecycle contracts for operation and subprocess implementations.

`class SubprocessContract`

class contree_sdk.session.contracts.SubprocessContract()

Waitable event stream for one subprocess. Iteration and wait share completion state.

Attributes

int

Methods

`wait()`

@abstractmethod
def wait(*, timeout) -> InstanceResult

default:"None"

InstanceResult

`pipe_to()`

@abstractmethod
def pipe_to(*, stdout, stderr) -> InstanceResult

default:"None"

InstanceResult

`class AsyncSubprocessContract`

class contree_sdk.session.contracts.AsyncSubprocessContract()

Waitable event stream for one subprocess. Iteration and wait share completion state.

Attributes

int

Methods

`wait()`

def wait(*, timeout) -> InstanceResult

default:"None"

InstanceResult

`pipe_to()`

def pipe_to(*, stdout, stderr) -> InstanceResult

default:"None"

InstanceResult

`class OperationContract`

class contree_sdk.session.contracts.OperationContract()

An operation lifecycle. wait stores response before returning; cleanup preserves primary errors.

Attributes

str

OperationContext | None

OperationContext | None

OperationResponse | None

Methods

`add_observer()`

def add_observer(observer) -> None

Register an observer before starting the shared operation reader.A None event marks EOF, with an optional stream error. Observers must not consume events or wait for this operation. Implementations without this optional facility reject registration.

required

None

`events()`

@abstractmethod
def events(*, since, spid, timeout) -> Iterator[OperationEvent]

default:"None"

Iterator[OperationEvent]

`status()`

@abstractmethod
def status(*, inflight) -> OperationResponse

default:"False"

OperationResponse

`send_stdin()`

@abstractmethod
def send_stdin(data, *, spid, close) -> None

required

default:"1"

default:"True"

None

`pipe_stdin()`

@abstractmethod
def pipe_stdin(chunks, *, spid, close, chunk_size) -> StdinResult

required

default:"1"

default:"True"

default:"65536"

StdinResult

StdinResult

`signal()`

@abstractmethod
def signal(sig, *, spid) -> None

default:"None"

default:"1"

None

`cancel()`

@abstractmethod
def cancel() -> None

None

`wait()`

@abstractmethod
def wait(*, timeout) -> InstanceResult

default:"None"

InstanceResult

`run()`

@abstractmethod
def run(command, *, shell, args, env, cwd, uid, gid, stdin, stdin_open, truncate_output_at) -> SubprocessContract

required

default:"False"

default:"()"

default:"None"

default:"False"

default:"None"

SubprocessContract

SubprocessContract

`shutdown()`

@abstractmethod
def shutdown() -> None

None

`class AsyncOperationContract`

class contree_sdk.session.contracts.AsyncOperationContract()

An operation lifecycle. wait stores response before returning; cleanup preserves primary errors.

Attributes

str

OperationContext | None

OperationContext | None

OperationResponse | None

Methods

`add_observer()`

def add_observer(observer) -> None

required

None

`events()`

@abstractmethod
def events(*, since, spid, timeout) -> AsyncIterator[OperationEvent]

default:"None"

AsyncIterator[OperationEvent]

`status()`

def status(*, inflight) -> OperationResponse

default:"False"

OperationResponse

`send_stdin()`

def send_stdin(data, *, spid, close) -> None

required

default:"1"

default:"True"

None

`pipe_stdin()`

def pipe_stdin(chunks, *, spid, close, chunk_size) -> StdinResult

required

default:"1"

default:"True"

default:"65536"

StdinResult

StdinResult

`signal()`

def signal(sig, *, spid) -> None

default:"None"

default:"1"

None

`cancel()`

def cancel() -> None

None

`wait()`

def wait(*, timeout) -> InstanceResult

default:"None"

InstanceResult

`run()`

def run(command, *, shell, args, env, cwd, uid, gid, stdin, stdin_open, truncate_output_at) -> AsyncSubprocessContract

required

default:"False"

default:"()"

default:"None"

default:"False"

default:"None"

AsyncSubprocessContract

AsyncSubprocessContract

`shutdown()`

def shutdown() -> None

None

​class RunRequest

​Attributes

​class OperationContext

​Attributes

​class SyncExecutor

​Attributes

​Methods

​execute()

​read_file()

​write_file()

​class AsyncExecutor

​Attributes

​Methods

​execute()

​read_file()

​write_file()

​class SubprocessContract

​Attributes

​Methods

​wait()

​pipe_to()

​class AsyncSubprocessContract

​Attributes

​Methods

​wait()

​pipe_to()

​class OperationContract

​Attributes

​Methods

​add_observer()

​events()

​status()

​send_stdin()

​pipe_stdin()

​signal()

​cancel()

​wait()

​run()

​shutdown()

​class AsyncOperationContract

​Attributes

​Methods

​add_observer()

​events()

​status()

​send_stdin()

​pipe_stdin()

​signal()

​cancel()

​wait()

​run()

​shutdown()

`class RunRequest`

Attributes

`class OperationContext`

Attributes

`class SyncExecutor`

Attributes

Methods

`execute()`

`read_file()`

`write_file()`

`class AsyncExecutor`

Attributes

Methods

`execute()`

`read_file()`

`write_file()`

`class SubprocessContract`

Attributes

Methods

`wait()`

`pipe_to()`

`class AsyncSubprocessContract`

Attributes

Methods

`wait()`

`pipe_to()`

`class OperationContract`

Attributes

Methods

`add_observer()`

`events()`

`status()`

`send_stdin()`

`pipe_stdin()`

`signal()`

`cancel()`

`wait()`

`run()`

`shutdown()`

`class AsyncOperationContract`

Attributes

Methods

`add_observer()`

`events()`

`status()`

`send_stdin()`

`pipe_stdin()`

`signal()`

`cancel()`

`wait()`

`run()`

`shutdown()`