> ## Documentation Index
> Fetch the complete documentation index at: https://www.adaline.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PromptVariable

# PromptVariable

Types for prompt variables with modality definitions.

## Overview

Variable types define dynamic content that can be injected into prompts, with support for multiple modalities.

***

## PromptVariable

Prompt variable with name and modality.

```python theme={null}
from adaline_api.models.prompt_variable import PromptVariable
```

### Fields

<ParamField body="name" type="str" required>
  The variable name as it appears in the prompt template (used as `{{variable_name}}` in prompts).
</ParamField>

<ParamField body="modality" type="VariableModality" required>
  The variable modality type. See [VariableModality](#variablemodality).
</ParamField>

### Example

```python theme={null}
from adaline_api.models.prompt_variable import PromptVariable
from adaline_api.models.variable_modality import VariableModality

variables: list[PromptVariable] = [
    PromptVariable(name="user_name", modality=VariableModality.TEXT),
    PromptVariable(name="company_name", modality=VariableModality.TEXT),
    PromptVariable(name="company_logo", modality=VariableModality.IMAGE),
    PromptVariable(name="report", modality=VariableModality.PDF),
    PromptVariable(name="external_data", modality=VariableModality.API),
    PromptVariable(name="nested_prompt", modality=VariableModality.PROMPT),
]
```

**JSON**:

```json theme={null}
[
  { "name": "user_name", "modality": "text" },
  { "name": "company_name", "modality": "text" },
  { "name": "company_logo", "modality": "image" },
  { "name": "report", "modality": "pdf" }
]
```

***

## VariableModality

See the dedicated [VariableModality](/docs/reference/sdk/v2/python/types/VariableModality) page for full documentation.

Variable modality type enumeration.

```python theme={null}
from adaline_api.models.variable_modality import VariableModality
```

`VariableModality` is a `str` enum with the following values:

| Value      | Enum Member               | Description                   |
| ---------- | ------------------------- | ----------------------------- |
| `"text"`   | `VariableModality.TEXT`   | Plain text content            |
| `"image"`  | `VariableModality.IMAGE`  | Image content (URL or base64) |
| `"pdf"`    | `VariableModality.PDF`    | PDF document content          |
| `"api"`    | `VariableModality.API`    | External API data source      |
| `"prompt"` | `VariableModality.PROMPT` | Nested prompt reference       |

### Example

```python theme={null}
from adaline_api.models.variable_modality import VariableModality

modality = VariableModality.TEXT       # 'text'
modality = VariableModality.IMAGE      # 'image'

# String comparison works
assert VariableModality.TEXT == "text"
```

***

## Using with Deployments

```python theme={null}
from adaline.main import Adaline
from adaline_api.models.prompt_variable import PromptVariable

adaline = Adaline()

deployment = await adaline.get_latest_deployment(
    prompt_id="prompt_abc123",
    deployment_environment_id="environment_abc123"
)

# Access variable definitions from the deployment
variables: list[PromptVariable] = deployment.prompt.variables

for v in variables:
    print(f"Variable: {v.name}, Modality: {v.modality}")
    # e.g. "Variable: user_name, Modality: text"
```

***

## Replacing variables at runtime

The SDK returns deployments with `{{variable_name}}` placeholders intact — substitute them yourself before sending the prompt to your AI provider.

### Text variables

```python theme={null}
import re
from adaline.main import Adaline

adaline = Adaline()

deployment = await adaline.get_latest_deployment(
    prompt_id="prompt_abc123",
    deployment_environment_id="environment_abc123",
)

variables = {
    "user_name": "Alice",
    "company_name": "Acme Corp",
}

# Replace placeholders in text content across every message
pattern = re.compile(r"\{\{(\w+)\}\}")
for message in deployment.prompt.messages:
    for content in message.content:
        if content.modality == "text":
            content.value = pattern.sub(
                lambda m: str(variables.get(m.group(1), m.group(0))),
                content.value,
            )
```

### Image and PDF variables

For non-text variables, replace a text content item whose entire value is `{{variable_name}}` with the corresponding `ImageContent` or `PdfContent`:

```python theme={null}
from adaline_api.models.image_content import ImageContent
from adaline_api.models.image_content_value import ImageContentValue
from adaline_api.models.url_image_content_value import UrlImageContentValue
from adaline_api.models.pdf_content import PdfContent
from adaline_api.models.pdf_content_value import PdfContentValue
from adaline_api.models.url_pdf_content_value import UrlPdfContentValue
from adaline_api.models.pdf_content_file import PdfContentFile

assets = {
    "profile_pic": ImageContent(
        modality="image",
        detail="auto",
        value=ImageContentValue(
            actual_instance=UrlImageContentValue(
                type="url", url="https://example.com/alice.png"
            )
        ),
    ),
    "report": PdfContent(
        modality="pdf",
        value=PdfContentValue(
            actual_instance=UrlPdfContentValue(
                type="url", url="https://example.com/report.pdf"
            )
        ),
        file=PdfContentFile(name="report.pdf", id="file_abc123"),
    ),
}

for message in deployment.prompt.messages:
    new_content = []
    for c in message.content:
        if c.modality == "text":
            stripped = c.value.strip()
            if stripped.startswith("{{") and stripped.endswith("}}"):
                name = stripped[2:-2]
                if name in assets:
                    new_content.append(assets[name])
                    continue
        new_content.append(c)
    message.content = new_content
```

<Note>
  Image and PDF variables can only replace a text content item whose **entire** value is `{{variable_name}}`. A placeholder embedded in larger text (e.g., `"See: {{pic}}"`) cannot be swapped for a binary modality.
</Note>