> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baytos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Versioning

> Manage and track prompt versions with Claro's version control system

# 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:

<Tabs>
  <Tab title="Prompt Metadata">
    **The Prompt Record**

    * Title, description, and slug
    * Ownership and privacy settings
    * Pointer to published version
    * Workspace or user namespace
  </Tab>

  <Tab title="Version Content">
    **Version Records**

    * Actual prompt content
    * Version number (v1, v2, v3...)
    * Status (draft, published, archived)
    * Creation timestamp and author
  </Tab>
</Tabs>

### Version States

Each prompt version exists in one of three states:

<CardGroup cols={3}>
  <Card title="Draft" icon="pencil">
    **Work in Progress**

    * Not publicly visible
    * Can be edited freely
    * Only visible to prompt owner
  </Card>

  <Card title="Published" icon="circle-check">
    **Live Version**

    * Publicly accessible
    * Returned by API calls
    * Immutable once published
  </Card>

  <Card title="Archived" icon="box-archive">
    **Historical Version**

    * Preserved for reference
    * Accessible in version history
    * Can be restored if needed
  </Card>
</CardGroup>

## 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:

<Tabs>
  <Tab title="Major Versions">
    **v1 → v2 → v3**

    Use 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)
    ```
  </Tab>

  <Tab title="Minor Versions">
    **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
    ```
  </Tab>

  <Tab title="Patch Updates">
    **Small fixes** (use description to note)

    Use for minor fixes:

    * Typo corrections
    * Small clarifications
    * Formatting improvements

    **Example:**

    ```
    v3: (description: "Fixed typo in example")
    ```
  </Tab>
</Tabs>

## Creating New Versions

### Initial Prompt Creation

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

<Steps>
  <Step title="Create Prompt">
    Click **New Prompt** in the Claro dashboard
  </Step>

  <Step title="Add Content">
    Fill in the prompt details:

    * Title and description
    * Main prompt content
    * Tags and category
  </Step>

  <Step title="Publish">
    Click **Publish** - this creates and publishes v1 automatically
  </Step>
</Steps>

### Creating Subsequent Versions

<Steps>
  <Step title="Navigate to Prompt">
    Open the prompt you want to update in the Claro dashboard
  </Step>

  <Step title="Create Draft">
    Click **Edit** or **New Version** to create a draft of the next version
  </Step>

  <Step title="Make Changes">
    Edit the prompt content, critique prompt, or metadata as needed
  </Step>

  <Step title="Preview">
    Test your changes before publishing. See how the new version performs.
  </Step>

  <Step title="Publish Version">
    When satisfied, click **Publish** to make the new version live
  </Step>
</Steps>

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

## Working with Drafts

### Draft Workflow

Drafts allow safe experimentation without affecting production:

```typescript theme={null}
// 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

<Tip>
  Use descriptive notes in draft descriptions to remember what you're testing in each version.
</Tip>

### Draft Best Practices

<AccordionGroup>
  <Accordion title="Test Before Publishing" icon="flask">
    Always test draft versions before publishing:

    * Use the preview feature
    * Test with real inputs
    * Compare outputs with current version
    * Get feedback from team members
  </Accordion>

  <Accordion title="Document Changes" icon="file-lines">
    Keep clear notes about what changed:

    ```
    v2 Draft Notes:
    - Added examples for edge cases
    - Improved tone for international users
    - Enhanced error handling instructions
    ```
  </Accordion>

  <Accordion title="Clean Up Old Drafts" icon="broom">
    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
  </Accordion>
</AccordionGroup>

## Version Comparison

### Viewing Version History

Access complete version history in the dashboard:

<Steps>
  <Step title="Open Prompt">
    Navigate to any prompt in the Claro dashboard
  </Step>

  <Step title="View Versions">
    Click **Version History** to see all versions
  </Step>

  <Step title="Compare Versions">
    Select two versions to see a side-by-side comparison
  </Step>
</Steps>

### 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:

* <span style={{color: '#22c55e', fontWeight: 'bold'}}>+ Added content</span>
* <span style={{color: '#ef4444', fontWeight: 'bold'}}>- Removed content</span>
* <span style={{color: '#3b82f6', fontWeight: 'bold'}}>\~ Modified sections</span>

## Rolling Back Changes

### Restoring Previous Versions

If a new version causes issues, you can rollback:

<Steps>
  <Step title="View Version History">
    Open the prompt and click **Version History**
  </Step>

  <Step title="Select Version">
    Find the version you want to restore
  </Step>

  <Step title="Restore as New Version">
    Click **Restore** to create a new draft based on the old version
  </Step>

  <Step title="Publish">
    Review the restored version and publish when ready
  </Step>
</Steps>

<Warning>
  Restoring a version creates a new version number. This preserves the complete history and prevents confusion about what's current.
</Warning>

### Emergency Rollback

For critical issues with published versions:

1. **Immediate fix**: Restore previous version and publish immediately
2. **Notify users**: If using API, inform integration teams of the rollback
3. **Document issue**: Add notes about why the rollback was necessary
4. **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:

```python theme={null}
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:

<Tabs>
  <Tab title="Development">
    ```python theme={null}
    # Development: Use latest for testing
    prompt = client.get_prompt("@workspace/support:latest")
    ```

    In development, using `:latest` helps you test new versions automatically.
  </Tab>

  <Tab title="Staging">
    ```python theme={null}
    # Staging: Test specific new versions
    prompt = client.get_prompt("@workspace/support:v2")
    ```

    In staging, pin to specific versions to validate before production.
  </Tab>

  <Tab title="Production">
    ```python theme={null}
    # 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.
  </Tab>
</Tabs>

### Version Migration Strategy

When updating versions in production:

<Steps>
  <Step title="Test New Version">
    Thoroughly test v2 in development and staging
  </Step>

  <Step title="Gradual Rollout">
    Deploy to a small percentage of users first:

    ```python theme={null}
    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}")
    ```
  </Step>

  <Step title="Monitor Performance">
    Track metrics for both versions:

    * Response quality
    * Error rates
    * User satisfaction
  </Step>

  <Step title="Full Rollout">
    Once v2 is validated, update all code to use v2
  </Step>
</Steps>

## Version Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Version Notes" icon="note-sticky">
    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
    ```
  </Accordion>

  <Accordion title="Test Major Changes Thoroughly" icon="vial">
    Before publishing breaking changes:

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

    See the [Testing guide](/guides/testing) for comprehensive testing strategies.
  </Accordion>

  <Accordion title="Maintain Version Compatibility" icon="puzzle-piece">
    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).
  </Accordion>

  <Accordion title="Keep Important Versions Archived" icon="archive">
    Don't delete historical versions:

    * They provide rollback safety
    * They document prompt evolution
    * They help understand what worked/didn't work
  </Accordion>

  <Accordion title="Coordinate with Team" icon="users">
    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](/guides/workspace-collaboration) for team workflows.
  </Accordion>
</AccordionGroup>

## 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

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

### A/B Testing Versions

Compare versions in production:

```python theme={null}
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](/guides/testing) 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Workspace Collaboration" icon="users" href="/guides/workspace-collaboration">
    Learn how to manage versions in team environments
  </Card>

  <Card title="Testing Strategies" icon="flask" href="/guides/testing">
    Test prompt versions before deploying to production
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python/prompts">
    Access specific prompt versions programmatically
  </Card>

  <Card title="Performance Guide" icon="gauge" href="/guides/performance">
    Optimize version fetching and caching
  </Card>
</CardGroup>