Skip to main content
New to bgit? Start with the Quickstart to create your first model.
Now that you’ve created your first model, let’s dive into how to actually work with bgit: iterating on models, experimenting with branches, and collaborating with teams.

Core Concepts

bgit transforms model training into a familiar git workflow where:
  • Your repository tracks model weight evolution (not just config files)
  • Commits represent model versions in weight space
  • recipe.yml is your complete audit trail from base model → current weights
Edit
input.yml
Commit
Version change
Run
Operations
Test
Chat with model
Iterate
Repeat cycle

Understanding Your Files in Depth

Three Primary Files

input.ymlYou EditInput box for next baking operation

.breadAuto-generatedCurrent state metadata (read-only)

recipe.ymlAuto-generatedComplete history log (read-only)

input.yml: Your Control Panel

This is the only file you edit. It specifies what operation to perform next:
PROMPT:
  teacher:                    # What behavior to bake in
    messages:
      - role: system
        content: "You are an expert Python developer..."
  
  student:                    # Trigger at inference (empty = always-on)
    messages:
      - role: system
        content: ""           # Empty string = zero-token, permanent behavior

TARGET:
  name: main_target           # Target name (will be hashed: main_target_abc123...)
  generators:                 # How to generate training data
    - type: oneshot_qs        # AI-generated questions
      model: claude-sonnet-4-5-20250929
      numq: 100
      temperature: 0.7
    
    - type: hardcoded         # Specific test cases
      questions:
        - "Write an email validator"
        - "Implement LRU cache"
  
  num_traj_per_stimulus: 5     # Responses per question

BAKE:
  name: main_bake                    # Bake name (will be hashed: main_bake_abc123...)
  datasets:
    - target: main_target     # References the named target above
      weight: 1.0             # Relative weight
  
  epochs: 1                   # Training epochs
  micro_batch_size: 1
  gradient_accumulation_steps: 8
  
  model:
    dtype: bf16               # Model precision
    baked_adapter_config:     # LoRA configuration
      r: 32
      lora_alpha: 64
      lora_dropout: 0.05

recipe.yml: Your Audit Trail

Read-only - automatically updated after operations run. Tracks the history of your model up to the current commit. The file structure includes:
# This file is auto-generated - do not edit manually

base_model: Qwen/Qwen3-32B
total_steps: 8
steps:
# First bake cycle: prompts → stim → rollout → bake
  - step: 1
operation: add_prompt
prompt_name: python_expert_teacher
- step: 2
operation: run_stim
target: main_target_abc123
output_count: 150
- step: 3
operation: run_rollout
target: main_target_abc123
trajectory_count: 750
- step: 4
operation: bake
bake_name: main_bake_abc123
model_names:
  - user/repo/main_bake_abc123/120

# Second bake cycle: new prompt version → stim → rollout → bake
- step: 5
operation: add_prompt
prompt_name: python_expert_teacher_v2
- step: 6
operation: run_stim
target: main_target_def456
output_count: 200
- step: 7
operation: run_rollout
target: main_target_def456
trajectory_count: 1000
- step: 8
operation: bake
bake_name: refined_bake_def456
model_names:
  - user/repo/refined_bake_def456/150
resources:
prompts:
- python_expert_teacher
- python_expert_teacher_v2
targets:
- main_target_abc123
- main_target_def456
bakes:
- bake_name: main_bake_abc123
  model_names:
    - user/repo/main_bake_abc123/120
- bake_name: refined_bake_def456
  model_names:
    - user/repo/refined_bake_def456/150
# This file is auto-generated - do not edit manually

base_model: Qwen/Qwen3-32B
total_steps: 4
steps:
  # Step 1: Prompts were added to the repository
  - step: 1
    operation: add_prompt
    prompt_name: python_expert_teacher
  
  # Step 2: Stim operation generated questions
  - step: 2
    operation: run_stim
    target: main_target_abc123
    output_count: 150
  
  # Step 3: Rollout operation generated responses
  - step: 3
    operation: run_rollout
    target: main_target_abc123
    trajectory_count: 750
  
  # Step 4: Bake operation trained the model
  - step: 4
    operation: bake
    bake_name: main_bake_abc123
    model_names:
      - user/repo/main_bake_abc123/120
resources:
  prompts:
    - python_expert_teacher
  targets:
    - main_target_abc123
  bakes:
    - bake_name: main_bake_abc123
      model_names:
        - user/repo/main_bake_abc123/120
When to read recipe.yml:
Read chronologically to see how your model developed:
  • Which prompts were tried
  • How many bakes were performed
  • What models resulted at each step
  • Training loss progression
Identify which operation introduced specific behavior:
# View recipe at different commits
git show HEAD~1:recipe.yml
git show HEAD:recipe.yml

# The diff shows what operation was added
git diff HEAD~1 recipe.yml
The recipe is a complete build script. You could theoretically replay these steps from the base model to recreate the exact same weights.
Complete paper trail for regulatory or documentation purposes:
  • What data was used (stim/rollout counts)
  • When operations occurred (timestamps)
  • What models were produced

.bread: Current State Metadata

Read-only - tracks your model’s current configuration state. Useful for:
  • Checking operation status before running
  • Verifying prompt/target setup
  • Debugging configuration issues
Never edit .bread or recipe.yml manually. They’re automatically maintained by bgit. Manual edits will be overwritten on the next operation.

Core Workflow: Iterative Baking

Sequential Baking: When you run multiple bakes, each bake automatically uses the previous bake’s model as the parent. See Sequential Baking for details on building models incrementally.
1

Edit Configuration

Make changes to input.yml to specify your next baking operation:
  • Modify prompts
  • Adjust stim settings (more questions, different temperature)
  • Change bake parameters (epochs, LoRA rank)
# Example: Increase temperature for more creative responses
TARGET:
  generators:
    - type: oneshot_qs
      numq: 150          # More questions
      temperature: 0.9    # Higher creativity
2

Commit Your Changes

Create a version marker with descriptive message:
bgit add .
bgit commit -m "Increase temp to 0.9 for more creative Python examples"
Your commit message documents what you’re baking and why.
Good commit messages:
  • “Add error handling emphasis to teacher prompt”
  • “Increase LoRA rank to 64 for better capacity”
  • “Add hardcoded edge cases for validation functions”
Bad commit messages:
  • “Update file”
  • “Changes”
  • “Fix”
3

Run Operations

Execute the baking operations:
# Run all operations in sequence
bgit run stim rollout bake

# Or run individually
bgit run stim       # Generate questions
bgit run rollout    # Generate responses
bgit run bake       # Train weights
This produces new model weights. The .bread and recipe.yml files are automatically updated.
4

Check Status

Monitor operation progress:
bgit status
Shows:
  • Stim: complete (150 stimuli generated)
  • Rollout: running (450/750 trajectories, 60%)
  • Bake: not started
5

Test Your Model

Once bake completes, test the new weights:
# Model name is displayed when bake completes
# Or check recipe.yml for model_names under the latest bake
bgit chat user/repo/v1/checkpoint_2
Verify the behavior changed as expected.
Automatic commits: bgit automatically commits recipe.yml after each successful bake. The .bread file is committed via the pre-commit hook when you stage changes. You don’t need to manually commit these files.
6

Repeat

Continue iterating:
  • Make more changes to input.yml
  • Commit and run operations
  • Test and evaluate
  • Document results in commits

Advanced Git Workflows

Branching for Experiments

Key concept: Branches in bgit represent parallel weight evolutions. Each branch has its own recipe.yml tracking independent operations from a common ancestor.
Use --detach flag when baking on branches: When working with branches, use the --detach flag for bake operations to avoid conflicts with Git state changes. This allows you to switch branches or make commits while the bake runs in the background. Use bgit fetch to retrieve results when the bake completes.
bgit doesn’t support merging because model weights can’t be combined. You experiment on branches, then copy the winning branch’s files to main.
Workflow:
1

Create Experiment Branches

# Start from current main state
git checkout main

# Create first experiment
git checkout -b experiment/formal-tone
vim input.yml  # Edit for formal tone
bgit add input.yml
bgit commit -m "Experiment: formal business tone"
bgit run stim rollout bake --detach  # Detach to allow branch switching

# Create second experiment (from main, not formal-tone)
git checkout main
git checkout -b experiment/casual-tone
vim input.yml  # Edit for casual tone
bgit add input.yml
bgit commit -m "Experiment: casual friendly tone"
bgit run stim rollout bake --detach  # Detach to allow branch switching
The --detach flag runs the bake operation in the background, allowing you to switch branches or continue working while the bake completes. This is especially useful when running multiple experiments in parallel.
Each branch now has divergent recipe.yml files:
  • main: base → prompt1 → bake1
  • experiment/formal-tone: base → prompt1 → bake1 → prompt2_formal → bake2
  • experiment/casual-tone: base → prompt1 → bake1 → prompt2_casual → bake2
2

Retrieve Bake Results

After bakes complete (they run in the background with --detach), retrieve the results:
# Switch to the branch you want to check
git checkout experiment/formal-tone

# Fetch results from detached bake operations
bgit fetch

# This updates .bread and recipe.yml with the completed bake results
# Model names are displayed in the terminal output
Repeat for other branches:
git checkout experiment/casual-tone
bgit fetch  # Retrieve results for this branch's bake
3

Test Both Models

# Test formal experiment
git checkout experiment/formal-tone
# Check recipe.yml or .bread for model name
bgit chat user/repo/v1/formal_checkpoint

# Test casual experiment
git checkout experiment/casual-tone
# Check recipe.yml or .bread for model name
bgit chat user/repo/v1/casual_checkpoint
4

Pick the Winner

Decide which experiment succeeded:
# Casual tone was better, adopt it to main
git checkout main

# Copy the winning branch's files (this is how you "merge")
git checkout experiment/casual-tone -- input.yml .bread recipe.yml

# Commit the adoption
git commit -m "Adopt casual-tone approach: better user engagement"
Now main has the casual branch’s weight evolution. The formal experiment’s operations are discarded.
5

Clean Up (Optional)

# Delete losing experiment
git branch -d experiment/formal-tone

# Or keep for reference/future comparison
git tag archive/formal-tone-experiment experiment/formal-tone
git branch -d experiment/formal-tone
Why no merging?
Model weights can’t be “merged” like code files. If branch A bakes in formal tone and branch B bakes in casual tone, there’s no meaningful way to combine those weight changes - you’d get incoherent behavior.Think of it like training two different models - you can’t merge their weights and expect sensible results. You must choose one evolutionary path.This is actually simpler than traditional git - no merge conflicts to resolve!

Comparing Branches

# Compare what you're ABOUT to bake differently
git diff main..experiment/formal-tone input.yml

# Compare complete HISTORIES (what was actually baked)
git diff main..experiment/formal-tone recipe.yml

# This shows the divergent operations after the branch point
Example diff output:
# recipe.yml diff
+ - step: 7
+   operation: update_prompt
+   prompt_name: teacher
+   changes: "Added formal business language guidelines"
+ - step: 8
+   operation: run_bake
+   result_model: user/repo/v1/formal_checkpoint

# vs on the other branch:
+ - step: 7
+   operation: update_prompt
+   prompt_name: teacher
+   changes: "Added casual friendly conversational style"
+ - step: 8
+   operation: run_bake
+   result_model: user/repo/v1/casual_checkpoint

Time Travel

Git’s history features work perfectly with bgit:
# See all model versions
git log --oneline

# Output:
# a3f7c2e Increase creativity with temp 0.9
# b8e4d1a Add error handling emphasis
# c5f9a7b Initial Python expert personality

# Go back to previous version
git checkout b8e4d1a

# Your model is now at that historical state
# recipe.yml shows operations up to that point
cat recipe.yml  # Only steps 1-6

# Test that historical model
bgit chat <model-from-that-commit>

# Return to latest
git checkout main
Use cases:
  • Compare current vs previous performance
  • Roll back a bad baking decision
  • Understand when behavior changed

Tagging Milestones

Mark successful production models:
# Tag current state as production
git tag -a v1.0 -m "Production: Python expert baseline - training loss 4.7e-6"
git push --tags

# Tag after significant improvements
git tag -a v1.1 -m "Production: Added edge case handling - loss 5.2e-6"

# Roll back to a tagged version
git checkout v1.0
Recommended tags:
  • v1.0, v1.1: Production versions
  • baseline: Initial working model
  • pre-refactor: Before major changes
  • deployment-2024-01-15: Timestamped deployments

Team Collaboration

bgit repositories work like any git repository:
# Clone teammate's model repository
git clone [email protected]:team/customer-support-bot.git
cd customer-support-bot

# Fetch latest updates from remote
git fetch origin

# See what they've been doing
git log

# Test their latest model
bgit status
bgit chat <their-model>

# Create your own experiment
git checkout -b experiment/add-product-knowledge
vim input.yml  # Add product database prompt
bgit add input.yml
bgit commit -m "Experiment: integrate product knowledge base"
bgit run stim rollout bake --detach  # Use --detach when on branches

# Retrieve results when complete
bgit fetch

# Push your experiment for team review
git push origin experiment/add-product-knowledge
Pull request workflow:
  1. Teammate creates experiment branch
  2. Pushes to shared repository
  3. Team members pull and test the branch model
  4. Discuss results in PR comments
  5. If successful, adopt to main (copy files)
  6. Everyone pulls updated main
No merge conflicts! Since you can’t merge weights, you either adopt one branch or the other - no conflicts to resolve.

Command Reference

bgit init <model-name>

Initialize a new model repository.
bgit init <REPO-NAME>
Creates:
  • Model directory with YAML config
  • Git repository
  • Pre-commit hooks
  • README.md
Options:
  • Prompts for API key if not configured
  • Validates API key before proceeding

bgit add [files...]

Stage files for commit (wraps git add).
bgit add .
bgit add input.yml
The pre-commit hook automatically updates .bread when YAML files change.

bgit commit [options]

Commit changes (wraps git commit).
bgit commit -m "Add edge case handling to prompts"
bgit commit -am "Quick fix: adjust temperature"  # -a stages all changes
Best practices:
  • Describe what you’re baking
  • Explain why if non-obvious
  • Reference issues/tickets if applicable

bgit status

Show current operation status with progress indicators.
bgit status
Example output:
Repository: <REPO-NAME>
Current state: user/repo/v1/checkpoint_2

Operations:
  Stim:    complete (150 stimuli)
  Rollout: complete (750 trajectories)
  Bake:    running (45% complete, loss: 0.0000052, ETA: 15 min)

Latest model: user/repo/v1/checkpoint_2
Training loss: 0.0000047

bgit run <operations...> [--detach]

Run one or more operations.
# Run individually
bgit run stim
bgit run rollout
bgit run bake

# Run in sequence
bgit run stim rollout bake

# Just run bake (if stim/rollout already complete)
bgit run bake

# Run with detach flag (recommended for branches)
bgit run stim rollout bake --detach
Operations:
  • stim: Generate training questions
  • rollout: Generate model responses
  • bake: Train model weights
Flags:
  • --detach: Run operations in the background. Recommended when working on branches to avoid conflicts with Git state changes. Allows you to switch branches or make commits while operations run. Use bgit fetch to retrieve results when complete.
Updates .bread and recipe.yml automatically after each operation completes.

bgit stim [--limit <number>]

View stim outputs (generated questions).
# View all stim outputs
bgit stim

# Limit to first 10
bgit stim --limit 10
Example output:
Stim outputs (150 total):
1. "Write a function to validate email addresses"
2. "Implement an LRU cache with O(1) operations"
3. "Create a REST API endpoint with proper error handling"
...

bgit rollout [--limit <number>]

View rollout outputs (model responses to stim).
# View all rollout outputs
bgit rollout

# Limit to first 5
bgit rollout --limit 5
Example output:
Rollout outputs (750 total):

Stimulus: "Write a function to validate email addresses"
Response:
```python
import re
from typing import Optional

def validate_email(email: str) -> bool:
    """
    Validate email address format.
    
    Args:
        email: Email address to validate
    ...

bgit fetch

Retrieve results from detached bake operations.
# Fetch results from detached operations
bgit fetch
When to use:
  • After running bgit run with --detach flag
  • When switching to a branch that had detached operations running
  • To check if background operations have completed
What it does:
  • Updates .bread and recipe.yml with completed operation results
  • Displays model names if bakes completed
  • Shows operation status
Best practice: When working on branches, always use bgit run ... --detach and then bgit fetch to retrieve results. This prevents Git state conflicts and allows parallel experimentation.

bgit chat <model-name>

Start interactive chat session with a baked model.
# Model name is displayed when bake completes
# Or check recipe.yml (model_names) or use bgit models
bgit chat user/repo/v1/checkpoint_2
Chat commands:
  • /help - Show available commands
  • /clear - Clear conversation history
  • /system <prompt> - Set system prompt
  • /status - Show current settings
  • /quit - Exit chat

bgit metrics [bake-name]

Display training metrics chart for a bake. Shows an ASCII chart of loss over iterations.
# Display metrics for the current bake (from .bread file)
bgit metrics

# Display metrics for a specific bake
bgit metrics my_bake
What it shows:
  • Loss function over iterations as an ASCII chart
  • Min and max loss values
  • Training progress visualization
Example output:
Bake Metrics: my_bake

Loss Function Over Iterations
Min: 1.23e-07 | Max: 5.67e-06
    5.67e-06 ┤  ╭─╮
    4.50e-06 ┤ ╭╯ ╰─╮
    3.33e-06 ┤╭╯    ╰─╮
    2.17e-06 ┤╯       ╰─╮
    1.00e-06 ┤          ╰─╮
    1.23e-07 ┤            ╰─
Use Case: Monitor training progress and analyze loss curves. Useful for understanding how your model is learning during the bake process.

bgit download [bake-name] [--checkpoint <number>]

Get presigned URL for downloading model weights.
# Get download URL for current bake (latest checkpoint)
bgit download

# Get download URL for a specific bake
bgit download my_bake

# Get download URL for a specific checkpoint
bgit download my_bake --checkpoint 35
What it does:
  • Retrieves a presigned URL for downloading model weights
  • Displays download information (bake name, checkpoint, expiry time, URL)
  • Provides ready-to-use wget and curl commands
Example output:
Bake: my_bake
Checkpoint: 35
Expires in: 3600s
URL: https://presigned-url-to-model-weights.tar.gz

To download, run:
  wget -O my_bake_checkpoint_35.tar.gz "https://presigned-url-to-model-weights.tar.gz"

Or using curl:
  curl -o my_bake_checkpoint_35.tar.gz "https://presigned-url-to-model-weights.tar.gz"
Important Notes:
  • Presigned URLs expire after 1 hour by default
  • Download the weights promptly after receiving the URL
  • Model weights are typically large files (several GB), ensure sufficient storage space
  • The checkpoint number defaults to the latest checkpoint if not specified

Best Practices

Commit Message Conventions

Format: <action>: <what> [why] Good examples:
git commit -m "Increase LoRA rank: improve model capacity for complex patterns"
git commit -m "Add edge cases: validator functions need better error handling"
git commit -m "Reduce temperature: responses too creative, losing accuracy"
Bad examples:
git commit -m "Update config"  # What changed?
git commit -m "Fix"            # Fix what?
git commit -m "Changes"        # Too vague

Branch Naming Strategies

Convention: <type>/<description> Types:
  • experiment/: Testing new approaches
  • feat/: Adding new capabilities
  • fix/: Correcting issues
  • test/: Parameter tuning
Examples:
experiment/formal-business-tone
experiment/higher-creativity
feat/multi-language-support
feat/domain-specific-knowledge
fix/reduce-hallucinations
test/optimal-lora-rank

When to Run Operations

Run stim when:
  • First time setting up target
  • Changed stim generators (added/removed)
  • Want more training data
Run rollout when:
  • Stim outputs changed
  • Changed teacher prompt significantly
  • Want to see how prompted model responds
Run bake when:
  • Have new rollout data
  • Changed bake parameters (epochs, LoRA config)
  • Ready to update model weights
Run all three when:
  • Significant prompt changes
  • Starting from scratch
  • Want fresh training data

Troubleshooting

Symptom: bgit: command not foundSolution:
# Reinstall and link
cd bread_sdk_git_interface
npm install
npm run build
npm link

# Or use npx
npx bgit status
Symptom: “Invalid API key” errorSolution:
# Check environment variable
echo $BREAD_API_KEY

# Check config file
cat ~/.bgit/config.json

# Re-run init to update
bgit init test-model  # Will prompt for new key
Symptom: Stim/rollout/bake operations failCommon causes:
  • Invalid prompt names in YAML
  • Incorrect repo name
  • Network issues
  • API rate limits
Solution:
# Check status for error details
bgit status

# Verify YAML configuration
cat input.yml

# Check .bread for current state
cat .bread
Symptom: .bread file not foundSolution: The pre-commit hook auto-generates it. If missing:
# Manually trigger update
npx bgit update-bread $(pwd)

# Or re-commit
git add .
git commit --amend --no-edit
Symptom: Can’t connect to model for chatCheck:
  • Model name is correct (from bgit status)
  • API key is valid
  • Network connectivity
Solution:
# Verify model exists
bgit status

# Try with full model path
bgit chat user/repo/bake_name/checkpoint_number

Next Steps