Quickstart Guide

Get up and running with FlexLock in 5 minutes.

Installation

With conda:

conda install -c quentinf00 flexlock

Your First Experiment

Step 1: Decorate Your Function

# train.py
from flexlock import flexcli

@flexcli
def train(lr: float = 0.01, epochs: int = 10, save_dir='outputs'):
    """Train a model."""
    print(f"Training with lr={lr} for {epochs} epochs")
    # ... your training code ...
    return {"accuracy": 0.95}

if __name__ == "__main__":
    train()

Step 2: Run It

$ python train.py
Training with lr=0.01 for 10 epochs
✓ Results saved to: outputs

That’s it! FlexLock automatically:

  • Created a CLI for your function

  • Saved results with auto-versioning

  • Tracked the configuration in run.lock

Step 3: Override Parameters

$ python train.py -o lr=0.1 epochs=20
Training with lr=0.1 for 20 epochs
✓ Results saved to: results/train/run_0002/

Step 4: Run a Parameter Sweep

$ python train.py --sweep "0.001,0.01,0.1" --sweep-target lr --n_jobs 3
✓ Running 3 experiments in parallel...
✓ Sweep complete! Results in results/train/

Next: Multi-Stage Pipelines

# pipeline.py
from flexlock import Project

# Load configurations
proj = Project(defaults='configs.defaults')

# Stage 1: Preprocess
preprocess_result = proj.submit(proj.get('preprocess'))

# Stage 2: Train (uses preprocess output)
train_cfg = proj.get('train')
train_cfg.data_dir = preprocess_result.output_dir
train_result = proj.submit(train_cfg)

# Stage 3: Evaluate
eval_cfg = proj.get('evaluate')
eval_cfg.model_dir = train_result.save_dir
eval_result = proj.submit(eval_cfg)

print(f"Final accuracy: {eval_result.accuracy}")

Run again with the same config? FlexLock automatically skips stages that haven’t changed:

$ python pipeline.py
⚡ Cache Hit! Preprocess already done
⚡ Cache Hit! Training already done
⚡ Cache Hit! Evaluation already done
Final accuracy: 0.95

Key Concepts

1. Configuration

Three ways to configure:

# Method 1: @flexcli decorator (simplest)
@flexcli
def train(lr=0.01): ...

# Method 2: Python configs (most flexible)
from flexlock import py2cfg
config = py2cfg(train, lr=0.01, model=py2cfg(Transformer, layers=12))

# Method 3: YAML configs (declarative)
# config.yaml
train:
  lr: 0.01
  epochs: 100

2. Reproducibility

Every run creates a run.lock snapshot:

# run.lock
timestamp: 2024-01-15T10:30:00
config:
  lr: 0.01
  epochs: 10
repos:
  main:
    tree: abc123def...  # Git tree hash
data:
  train: hash_abc123...  # Data fingerprint

Compare runs:

$ flexlock diff run_0001 run_0002
Differences:
  config.lr: 0.01 → 0.1

3. Smart Caching

FlexLock never reruns identical experiments:

# First run: executes
result = proj.submit(config)

# Second run: instant cache hit
result = proj.submit(config)  # ⚡ Skipped!

What’s Next?

Explore Features

API Reference

Getting Help

Ready to dive deeper? Continue with the Usage Guide.