# Quickstart Guide

Get up and running with FlexLock in 5 minutes.

## Installation
With conda:

```bash
conda install -c quentinf00 flexlock
```

## Your First Experiment

### Step 1: Decorate Your Function

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

```bash
$ 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

```bash
$ 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

```bash
$ 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

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

```bash
$ 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:

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

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

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

### 3. Smart Caching

FlexLock never reruns identical experiments:

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

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

## What's Next?

### Explore Features

- **[Usage Guide](./usage_guide.md)**: Comprehensive usage patterns
- **[HPC Integration](./hpc_integration.md)**: Slurm, PBS, Singularity support
- **[MLflow Integration](./mlflow_integration.md)**: Export to MLflow
- **[Debugging](./debugging.md)**: Interactive debugging on failure

### API Reference

- **[Python API](./python_api.md)**: Project class, py2cfg, and more
- **[CLI Reference](./cli_reference.md)**: Command-line tools
- **[Resolvers](./resolvers.md)**: Dynamic configuration values

## Getting Help

- **Documentation**: [https://quentinf00.github.io/flexlock/](https://quentinf00.github.io/flexlock/)
- **GitHub Issues**: [Report bugs](https://github.com/quentinf00/flexlock/issues)
- **Examples**: Check `examples/` in the repository

Ready to dive deeper? Continue with the [Usage Guide](./usage_guide.md).