---
sidebar:
  label: roboto.action_runtime.invocation_context
  order: 4
title: roboto.action_runtime.invocation_context
---
## Module Contents

### ActionRuntime

```python
class roboto.action_runtime.invocation_context.ActionRuntime(*args, **kwargs)
```

`from roboto import ActionRuntime`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L482-L491)

Bases: [`InvocationContext`](/reference/python-sdk/roboto/action_runtime/invocation_context#roboto.action_runtime.invocation_context.InvocationContext)

Deprecated. Use InvocationContext instead.

### InvocationContext

```python
class roboto.action_runtime.invocation_context.InvocationContext(
    dataset_id: str,
    input_dir: pathlib.Path,
    invocation_id: str,
    org_id: str,
    output_dir: pathlib.Path,
    input_data_manifest_file: Optional[pathlib.Path] = None,
    parameters_file: Optional[pathlib.Path] = None,
    secrets_file: Optional[pathlib.Path] = None,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
    dry_run: bool = False,
    log_level: Optional[str] = None,
)
```

`from roboto import InvocationContext`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L49-L479)

A utility for performing common lookups and other operations during a Roboto Action's runtime.

The easiest and most common way to initialize this is:

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
```

...which will inspect environment variables to initialize the InvocationContext.

If you want to test a script using InvocationContext in a setting such as a developer machine or unit test, and you don't want to set environment variables to mirror Roboto's remote execution environment, initialize InvocationContext directly:

```python
import pathlib
from roboto import InvocationContext
context = InvocationContext(
    dataset_id="ds_XXXXXXXXXXXX",
    input_dir=pathlib.Path("/path/to/tmp/input/dir"),
    invocation_id="iv_XXXXXXXXXXXX",
    org_id="og_XXXXXXXXXXXX",
    output_dir=pathlib.Path("/path/to/tmp/output/dir"),
)
```

**Parameters**

- **dataset_id** (`str`)
- **input_dir** (`pathlib.Path`)
- **invocation_id** (`str`)
- **org_id** (`str`)
- **output_dir** (`pathlib.Path`)
- **input_data_manifest_file** (`Optional[pathlib.Path]`)
- **parameters_file** (`Optional[pathlib.Path]`)
- **secrets_file** (`Optional[pathlib.Path]`)
- **roboto_client** (`Optional[roboto.http.RobotoClient]`)
- **dry_run** (`bool`)
- **log_level** (`Optional[str]`)

**Properties**

- **InvocationContext.dataset** (`roboto.domain.datasets.Dataset`): A [`Dataset`](/reference/python-sdk/roboto/domain/datasets/dataset#roboto.domain.datasets.dataset.Dataset) instance for the dataset whose data this action is operating on, if any.

  This resource will be lazily initialized the first time it is accessed. After the first call, the dataset will be cached.

  This is particularly useful for adding tags or metadata to a dataset at runtime.

  **Raises**

  - [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): If the dataset does not exist.
  - [`ActionRuntimeException`](/reference/python-sdk/roboto/action_runtime/exceptions#roboto.action_runtime.exceptions.ActionRuntimeException): If the dataset is not specified (e.g., when running locally, using scheduled triggers, or invoking via CLI with query-based input data).

  **Returns**

  - `roboto.domain.datasets.Dataset`

  **Usage**

  Add tags/metadata to the dataset:

  ```python
  context.dataset.put_tags(["tagged_by_action"])
  context.dataset.put_metadata({"voltage_spikes_seen": 693})
  ```

- **InvocationContext.dataset_id** (`str`): The ID of the dataset whose data this action is operating on.

- **InvocationContext.file_changeset_manager** (`roboto.action_runtime.file_changeset.FilesChangesetFileManager`): A [`FilesChangesetFileManager`](/reference/python-sdk/roboto/action_runtime/file_changeset#roboto.action_runtime.file_changeset.FilesChangesetFileManager) which can be used to associate tags and metadata with the yet-to-be-uploaded files in this invocation's output directory. In practice, you might use this like:

  ```python
  from roboto import InvocationContext
  context = InvocationContext.from_env()
  my_output_file = context.output_dir / "my_output_file.txt"
  my_output_file.write_text("Hello World")
  context.file_changeset_manager.put_tags(my_output_file.name, ["tagged_by_action"])
  context.file_changeset_manager.put_fields(
      my_output_file.name, {"roboto_proficiency": "extreme - I can annotate output files!"}
  )
  ```

  This only works for files that have not yet been uploaded to Roboto. To tag existing files, you should instead use:

  ```python
  from roboto import InvocationContext
  context = InvocationContext.from_env()
  existing_file = context.dataset.get_file_by_path("some_file_that_already_exists.txt")
  existing_file.put_tags(["tagged_by_action"])
  existing_file.put_metadata({"roboto_proficiency": "also extreme - I can annotate input files!"})
  ```

  For more info, see the top-level docs on the FilesChangesetFileManager class.

- **InvocationContext.input_dir** (`pathlib.Path`): The directory where the action's input files are located.

- **InvocationContext.invocation** (`roboto.domain.actions.Invocation`): An [`Invocation`](/reference/python-sdk/roboto/domain/actions/invocation#roboto.domain.actions.invocation.Invocation) object for the currently running action invocation.

  This object will be lazy-initialized the first time it is accessed, which might result in a [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException) if the invocation does not exist. After the first call, the invocation will be cached.

- **InvocationContext.invocation_id** (`str`): The ID of the currently running action invocation.

- **InvocationContext.is_dry_run** (`bool`)

- **InvocationContext.log_level** (`int`): The log level for the action invocation.

  **Returns**

  - `int`: The log level constant (e.g., logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR) if set, or logging.INFO if no log level was specified.

  > **Note**
  >
  > This value must be explicitly applied using `logging.getLogger().setLevel()` or similar logging configuration to take effect.

- **InvocationContext.org** (`roboto.domain.orgs.Org`): An [`Org`](/reference/python-sdk/roboto/domain/orgs/org#roboto.domain.orgs.org.Org) object for the org which invoked the currently running action.

  This object will be lazy-initialized the first time it is accessed, which might result in a [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException) if the org does not exist. After the first call, the org will be cached.

- **InvocationContext.org_id** (`str`): The ID of the org which invoked the currently running action.

- **InvocationContext.output_dir** (`pathlib.Path`): The directory where the action's output files are expected. After the user portion of the action runtime concludes (i.e. when their container exits with a 0 exit code), every file in this directory will be uploaded to the dataset associated with this action invocation.

- **InvocationContext.roboto_client** (`roboto.http.RobotoClient`): The [`RobotoClient`](/reference/python-sdk/roboto/http/roboto_client#roboto.http.roboto_client.RobotoClient) instance used by this action runtime.

#### InvocationContext.from_env()

```python
@classmethod
def from_env() -> InvocationContext
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L95-L153)

Initialize an InvocationContext from values in environment variables. Will throw an exception if any required environment variables are not available.

All required environment variables will be available at runtime when an action is running in Roboto's remote execution environment.

**Usage**

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
```

**Returns**

- `InvocationContext`

#### InvocationContext.get_input()

```python
def get_input() -> roboto.action_runtime.action_input.ActionInput
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L351-L377)

Instance of [`ActionInput`](/reference/python-sdk/roboto/action_runtime/action_input/action_input#roboto.action_runtime.action_input.action_input.ActionInput) containing resolved references to input data.

**Returns**

- `roboto.action_runtime.action_input.ActionInput`

#### InvocationContext.get_optional_parameter()

```python
def get_optional_parameter(
    name: str,
    default_value: Optional[str] = None,
) -> Optional[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L379-L414)

Retrieve the value of the action parameter with the given name, defaulting to default_value if the parameter is not set.

**Parameters**

- **name** (`str`): The name of the parameter to retrieve.
- **default_value** (`Optional[str]`): The value to return if the parameter is not set. Defaults to None.

**Returns**

- `Optional[str]`: The parameter value, or default_value if not set. If the value is a secret URI, returns the resolved secret value.

**Usage**

```python
import roboto
context = roboto.InvocationContext.from_env()
context.get_optional_parameter("model_version", "latest")
# "latest"
```

#### InvocationContext.get_parameter()

```python
def get_parameter(name: str) -> str
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L416-L428)

Gets the value of the action parameter with the given name, raising an ActionRuntimeException if the parameter is not set.

**Parameters**

- **name** (`str`)

**Returns**

- `str`

#### InvocationContext.get_secret_parameter()

```python
def get_secret_parameter(name: str) -> str
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L430-L440)

Gets the value of the secret action parameter with the given name.

**Parameters**

- **name** (`str`)

**Returns**

- `str`

### log

```python
roboto.action_runtime.invocation_context.log
```

`from roboto.action_runtime.invocation_context import log`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/invocation_context.py#L30-L30)