From 6e3b1444313710a662adf38b6490086aa6a3d4a7 Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Tue, 16 Jun 2026 16:51:26 -0400 Subject: [PATCH 1/4] Adds keywords frontmatter to prompt versioning doc for Weave --- weave/guides/core-types/prompts-version.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/weave/guides/core-types/prompts-version.mdx b/weave/guides/core-types/prompts-version.mdx index 49511d3f76..821e2083ff 100644 --- a/weave/guides/core-types/prompts-version.mdx +++ b/weave/guides/core-types/prompts-version.mdx @@ -1,6 +1,7 @@ --- title: "Store and track versions of prompts" description: "Retrieve and manage versions of your prompts for LLM applications" +keywords: ["prompts", "prompt versions", "prompt tags", "prompt aliases", "tag", "alias","prompt versioning"] --- After [creating and publishing prompts](/weave/guides/core-types/prompts.mdx), you can reference, retrieve, and use specific versions in code and in production. From d96ecc04186d0fdaa8f5630ab7f44911dfabdb52 Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Tue, 16 Jun 2026 17:39:38 -0400 Subject: [PATCH 2/4] Draft of tags and aliases for objects --- weave/guides/tracking/objects.mdx | 98 ++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 2 deletions(-) diff --git a/weave/guides/tracking/objects.mdx b/weave/guides/tracking/objects.mdx index 832671a74a..9ad274c28e 100644 --- a/weave/guides/tracking/objects.mdx +++ b/weave/guides/tracking/objects.mdx @@ -1,7 +1,7 @@ --- title: "Track and version objects" description: "Track and version any JSON-serializable object in W&B Weave" -keywords: ["objects", "versioning", "refs", "weave.publish", "weave.ref"] +keywords: ["objects", "versioning", "refs", "weave.publish", "weave.ref", "tags", "aliases", "object tags", "object aliases", "set_aliases", "add_tags", "production alias", "promote version", "label versions"] --- This page explains how to publish, retrieve, delete, and reference versioned objects in W&B Weave. Use it when you need to track structured data such as datasets, models, or prompts across runs and over time. @@ -116,10 +116,104 @@ weave:///[YOUR-TEAM-NAME]/[YOUR-PROJECT-NAME]/object/[OBJECT-NAME]:[OBJECT-VERSI - `[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. +- `[OBJECT-VERSION]`: either a version hash, a string like `v0` or `v1`, or an alias like `:latest`. All objects have the `:latest` alias. See [Organize object versions with tags and aliases](#organize-object-versions-with-tags-and-aliases) to create your own aliases. You can construct refs with a few different styles: - `weave.ref([NAME])`: retrieves the `:latest` version of an object. Requires calling `weave.init(...)`. - `weave.ref([NAME]:[VERSION])`: retrieves the specified version of an object. Requires calling `weave.init(...)`. - `weave.ref([FULLY-QUALIFIED-REF-URI])`: retrieves the object located at the specified fully qualified object ref URI. Doesn't require calling `weave.init()`. + +## Organize object versions with tags and aliases + +Use **tags** and **aliases** to label specific versions of any Weave object — a `Dataset`, `Model`, `Prompt`, or any object you publish with `weave.publish`. These labels work on any `ObjectRef`, so the same APIs apply across object types. + +- **Alias:** A unique name that resolves to a single version. You can move an alias to a different version at any time, making it useful for stable references like `production` or `staging`. Every object automatically has a `:latest` alias that points to the most recent version. +- **Tag:** A descriptive label attached to a version. A version can have multiple tags, and the same tag can appear on multiple versions. Use tags to categorize and filter versions, such as `reviewed` or `passed-eval`. + +Resolve an alias or specific version by appending it to the object name in a ref: + +```python lines +import weave + +weave.init("your-team-name/your-project-name") + +# Resolve a version by alias. +dataset = weave.ref("test-cases:production").get() + +# Resolve a specific version index. +dataset = weave.ref("test-cases:v2").get() +``` + +### Manage tags and aliases in code + +The following example publishes two versions of a dataset, then assigns and updates tags and aliases on each version. Update `'your-team-name/your-project-name'` to match your project. + + +```python Python lines +import weave + +client = weave.init("your-team-name/your-project-name") + +# Publish two versions of an object. +v0_ref = weave.publish( + weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong"}]), +) +v1_ref = weave.publish( + weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong!"}]), +) + +# --- 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. +dataset = weave.ref("test-cases: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.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong!!"}]), + tags=["reviewed"], + aliases=["production"], +) +``` +```plaintext TypeScript lines +This feature is not available in the TypeScript SDK yet. +``` + + +For a prompt-focused workflow that uses aliases to safely promote new versions to production, see [Store and track versions of prompts](/weave/guides/core-types/prompts-version.mdx#add-prompt-tags-and-aliases). From 12472c69573e916adf880d1b0404b77ec68b6264 Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Wed, 17 Jun 2026 12:24:07 -0400 Subject: [PATCH 3/4] Cleans up first draft --- weave/guides/tracking/objects.mdx | 66 ++++++------------------------- 1 file changed, 12 insertions(+), 54 deletions(-) diff --git a/weave/guides/tracking/objects.mdx b/weave/guides/tracking/objects.mdx index 9ad274c28e..003ce856a1 100644 --- a/weave/guides/tracking/objects.mdx +++ b/weave/guides/tracking/objects.mdx @@ -126,94 +126,52 @@ You can construct refs with a few different styles: ## Organize object versions with tags and aliases -Use **tags** and **aliases** to label specific versions of any Weave object — a `Dataset`, `Model`, `Prompt`, or any object you publish with `weave.publish`. These labels work on any `ObjectRef`, so the same APIs apply across object types. +Use **tags** and **aliases** to label specific versions of any Weave object, including `Dataset`, `Model`, `Prompt`, or any other object you publish with `weave.publish`. These labels work on any `ObjectRef`, so the same APIs apply across object types. - **Alias:** A unique name that resolves to a single version. You can move an alias to a different version at any time, making it useful for stable references like `production` or `staging`. Every object automatically has a `:latest` alias that points to the most recent version. - **Tag:** A descriptive label attached to a version. A version can have multiple tags, and the same tag can appear on multiple versions. Use tags to categorize and filter versions, such as `reviewed` or `passed-eval`. Resolve an alias or specific version by appending it to the object name in a ref: -```python lines -import weave - -weave.init("your-team-name/your-project-name") - -# Resolve a version by alias. -dataset = weave.ref("test-cases:production").get() - -# Resolve a specific version index. -dataset = weave.ref("test-cases:v2").get() -``` - -### Manage tags and aliases in code - -The following example publishes two versions of a dataset, then assigns and updates tags and aliases on each version. Update `'your-team-name/your-project-name'` to match your project. +The following example publishes two versions of a dataset, then assigns and updates tags and aliases on each version. ```python Python lines import weave -client = weave.init("your-team-name/your-project-name") +client = weave.init("[YOUR-TEAM-NAME]/[YOUR-PROJECT-NAME]") # Publish two versions of an object. -v0_ref = weave.publish( +dataset_v0 = weave.publish( weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong"}]), ) -v1_ref = weave.publish( +dataset_v0 = weave.publish( weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong!"}]), ) -# --- Aliases: named pointers to a specific version. --- - -# Point aliases at a version. -client.set_aliases(v0_ref, "staging") -client.set_aliases(v1_ref, "production") +# Set aliases at a version. +client.set_aliases(dataset_v0, "staging") +client.set_aliases(dataset_v1, "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. +# Retrieve an object using its alias dataset = weave.ref("test-cases: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"]) +client.add_tags(dataset_v0, ["reviewed", "passed-eval"]) +client.add_tags(dataset_v1, ["reviewed", "needs-improvement"]) # Get tags for a version. -client.get_tags(v0_ref) # ["passed-eval", "reviewed"] +client.get_tags(dataset_v0) # ["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.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong!!"}]), - tags=["reviewed"], - aliases=["production"], -) ``` ```plaintext TypeScript lines This feature is not available in the TypeScript SDK yet. ``` - -For a prompt-focused workflow that uses aliases to safely promote new versions to production, see [Store and track versions of prompts](/weave/guides/core-types/prompts-version.mdx#add-prompt-tags-and-aliases). From be5b1466cb5a6844df7a33e5b89648421c848b98 Mon Sep 17 00:00:00 2001 From: dbrian57 Date: Wed, 17 Jun 2026 14:08:01 -0400 Subject: [PATCH 4/4] corrections --- weave/guides/tracking/objects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/weave/guides/tracking/objects.mdx b/weave/guides/tracking/objects.mdx index 003ce856a1..e790b444d4 100644 --- a/weave/guides/tracking/objects.mdx +++ b/weave/guides/tracking/objects.mdx @@ -145,7 +145,7 @@ client = weave.init("[YOUR-TEAM-NAME]/[YOUR-PROJECT-NAME]") dataset_v0 = weave.publish( weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong"}]), ) -dataset_v0 = weave.publish( +dataset_v1 = weave.publish( weave.Dataset(name="test-cases", rows=[{"input": "ping", "expected": "pong!"}]), )