Implementation:Mlflow Mlflow Prompt Version Entity

Knowledge Sources	MLflow MLflow Prompt API
Domains	ML_Ops, Prompt_Engineering
Last Updated	2026-02-13 20:00 GMT

Overview

Concrete tool for representing a versioned prompt template with its metadata, variables, and model configuration, provided by the MLflow library.

Description

The PromptVersion class is the core entity in MLflow's Prompt Registry that encapsulates a specific version of a prompt. It stores the template content (either a plain text string with {{variable}} placeholders or a list of chat message dictionaries), along with version metadata such as name, version number, creation timestamp, commit message, tags, and aliases.

The class automatically detects whether a template is a text prompt or a chat prompt by inspecting the template type at construction time. It extracts variable names from the template using a regular expression pattern. The format() method performs variable substitution, supporting both simple double-brace replacement and full Jinja2 rendering (with optional sandboxing) for templates that use Jinja2 control flow syntax.

The companion PromptModelConfig class (a Pydantic BaseModel) provides a structured, validated container for model inference parameters including provider, model name, temperature, max tokens, top-p, top-k, frequency penalty, presence penalty, stop sequences, and an extensible extra_params dictionary for provider-specific settings.

Usage

Use PromptVersion whenever you need to work with a specific version of a registered prompt -- for example, after loading a prompt from the registry with mlflow.genai.load_prompt(), or when inspecting the result of mlflow.genai.register_prompt(). Use PromptModelConfig when you need to attach validated model settings to a prompt version during registration or after the fact.

Code Reference

Source Location

• Repository: mlflow
• File: mlflow/entities/model_registry/prompt_version.py
• Lines: L37-142 (PromptModelConfig), L155-573 (PromptVersion)

Signature

class PromptVersion(_ModelRegistryEntity):
    def __init__(
        self,
        name: str,
        version: int,
        template: str | list[dict[str, Any]],
        commit_message: str | None = None,
        creation_timestamp: int | None = None,
        tags: dict[str, str] | None = None,
        aliases: list[str] | None = None,
        last_updated_timestamp: int | None = None,
        user_id: str | None = None,
        response_format: type[BaseModel] | dict[str, Any] | None = None,
        model_config: PromptModelConfig | dict[str, Any] | None = None,
    ):
        ...

    def format(
        self,
        allow_partial: bool = False,
        use_jinja_sandbox: bool = True,
        **kwargs,
    ) -> PromptVersion | str | list[dict[str, Any]]:
        ...


class PromptModelConfig(BaseModel):
    provider: str | None = None
    model_name: str | None = None
    temperature: float | None = Field(None, ge=0)
    max_tokens: int | None = Field(None, gt=0)
    top_p: float | None = Field(None, ge=0, le=1)
    top_k: int | None = Field(None, gt=0)
    frequency_penalty: float | None = None
    presence_penalty: float | None = None
    stop_sequences: list[str] | None = None
    extra_params: dict[str, Any] = Field(default_factory=dict)

Import

from mlflow.entities.model_registry import PromptVersion
from mlflow.entities.model_registry import PromptModelConfig

I/O Contract

Inputs (PromptVersion constructor)

Name	Type	Required	Description
name	str	Yes	The name of the prompt.
version	int	Yes	The version number of the prompt.
template	list[dict[str, Any]]	Yes	The template content. A string with {{var}} placeholders (text prompt) or a list of dicts with role/content keys (chat prompt).
commit_message	None	No	A message describing the changes made to this version.
creation_timestamp	None	No	Timestamp of creation in milliseconds since the Unix epoch.
tags	None	No	Version-level tags as key-value pairs.
aliases	None	No	List of aliases assigned to this version.
last_updated_timestamp	None	No	Timestamp of last update in milliseconds since the Unix epoch.
user_id	None	No	User ID that created this version.
response_format	dict[str, Any] | None	No	Pydantic class or dict defining expected response structure.
model_config	dict[str, Any] | None	No	Model-specific configuration (provider, temperature, etc.).

Inputs (format method)

Name	Type	Required	Description
allow_partial	bool	No	If True, allow partial formatting when variables are missing. Defaults to False.
use_jinja_sandbox	bool	No	If True, use Jinja2 SandboxedEnvironment for safe rendering. Defaults to True.
**kwargs	Any	No	Variable values to substitute into the template placeholders.

Outputs

Name	Type	Description
PromptVersion (constructor)	PromptVersion	The constructed entity with template, variables, tags, and metadata.
format() result	list[dict[str, Any]] | PromptVersion	For text prompts, a formatted string. For chat prompts, a list of message dicts. If allow_partial is True and variables are missing, a new PromptVersion with partially substituted template.

Key Properties

Property	Type	Description
template	list[dict[str, Any]]	The raw template content.
name	str	The prompt name.
version	int	The version number.
variables	set[str]	Set of variable names extracted from the template.
is_text_prompt	bool	True for text prompts, False for chat prompts.
commit_message	None	The commit message for this version.
tags	dict[str, str]	Version-level tags (excluding reserved internal tags).
aliases	list[str]	Aliases assigned to this version.
uri	str	The URI in the format prompts:/{name}/{version}.
response_format	None	The response format specification.
model_config	None	The model configuration dictionary.
creation_timestamp	int	Creation time in milliseconds since epoch.

Usage Examples

Basic Usage: Text Prompt

from mlflow.entities.model_registry import PromptVersion

# Create a text prompt version
prompt = PromptVersion(
    name="greeting",
    version=1,
    template="Hello, {{title}} {{name}}! Welcome to {{place}}.",
)

# Format with all variables
result = prompt.format(title="Dr", name="Smith", place="MLflow")
# Returns: "Hello, Dr Smith! Welcome to MLflow."

# Check variables
print(prompt.variables)
# Output: {'title', 'name', 'place'}

Chat Prompt with Model Config

from mlflow.entities.model_registry import PromptVersion, PromptModelConfig

config = PromptModelConfig(
    provider="openai",
    model_name="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

chat_prompt = PromptVersion(
    name="assistant",
    version=1,
    template=[
        {"role": "system", "content": "You are a {{style}} assistant."},
        {"role": "user", "content": "{{question}}"},
    ],
    model_config=config,
)

formatted = chat_prompt.format(style="friendly", question="How are you?")
# Returns: [{"role": "system", "content": "You are a friendly assistant."},
#           {"role": "user", "content": "How are you?"}]

Partial Formatting

prompt = PromptVersion("my-prompt", 1, "Hello, {{title}} {{name}}!")
partial = prompt.format(title="Ms", allow_partial=True)
# Returns: PromptVersion with template "Hello, Ms {{name}}!"

# Complete the formatting later
result = partial.format(name="Alice")
# Returns: "Hello, Ms Alice!"

Related Pages

Implements Principle

• Principle:Mlflow_Mlflow_Prompt_Template_Design