# flow\.sdk.models

#### TaskSpec

Complete task specification - the core IR model.

**Fields:**

* **api\_version** (`Literal`): IR schema version (default: `flow.ir/v1`)
* **name** (`str`): Task name
* **command** (`list`): Command to execute
* **resources** (`ResourceSpec`): Resource requirements
* **mounts** (`list`): Volume mounts
* **params** (`RunParams`): Runtime parameters

#### ResourceSpec

Hardware resource requirements.

**Fields:**

* **gpus** (`int`): Number of GPUs required (default: `0`)
* **gpu\_type** (`str | None`): GPU type (e.g., 'H100-80GB')
* **cpus** (`int`): Number of CPUs required (default: `4`)
* **memory\_gb** (`int`): Memory in GB (default: `16`)
* **accelerator\_hints** (`dict`): Hints for accelerator configuration (MIG, NVLink, SXM/PCIe, compute capability)

#### MountSpec

Volume mount specification.

**Fields:**

* **kind** (`Literal`): Type of mount
* **source** (`str`): Source path or URI
* **target** (`str`): Target mount path in container
* **read\_only** (`bool`): Whether mount is read-only (default: `True`)
* **cache** (`dict[str, str] | None`): Cache configuration for remote mounts

#### RunParams

Runtime parameters for task execution.

**Fields:**

* **env** (`dict`): Environment variables
* **working\_dir** (`str | None`): Working directory
* **retry** (`int`): Number of retries on failure (default: `0`)
* **preemptible\_ok** (`bool`): Allow preemptible instances (default: `False`)
* **time\_limit\_s** (`int | None`): Time limit in seconds
* **image** (`str | None`): Container image to use

#### TaskStatus

Task lifecycle states.

**Values:**

* **PENDING** = `"pending"`
* **RUNNING** = `"running"`
* **PAUSED** = `"paused"`
* **PREEMPTING** = `"preempting"`
* **COMPLETED** = `"completed"`
* **FAILED** = `"failed"`
* **CANCELLED** = `"cancelled"`

#### InstanceStatus

Status of a compute instance.

**Values:**

* **PENDING** = `"pending"`
* **RUNNING** = `"running"`
* **STOPPED** = `"stopped"`
* **TERMINATED** = `"terminated"`

#### ReservationStatus

Reservation lifecycle states.

**Values:**

* **SCHEDULED** = `"scheduled"`
* **ACTIVE** = `"active"`
* **EXPIRED** = `"expired"`
* **FAILED** = `"failed"`

#### StorageInterface

Storage interface type.

**Values:**

* **BLOCK** = `"block"`
* **FILE** = `"file"`

#### Retries

Retry policy with fixed or exponential backoff.

**Fields:**

* **max\_retries** (`int`): Maximum retry attempts (0-10) (default: `3`)
* **backoff\_coefficient** (`float`): Delay multiplier between retries (default: `2.0`)
* **initial\_delay** (`float`): Initial delay in seconds before first retry (default: `1.0`)
* **max\_delay** (`float | None`): Maximum delay between retries (seconds)

**Retries.get\_delay**

```python
get_delay(self, attempt: int) -> float
```

Calculate delay for a given retry attempt.

**Parameters:**

* **attempt**: Retry attempt number (1-based)

**Returns:**

Delay in seconds before this retry attempt

**Retries.validate\_delays**

```python
validate_delays(self) -> Retries
```

Ensure max\_delay is greater than initial\_delay if set.

#### Task

Task handle with lifecycle control (status, logs, wait, cancel, ssh).

**Fields:**

* **task\_id** (`str`): Task UUID
* **name** (`str`): Human-readable name
* **status** (`TaskStatus`): Execution state
* **config** (`flow.sdk.models.task_config.TaskConfig | None`): Original configuration
* **created\_at** (`datetime`)
* **started\_at** (`datetime.datetime | None`)
* **completed\_at** (`datetime.datetime | None`)
* **instance\_created\_at** (`datetime.datetime | None`): Creation time of current instance (for preempted/restarted tasks)
* **instance\_type** (`str`)
* **num\_instances** (`int`)
* **region** (`str`)
* **cost\_per\_hour** (`str`): Hourly cost
* **total\_cost** (`str | None`): Accumulated cost
* **created\_by** (`str | None`): Creator user ID
* **ssh\_host** (`str | None`): SSH endpoint
* **ssh\_port** (`int | None`): SSH port (default: `22`)
* **ssh\_user** (`str`): SSH user (default: `ubuntu`)
* **shell\_command** (`str | None`): Complete shell command
* **endpoints** (`dict`): Exposed service URLs
* **instances** (`list`): Instance identifiers
* **message** (`str | None`): Human-readable status
* **provider\_metadata** (`dict`): Provider-specific state and metadata (e.g., Mithril bid status, preemption reasons)

**Task.cancel**

```python
cancel(self) -> None
```

**Task.get\_instances**

```python
get_instances(self) -> list[Instance]
```

**Task.get\_user**

```python
get_user(self) -> Any | None
```

**Task.logs**

```python
logs(
    self,
    follow: bool = False,
    tail: int = 100,
    stderr: bool = False,
    source: str | None = None,
    stream: str | None = None
) -> str | Iterator[str]
```

**Task.refresh**

```python
refresh(self) -> None
```

**Task.result**

```python
result(self) -> Any
```

**Task.shell**

```python
shell(
    self,
    command: str | None = None,
    node: int | None = None,
    progress_context = None,
    record: bool = False
) -> None
```

**Task.stop**

```python
stop(self) -> None
```

**Task.wait**

```python
wait(self, timeout: int | None = None) -> None
```

#### TaskConfig

Complete task specification used by `Flow.run()`.

One obvious way to express requirements; fails fast with clear validation.

**Fields:**

* **name** (`str`): Task identifier (default: `flow-task`)
* **unique\_name** (`bool`): Append unique suffix to name to ensure uniqueness (default: `True`)
* **instance\_type** (`str | None`): Explicit instance type
* **min\_gpu\_memory\_gb** (`int | None`): Minimum GPU memory requirement
* **command** (`str | list[str] | None`): Command to execute when the task starts. Supports three formats: list format (recommended for precise control), single-line string (shell execution), or multi-line script (for complex workflows). Multi-line commands or scripts starting with shebang (#!) are automatically detected and executed as shell scripts. If not specified, defaults to 'sleep infinity' for interactive sessions.

  **Examples:**

  * `['python', 'train.py', '--epochs', '10']`
  * `'python train.py --epochs 10'`
  * Multi-line script:

    ```python

    #!/bin/bash

    pip install -r requirements.txt

    python train.py

    python evaluate.py

    ```
  * `'nvidia-smi'`
* **image** (`str`): Container image (default: `nvidia/cuda:12.1.0-runtime-ubuntu22.04`)
* **env** (`dict`): Environment
* **working\_dir** (`str`): Container working directory (default: `/workspace`)
* **volumes** (`list`)
* **data\_mounts** (`list`): Data to mount
* **ports** (`list`): Container/instance ports to expose. High ports only (>=1024).
* **allow\_docker\_cache** (`bool`): Allow mounting a volume at /var/lib/docker to persist Docker image layers. Single-node tasks only; use with caution. (default: `False`)
* **retries** (`flow.sdk.models.retry.Retries | None`): Advanced retry configuration for task submission/execution
* **max\_price\_per\_hour** (`float | None`): Maximum hourly price (USD)
* **max\_run\_time\_hours** (`float | None`): Maximum runtime hours; 0 or None disables runtime monitoring
* **min\_run\_time\_hours** (`float | None`): Minimum guaranteed runtime hours
* **deadline\_hours** (`float | None`): Hours from submission until deadline
* **ssh\_keys** (`list`): Authorized SSH key IDs
* **allocation\_mode** (`Literal`): Allocation strategy: 'spot' (default, preemptible), 'reserved' (scheduled capacity), or 'auto'. (default: `spot`)
* **reservation\_id** (`str | None`): Target an existing reservation (advanced).
* **scheduled\_start\_time** (`str | None`): When allocation\_mode='reserved', schedule start (UTC).
* **reserved\_duration\_hours** (`int | None`): When allocation\_mode='reserved', reservation duration in hours (3-336).
* **region** (`str | None`): Target region
* **num\_instances** (`int`): Instance count (default: `1`)
* **priority** (`Literal`): Task priority tier affecting limit price (default: `med`)
* **distributed\_mode** (`Optional`): Distributed rendezvous mode when num\_instances > 1: 'auto' lets Flow assign rank and leader IP; 'manual' expects user-set FLOW\_\* envs.
* **internode\_interconnect** (`str | None`): Preferred inter-node network (e.g., InfiniBand, IB\_3200, Ethernet)
* **intranode\_interconnect** (`str | None`): Preferred intra-node interconnect (e.g., SXM5, PCIe)
* **upload\_code** (`bool`): Upload current directory code to job (default: `True`)
* **dev\_vm** (`bool | None`): Hint: this task is a developer VM. When True, provider background code uploads are disabled and Docker startup adapts accordingly. If None, falls back to FLOW\_DEV\_VM env.
* **upload\_strategy** (`Literal`): Strategy for uploading code to instances:
  * auto: Use SCP for large (>8KB), embedded for small
  * embedded: Include in startup script (10KB limit)
  * scp: Transfer after instance starts (no size limit)
  * none: No code upload (default: `auto`)
* **terminate\_on\_exit** (`bool`): When true, a watcher cancels the task as soon as the main container exits. (default: `False`)
* **upload\_timeout** (`int`): Maximum seconds to wait for code upload (60-3600) (default: `600`)
* **code\_root** (`str | pathlib._local.Path | None`): Local project directory to upload when upload\_code=True. Defaults to the current working directory when not set.

**TaskConfig.to\_spec**

```python
to_spec(self)
```

Convert TaskConfig into canonical IR TaskSpec.

Keep mapping minimal and user-facing config simple. Code is modeled as a first-class mount in IR when `upload_code=True`, without extra env flags or strategy knobs. Providers decide delivery details.

**TaskConfig.to\_yaml**

```python
to_yaml(self, path: str | Path) -> None
```

**TaskConfig.validate\_config**

```python
validate_config(self) -> TaskConfig
```

#### VolumeSpec

Persistent volume specification (create or attach).

**Fields:**

* **name** (`str | None`): Human-readable name (3-64 chars, lowercase alphanumeric with hyphens)
* **size\_gb** (`int`): Size in GB (default: `1`)
* **mount\_path** (`str | None`): Mount path in container (default: /volumes/)
* **volume\_id** (`str | None`): ID of existing volume to attach
* **interface** (`StorageInterface`): Storage interface type (default: `StorageInterface.BLOCK`)
* **iops** (`int | None`): Provisioned IOPS
* **throughput\_mb\_s** (`int | None`): Provisioned throughput

**VolumeSpec.validate\_volume\_spec**

```python
validate_volume_spec(self) -> VolumeSpec
```

Validate volume specification.

#### MountSpec

Mount specification for volumes, S3, or bind mounts.

**Fields:**

* **source** (`str`): Source URL or path
* **target** (`str`): Mount path in container
* **mount\_type** (`Literal`): Type of mount (default: `bind`)
* **options** (`dict`): Provider-specific options
* **cache\_key** (`str | None`): Key for caching mount metadata
* **size\_estimate\_gb** (`float | None`): Estimated size for planning

#### GPUSpec

Immutable GPU hardware specification used for matching.

**Fields:**

* **vendor** (`str`): GPU vendor (default: `NVIDIA`)
* **model** (`str`): GPU model (e.g., A100, H100)
* **memory\_gb** (`int`): GPU memory in GB
* **memory\_type** (`str`): Memory type (HBM2e, HBM3, GDDR6) (default: \`\`)
* **architecture** (`str`): GPU architecture (Ampere, Hopper) (default: \`\`)
* **compute\_capability** (`tuple`): CUDA compute capability (default: `(0, 0)`)
* **tflops\_fp32** (`float`): FP32 performance in TFLOPS (default: `0.0`)
* **tflops\_fp16** (`float`): FP16 performance in TFLOPS (default: `0.0`)
* **memory\_bandwidth\_gb\_s** (`float`): Memory bandwidth in GB/s (default: `0.0`)

#### CPUSpec

CPU specification.

**Fields:**

* **vendor** (`str`): CPU vendor (default: `Intel`)
* **model** (`str`): CPU model (default: `Xeon`)
* **cores** (`int`): Number of CPU cores
* **threads** (`int`): Number of threads (0 = same as cores) (default: `0`)
* **base\_clock\_ghz** (`float`): Base clock speed in GHz (default: `0.0`)

**CPUSpec.set\_threads\_default**

```python
set_threads_default(self) -> CPUSpec
```

Default `threads` to `cores` when not specified.

#### MemorySpec

System memory specification.

**Fields:**

* **size\_gb** (`int`): Memory size in GB
* **type** (`str`): Memory type (default: `DDR4`)
* **speed\_mhz** (`int`): Memory speed in MHz (default: `3200`)
* **ecc** (`bool`): ECC memory support (default: `True`)

#### StorageSpec

Storage specification.

**Fields:**

* **size\_gb** (`int`): Storage size in GB
* **type** (`str`): Storage type (NVMe, SSD, HDD) (default: `NVMe`)
* **iops** (`int | None`): IOPS rating
* **bandwidth\_mb\_s** (`int | None`): Bandwidth in MB/s

#### NetworkSpec

Network specification.

**Fields:**

* **intranode** (`str`): Intra-node interconnect (SXM4, SXM5, PCIe) (default: \`\`)
* **internode** (`str | None`): Inter-node network (InfiniBand, Ethernet)
* **bandwidth\_gbps** (`float | None`): Network bandwidth in Gbps

#### InstanceType

Canonical instance type specification (immutable).

**Fields:**

* **gpu** (`GPUSpec`)
* **gpu\_count** (`int`): Number of GPUs
* **cpu** (`CPUSpec`)
* **memory** (`MemorySpec`)
* **storage** (`StorageSpec`)
* **network** (`NetworkSpec`)
* **id** (`uuid.UUID | None`): Unique instance type ID
* **aliases** (`set`): Alternative names
* **created\_at** (`datetime`)
* **version** (`int`) (default: `1`)

**InstanceType.compute\_id\_and\_aliases**

```python
compute_id_and_aliases(self) -> InstanceType
```

Compute a stable ID and default aliases.

#### InstanceMatch

Matched instance with price and availability.

**Fields:**

* **instance** (`InstanceType`)
* **region** (`str`)
* **availability** (`int`): Number of available instances
* **price\_per\_hour** (`float`): Price in USD per hour
* **match\_score** (`float`): Match quality score (default: `1.0`)

#### Instance

Compute instance entity.

**Fields:**

* **instance\_id** (`str`): Instance UUID
* **task\_id** (`str`): Parent task ID
* **status** (`InstanceStatus`): Instance state
* **ssh\_host** (`str | None`): Public hostname/IP
* **private\_ip** (`str | None`): VPC-internal IP
* **created\_at** (`datetime`)
* **terminated\_at** (`datetime.datetime | None`)

#### AvailableInstance

Available compute resource.

**Fields:**

* **allocation\_id** (`str`): Resource allocation ID
* **instance\_type** (`str`): Instance type identifier
* **region** (`str`): Availability region
* **price\_per\_hour** (`float`): Hourly price (USD)
* **gpu\_type** (`str | None`): GPU type
* **gpu\_count** (`int | None`): Number of GPUs
* **cpu\_count** (`int | None`): Number of CPUs
* **memory\_gb** (`int | None`): Memory in GB
* **available\_quantity** (`int | None`): Number available
* **status** (`str | None`): Allocation status
* **expires\_at** (`datetime.datetime | None`): Expiration time
* **internode\_interconnect** (`str | None`): Inter-node network (e.g., InfiniBand, IB\_3200, Ethernet)
* **intranode\_interconnect** (`str | None`): Intra-node interconnect (e.g., SXM5, PCIe)

#### Reservation

Reservation details returned by providers.

**Fields:**

* **reservation\_id** (`str`): Reservation identifier
* **name** (`str | None`): Display name
* **status** (`ReservationStatus`): Lifecycle state
* **instance\_type** (`str`): Instance type identifier
* **region** (`str`): Region/zone
* **quantity** (`int`): Number of instances
* **start\_time\_utc** (`datetime`): Scheduled start time (UTC)
* **end\_time\_utc** (`datetime.datetime | None`): Scheduled end time (UTC)
* **price\_total\_usd** (`float | None`): Quoted/actual total price
* **provider\_metadata** (`dict`)

#### ReservationSpec

Provider-agnostic spec for creating a reservation.

**Fields:**

* **name** (`str | None`): Optional reservation name for display
* **project\_id** (`str | None`): Provider project/workspace ID
* **instance\_type** (`str`): Explicit instance type (e.g., 'a100', '8xh100')
* **region** (`str`): Target region/zone for the reservation
* **quantity** (`int`): Number of instances to reserve (default: `1`)
* **start\_time\_utc** (`datetime`): Reservation start time (UTC)
* **duration\_hours** (`int`): Reservation duration in hours (3-336)
* **ssh\_keys** (`list`): Authorized SSH key IDs
* **volumes** (`list`): Volume IDs to attach (provider-specific)
* **startup\_script** (`str | None`): Optional startup script executed when instances boot

#### FlowConfig

Flow SDK configuration settings.

Immutable configuration for API authentication and default behaviors. Typically loaded from environment variables or config files.

**Fields:**

* **api\_key** (`str`): Authentication key
* **project** (`str`): Project identifier
* **region** (`str`): Default deployment region (default: `us-central1-b`)
* **api\_url** (`str`): API base URL (default: `https://api.mithril.ai`)

#### Project

Project metadata.

**Fields:**

* **name** (`str`): Project identifier
* **region** (`str`): Primary region

#### ValidationResult

Configuration validation result.

**Fields:**

* **is\_valid** (`bool`): Validation status
* **projects** (`list`): Accessible projects
* **error\_message** (`str | None`): Validation error

#### SubmitTaskRequest

Task submission request.

**Fields:**

* **config** (`TaskConfig`): Task specification
* **wait** (`bool`): Block until complete (default: `False`)
* **dry\_run** (`bool`): Validation only (default: `False`)

#### SubmitTaskResponse

Task submission result.

**Fields:**

* **task\_id** (`str`): Assigned task ID
* **status** (`TaskStatus`): Initial state
* **message** (`str | None`): Status details

#### ListTasksRequest

Task listing request.

**Fields:**

* **status** (`flow.sdk.models.enums.TaskStatus | None`): Status filter
* **limit** (`int`): Page size (default: `100`)
* **offset** (`int`): Skip count (default: `0`)

#### ListTasksResponse

Task listing result.

**Fields:**

* **tasks** (`list`): Task collection
* **total** (`int`): Total available
* **has\_more** (`bool`): Pagination indicator

#### User

User identity information.

**Fields:**

* **user\_id** (`str`): Unique user identifier (e.g., 'user\_kfV4CCaapLiqCNlv')
* **username** (`str`): Username for display
* **email** (`str`): User email address

#### Volume

Backwards-compatible alias to the canonical Volume model.

Kept for import stability of the legacy Volume class while delegating to the real implementation in the volume module, which supports both persistent volumes and bind mounts (local/remote/read\_only).

**Fields:**

* **local** (`str | None`): Source path on host
* **remote** (`str | None`): Target path in container
* **read\_only** (`bool | None`): Mount read-only
* **volume\_id** (`str | None`): Volume ID
* **name** (`str | None`): Volume name
* **size\_gb** (`int | None`): Capacity (GB)
* **region** (`str | None`): Storage region
* **interface** (`flow.sdk.models.enums.StorageInterface | None`): Storage interface type
* **attached\_to** (`list`): Attached instance IDs
* **created\_at** (`Any | None`): Creation timestamp


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mithril.ai/flow-cli-and-sdk/sdk-research-preview/flow.sdk.models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.