Store and track versions of prompts

Retrieve and manage versions of your prompts for LLM applications

After creating and publishing prompts, you can reference, retrieve, and use specific versions in code and in production.

When you publish a prompt with weave.publish, W&B Weave creates an immutable version. Each version can be referenced by name and version, retrieved in code with weave.ref(...).get(), and viewed in the Weave UI.

Prompt versions

Prompts in Weave are stored as versioned objects. This allows you to safely iterate on prompts while ensuring that evaluations, experiments, and production systems can reference the exact prompt version they were run with.

Prompt versions are accessed using Weave object references. This page explains how prompt versions are created, how to retrieve a specific version in code, and how to inspect and compare versions in the Weave UI.

How prompt versions are created

Weave automatically tracks every version of your prompts, creating a complete history of how your prompts evolve. This versioning system is crucial for prompt engineering workflows, allowing you to experiment safely, track what changes improved or hurt performance, and easily roll back to previous versions if needed. Each time you publish a prompt with the same name but different content, Weave creates a new version while preserving all previous versions.

Each version is immutable. Once created, the contents of that version cannot be changed. If you update a prompt and publish it again, Weave creates a new version while preserving previous versions.

Versioning enables you to:

• Reproduce past experiments.
• Safely iterate on prompt changes.
• Roll out prompt updates in a controlled way.

Construct a fully qualified ref URI

Weave objects can be uniquely identified using a fully qualified ref URI.

A fully qualified Weave object ref URI looks like this:

weave:///<your-team-name>/<your-project-name>/object/<object_name>:<object_version>

• your-team-name: W&B entity (username or team name)
• your-project-name: W&B project
• object_name: object name
• object_version: either a version hash, a string like v0 or v1, or an alias like :latest. All objects have the :latest alias.

For example, a fully qualified Weave prompt URI looks like this:

weave:///your-team-name/your-project-name/object/support_prompt:v3

Retrieve a prompt version in code

To retrieve a prompt, create a reference to its name and version, then call .get() to load it. A ref points to a stored object; .get() fetches that object so you can use it in your application.

You can construct refs with a few different styles:

• weave.ref(<name>): Retrieves the :latest version of a prompt. Requires calling weave.init(...).
• weave.ref(<name>:<version>): Retrieves the specified version of a prompt. Requires calling weave.init(...).
• weave.ref(<fully_qualified_ref_uri>): Retrieves the prompt located at the specified fully qualified ref URI. Does not require calling weave.init.

The following example loads the support_prompt:v3 version so you can use it in your application:

import weave

weave.init("your-team-name/your-project-name")

prompt = weave.ref("support_prompt:v3").get()

Use prompt versions in production

When deploying prompts in production systems, pin a specific prompt version rather than referencing the latest version. In your production application, load that version with weave.ref(<name>:<version>).get().

Pinning a version ensures that production behavior remains stable even if new prompt versions are published later.

A common workflow looks like this:

1. Develop and test a new prompt version.
2. Evaluate the new prompt against datasets or evaluation suites.
3. Update the production system to reference the new version.

This approach allows teams to safely iterate on prompts without unexpectedly changing production behavior.

View and compare prompt versions

To view versions of the prompt in the UI:

1. Navigate to wandb.ai and select your project.
2. In the Weave project sidebar, click Assets. This opens the Assets page.
3. In the Assets page, click Prompts. This opens the Prompts page where your project’s prompts are listed.
4. Under the Versions column, click (x) Versions for the prompt you want to view. This opens a list of prompt versions.

5. (Optional) You can compare versions of prompts by clicking the checkboxes beside the listed prompts and then clicking the Compare button in the table toolbar. This allows you to see the diff between your prompts.

Prompt tags and aliases

You can organize prompt versions using aliases and tags. These labels help identify and reference specific versions.

• Aliases are named pointers to a specific prompt version.
• Tags are labels applied to a specific prompt version.

To set aliases and tags for your prompts in the UI:

1. In the Weave project sidebar, click Assets. This opens the Assets page.
2. In the Assets page, click Prompts. Note that you can view assigned Aliases and Tags in the table.
3. In the Prompts table, click the link of the prompt you want to change.
4. In the prompt detail panel for your selected prompt, the title bar displays the name of the prompt and a specific version. Choose the version of the prompt you want to update.
5. In the panel toolbar, use the controls to add and remove assigned aliases and tags to this specific version.

Modify tags and aliases in code

Tags and aliases can also be managed in code, such as publishing prompts with tags and aliases inline, pointing aliases at specific versions and resolving them to load prompts, and adding, removing, or listing tags and aliases on versions.

The following code example will add a prompt my-prompt to your project with three versions, each having various tags and aliases. Update 'your-team-name/your-project-name' accordingly for your project.

Python

import weave

client = weave.init('your-team-name/your-project-name')

# Publish two versions of a prompt
v0_ref = weave.publish(
    weave.StringPrompt("Answer the user's question: {question}"),
    name="my-prompt",
)
v1_ref = weave.publish(
    weave.StringPrompt("Answer the user's question helpfully and concisely: {question}"),
    name="my-prompt",
)

# --- Aliases: named pointers to a specific version. ---

# Point aliases at a version.
client.set_aliases(v0_ref, "staging")
client.set_aliases(v1_ref, "production")

# Retrieve aliases for a version.
client.get_aliases(v1_ref)  # ["production", "latest"]

# Move an alias by setting it on a different version.
client.set_aliases(v0_ref, "production")  # Automatically detaches from v1.

# Resolve an alias to load the object.
prompt = weave.ref("my-prompt:production").get()

# List all aliases in the project.
client.list_aliases()

# Remove an alias.
client.remove_aliases(v0_ref, "production")

# --- Tags: labels on a specific version. ---

# Add tags to a version.
client.add_tags(v0_ref, ["reviewed", "passed-eval"])
client.add_tags(v1_ref, ["reviewed", "needs-improvement"])

# Get tags for a version.
client.get_tags(v0_ref)  # ["passed-eval", "reviewed"]

# List all distinct tags in the project.
client.list_tags()

# Remove tags from a version.
client.remove_tags(v1_ref, ["needs-improvement"])

# --- Combined: fetch both in a single call. ---

tags, aliases = client.get_tags_and_aliases(v0_ref)

# --- Publish with tags and aliases inline. ---

ref = weave.publish(
    weave.StringPrompt("Be brief: {question}"),
    name="my-prompt",
    tags=["reviewed"],
    aliases=["production"],
)

When you run the example, Weave prints links to your objects in the Weave dashboard. Follow the links to see your prompts.