> ## 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.

```typescript theme={null}
interface PromptVariable {
  name: string;
  modality: VariableModality;
}
```

**Properties**:

* `name` - Variable name (used as `{{variable_name}}` in prompts)
* `modality` - Variable modality type ([VariableModality](#variablemodality))

**Example**:

```typescript theme={null}
import type { PromptVariable } from '@adaline/api';

const variables: PromptVariable[] = [
  { name: 'user_name', modality: 'text' },
  { name: 'company_name', modality: 'text' },
  { name: 'company_logo', modality: 'image' },
  { name: 'report', modality: 'pdf' },
  { name: 'external_data', modality: 'api' },
  { name: 'nested_prompt', modality: '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/typescript/types/VariableModality) page for full documentation.

Variable modality type enumeration.

```typescript theme={null}
type VariableModality = 'text' | 'image' | 'pdf' | 'api' | 'prompt';
```

**Values**:

* `'text'` - Plain text content
* `'image'` - Image content (URL or base64)
* `'pdf'` - PDF document content
* `'api'` - External API data source
* `'prompt'` - Nested prompt reference

**Example**:

```typescript theme={null}
import type { VariableModality } from '@adaline/api';

const modality: VariableModality = 'text';
```

***

## VariableValue

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

Variable value type, discriminated by `modality`. Used when providing values for prompt variables.

```typescript theme={null}
type VariableValue =
  | TextContent
  | ImageContent
  | PdfContent
  | ApiContent
  | PromptContent;
```

**Example**:

```typescript theme={null}
import type { VariableValue } from '@adaline/api';

// Text value
const textValue: VariableValue = {
  modality: 'text',
  value: 'John Doe'
};

// Image value
const imageValue: VariableValue = {
  modality: 'image',
  detail: 'auto',
  value: {
    type: 'url',
    url: 'https://example.com/logo.png'
  }
};

// PDF value
const pdfValue: VariableValue = {
  modality: 'pdf',
  value: {
    type: 'url',
    url: 'https://example.com/docs.pdf'
  },
  file: {
    name: 'user_guide.pdf',
    id: 'file_123'
  }
};
```

***

## Using with Deployments

```typescript theme={null}
import { Adaline } from '@adaline/client';
import type { Deployment, PromptVariable } from '@adaline/api';

const adaline = new Adaline();

const deployment: Deployment = await adaline.getLatestDeployment({
  promptId: 'prompt_abc123',
  deploymentEnvironmentId: 'environment_abc123'
});

// Access variable definitions from the deployment
const variables: PromptVariable[] = deployment.prompt.variables;

variables.forEach(v => {
  console.log(`Variable: ${v.name}, Modality: ${v.modality}`);
});
```

***

## 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

```typescript theme={null}
import { Adaline } from '@adaline/client';

const adaline = new Adaline();

const deployment = await adaline.getLatestDeployment({
  promptId: 'prompt_abc123',
  deploymentEnvironmentId: 'environment_abc123'
});

const variables = {
  user_name: 'Alice',
  company_name: 'Acme Corp',
};

// Replace placeholders in text content across every message
const messages = deployment.prompt.messages.map((msg) => ({
  ...msg,
  content: msg.content.map((c) => {
    if (c.modality !== 'text') return c;
    return {
      ...c,
      value: c.value.replace(/\{\{(\w+)\}\}/g, (match, name) => {
        return typeof variables[name] === 'string' ? variables[name] : match;
      }),
    };
  }),
}));
```

### 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` item:

```typescript theme={null}
import type { ImageContent, MessageContent, PdfContent } from '@adaline/api';

const assets: Record<string, ImageContent | PdfContent> = {
  profile_pic: {
    modality: 'image',
    detail: 'auto',
    value: { type: 'url', url: 'https://example.com/alice.png' },
  },
  report: {
    modality: 'pdf',
    value: { type: 'url', url: 'https://example.com/report.pdf' },
    file: { name: 'report.pdf', id: 'file_abc123' },
  },
};

const messages = deployment.prompt.messages.map((msg) => ({
  ...msg,
  content: msg.content.flatMap<MessageContent>((c) => {
    if (c.modality !== 'text') return [c];
    const match = c.value.trim().match(/^\{\{(\w+)\}\}$/);
    if (match && assets[match[1]]) return [assets[match[1]]];
    return [c];
  }),
}));
```

<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>