Skip to content

Variables and Resolution

Jump to bottom
Valerio edited this page Apr 27, 2026 · 2 revisions

Variables and Resolution

Variables let prompt authors define placeholders once and resolve them differently by scope. This allows teams to share reusable prompt templates without hardcoding every environment, project, or user-specific value.

Core entities

Entity Purpose
VariableDefinition Name, description, data type, scope, and metadata
VariableValue Concrete value for a definition at a specific scope

Secret values are protected by ISecretProtector, implemented by AesSecretProtector in Infrastructure.

Variable scopes

VariableScope defines where a value applies. The service code uses an explicit precedence model instead of relying on enum numeric order.

The current precedence is:

Prompt
  -> Project
  -> Workspace/Tenant
  -> User
  -> System/default

The highest available value wins for each variable name.

Resolution flow

Prompt content with placeholders
  -> PromptResolutionService.ResolveAsync
  -> load applicable variable definitions and values
  -> apply explicit precedence
  -> produce resolved prompt text plus resolution metadata

Resolution is read-only. It does not change the prompt content or create a prompt version.

Secret handling

Secret variable values are encrypted before persistence and decrypted only when needed for resolution. Secret plaintext should not be logged, emitted to telemetry, or returned in management listings unless the user is explicitly resolving content they are allowed to access.

Configuration keys:

Key Purpose
Security:SecretEncryptionKey AES key material used by AesSecretProtector

Management UI

Variable management is exposed through:

The UI should treat variable management as an administrative workflow: listing, creating, editing, and deleting definitions and values are permissioned operations.

Source pointers

Clone this wiki locally