# Variables

## Overview

Variables are structured prompts that define persistent variables for agent sessions. Each variable specifies a name, data type, persistence scope, and default value.

Variables are stored as text prompts on the platform. The SDK parses the YAML or JSON content into typed Python objects.

***

## Convenience methods

These methods automatically apply the folder prefix and `type="variable"`, so you don't have to.

## `get_variable` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3632)

Get a variable prompt by name.

Automatically prefixes the name with `variables/` and sets `type="variable"`.

```python
get_variable(
    name: str,
    *,
    version: int | None = None,
    label: str | None = None,
    cache_ttl_seconds: int | None = None,
    fallback: str | None = None,
    max_retries: int | None = None,
    fetch_timeout_seconds: int | None = None,
) -> VariablePromptClient
```

**Parameters**

* `name` — Variable name (without the `variables/` prefix).
* `version` — Optional version number.
* `label` — Optional label filter.
* `cache_ttl_seconds` — Cache TTL override.
* `fallback` — Fallback YAML/JSON content string.
* `max_retries` — Maximum number of retries.
* `fetch_timeout_seconds` — Fetch timeout override.

**Returns**

VariablePromptClient

***

## `create_variable` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3670)

Create a variable prompt.

Automatically prefixes the name with `variables/` and sets `type="variable"`.

```python
create_variable(
    *,
    name: str,
    prompt: str,
    labels: List[str] | None = None,
    tags: List[str] | None = None,
    config: Any | None = None,
    commit_message: str | None = None,
) -> VariablePromptClient
```

**Parameters**

* `name` — Variable name (without the `variables/` prefix).
* `prompt` — JSON content string.
* `labels` — Labels to assign.
* `tags` — Tags to assign.
* `config` — Additional config dict.
* `commit_message` — Optional commit message.

**Returns**

VariablePromptClient

***

## `update_variable` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3705)

Update a variable prompt version.

Automatically sets `type="variable"` and routes through the type-specific endpoint.

```python
update_variable(
    *,
    name: str,
    version: int,
    new_labels: List[str] | None = None,
) -> Any
```

**Parameters**

* `name` — Variable name (without the `variables/` prefix).
* `version` — The version number of the prompt to update.
* `new_labels` — New labels to assign to the prompt version.

**Returns**

The updated prompt from the InteractiveAI API.

***

## `list_variables` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3729)

List variable prompts.

```python
list_variables(
    *,
    label: str | None = None,
    tag: str | None = None,
    page: int | None = None,
    limit: int | None = None,
) -> PromptMetaListResponse
```

**Parameters**

* `label` — Optional label filter.
* `tag` — Optional tag filter.
* `page` — Page number.
* `limit` — Items per page.

**Returns**

PromptMetaListResponse

***

## `delete_variable` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3752)

Delete a variable prompt.

Automatically prefixes the name with `variables/`.

```python
delete_variable(
    name: str,
    *,
    label: str | None = None,
    version: int | None = None,
) -> None
```

**Parameters**

* `name` — Variable name (without the `variables/` prefix).
* `label` — If set, deletes versions carrying this label.
* `version` — If set, deletes only this specific version.

***

## Fetching variables

```python
variables = client.get_variable("session-state")

for v in variables.entries:
    print(v.name, v.type, v.default_value)
```

***

## Creating variables

```python
content = """
{
  "variables": [
    {
      "name": "is_authenticated",
      "type": "boolean",
      "persistence": "customer",
      "default_value": false
    },
    {
      "name": "subscription_plan",
      "type": "string",
      "persistence": "customer",
      "default_value": "guest"
    }
  ]
}
"""

variables = client.create_variable(
    name="session-state",
    prompt=content,
    labels=["production"],
)
```

The SDK validates the YAML structure on create and raises `ValueError` if the content is malformed.

***

## `VariablePromptClient`

Returned by `get_variable()` and `create_variable()`.

**Attributes**

* `name` — Prompt name.
* `version` — Prompt version number.
* `labels` — List of labels (e.g. `["production"]`).
* `tags` — List of tags.
* `config` — Arbitrary config dict stored with the prompt.
* `is_fallback` — `True` if this was returned from a fallback value.
* `raw_content` — The original unparsed text content.
* `entries` — `List[VariableEntry]` (property).

**Methods**

* `compile()` — Returns the parsed `VariablesContent` dataclass. Template variable substitution does not apply to structured prompts.
* `variables` — Always returns an empty list.

***

## `VariableEntry`

Dataclass representing a single variable definition.

| Field           | Type            | Description                                            |
| --------------- | --------------- | ------------------------------------------------------ |
| `name`          | `str`           | Variable name (e.g. `"is_authenticated"`).             |
| `type`          | `str`           | Data type (`"boolean"`, `"string"`, `"number"`, etc.). |
| `persistence`   | `Optional[str]` | Persistence scope (`"customer"`, `"session"`, etc.).   |
| `default_value` | `Any`           | Default value for the variable.                        |

***

## Content format

Variables can be authored in YAML or JSON. JSON is recommended for readability.

```json
{
  "variables": [
    {
      "name": "is_authenticated",
      "type": "boolean",
      "persistence": "customer",
      "default_value": false
    },
    {
      "name": "language",
      "type": "string",
      "persistence": "session",
      "default_value": "en"
    }
  ]
}
```