Docs/Version Control/Commits

Version Control

Commits

Commits create immutable snapshots of your taste profile. Track changes over time, compare versions, and roll back if needed.

What is a Commit?

A commit is a saved snapshot of your taste profile at a specific point in time. It captures:

Constraints

Q&A responses that define high-level aesthetic rules.

Exemplars

Labeled reference images (good/bad examples).

Comparisons

Pairwise preference judgments between frames.

Computed Data

Latent scores, embedding centroids, and prompt summaries.

Commit History

Each branch maintains a linear history of commits. The latest commit on a branch is called the "head" of that branch.

main branch:

v_001 ──> v_002 ──> v_003 ──> v_004 (HEAD)
  │         │         │         │
  │         │         │         └── "Added 30 new comparisons"
  │         │         └── "Refined warm color preferences"
  │         └── "Initial labels batch"
  └── "Profile created"

Creating a Commit

Commits are typically created through the dashboard after making changes to your profile (adding labels, comparisons, or answering questions).

Via Dashboard

1Make changes to your profile (labels, comparisons, Q&A)
2Navigate to your profile's History page
3Click Commit Changes
4Add a descriptive commit message

Via API

Add a new version to the profile's version array:

PATCH /v1/profiles/:id

curl -X PATCH https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileData": {
      "versions": [
        ...existingVersions,
        {
          "id": "v_005",
          "branchId": "main",
          "parentVersionId": "v_004",
          "message": "Added 50 comparisons for color preferences",
          "snapshot": {
            "constraints": [...],
            "exemplars": [...],
            "comparisons": [...],
            "latentScores": {...}
          },
          "createdAt": "2024-01-21T10:00:00Z"
        }
      ],
      "branches": [
        {
          "id": "main",
          "name": "main",
          "headVersionId": "v_005"
        }
      ],
      "workingChanges": {
        "constraints": [],
        "exemplars": [],
        "comparisons": []
      }
    }
  }'

Version Data Structure

Field	Type	Description
id	string	Unique identifier for this version
branchId	string	The branch this commit belongs to
parentVersionId	string \| null	The previous version (null for first commit)
message	string	Human-readable description of changes
snapshot	object	Complete state at this version
createdAt	string	ISO timestamp of commit creation

Viewing Commit History

The commit history is included in the profile's profileData.versions array when you fetch a profile.

GET /v1/profiles/:id

{
  "id": "prof_abc123",
  "profileData": {
    "versions": [
      {
        "id": "v_001",
        "branchId": "main",
        "parentVersionId": null,
        "message": "Profile created",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "v_002",
        "branchId": "main",
        "parentVersionId": "v_001",
        "message": "Added 25 initial labels",
        "createdAt": "2024-01-16T14:00:00Z"
      },
      {
        "id": "v_003",
        "branchId": "main",
        "parentVersionId": "v_002",
        "message": "Completed comparison phase",
        "createdAt": "2024-01-18T09:30:00Z"
      }
    ],
    "branches": [
      {
        "id": "main",
        "headVersionId": "v_003"
      }
    ]
  }
}

Rolling Back to a Previous Version

To restore a previous version, update the branch's headVersionId and the effectiveSnapshot to match that version's snapshot.

Rollback Process

1. Identify the version you want to restore
2. Update the branch's headVersionId to that version
3. Copy that version's snapshot to effectiveSnapshot
4. Optionally, create a new commit documenting the rollback

Rollback Example

# First, get the version you want to restore
curl https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Then update the profile with that version's snapshot
curl -X PATCH https://api.commandAGI.com/v1/profiles/prof_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "effectiveSnapshot": <v_002 snapshot data>,
    "profileData": {
      "branches": [{
        "id": "main",
        "headVersionId": "v_002"
      }]
    }
  }'

Best Practices

Write Descriptive Messages

Good: "Added 30 comparisons focusing on lighting quality"
Bad: "Updated profile"

Commit Logical Units

Group related changes together. Complete a phase (all labels, all comparisons) before committing rather than committing after each individual change.

Commit Before Branching

Always commit your working changes before creating a new branch. This ensures the branch starts from a clean, known state.

Regular Commits

Commit regularly to maintain a detailed history. This makes it easier to identify when changes were made and roll back if needed.