Peer & App Versioning

Versioning in Cognipeer AI allows you to maintain multiple iterations of your peers and apps, track changes over time, and easily roll back to previous versions when needed. This feature is essential for development workflows, testing, and maintaining production stability.

Overview

The versioning system provides:

Version Control: Track all changes to peers and apps
Easy Rollback: Restore previous versions instantly
Version Comparison: See what changed between versions
Safe Testing: Test new versions without affecting production
Change History: Complete audit trail of modifications

Key Concepts

Version Structure

Each version contains:

Version {
  versionId: Unique identifier
  number: Sequential version number (v1, v2, v3...)
  timestamp: When version was created
  author: Who created this version
  changes: What was modified
  config: Complete peer/app configuration snapshot
  status: draft, active, archived
  tags: Labels for organization
}

Version States

Draft: Work in progress, not publicly accessible
Active: Currently deployed and serving requests
Archived: Old version, kept for history

Creating Versions

Automatic Versioning

Versions are created automatically when you save major changes:

Triggers:

Prompt modifications
Tool addition/removal
Model changes
Datasource updates
Settings modifications

Example Flow:

1. Edit peer prompt
2. Click "Save"
3. System creates new version (v2)
4. Previous version (v1) archived automatically

Manual Version Creation

Create versions manually for specific checkpoints:

Navigate to peer or app settings
Click "Version History" tab
Click "Create Version"

Add version details:

Version Name: v1.5.0
Description: Added customer feedback analysis
Tags: feature, production-ready

Click "Create"

Version Naming

Use semantic versioning for clarity:

Format: vMAJOR.MINOR.PATCH

MAJOR: Breaking changes (v1 → v2)
MINOR: New features, backward compatible (v1.1 → v1.2)
PATCH: Bug fixes, small tweaks (v1.1.0 → v1.1.1)

Examples:

v1.0.0 - Initial release
v1.1.0 - Added new tool
v1.1.1 - Fixed prompt typo
v2.0.0 - Complete redesign

Managing Versions

Viewing Version History

Access version history:

For Peers:

Peer Detail Page → Version History Tab

For Apps:

App Settings → Version History

Version List Display:

┌─────────────────────────────────────────┐
│ v1.3.0 (Active) - Oct 21, 2025          │
│ Added sentiment analysis                 │
│ By: john@example.com                     │
│ [View] [Compare] [Make Active]           │
├─────────────────────────────────────────┤
│ v1.2.1 - Oct 18, 2025                    │
│ Fixed response formatting                │
│ By: sarah@example.com                    │
│ [View] [Compare] [Restore]               │
├─────────────────────────────────────────┤
│ v1.2.0 - Oct 15, 2025                    │
│ Added new datasource integration         │
│ By: john@example.com                     │
│ [View] [Compare] [Restore]               │
└─────────────────────────────────────────┘

Comparing Versions

Compare any two versions to see changes:

Click "Compare" next to a version
Select second version to compare with
View side-by-side diff

Comparison View:

┌──────────────────┬──────────────────┐
│ v1.2.0           │ v1.3.0           │
├──────────────────┼──────────────────┤
│ Prompt:          │ Prompt:          │
│ "You are a       │ "You are a       │
│  helpful         │  helpful         │
│  assistant"      │  assistant with  │
│                  │  sentiment       │
│                  │  analysis"       │
├──────────────────┼──────────────────┤
│ Tools: [3]       │ Tools: [4]       │
│ - search         │ - search         │
│ - email          │ - email          │
│ - calendar       │ - calendar       │
│                  │ + sentiment      │
├──────────────────┼──────────────────┤
│ Model:           │ Model:           │
│ chatgpt-4o-mini  │ chatgpt-4o-mini  │
└──────────────────┴──────────────────┘

Changes Summary:
+ Added sentiment analysis tool
+ Updated prompt with sentiment instructions

Restoring Previous Versions

Roll back to any previous version:

Find desired version in history
Click "Restore"
Confirm restoration
Previous version becomes new active version

Important: Restoration creates a new version (doesn't delete current):

Before:  v1.0 → v1.1 → v1.2 (active)
Restore: v1.0 → v1.1 → v1.2 → v1.3 (copy of v1.1) (active)

Deleting Versions

Remove unnecessary versions:

Restrictions:

Cannot delete active version
Cannot delete if only version
Requires admin permissions

To Delete:

Select version to delete
Click "Delete"
Confirm (action cannot be undone)

Version Tags & Organization

Tagging Versions

Add tags to organize versions:

Common Tags:

production     - Live production version
staging        - Testing version
experimental   - New features being tested
backup         - Safety backup before major change
release        - Official release version
hotfix         - Emergency bug fix

Adding Tags:

Version Settings → Tags → Add Tag

Using Tags:

Filter by tag: [production] → Shows only production versions

Version Descriptions

Add detailed descriptions:

markdown

## Version 1.3.0 - Customer Feedback Update

### Changes:
- Added sentiment analysis tool
- Updated prompt to request customer satisfaction ratings
- Integrated with Zendesk for ticket creation

### Testing:
- Tested with 50 sample conversations
- Average satisfaction score: 4.5/5
- No regressions detected

### Deployment:
- Deployed to staging: Oct 20, 2025
- Production deployment: Oct 21, 2025

Development Workflows

Feature Development

Workflow:

1. Create draft version for new feature
   v1.2.0 → v1.3.0-draft

2. Develop and test in draft
   - Modify prompt
   - Add tools
   - Configure settings
   - Test thoroughly

3. Mark as production-ready
   v1.3.0-draft → v1.3.0
   Tag: production-ready

4. Deploy to staging
   Test in staging environment
   Tag: staging

5. Deploy to production
   Make active version
   Tag: production

A/B Testing

Test multiple versions simultaneously:

Setup:
├── v1.2.0 (Control) - 50% traffic
└── v1.3.0 (Test) - 50% traffic

Monitor:
├── Response quality
├── User satisfaction
├── Performance metrics
└── Cost per conversation

Decision:
If v1.3.0 performs better:
  → Make v1.3.0 active (100% traffic)
Else:
  → Keep v1.2.0, iterate on v1.4.0

Implementation:

javascript

// Route traffic based on version
const version = Math.random() < 0.5 ? 'v1.2.0' : 'v1.3.0';

const response = await peer.chat({
  message: userMessage,
  version: version
});

Hotfix Process

Quick fixes for production issues:

1. Identify bug in production (v1.3.0)

2. Create hotfix version
   v1.3.0 → v1.3.1
   Tag: hotfix

3. Fix the specific issue
   Minimal changes only

4. Test fix
   Verify bug resolved
   Ensure no new issues

5. Deploy immediately
   Make v1.3.1 active
   Archive v1.3.0

6. Monitor
   Watch for any issues
   Prepare rollback if needed

Version-Specific Features

Testing Versions

Test specific versions before making them active:

Test Endpoint:

javascript

POST /api/v1/peer/:peerId/chat

{
  "message": "Hello!",
  "version": "v1.3.0"  // Test specific version
}

In UI:

Chat Interface → Settings → Version: [v1.3.0 ▼]

Running Evaluations on Versions

Compare version performance:

1. Create evaluation suite
2. Run against v1.2.0
3. Run against v1.3.0
4. Compare results:

   ┌─────────┬──────────┬──────────┐
   │ Metric  │ v1.2.0   │ v1.3.0   │
   ├─────────┼──────────┼──────────┤
   │ Score   │ 85%      │ 92%      │
   │ Speed   │ 1.2s     │ 0.9s     │
   │ Cost    │ $0.015   │ $0.012   │
   └─────────┴──────────┴──────────┘

   Winner: v1.3.0 (better on all metrics)

Version-Specific Analytics

Track metrics per version:

Analytics → Group by Version

Version Performance:
├── v1.3.0: 10,000 requests, 95% satisfaction
├── v1.2.0: 5,000 requests, 88% satisfaction
└── v1.1.0: 2,000 requests, 82% satisfaction

API Reference

List Versions

javascript

GET /api/v1/peer/:peerId/versions

Response:
{
  "versions": [
    {
      "versionId": "ver_123",
      "number": "v1.3.0",
      "timestamp": "2025-10-21T10:00:00Z",
      "author": {
        "id": "user_456",
        "email": "john@example.com"
      },
      "description": "Added sentiment analysis",
      "status": "active",
      "tags": ["production"],
      "changes": [...]
    }
  ]
}

Get Version Details

javascript

GET /api/v1/peer/:peerId/versions/:versionId

Response:
{
  "version": {
    "versionId": "ver_123",
    "number": "v1.3.0",
    "timestamp": "2025-10-21T10:00:00Z",
    "author": {...},
    "description": "Added sentiment analysis",
    "status": "active",
    "tags": ["production"],
    "config": {
      "prompt": "...",
      "tools": [...],
      "model": "chatgpt-4o-mini",
      "settings": {...}
    },
    "changes": [
      {
        "field": "tools",
        "action": "added",
        "value": "sentiment-analysis"
      },
      {
        "field": "prompt",
        "action": "modified",
        "diff": "..."
      }
    ]
  }
}

Create Version

javascript

POST /api/v1/peer/:peerId/versions

Body:
{
  "number": "v1.4.0",
  "description": "Major update with new features",
  "tags": ["production-ready"],
  "config": {
    // Complete peer configuration
  }
}

Response:
{
  "versionId": "ver_124",
  "number": "v1.4.0",
  "timestamp": "2025-10-21T15:30:00Z",
  "status": "draft"
}

Restore Version

javascript

POST /api/v1/peer/:peerId/versions/:versionId/restore

Response:
{
  "newVersionId": "ver_125",
  "number": "v1.5.0",
  "restoredFrom": "v1.2.0",
  "status": "active"
}

Compare Versions

javascript

GET /api/v1/peer/:peerId/versions/compare?v1=ver_123&v2=ver_124

Response:
{
  "version1": "v1.2.0",
  "version2": "v1.3.0",
  "differences": [
    {
      "field": "prompt",
      "type": "modified",
      "oldValue": "...",
      "newValue": "..."
    },
    {
      "field": "tools",
      "type": "added",
      "value": "sentiment-analysis"
    }
  ]
}

Best Practices

Version Management

✅ Do:

Create versions before major changes
Use semantic versioning
Add descriptive version notes
Tag production versions
Test before making active

❌ Avoid:

Skipping version creation for "small" changes
Vague version descriptions
Making untested versions active
Deleting important version history

Development Process

✅ Do:

Work in draft versions
Test thoroughly before release
Compare with previous versions
Monitor after deployment
Keep backup versions

❌ Avoid:

Editing production version directly
Deploying without testing
Ignoring version comparison
Removing all old versions

Documentation

✅ Do:

Document what changed
Explain why changes were made
List any breaking changes
Include test results
Update team on new versions

❌ Avoid:

Empty version descriptions
Missing change logs
Undocumented breaking changes
No testing notes

Troubleshooting

Version Not Appearing

Problem: Created version but can't see it

Solutions:

Refresh page
Check filters (might be filtering it out)
Verify permissions
Check version status (might be draft)

Can't Restore Version

Problem: Restore button disabled

Solutions:

Verify you have edit permissions
Check if version is corrupted
Try creating new version from old config
Contact support if issue persists

Version Comparison Showing No Changes

Problem: Comparison shows identical when they're different

Solutions:

Verify you selected different versions
Check if changes are in fields not displayed
Try detailed comparison view
Clear browser cache

Evaluation System - Test versions
Peer Settings - Configure peers
AI Analysis - Optimize versions

Start versioning today! Create your first version and maintain better control over your peers and apps.

Peer & App Versioning ​

Overview ​

Key Concepts ​

Version Structure ​

Version States ​

Creating Versions ​

Automatic Versioning ​

Manual Version Creation ​

Version Naming ​

Managing Versions ​

Viewing Version History ​

Comparing Versions ​

Restoring Previous Versions ​

Deleting Versions ​

Version Tags & Organization ​

Tagging Versions ​

Version Descriptions ​

Development Workflows ​

Feature Development ​

A/B Testing ​

Hotfix Process ​

Version-Specific Features ​

Testing Versions ​

Running Evaluations on Versions ​

Version-Specific Analytics ​

API Reference ​

List Versions ​

Get Version Details ​

Create Version ​

Restore Version ​

Compare Versions ​

Best Practices ​

Version Management ​

Development Process ​

Documentation ​

Troubleshooting ​

Version Not Appearing ​

Can't Restore Version ​

Version Comparison Showing No Changes ​

Related Features ​

Peer & App Versioning

Overview

Key Concepts

Version Structure

Version States

Creating Versions

Automatic Versioning

Manual Version Creation

Version Naming

Managing Versions

Viewing Version History

Comparing Versions

Restoring Previous Versions

Deleting Versions

Version Tags & Organization

Tagging Versions

Version Descriptions

Development Workflows

Feature Development

A/B Testing

Hotfix Process

Version-Specific Features

Testing Versions

Running Evaluations on Versions

Version-Specific Analytics

API Reference

List Versions

Get Version Details

Create Version

Restore Version

Compare Versions

Best Practices

Version Management

Development Process

Documentation

Troubleshooting

Version Not Appearing

Can't Restore Version

Version Comparison Showing No Changes

Related Features