ato 2.0.4__py3-none-any.whl → 2.1.4__py3-none-any.whl

ato-2.1.4.dist-info/METADATA

@@ -0,0 +1,1134 @@
+Metadata-Version: 2.4
+Name: ato
+Version: 2.1.4
+Summary: Configuration, experimentation, and hyperparameter optimization for Python. No runtime magic. No launcher. Just Python modules you compose.
+Author: ato contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/ato
+Project-URL: Repository, https://github.com/yourusername/ato
+Project-URL: Documentation, https://github.com/yourusername/ato#readme
+Project-URL: Issues, https://github.com/yourusername/ato/issues
+Keywords: config management,experiment tracking,hyperparameter optimization,lightweight,composable,namespace isolation,machine learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: numpy>=1.19.0
+Provides-Extra: distributed
+Requires-Dist: torch>=1.8.0; extra == "distributed"
+Dynamic: license-file
+
+# Ato: A Thin Operating Layer
+
+**Minimal reproducibility for ML.**
+Tracks config structure, code, and runtime so you can explain why runs differ — without a platform.
+
+```bash
+pip install ato
+```
+
+```python
+# Your experiment breaks. Here's how to debug it:
+python train.py manual  # See exactly how configs merged
+finder.get_trace_statistics('my_project', 'train_step')  # See which code versions ran
+finder.find_similar_runs(run_id=123)  # Find experiments with same structure
+```
+
+**One question:** "Why did this result change?"
+Ato fingerprints config structure, function logic, and runtime outputs to answer it.
+
+---
+
+## What Ato Is
+
+Ato is a thin layer that fingerprints your config structure, function logic, and runtime outputs.
+
+It doesn't replace your stack; it sits beside it to answer one question: **"Why did this result change?"**
+
+Three pieces, zero coupling:
+
+1. **ADict** — Structural hashing for configs (tracks architecture changes, not just values)
+2. **Scope** — Priority-based config merging with reasoning and code fingerprinting
+3. **SQLTracker** — Local-first experiment tracking in SQLite (zero setup, zero servers)
+
+Each works alone. Together, they explain why experiments diverge.
+
+**Config is not logging — it's reasoning.**
+Ato makes config merge order, priority, and causality visible.
+
+---
+
+## Config Superpowers (That Make Reproducibility Real)
+
+These aren't features. They're how Ato is built:
+
+| Capability | What It Does | Why It Matters |
+|------------|--------------|----------------|
+| **Structural hashing** | Hash based on keys + types, not values | Detect when experiment **architecture** changes, not just hyperparameters |
+| **Priority/merge reasoning** | Explicit merge order with `manual` inspection | See **why** a config value won — trace the entire merge path |
+| **Namespace isolation** | Each scope owns its keys | Team/module collisions are impossible — no need for `model_lr` vs `data_lr` prefixes |
+| **Code fingerprinting** | SHA256 of function bytecode, not git commits | Track **logic changes** automatically — refactoring doesn't create false versions |
+| **Runtime fingerprinting** | SHA256 of actual outputs | Detect silent failures when code is unchanged but behavior differs |
+
+**No dashboards. No servers. No ecosystems.**
+Just fingerprints and SQLite.
+
+---
+
+## Works With Your Stack (Keep Hydra, MLflow, W&B, ...)
+
+Ato doesn't compete with your config system or tracking platform.
+It **observes and fingerprints** what you already use.
+
+**Compose configs however you like:**
+- Load Hydra/OmegaConf configs → Ato fingerprints the final merged structure
+- Use argparse → Ato observes and integrates seamlessly
+- Import OpenMMLab configs → Ato handles `_base_` inheritance automatically
+- Mix YAML/JSON/TOML → Ato is format-agnostic
+
+**Track experiments however you like:**
+- Log to MLflow/W&B for dashboards → Ato tracks causality in local SQLite
+- Use both together → Cloud tracking for metrics, Ato for "why did this change?"
+- Or just use Ato → Zero-setup local tracking with full history
+
+**Ato is a complement, not a replacement.**
+No migration required. No lock-in. Add it incrementally.
+
+---
+
+## When to Use Ato
+
+Use Ato when:
+
+- **Experiments diverge occasionally** and you need to narrow down the cause
+- **Config include/override order** changes results in unexpected ways
+- **"I didn't change the code but results differ"** happens repeatedly (dependency/environment/bytecode drift)
+- **Multiple people modify configs** and you need to trace who set what and why
+- **You're debugging non-determinism** and need runtime fingerprints to catch silent failures
+
+**Ato is for causality, not compliance.**
+If you need audit trails or dashboards, keep using your existing tracking platform.
+
+---
+
+## Non-Goals
+
+Ato is **not**:
+
+- A pipeline orchestrator (use Airflow, Prefect, Luigi, ...)
+- A hyperparameter scheduler (use Optuna, Ray Tune, ...)
+- A model registry (use MLflow Model Registry, ...)
+- An experiment dashboard (use MLflow, W&B, TensorBoard, ...)
+- A dataset versioner (use DVC, Pachyderm, ...)
+
+**Ato has one job:** Explain why results changed.
+Everything else belongs in specialized tools.
+
+---
+
+## Incremental Adoption (No Migration Required)
+
+You don't need to replace anything. Add Ato in steps:
+
+**Step 1: Fingerprint config structure (zero code changes)**
+```python
+from ato.adict import ADict
+
+config = ADict(lr=0.001, batch_size=32, model='resnet50')
+print(config.get_structural_hash())  # Tracks structure, not values
+```
+
+**Step 2: Add code fingerprinting to key functions**
+```python
+from ato.scope import Scope
+
+scope = Scope()
+
+@scope.trace(trace_id='train_step')
+@scope
+def train_epoch(config):
+    # Your training code
+    pass
+```
+
+**Step 3: Add runtime fingerprinting to outputs**
+```python
+@scope.runtime_trace(
+    trace_id='predictions',
+    init_fn=lambda: np.random.seed(42),  # Fix randomness
+    inspect_fn=lambda preds: preds[:100]  # Track first 100
+)
+def evaluate(model, data):
+    return model.predict(data)
+```
+
+**Step 4: Inspect config merge order**
+```bash
+python train.py manual  # See exactly how configs merged
+```
+
+**Step 5: Track experiments locally**
+```python
+from ato.db_routers.sql.manager import SQLLogger
+
+logger = SQLLogger(config)
+run_id = logger.run(tags=['baseline'])
+# Your training loop
+logger.log_metric('loss', loss, step=epoch)
+logger.finish(status='completed')
+```
+
+---
+
+## Quick Start
+
+**Three lines to tracked experiments:**
+
+```python
+from ato.scope import Scope
+
+scope = Scope()
+
+@scope.observe(default=True)
+def config(config):
+    config.lr = 0.001
+    config.batch_size = 32
+    config.model = 'resnet50'
+
+@scope
+def train(config):
+    print(f"Training {config.model} with lr={config.lr}")
+
+if __name__ == '__main__':
+    train()
+```
+
+**Run it:**
+```bash
+python train.py                          # Uses defaults
+python train.py lr=0.01                  # Override from CLI
+python train.py manual                   # See config merge order
+```
+
+---
+
+## Table of Contents
+
+- [ADict: Structural Hashing](#adict-structural-hashing)
+- [Scope: Config Reasoning](#scope-config-reasoning)
+  - [Priority-based Merging](#priority-based-merging)
+  - [Config Chaining](#config-chaining)
+  - [Lazy Evaluation](#lazy-evaluation)
+  - [MultiScope: Namespace Isolation](#multiscope-namespace-isolation)
+  - [Config Documentation & Debugging](#config-documentation--debugging)
+  - [Code Fingerprinting](#code-fingerprinting)
+  - [Runtime Fingerprinting](#runtime-fingerprinting)
+- [SQL Tracker: Local Experiment Tracking](#sql-tracker-local-experiment-tracking)
+- [Hyperparameter Optimization](#hyperparameter-optimization)
+- [Best Practices](#best-practices)
+- [FAQ](#faq)
+- [Quality Signals](#quality-signals)
+- [Contributing](#contributing)
+
+---
+
+## ADict: Structural Hashing
+
+`ADict` tracks when experiment **architecture** changes, not just hyperparameter values.
+
+### Core Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| **Structural Hashing** | Hash based on keys + types → detect architecture changes |
+| **Nested Access** | Dot notation: `config.model.lr` instead of `config['model']['lr']` |
+| **Format Agnostic** | Load/save JSON, YAML, TOML, XYZ |
+| **Safe Updates** | `update_if_absent()` → merge without overwrites |
+| **Auto-nested** | `ADict.auto()` → `config.a.b.c = 1` just works |
+
+### Examples
+
+#### Structural Hashing
+
+```python
+from ato.adict import ADict
+
+# Same structure, different values
+config1 = ADict(lr=0.1, epochs=100, model='resnet50')
+config2 = ADict(lr=0.01, epochs=200, model='resnet101')
+print(config1.get_structural_hash() == config2.get_structural_hash())  # True
+
+# Different structure (epochs is str!)
+config3 = ADict(lr=0.1, epochs='100', model='resnet50')
+print(config1.get_structural_hash() == config3.get_structural_hash())  # False
+```
+
+**Why this matters:**
+When results differ, you need to know if the experiment **architecture** changed or just the values.
+
+#### Auto-nested Configs
+
+```python
+# ❌ Traditional way
+config = ADict()
+config.model = ADict()
+config.model.backbone = ADict()
+config.model.backbone.layers = [64, 128, 256]
+
+# ✅ With ADict.auto()
+config = ADict.auto()
+config.model.backbone.layers = [64, 128, 256]  # Just works!
+```
+
+#### Format Agnostic
+
+```python
+# Load/save any format
+config = ADict.from_file('config.json')
+config.dump('config.yaml')
+
+# Safe updates
+config.update_if_absent(lr=0.01, scheduler='cosine')  # Only adds scheduler
+```
+
+---
+
+## Scope: Config Reasoning
+
+Scope manages configuration through **priority-based merging** with **full reasoning**.
+
+**Config is not logging — it's reasoning.**
+Scope makes merge order, priority, and causality visible.
+
+### Priority-based Merging
+
+```
+Default Configs (priority=0)
+    ↓
+Named Configs (priority=0+)
+    ↓
+CLI Arguments (highest priority)
+    ↓
+Lazy Configs (computed after CLI)
+```
+
+#### Example
+
+```python
+from ato.scope import Scope
+
+scope = Scope()
+
+@scope.observe(default=True)  # Always applied
+def defaults(config):
+    config.lr = 0.001
+    config.epochs = 100
+
+@scope.observe(priority=1)  # Applied after defaults
+def high_lr(config):
+    config.lr = 0.01
+
+@scope.observe(priority=2)  # Applied last
+def long_training(config):
+    config.epochs = 300
+```
+
+```bash
+python train.py                           # lr=0.001, epochs=100
+python train.py high_lr                   # lr=0.01, epochs=100
+python train.py high_lr long_training     # lr=0.01, epochs=300
+```
+
+### Config Chaining
+
+Chain configs with dependencies:
+
+```python
+@scope.observe()
+def base_setup(config):
+    config.project_name = 'my_project'
+    config.data_dir = '/data'
+
+@scope.observe(chain_with='base_setup')  # Automatically applies base_setup first
+def advanced_training(config):
+    config.distributed = True
+    config.mixed_precision = True
+
+@scope.observe(chain_with=['base_setup', 'gpu_setup'])  # Multiple dependencies
+def multi_node_training(config):
+    config.nodes = 4
+    config.world_size = 16
+```
+
+```bash
+# Calling advanced_training automatically applies base_setup first
+python train.py advanced_training
+# Results in: base_setup → advanced_training
+```
+
+### Lazy Evaluation
+
+**Note:** Lazy evaluation requires Python 3.8 or higher.
+
+Compute configs **after** CLI args are applied:
+
+```python
+@scope.observe()
+def base_config(config):
+    config.model = 'resnet50'
+    config.dataset = 'imagenet'
+
+@scope.observe(lazy=True)  # Evaluated AFTER CLI args
+def computed_config(config):
+    # Adjust based on dataset
+    if config.dataset == 'imagenet':
+        config.num_classes = 1000
+        config.image_size = 224
+    elif config.dataset == 'cifar10':
+        config.num_classes = 10
+        config.image_size = 32
+```
+
+```bash
+python train.py dataset=%cifar10% computed_config
+# Results in: num_classes=10, image_size=32
+```
+
+**Python 3.11+ Context Manager:**
+
+```python
+@scope.observe()
+def my_config(config):
+    config.model = 'resnet50'
+    config.num_layers = 50
+
+    with Scope.lazy():  # Evaluated after CLI
+        if config.model == 'resnet101':
+            config.num_layers = 101
+```
+
+### MultiScope: Namespace Isolation
+
+Manage completely separate configuration namespaces with independent priority systems.
+
+**Use case:** Different teams own different scopes without key collisions.
+
+```python
+from ato.scope import Scope, MultiScope
+
+model_scope = Scope(name='model')
+data_scope = Scope(name='data')
+scope = MultiScope(model_scope, data_scope)
+
+@model_scope.observe(default=True)
+def model_config(model):
+    model.backbone = 'resnet50'
+    model.lr = 0.1  # Model-specific learning rate
+
+@data_scope.observe(default=True)
+def data_config(data):
+    data.dataset = 'cifar10'
+    data.lr = 0.001  # Data augmentation learning rate (no conflict!)
+
+@scope
+def train(model, data):  # Named parameters match scope names
+    # Both have 'lr' but in separate namespaces!
+    print(f"Model LR: {model.lr}, Data LR: {data.lr}")
+```
+
+**Key advantage:** `model.lr` and `data.lr` are completely independent. No naming prefixes needed.
+
+**CLI with MultiScope:**
+
+```bash
+# Override model scope only
+python train.py model.backbone=%resnet101%
+
+# Override both
+python train.py model.backbone=%resnet101% data.dataset=%imagenet%
+```
+
+### Config Documentation & Debugging
+
+**The `manual` command** visualizes the exact order of configuration application.
+
+```python
+@scope.observe(default=True)
+def config(config):
+    config.lr = 0.001
+    config.batch_size = 32
+    config.model = 'resnet50'
+
+@scope.manual
+def config_docs(config):
+    config.lr = 'Learning rate for optimizer'
+    config.batch_size = 'Number of samples per batch'
+    config.model = 'Model architecture (resnet50, resnet101, etc.)'
+```
+
+```bash
+python train.py manual
+```
+
+**Output:**
+```
+--------------------------------------------------
+[Scope "config"]
+(The Applying Order of Views)
+config → (CLI Inputs)
+
+(User Manuals)
+lr: Learning rate for optimizer
+batch_size: Number of samples per batch
+model: Model architecture (resnet50, resnet101, etc.)
+--------------------------------------------------
+```
+
+**Why this matters:**
+When debugging "why is this config value not what I expect?", you see **exactly** which function set it and in what order.
+
+**Complex example:**
+
+```python
+@scope.observe(default=True)
+def defaults(config):
+    config.lr = 0.001
+
+@scope.observe(priority=1)
+def experiment_config(config):
+    config.lr = 0.01
+
+@scope.observe(priority=2)
+def another_config(config):
+    config.lr = 0.1
+
+@scope.observe(lazy=True)
+def adaptive_lr(config):
+    if config.batch_size > 64:
+        config.lr = config.lr * 2
+```
+
+When you run `python train.py manual`, you see:
+```
+(The Applying Order of Views)
+defaults → experiment_config → another_config → (CLI Inputs) → adaptive_lr
+```
+
+Now it's **crystal clear** why `lr=0.1` (from `another_config`) and not `0.01`!
+
+### Code Fingerprinting
+
+Track **logic changes** automatically, ignoring cosmetic edits.
+
+#### Static Tracing (`@scope.trace`)
+
+Generates a fingerprint of the function's **logic**, not its name or formatting:
+
+```python
+# These three functions have IDENTICAL fingerprints
+@scope.trace(trace_id='train_step')
+@scope
+def train_v1(config):
+    loss = model(data)
+    return loss
+
+@scope.trace(trace_id='train_step')
+@scope
+def train_v2(config):
+    # Added comments
+    loss = model(data)  # Compute loss
+    return loss
+
+@scope.trace(trace_id='train_step')
+@scope
+def completely_different_name(config):
+    loss=model(data)  # Different whitespace
+    return loss
+```
+
+All three produce the **same fingerprint** because the underlying logic is identical.
+
+**When fingerprints change:**
+
+```python
+@scope.trace(trace_id='train_step')
+@scope
+def train_v1(config):
+    loss = model(data)
+    return loss
+
+@scope.trace(trace_id='train_step')
+@scope
+def train_v2(config):
+    loss = model(data) * 2  # ← Logic changed!
+    return loss
+```
+
+Now fingerprints differ — you've changed the actual computation.
+
+**Example: Catching refactoring bugs**
+
+```python
+# Original implementation
+@scope.trace(trace_id='forward_pass')
+@scope
+def forward(model, x):
+    out = model(x)
+    return out
+
+# Safe refactoring: Added comments, changed variable name, different whitespace
+@scope.trace(trace_id='forward_pass')
+@scope
+def forward(model,x):
+    # Forward pass through model
+    result=model(x)  # No spaces
+    return result
+```
+
+These have **the same fingerprint** because the underlying logic is identical — only cosmetic changes.
+
+```python
+# Unsafe refactoring: Logic changed
+@scope.trace(trace_id='forward_pass')
+@scope
+def forward(model, x):
+    features = model.backbone(x)  # Now calling backbone + head separately!
+    logits = model.head(features)
+    return logits
+```
+
+This has a **different fingerprint** — the logic changed. If you expected them to be equivalent but they have different fingerprints, you've caught a refactoring bug.
+
+### Runtime Fingerprinting
+
+Track what the function **produces**, not what it does.
+
+#### Runtime Tracing (`@scope.runtime_trace`)
+
+```python
+import numpy as np
+
+# Basic: Track full output
+@scope.runtime_trace(trace_id='predictions')
+@scope
+def evaluate(model, data):
+    return model.predict(data)
+
+# With init_fn: Fix randomness for reproducibility
+@scope.runtime_trace(
+    trace_id='predictions',
+    init_fn=lambda: np.random.seed(42)  # Initialize before execution
+)
+@scope
+def evaluate_with_dropout(model, data):
+    return model.predict(data)  # Now deterministic
+
+# With inspect_fn: Track specific parts of output
+@scope.runtime_trace(
+    trace_id='predictions',
+    inspect_fn=lambda preds: preds[:100]  # Only hash first 100 predictions
+)
+@scope
+def evaluate_large_output(model, data):
+    return model.predict(data)
+
+# Advanced: Type-only checking (ignore values)
+@scope.runtime_trace(
+    trace_id='predictions',
+    inspect_fn=lambda preds: type(preds).__name__  # Track output type only
+)
+@scope
+def evaluate_structure(model, data):
+    return model.predict(data)
+```
+
+**Parameters:**
+- `init_fn`: Optional function called before execution (e.g., seed fixing, device setup)
+- `inspect_fn`: Optional function to extract/filter what to track (e.g., first N items, specific fields, types only)
+
+Even if code hasn't changed, if predictions differ, the runtime fingerprint changes.
+
+#### When to Use Each
+
+**Use `@scope.trace()` when:**
+- You want to track code changes automatically
+- You're refactoring and want to isolate performance impact
+- You need to audit "which code produced this result?"
+- You want to ignore cosmetic changes (comments, whitespace, renaming)
+
+**Use `@scope.runtime_trace()` when:**
+- You want to detect **silent failures** (code unchanged, output wrong)
+- You're debugging non-determinism
+- You need to verify model behavior across versions
+- You care about what the function produces, not how it's written
+
+**Use both when:**
+- Building production ML systems
+- Running long-term research experiments
+- Multiple people modifying the same codebase
+
+---
+
+## SQL Tracker: Local Experiment Tracking
+
+Lightweight experiment tracking using SQLite.
+
+### Why SQL Tracker?
+
+- **Zero Setup**: Just a SQLite file, no servers
+- **Full History**: Track all runs, metrics, and artifacts
+- **Smart Search**: Find similar experiments by config structure
+- **Code Versioning**: Track code changes via fingerprints
+- **Offline-first**: No network required
+
+### Database Schema
+
+```
+Project (my_ml_project)
+├── Experiment (run_1)
+│   ├── config: {...}
+│   ├── structural_hash: "abc123..."
+│   ├── Metrics: [loss, accuracy, ...]
+│   ├── Artifacts: [model.pt, plots/*, ...]
+│   └── Fingerprints: [model_forward, train_step, ...]
+├── Experiment (run_2)
+└── ...
+```
+
+### Usage
+
+#### Logging Experiments
+
+```python
+from ato.db_routers.sql.manager import SQLLogger
+from ato.adict import ADict
+
+# Setup config
+config = ADict(
+    experiment=ADict(
+        project_name='image_classification',
+        sql=ADict(db_path='sqlite:///experiments.db')
+    ),
+    # Your hyperparameters
+    lr=0.001,
+    batch_size=32,
+    model='resnet50'
+)
+
+# Create logger
+logger = SQLLogger(config)
+
+# Start experiment run
+run_id = logger.run(tags=['baseline', 'resnet50', 'cifar10'])
+
+# Training loop
+for epoch in range(100):
+    # Your training code
+    train_loss = train_one_epoch()
+    val_acc = validate()
+
+    # Log metrics
+    logger.log_metric('train_loss', train_loss, step=epoch)
+    logger.log_metric('val_accuracy', val_acc, step=epoch)
+
+# Log artifacts
+logger.log_artifact(run_id, 'checkpoints/model_best.pt',
+                   data_type='model',
+                   metadata={'epoch': best_epoch})
+
+# Finish run
+logger.finish(status='completed')
+```
+
+#### Querying Experiments
+
+```python
+from ato.db_routers.sql.manager import SQLFinder
+
+finder = SQLFinder(config)
+
+# Get all runs in project
+runs = finder.get_runs_in_project('image_classification')
+for run in runs:
+    print(f"Run {run.id}: {run.config.model} - {run.status}")
+
+# Find best performing run
+best_run = finder.find_best_run(
+    project_name='image_classification',
+    metric_key='val_accuracy',
+    mode='max'  # or 'min' for loss
+)
+print(f"Best config: {best_run.config}")
+
+# Find similar experiments (same config structure)
+similar = finder.find_similar_runs(run_id=123)
+print(f"Found {len(similar)} runs with similar config structure")
+
+# Trace statistics (code fingerprints)
+stats = finder.get_trace_statistics('image_classification', trace_id='model_forward')
+print(f"Model forward pass has {stats['static_trace_versions']} versions")
+```
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| **Structural Hash** | Auto-track config structure changes |
+| **Metric Logging** | Time-series metrics with step tracking |
+| **Artifact Management** | Track model checkpoints, plots, data files |
+| **Fingerprint Tracking** | Version control for code (static & runtime) |
+| **Smart Search** | Find similar configs, best runs, statistics |
+
+---
+
+## Hyperparameter Optimization
+
+Built-in **Hyperband** algorithm for efficient hyperparameter search with early stopping.
+
+### How Hyperband Works
+
+Hyperband uses successive halving:
+1. Start with many configs, train briefly
+2. Keep top performers, discard poor ones
+3. Train survivors longer
+4. Repeat until one winner remains
+
+### Basic Usage
+
+```python
+from ato.adict import ADict
+from ato.hyperopt.hyperband import HyperBand
+from ato.scope import Scope
+
+scope = Scope()
+
+# Define search space
+search_spaces = ADict(
+    lr=ADict(
+        param_type='FLOAT',
+        param_range=(1e-5, 1e-1),
+        num_samples=20,
+        space_type='LOG'  # Logarithmic spacing
+    ),
+    batch_size=ADict(
+        param_type='INTEGER',
+        param_range=(16, 128),
+        num_samples=5,
+        space_type='LOG'
+    ),
+    model=ADict(
+        param_type='CATEGORY',
+        categories=['resnet50', 'resnet101', 'efficientnet_b0']
+    )
+)
+
+# Create Hyperband optimizer
+hyperband = HyperBand(
+    scope,
+    search_spaces,
+    halving_rate=0.3,      # Keep top 30% each round
+    num_min_samples=3,     # Stop when <= 3 configs remain
+    mode='max'             # Maximize metric (use 'min' for loss)
+)
+
+@hyperband.main
+def train(config):
+    # Your training code
+    model = create_model(config.model)
+    optimizer = Adam(lr=config.lr)
+
+    # Use __num_halved__ for early stopping
+    num_epochs = compute_epochs(config.__num_halved__)
+
+    # Train and return metric
+    val_acc = train_and_evaluate(model, optimizer, num_epochs)
+    return val_acc
+
+if __name__ == '__main__':
+    # Run hyperparameter search
+    best_result = train()
+    print(f"Best config: {best_result.config}")
+    print(f"Best metric: {best_result.metric}")
+```
+
+### Parameter Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `FLOAT` | Continuous values | Learning rate, dropout |
+| `INTEGER` | Discrete integers | Batch size, num layers |
+| `CATEGORY` | Categorical choices | Model type, optimizer |
+
+Space types:
+- `LOG`: Logarithmic spacing (good for learning rates)
+- `LINEAR`: Linear spacing (default)
+
+### Distributed Search
+
+```python
+from ato.hyperopt.hyperband import DistributedHyperBand
+import torch.distributed as dist
+
+# Initialize distributed training
+dist.init_process_group(backend='nccl')
+rank = dist.get_rank()
+world_size = dist.get_world_size()
+
+# Create distributed hyperband
+hyperband = DistributedHyperBand(
+    scope,
+    search_spaces,
+    halving_rate=0.3,
+    num_min_samples=3,
+    mode='max',
+    rank=rank,
+    world_size=world_size,
+    backend='pytorch'
+)
+
+@hyperband.main
+def train(config):
+    # Your distributed training code
+    model = create_model(config)
+    model = DDP(model, device_ids=[rank])
+    metric = train_and_evaluate(model)
+    return metric
+
+if __name__ == '__main__':
+    result = train()
+    if rank == 0:
+        print(f"Best config: {result.config}")
+```
+
+---
+
+## Best Practices
+
+### 1. Project Structure
+
+```
+my_project/
+├── configs/
+│   ├── default.py       # Default config with @scope.observe(default=True)
+│   ├── models.py        # Model-specific configs
+│   └── datasets.py      # Dataset configs
+├── train.py             # Main training script
+├── experiments.db       # SQLite experiment tracking
+└── experiments/
+    ├── run_001/
+    │   ├── checkpoints/
+    │   └── logs/
+    └── run_002/
+```
+
+### 2. Config Organization
+
+```python
+# configs/default.py
+from ato.scope import Scope
+from ato.adict import ADict
+
+scope = Scope()
+
+@scope.observe(default=True)
+def defaults(config):
+    # Data
+    config.data = ADict(
+        dataset='cifar10',
+        batch_size=32,
+        num_workers=4
+    )
+
+    # Model
+    config.model = ADict(
+        backbone='resnet50',
+        pretrained=True
+    )
+
+    # Training
+    config.train = ADict(
+        lr=0.001,
+        epochs=100,
+        optimizer='adam'
+    )
+
+    # Experiment tracking
+    config.experiment = ADict(
+        project_name='my_project',
+        sql=ADict(db_path='sqlite:///experiments.db')
+    )
+```
+
+### 3. Combined Workflow
+
+```python
+from ato.scope import Scope
+from ato.db_routers.sql.manager import SQLLogger
+from configs.default import scope
+
+@scope
+def train(config):
+    # Setup experiment tracking
+    logger = SQLLogger(config)
+    run_id = logger.run(tags=[config.model.backbone, config.data.dataset])
+
+    try:
+        # Training loop
+        for epoch in range(config.train.epochs):
+            loss = train_epoch()
+            acc = validate()
+
+            logger.log_metric('loss', loss, epoch)
+            logger.log_metric('accuracy', acc, epoch)
+
+        logger.finish(status='completed')
+
+    except Exception as e:
+        logger.finish(status='failed')
+        raise e
+
+if __name__ == '__main__':
+    train()
+```
+
+### 4. Reproducibility Checklist
+
+- ✅ Use structural hashing to track config changes
+- ✅ Log all hyperparameters to SQLLogger
+- ✅ Tag experiments with meaningful labels
+- ✅ Track artifacts (checkpoints, plots)
+- ✅ Use lazy configs for derived parameters
+- ✅ Document configs with `@scope.manual`
+- ✅ Add code fingerprinting to key functions
+- ✅ Add runtime fingerprinting to critical outputs
+
+---
+
+## FAQ
+
+### Does Ato replace Hydra?
+
+No. Hydra is excellent at config composition.
+Ato is a layer that explains **why** results differ — it observes and fingerprints the final merged config.
+
+Use them together: Hydra for composition, Ato for causality.
+
+### Does Ato conflict with MLflow/W&B?
+
+No. MLflow/W&B provide dashboards and cloud tracking.
+Ato provides local causality tracking (config reasoning + code fingerprinting).
+
+Use them together: MLflow/W&B for metrics/dashboards, Ato for "why did this change?"
+
+### Do I need a server?
+
+No. Ato uses local SQLite. Zero setup, zero network calls.
+
+### Can I use Ato with my existing config files?
+
+Yes. Ato is format-agnostic:
+- Load YAML/JSON/TOML → Ato fingerprints the result
+- Import OpenMMLab configs → Ato handles `_base_` inheritance
+- Use argparse → Ato integrates seamlessly
+
+### What if I already have experiment tracking?
+
+Keep it. Ato complements existing tracking:
+- Your tracking: metrics, artifacts, dashboards
+- Ato: config reasoning, code fingerprinting, causality
+
+No migration required.
+
+### Is Ato production-ready?
+
+Yes. Ato has ~100 unit tests that pass on every release.
+Python codebase is ~10 files — small, readable, auditable.
+
+### What's the performance overhead?
+
+Minimal:
+- Config fingerprinting: microseconds
+- Code fingerprinting: happens once at decoration time
+- Runtime fingerprinting: depends on `inspect_fn` complexity
+- SQLite logging: milliseconds per metric
+
+### Can I self-host?
+
+Ato runs entirely locally. There's nothing to host.
+If you need centralized tracking, use MLflow/W&B alongside Ato.
+
+---
+
+## Quality Signals
+
+**Every release passes 100+ unit tests.**
+No unchecked code. No silent failure.
+
+This isn't a feature. It's a commitment.
+
+When you fingerprint experiments, you're trusting the fingerprints are correct.
+When you merge configs, you're trusting the merge order is deterministic.
+When you trace code, you're trusting the bytecode hashing is stable.
+
+Ato has zero tolerance for regressions.
+
+Tests cover every module — ADict, Scope, MultiScope, SQLTracker, HyperBand — and every edge case we've encountered in production use.
+
+```bash
+python -m pytest unit_tests/  # Run locally. Always passes.
+```
+
+**If a test fails, the release doesn't ship. Period.**
+
+**Codebase size:** ~10 Python files
+Small, readable, auditable. No magic, no metaprogramming.
+
+---
+
+## Requirements
+
+- Python >= 3.7 (Python >= 3.8 required for lazy evaluation features)
+- SQLAlchemy (for SQL Tracker)
+- PyYAML, toml (for config serialization)
+
+See `pyproject.toml` for full dependencies.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+### Development Setup
+
+```bash
+git clone https://github.com/Dirac-Robot/ato.git
+cd ato
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+python -m pytest unit_tests/
+```
+
+---
+
+## License
+
+MIT License