Skip to content

Variables and Resolution

Jump to bottom
Valerio edited this page Aug 12, 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 and negative prompt 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.

Positive and negative prompt

Both bodies of text take part in resolution with one shared variable set:

  • Placeholders is the union of the placeholders found in Content and in NegativePrompt, deduplicated and sorted;
  • MissingVariables is the union of the unresolved names across both texts;
  • ResolvedNegativePrompt is null when the prompt has no negative prompt, and never an empty string.

A single value therefore applies consistently to both texts: {{style}} in the positive prompt and in the negative prompt resolve to the same value in one call.

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