Prompt Versioning

Bayt OS, The Collaborative Intelligence platform, provides a powerful version control system for AI prompts, enabling safe editing, complete history tracking, and collaborative workflows.

Understanding Versions

Claro uses a two-tier versioning architecture:

Prompt Metadata
Version Content

The Prompt Record

Title, description, and slug
Ownership and privacy settings
Pointer to published version
Workspace or user namespace

Version States

Each prompt version exists in one of three states:

Draft

Work in Progress

Not publicly visible
Can be edited freely
Only visible to prompt owner

Published

Live Version

Publicly accessible
Returned by API calls
Immutable once published

Archived

Historical Version

Preserved for reference
Accessible in version history
Can be restored if needed

Semantic Versioning for Prompts

Claro uses semantic versioning to help teams understand the impact of changes:

v1.0.0 → v1.1.0 → v2.0.0
 │        │        │
 │        │        └─ Major: Breaking changes to prompt behavior
 │        └─ Minor: New features or significant improvements
 └─ Patch: Bug fixes or minor tweaks (implied)

Version Naming Convention

While Claro uses simple version numbers (v1, v2, v3), teams should adopt semantic meaning:

Major Versions
Minor Versions
Patch Updates

v1 → v2 → v3Use for breaking changes:

Complete prompt rewrites
Changed input/output format
Different LLM requirements
New response structure

Example:

v1: Customer support prompt for chat
v2: Customer support prompt for email (different format)

v1 → v1.1 → v1.2 (represented as v1, v2, v3 in Claro)Use for improvements:

Enhanced instructions
Better example outputs
Additional context
Improved tone or style

Example:

v1: Basic code review prompt
v2: Code review with security focus
v3: Code review with security + performance focus

Small fixes (use description to note)Use for minor fixes:

Typo corrections
Small clarifications
Formatting improvements

Example:

v3: (description: "Fixed typo in example")

Creating New Versions

Initial Prompt Creation

When you create a new prompt, Claro automatically creates v1:

Create Prompt

Click New Prompt in the Claro dashboard

Add Content

Fill in the prompt details:

Title and description
Main prompt content
Tags and category

Publish

Click Publish - this creates and publishes v1 automatically

Creating Subsequent Versions

Navigate to Prompt

Open the prompt you want to update in the Claro dashboard

Create Draft

Click Edit or New Version to create a draft of the next version

Make Changes

Edit the prompt content, critique prompt, or metadata as needed

Preview

Test your changes before publishing. See how the new version performs.

Publish Version

When satisfied, click Publish to make the new version live

Publishing a new version automatically archives the previous published version. The old version remains accessible in version history but is no longer the default.

Working with Drafts

Draft Workflow

Drafts allow safe experimentation without affecting production:

// Production continues to use published version
const prompt = client.get_prompt("@workspace/support:v1");

// Meanwhile, you're working on v2 as a draft
// Drafts are only visible in the dashboard to the owner

Multiple Drafts

You can maintain multiple draft versions:

Work on incremental improvements (draft v2)
Experiment with major rewrites (draft v3)
Test different approaches simultaneously

Use descriptive notes in draft descriptions to remember what you’re testing in each version.

Draft Best Practices

Test Before Publishing

Always test draft versions before publishing:

Use the preview feature
Test with real inputs
Compare outputs with current version
Get feedback from team members

Document Changes

Keep clear notes about what changed:

v2 Draft Notes:
- Added examples for edge cases
- Improved tone for international users
- Enhanced error handling instructions

Clean Up Old Drafts

Delete abandoned drafts to keep version history clean:

Remove experimental versions that didn’t work
Consolidate similar drafts
Keep only active work-in-progress versions

Version Comparison

Viewing Version History

Access complete version history in the dashboard:

Open Prompt

Navigate to any prompt in the Claro dashboard

View Versions

Click Version History to see all versions

Compare Versions

Select two versions to see a side-by-side comparison

What Gets Compared

The comparison view shows differences in:

Prompt content - Main instruction text
Critique prompt - Feedback instructions
Tags - Categorization changes
Metadata - Description and settings updates

Visual Diff

The comparison interface highlights:

+ Added content
- Removed content
~ Modified sections

Rolling Back Changes

Restoring Previous Versions

If a new version causes issues, you can rollback:

View Version History

Open the prompt and click Version History

Select Version

Find the version you want to restore

Restore as New Version

Click Restore to create a new draft based on the old version

Publish

Review the restored version and publish when ready

Restoring a version creates a new version number. This preserves the complete history and prevents confusion about what’s current.

Emergency Rollback

For critical issues with published versions:

Immediate fix: Restore previous version and publish immediately
Notify users: If using API, inform integration teams of the rollback
Document issue: Add notes about why the rollback was necessary
Fix and republish: Address the issue in a new draft and test thoroughly

Versioning in API Calls

Specifying Versions

Always specify versions in API calls for consistency:

from baytos.claro import BaytClient

client = BaytClient(api_key="your_api_key")

# Best practice: Specify exact version
prompt_v1 = client.get_prompt("@workspace/support:v1")
prompt_v2 = client.get_prompt("@workspace/support:v2")

# Avoid: Using 'latest' in production
prompt_latest = client.get_prompt("@workspace/support:latest")  # Not recommended for prod

Version Pinning

Pin versions in production for stability:

Development
Staging
Production

# Development: Use latest for testing
prompt = client.get_prompt("@workspace/support:latest")

In development, using :latest helps you test new versions automatically.

# Staging: Test specific new versions
prompt = client.get_prompt("@workspace/support:v2")

In staging, pin to specific versions to validate before production.

# Production: Pin to tested version
prompt = client.get_prompt("@workspace/support:v1")

# Update version only after validation
# prompt = client.get_prompt("@workspace/support:v2")

In production, never use :latest. Always pin to a validated version.

Version Migration Strategy

When updating versions in production:

Test New Version

Thoroughly test v2 in development and staging

Gradual Rollout

Deploy to a small percentage of users first:

import random

# 10% of traffic gets new version
version = "v2" if random.random() < 0.1 else "v1"
prompt = client.get_prompt(f"@workspace/support:{version}")

Monitor Performance

Track metrics for both versions:

Response quality
Error rates
User satisfaction

Full Rollout

Once v2 is validated, update all code to use v2

Version Best Practices

Use Descriptive Version Notes

Document what changed in each version:Good description:

v2: Enhanced customer support prompt with:
- Added empathy phrases for frustrated customers
- Improved product knowledge examples
- Updated escalation criteria

Bad description:

v2: Updated prompt

Test Major Changes Thoroughly

Before publishing breaking changes:

Test with diverse inputs
Get team feedback
Run A/B tests if possible
Document expected differences

See the Testing guide for comprehensive testing strategies.

Maintain Version Compatibility

When possible, keep versions backward compatible:

Don’t change expected output format drastically
Add new features rather than removing old ones
Document compatibility clearly

If breaking changes are necessary, increment major version (v1 → v2).

Keep Important Versions Archived

Don’t delete historical versions:

They provide rollback safety
They document prompt evolution
They help understand what worked/didn’t work

Coordinate with Team

For workspace prompts:

Notify team before publishing major versions
Allow review period for significant changes
Update documentation when versions change
Communicate version deprecation plans

See the Workspace Collaboration guide for team workflows.

Version Analytics

Tracking Version Performance

Monitor how different versions perform:

Usage metrics - Which versions are used most
Success rates - Error rates by version
User feedback - Ratings and feedback per version
Performance - Response times and quality

Version analytics are available on Team and Enterprise plans. Use these insights to make data-driven versioning decisions.

A/B Testing Versions

Compare versions in production:

import random
from baytos.claro import BaytClient

client = BaytClient(api_key="your_api_key")

def get_prompt_for_testing(user_id: str):
    """Consistently assign users to version for A/B test"""
    # Hash user ID to get consistent assignment
    version = "v2" if hash(user_id) % 2 == 0 else "v1"

    return client.get_prompt(f"@workspace/support:{version}")

# Track metrics per version to compare

See the Testing guide for comprehensive A/B testing strategies.

Common Versioning Patterns

Progressive Enhancement

Start simple, add features incrementally:

v1: Basic customer support prompt
v2: Add product-specific knowledge
v3: Add multilingual support
v4: Add sentiment analysis

Specialized Versions

Create versions for different use cases:

v1: General customer support
v2: Technical support specific
v3: Sales inquiry specific
v4: Billing inquiry specific

Quality Iterations

Continuously improve based on feedback:

v1: Initial draft
v2: Incorporate user feedback
v3: Add edge case handling
v4: Optimize for performance

Troubleshooting

Can't publish draft version

Common causes:

Missing required fields
Validation errors in content
Permissions issue (workspace prompts)

Solution: Check the error message for specific validation failures. Ensure all required fields are filled.

API returns old version after publishing

Common causes:

Caching delay (up to 60 seconds)
Still requesting old version explicitly
Client-side caching

Solution: Wait 1-2 minutes for cache to clear, or verify you’re requesting the correct version.

Lost draft changes

Common causes:

Navigated away without saving
Browser crash or connection issue
Simultaneous editing from multiple tabs

Solution: Claro auto-saves drafts every 30 seconds. If you lose changes, check draft versions in version history.

Version history not showing all versions

Common causes:

Filtering by status (e.g., only showing published)
Permissions issue with workspace prompts

Solution: Clear any filters in version history view. Ensure you have permission to view all versions.

Next Steps

Workspace Collaboration

Learn how to manage versions in team environments

Testing Strategies

Test prompt versions before deploying to production

Python SDK

Access specific prompt versions programmatically

Performance Guide

Optimize version fetching and caching

Getting Started

Python SDK

Examples

Guides

​Prompt Versioning

​Understanding Versions

​Version States

Draft

Published

Archived

​Semantic Versioning for Prompts

​Version Naming Convention

​Creating New Versions

​Initial Prompt Creation

​Creating Subsequent Versions

​Working with Drafts

​Draft Workflow

​Multiple Drafts

​Draft Best Practices

​Version Comparison

​Viewing Version History

​What Gets Compared

​Visual Diff

​Rolling Back Changes

​Restoring Previous Versions

​Emergency Rollback

​Versioning in API Calls

​Specifying Versions

​Version Pinning

​Version Migration Strategy

​Version Best Practices

​Version Analytics

​Tracking Version Performance

​A/B Testing Versions

​Common Versioning Patterns

​Progressive Enhancement

​Specialized Versions

​Quality Iterations

​Troubleshooting

​Next Steps

Workspace Collaboration

Testing Strategies

Python SDK

Performance Guide

Prompt Versioning

Understanding Versions

Version States

Semantic Versioning for Prompts

Version Naming Convention

Creating New Versions

Initial Prompt Creation

Creating Subsequent Versions

Working with Drafts

Draft Workflow

Multiple Drafts

Draft Best Practices

Version Comparison

Viewing Version History

What Gets Compared

Visual Diff

Rolling Back Changes

Restoring Previous Versions

Emergency Rollback

Versioning in API Calls

Specifying Versions

Version Pinning

Version Migration Strategy

Version Best Practices

Version Analytics

Tracking Version Performance

A/B Testing Versions

Common Versioning Patterns

Progressive Enhancement

Specialized Versions

Quality Iterations

Troubleshooting

Next Steps