ato 2.0.0__tar.gz → 2.1.0__tar.gz

{ato-2.0.0 → ato-2.1.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: ato
-Version: 2.0.0
-Summary: A Python library for experiment tracking and hyperparameter optimization
+Version: 2.1.0
+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: machine learning,experiment tracking,hyperparameter optimization
+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
@@ -32,38 +32,47 @@ Provides-Extra: distributed
 Requires-Dist: torch>=1.8.0; extra == "distributed"
 Dynamic: license-file
 
-# Ato
+# Ato: A Tiny Orchestrator
 
-Ato is intentionally small — it’s not about lines of code,  
-it’s about where they belong.  
-The core fits in a few hundred lines because it doesn’t need to fight Python — it flows with it.
+**Configuration, experimentation, and hyperparameter optimization for Python.**
+
+No runtime magic. No launcher. No platform.
+Just Python modules you compose.
+
+```bash
+pip install ato
+```
 
 ---
 
-**Ato** is a lightweight Python library for experiment management in machine learning and data science.  
-It provides flexible configuration management, experiment tracking, and hyperparameter optimization —  
-all without the complexity or overhead of heavy frameworks.
+## Design Philosophy
 
-## Why Ato?
+Ato was built on three constraints:
 
-### Core Differentiators
+1. **Visibility** — When configs merge from multiple sources, you should see **why** a value was set.
+2. **Composability** — Each module (ADict, Scope, SQLTracker, HyperOpt) works independently. Use one, use all, or mix with other tools.
+3. **Structural neutrality** — Ato is a layer, not a platform. It has no opinion on your stack.
 
-- **True Namespace Isolation**: MultiScope provides independent config contexts (unique to Ato!)
-- **Configuration Transparency**: Visualize exact config merge order - debug configs with `manual` command
-- **Built-in Experiment Tracking**: SQLite-based tracking with no external services required
-- **Structural Hashing**: Track experiment structure changes automatically
+This isn't minimalism for its own sake.
+It's **structural restraint** — interfering only where necessary, staying out of the way everywhere else.
 
-### Developer Experience
+**What Ato provides:**
+- **Config composition** with explicit priority and merge order debugging
+- **Namespace isolation** for multi-team projects (MultiScope)
+- **Experiment tracking** in local SQLite with zero setup
+- **Hyperparameter search** via Hyperband (or compose with Optuna/Ray Tune)
 
-- **Zero Boilerplate**: Auto-nested configs, lazy evaluation, attribute access
-- **CLI-first Design**: Configure experiments from command line without touching code
-- **Framework Agnostic**: Works with PyTorch, TensorFlow, JAX, or pure Python
+**What Ato doesn't provide:**
+- Web dashboards (use MLflow/W&B)
+- Model registry (use MLflow)
+- Dataset versioning (use DVC)
+- Plugin marketplace
 
-## Quick Start
+Ato is designed to work **between** tools, not replace them.
 
-```bash
-pip install ato-python
-```
+---
+
+## Quick Start
 
 ### 30-Second Example
 
@@ -73,14 +82,14 @@ from ato.scope import Scope
 scope = Scope()
 
 @scope.observe(default=True)
-def config(cfg):
-    cfg.lr = 0.001
-    cfg.batch_size = 32
-    cfg.model = 'resnet50'
+def config(config):
+    config.lr = 0.001
+    config.batch_size = 32
+    config.model = 'resnet50'
 
 @scope
-def train(cfg):
-    print(f"Training {cfg.model} with lr={cfg.lr}")
+def train(config):
+    print(f"Training {config.model} with lr={config.lr}")
     # Your training code here
 
 if __name__ == '__main__':
@@ -88,72 +97,60 @@ if __name__ == '__main__':
     # Override from CLI: python train.py lr=0.01 model=%resnet101%
 ```
 
+**Key features:**
+- `@scope.observe()` defines config sources
+- `@scope` injects the merged config
+- CLI overrides work automatically
+- Priority-based merging (defaults → named configs → CLI → lazy evaluation)
+
 ---
 
 ## Table of Contents
 
 - [ADict: Enhanced Dictionary](#adict-enhanced-dictionary)
 - [Scope: Configuration Management](#scope-configuration-management)
-  - [MultiScope: Namespace Isolation](#2-multiscope---multiple-configuration-contexts) ⭐ Unique to Ato
-  - [Config Documentation & Debugging](#5-configuration-documentation--inspection) ⭐ Unique to Ato
+  - [MultiScope: Namespace Isolation](#multiscope-namespace-isolation)
+  - [Config Documentation & Debugging](#configuration-documentation--debugging)
 - [SQL Tracker: Experiment Tracking](#sql-tracker-experiment-tracking)
 - [Hyperparameter Optimization](#hyperparameter-optimization)
 - [Best Practices](#best-practices)
-- [Comparison with Hydra](#ato-vs-hydra)
+- [Contributing](#contributing)
+- [Composability](#composability)
 
 ---
 
 ## ADict: Enhanced Dictionary
 
-`ADict` is an enhanced dictionary designed for managing experiment configurations. It combines the simplicity of Python dictionaries with powerful features for ML workflows.
+`ADict` is an enhanced dictionary for managing experiment configurations.
 
 ### Core Features
 
-These are the fundamental capabilities that make ADict powerful for experiment management:
-
 | Feature | Description | Why It Matters |
 |---------|-------------|----------------|
-| **Structural Hashing** | Hash based on keys + types, not values | Track when experiment structure changes |
+| **Structural Hashing** | Hash based on keys + types, not values | Track when experiment **structure** changes (not just hyperparameters) |
 | **Nested Access** | Dot notation for nested configs | `config.model.lr` instead of `config['model']['lr']` |
 | **Format Agnostic** | Load/save JSON, YAML, TOML, XYZ | Work with any config format |
-| **Safe Updates** | `update_if_absent()` method | Prevent accidental overwrites |
+| **Safe Updates** | `update_if_absent()` method | Merge configs without accidental overwrites |
+| **Auto-nested** | `ADict.auto()` for lazy creation | `config.a.b.c = 1` just works - no KeyError |
 
-### Developer Convenience Features
+### Examples
 
-These utilities maximize developer productivity and reduce boilerplate:
-
-| Feature | Description | Benefit |
-|---------|-------------|---------|
-| **Auto-nested (`ADict.auto()`)** | Infinite depth lazy creation | `config.a.b.c = 1` just works - no KeyError |
-| **Attribute-style Assignment** | `config.lr = 0.1` | Cleaner, more readable code |
-| **Conditional Updates** | Only update missing keys | Merge configs safely |
-
-### Quick Examples
+#### Structural Hashing
 
 ```python
 from ato.adict import ADict
 
-# Structural hashing - track config structure changes
+# 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
 
-config3 = ADict(lr=0.1, epochs='100', model='resnet50')  # epochs is str!
+# Different structure (epochs is str!)
+config3 = ADict(lr=0.1, epochs='100', model='resnet50')
 print(config1.get_structural_hash() == config3.get_structural_hash())  # False
-
-# 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
 ```
 
-### Convenience Features in Detail
-
-#### Auto-nested: Zero Boilerplate Config Building
-
-The most loved feature - no more manual nesting:
+#### Auto-nested Configs
 
 ```python
 # ❌ Traditional way
@@ -168,48 +165,24 @@ config.model.backbone.layers = [64, 128, 256]  # Just works!
 config.data.augmentation.brightness = 0.2
 ```
 
-**Perfect for Scope integration**:
-
-```python
-from ato.scope import Scope
-
-scope = Scope()
-
-@scope.observe(default=True)
-def config(cfg):
-    # No pre-definition needed!
-    cfg.training.optimizer.name = 'AdamW'
-    cfg.training.optimizer.lr = 0.001
-    cfg.model.encoder.num_layers = 12
-```
-
-**Works with CLI**:
-
-```bash
-python train.py model.backbone.resnet.depth=50 data.batch_size=32
-```
-
-#### More Convenience Utilities
+#### Format Agnostic
 
 ```python
-# Attribute-style access
-config.lr = 0.1
-print(config.lr)  # Instead of config['lr']
-
-# Nested access
-print(config.model.backbone.type)  # Clean and readable
+# Load/save any format
+config = ADict.from_file('config.json')
+config.dump('config.yaml')
 
-# Conditional updates - merge configs safely
-base_config.update_if_absent(**experiment_config)
+# Safe updates
+config.update_if_absent(lr=0.01, scheduler='cosine')  # Only adds scheduler
 ```
 
 ---
 
 ## Scope: Configuration Management
 
-Scope solves configuration complexity through **priority-based merging** and **CLI integration**. No more scattered config files or hard-coded parameters.
+Scope manages configuration through **priority-based merging** and **CLI integration**.
 
-### Key Concepts
+### Key Concept: Priority Chain
 
 ```
 Default Configs (priority=0)
@@ -249,17 +222,17 @@ if __name__ == '__main__':
 
 ```python
 @scope.observe(default=True)  # Always applied
-def defaults(cfg):
-    cfg.lr = 0.001
-    cfg.epochs = 100
+def defaults(config):
+    config.lr = 0.001
+    config.epochs = 100
 
 @scope.observe(priority=1)  # Applied after defaults
-def high_lr(cfg):
-    cfg.lr = 0.01
+def high_lr(config):
+    config.lr = 0.01
 
 @scope.observe(priority=2)  # Applied last
-def long_training(cfg):
-    cfg.epochs = 300
+def long_training(config):
+    config.epochs = 300
 ```
 
 ```bash
@@ -288,27 +261,25 @@ python train.py my_config lr=0.001 batch_size=128
 
 **Note**: Wrap strings with `%` (e.g., `%resnet101%`) instead of quotes.
 
-### Advanced Features
-
-#### 1. Lazy Evaluation - Dynamic Configuration
+### Lazy Evaluation
 
 Sometimes you need configs that depend on other values set via CLI:
 
 ```python
 @scope.observe()
-def base_config(cfg):
-    cfg.model = 'resnet50'
-    cfg.dataset = 'imagenet'
+def base_config(config):
+    config.model = 'resnet50'
+    config.dataset = 'imagenet'
 
 @scope.observe(lazy=True)  # Evaluated AFTER CLI args
-def computed_config(cfg):
+def computed_config(config):
     # Adjust based on dataset
-    if cfg.dataset == 'imagenet':
-        cfg.num_classes = 1000
-        cfg.image_size = 224
-    elif cfg.dataset == 'cifar10':
-        cfg.num_classes = 10
-        cfg.image_size = 32
+    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
@@ -320,29 +291,20 @@ python train.py dataset=%cifar10% computed_config
 
 ```python
 @scope.observe()
-def my_config(cfg):
-    cfg.model = 'resnet50'
-    cfg.num_layers = 50
+def my_config(config):
+    config.model = 'resnet50'
+    config.num_layers = 50
 
     with Scope.lazy():  # Evaluated after CLI
-        if cfg.model == 'resnet101':
-            cfg.num_layers = 101
+        if config.model == 'resnet101':
+            config.num_layers = 101
 ```
 
-#### 2. MultiScope - Multiple Configuration Contexts
+### MultiScope: Namespace Isolation
 
-**Unique to Ato**: Manage completely separate configuration namespaces. Unlike Hydra's config groups, MultiScope provides true **namespace isolation** with independent priority systems.
+Manage completely separate configuration namespaces with independent priority systems.
 
-##### Why MultiScope?
-
-| Challenge | Hydra's Approach | Ato's MultiScope |
-|-----------|------------------|---------------------|
-| Separate model/data configs | Config groups in one namespace | **Independent scopes with own priorities** |
-| Avoid key collisions | Manual prefixing (`model.lr`, `train.lr`) | **Automatic namespace isolation** |
-| Different teams/modules | Single config file | **Each scope can be owned separately** |
-| Priority conflicts | Global priority system | **Per-scope priority system** |
-
-##### Basic Usage
+**Use case**: Different teams own different scopes without key collisions.
 
 ```python
 from ato.scope import Scope, MultiScope
@@ -354,84 +316,103 @@ scope = MultiScope(model_scope, data_scope)
 @model_scope.observe(default=True)
 def model_config(model):
     model.backbone = 'resnet50'
-    model.pretrained = True
+    model.lr = 0.1  # Model-specific learning rate
 
 @data_scope.observe(default=True)
 def data_config(data):
     data.dataset = 'cifar10'
-    data.batch_size = 32
+    data.lr = 0.001  # Data augmentation learning rate (no conflict!)
 
 @scope
 def train(model, data):  # Named parameters match scope names
-    print(f"Training {model.backbone} on {data.dataset}")
+    # Both have 'lr' but in separate namespaces!
+    print(f"Model LR: {model.lr}, Data LR: {data.lr}")
 ```
 
-##### Real-world: Team Collaboration
+**Key advantage**: `model.lr` and `data.lr` are completely independent. No need for naming conventions like `model_lr` vs `data_lr`.
 
-Different team members can own different scopes without conflicts:
+**CLI with MultiScope:**
 
-```python
-# team_model.py - ML team owns this
-model_scope = Scope(name='model')
+```bash
+# Override model scope only
+python train.py model.backbone=%resnet101%
 
-@model_scope.observe(default=True)
-def resnet_default(model):
-    model.backbone = 'resnet50'
-    model.lr = 0.1  # Model-specific learning rate
+# Override data scope only
+python train.py data.dataset=%imagenet%
 
-@model_scope.observe(priority=1)
-def resnet101(model):
-    model.backbone = 'resnet101'
-    model.lr = 0.05  # Different lr for bigger model
+# Override both
+python train.py model.backbone=%resnet101% data.dataset=%imagenet%
+```
 
-# team_data.py - Data team owns this
-data_scope = Scope(name='data')
+### Configuration Documentation & Debugging
 
-@data_scope.observe(default=True)
-def cifar_default(data):
-    data.dataset = 'cifar10'
-    data.lr = 0.001  # Data augmentation learning rate (no conflict!)
+**The `manual` command** visualizes the exact order of configuration application.
 
-@data_scope.observe(priority=1)
-def imagenet(data):
-    data.dataset = 'imagenet'
-    data.workers = 16
+```python
+@scope.observe(default=True)
+def config(config):
+    config.lr = 0.001
+    config.batch_size = 32
+    config.model = 'resnet50'
 
-# train.py - Integration point
-from team_model import model_scope
-from team_data import data_scope
+@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.)'
+```
 
-scope = MultiScope(model_scope, data_scope)
+```bash
+python train.py manual
+```
 
-@scope
-def train(model, data):
-    # Both have 'lr' but in separate namespaces!
-    print(f"Model LR: {model.lr}, Data LR: {data.lr}")
+**Output:**
 ```
+--------------------------------------------------
+[Scope "config"]
+(The Applying Order of Views)
+config → (CLI Inputs)
 
-**Key advantage**: `model.lr` and `data.lr` are completely independent. No need for naming conventions like `model_lr` vs `data_lr`.
+(User Manuals)
+lr: Learning rate for optimizer
+batch_size: Number of samples per batch
+model: Model architecture (resnet50, resnet101, etc.)
+--------------------------------------------------
+```
 
-##### CLI with MultiScope
+**Why this matters:**
+When debugging "why is this config value not what I expect?", you can see **exactly** which function set it and in what order.
 
-Override each scope independently:
+**Complex example:**
 
-```bash
-# Override model scope only
-python train.py model.backbone=%resnet101%
+```python
+@scope.observe(default=True)
+def defaults(config):
+    config.lr = 0.001
 
-# Override data scope only
-python train.py data.dataset=%imagenet%
+@scope.observe(priority=1)
+def experiment_config(config):
+    config.lr = 0.01
 
-# Override both
-python train.py model.backbone=%resnet101% data.dataset=%imagenet%
+@scope.observe(priority=2)
+def another_config(config):
+    config.lr = 0.1
 
-# Call named configs per scope
-python train.py resnet101 imagenet
+@scope.observe(lazy=True)
+def adaptive_lr(config):
+    if config.batch_size > 64:
+        config.lr = config.lr * 2
 ```
 
-#### 3. Import/Export Configs
+When you run `python train.py manual`, you see:
+```
+(The Applying Order of Views)
+defaults → experiment_config → another_config → (CLI Inputs) → adaptive_lr
+```
 
-Ato supports importing configs from multiple frameworks:
+Now it's **crystal clear** why `lr=0.1` (from `another_config`) and not `0.01`!
+
+### Config Import/Export
 
 ```python
 @scope.observe()
@@ -442,36 +423,26 @@ def load_external(config):
 
     # Export to any format
     config.dump('output/final_config.toml')
-
-    # Import OpenMMLab configs - handles _base_ inheritance automatically
-    config.load_mm_config('mmdet_configs/faster_rcnn.py')
 ```
 
-**OpenMMLab compatibility** is built-in:
-- Automatically resolves `_base_` inheritance chains
-- Supports `_delete_` keys for config overriding
-- Makes migration from MMDetection/MMSegmentation/etc. seamless
+**OpenMMLab compatibility:**
 
-**Hydra-style config composition** is also built-in via `compose_hierarchy`:
+```python
+# Import OpenMMLab configs - handles _base_ inheritance automatically
+config.load_mm_config('mmdet_configs/faster_rcnn.py')
+```
+
+**Hierarchical composition:**
 
 ```python
 from ato.adict import ADict
 
-# Hydra-style directory structure:
-# configs/
-#   ├── config.yaml          # base config
-#   ├── model/
-#   │   ├── resnet50.yaml
-#   │   └── resnet101.yaml
-#   └── data/
-#       ├── cifar10.yaml
-#       └── imagenet.yaml
-
+# Load configs from directory structure
 config = ADict.compose_hierarchy(
     root='configs',
     config_filename='config',
     select={
-        'model': 'resnet50',      # or ['resnet50', 'resnet101'] for multiple
+        'model': 'resnet50',
         'data': 'imagenet'
     },
     overrides={
@@ -483,16 +454,7 @@ config = ADict.compose_hierarchy(
 )
 ```
 
-**Key features**:
-- Config groups (model/, data/, optimizer/, etc.)
-- Automatic file discovery (tries .yaml, .json, .toml, .xyz)
-- Dotted overrides (`model.lr=0.01`)
-- Required key validation
-- Flexible error handling
-
-#### 4. Argparse Integration
-
-Mix Ato with existing argparse code:
+### Argparse Integration
 
 ```python
 from ato.scope import Scope
@@ -504,170 +466,24 @@ parser.add_argument('--gpu', type=int, default=0)
 parser.add_argument('--seed', type=int, default=42)
 
 @scope.observe(default=True)
-def config(cfg):
-    cfg.lr = 0.001
-    cfg.batch_size = 32
+def config(config):
+    config.lr = 0.001
+    config.batch_size = 32
 
 @scope
-def train(cfg):
-    print(f"GPU: {cfg.gpu}, LR: {cfg.lr}")
+def train(config):
+    print(f"GPU: {config.gpu}, LR: {config.lr}")
 
 if __name__ == '__main__':
     parser.parse_args()  # Merges argparse with scope
     train()
 ```
 
-#### 5. Configuration Documentation & Inspection
-
-**One of Ato's most powerful features**: Auto-generate documentation AND visualize the exact order of configuration application.
-
-##### Basic Documentation
-
-```python
-@scope.manual
-def config_docs(cfg):
-    cfg.lr = 'Learning rate for optimizer'
-    cfg.batch_size = 'Number of samples per batch'
-    cfg.model = 'Model architecture (resnet50, resnet101, etc.)'
-```
-
-```bash
-python train.py manual
-```
-
-**Output:**
-```
---------------------------------------------------
-[Scope "config"]
-(The Applying Order of Views)
-defaults → (CLI Inputs) → lazy_config → main
-
-(User Manuals)
-config.lr: Learning rate for optimizer
-config.batch_size: Number of samples per batch
-config.model: Model architecture (resnet50, resnet101, etc.)
---------------------------------------------------
-```
-
-##### Why This Matters
-
-The **applying order visualization** shows you **exactly** how your configs are merged:
-- Which config functions are applied (in order)
-- When CLI inputs override values
-- Where lazy configs are evaluated
-- The final function that uses the config
-
-**This prevents configuration bugs** by making the merge order explicit and debuggable.
-
-##### MultiScope Documentation
-
-For complex projects with multiple scopes, `manual` shows each scope separately:
-
-```python
-from ato.scope import Scope, MultiScope
-
-model_scope = Scope(name='model')
-train_scope = Scope(name='train')
-scope = MultiScope(model_scope, train_scope)
-
-@model_scope.observe(default=True)
-def model_defaults(model):
-    model.backbone = 'resnet50'
-    model.num_layers = 50
-
-@model_scope.observe(priority=1)
-def model_advanced(model):
-    model.pretrained = True
-
-@model_scope.observe(lazy=True)
-def model_lazy(model):
-    if model.backbone == 'resnet101':
-        model.num_layers = 101
-
-@train_scope.observe(default=True)
-def train_defaults(train):
-    train.lr = 0.001
-    train.epochs = 100
-
-@model_scope.manual
-def model_docs(model):
-    model.backbone = 'Model backbone architecture'
-    model.num_layers = 'Number of layers in the model'
-
-@train_scope.manual
-def train_docs(train):
-    train.lr = 'Learning rate for optimizer'
-    train.epochs = 'Total training epochs'
-
-@scope
-def main(model, train):
-    print(f"Training {model.backbone} with lr={train.lr}")
-
-if __name__ == '__main__':
-    main()
-```
-
-```bash
-python train.py manual
-```
-
-**Output:**
-```
---------------------------------------------------
-[Scope "model"]
-(The Applying Order of Views)
-model_defaults → model_advanced → (CLI Inputs) → model_lazy → main
-
-(User Manuals)
-model.backbone: Model backbone architecture
-model.num_layers: Number of layers in the model
---------------------------------------------------
-[Scope "train"]
-(The Applying Order of Views)
-train_defaults → (CLI Inputs) → main
-
-(User Manuals)
-train.lr: Learning rate for optimizer
-train.epochs: Total training epochs
---------------------------------------------------
-```
-
-##### Real-world Example
-
-This is especially valuable when debugging why a config value isn't what you expect:
-
-```python
-@scope.observe(default=True)
-def defaults(cfg):
-    cfg.lr = 0.001
-
-@scope.observe(priority=1)
-def experiment_config(cfg):
-    cfg.lr = 0.01
-
-@scope.observe(priority=2)
-def another_config(cfg):
-    cfg.lr = 0.1
-
-@scope.observe(lazy=True)
-def adaptive_lr(cfg):
-    if cfg.batch_size > 64:
-        cfg.lr = cfg.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 → main
-```
-
-Now it's **crystal clear** why `lr=0.1` (from `another_config`) and not `0.01`!
-
 ---
 
 ## SQL Tracker: Experiment Tracking
 
-Lightweight experiment tracking using SQLite - no external services, no setup complexity.
+Lightweight experiment tracking using SQLite.
 
 ### Why SQL Tracker?
 
@@ -675,6 +491,7 @@ Lightweight experiment tracking using SQLite - no external services, no setup co
 - **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, sync to cloud tracking later if needed
 
 ### Database Schema
 
@@ -690,7 +507,7 @@ Project (my_ml_project)
 └── ...
 ```
 
-### Quick Start
+### Usage
 
 #### Logging Experiments
 
@@ -764,22 +581,7 @@ stats = finder.get_trace_statistics('image_classification', trace_id='model_forw
 print(f"Model forward pass has {stats['static_trace_versions']} versions")
 ```
 
-### Real-world Example: Experiment Comparison
-
-```python
-# Compare hyperparameter impact
-finder = SQLFinder(config)
-
-runs = finder.get_runs_in_project('my_project')
-for run in runs:
-    # Get final accuracy
-    final_metrics = [m for m in run.metrics if m.key == 'val_accuracy']
-    best_acc = max(m.value for m in final_metrics) if final_metrics else 0
-
-    print(f"LR: {run.config.lr}, Batch: {run.config.batch_size} → Acc: {best_acc:.2%}")
-```
-
-### Features Summary
+### Features
 
 | Feature | Description |
 |---------|-------------|
@@ -795,38 +597,6 @@ for run in runs:
 
 Built-in **Hyperband** algorithm for efficient hyperparameter search with early stopping.
 
-### Extensible Design
-
-Ato's hyperopt module is built for extensibility and reusability:
-
-| Component | Purpose | Benefit |
-|-----------|---------|---------|
-| `GridSpaceMixIn` | Parameter sampling logic | Reusable across different algorithms |
-| `HyperOpt` | Base optimization class | Easy to implement custom strategies |
-| `DistributedMixIn` | Distributed training support | Optional, composable |
-
-**This design makes it trivial to implement custom search algorithms**:
-
-```python
-from ato.hyperopt.base import GridSpaceMixIn, HyperOpt
-
-class RandomSearch(GridSpaceMixIn, HyperOpt):
-    def main(self, func):
-        # Reuse GridSpaceMixIn.prepare_distributions()
-        configs = self.prepare_distributions(self.config, self.search_spaces)
-
-        # Implement random sampling
-        import random
-        random.shuffle(configs)
-
-        results = []
-        for config in configs[:10]:  # Sample 10 random configs
-            metric = func(config)
-            results.append((config, metric))
-
-        return max(results, key=lambda x: x[1])
-```
-
 ### How Hyperband Works
 
 Hyperband uses successive halving:
@@ -895,8 +665,6 @@ if __name__ == '__main__':
 
 ### Automatic Step Calculation
 
-Let Hyperband compute optimal training steps:
-
 ```python
 hyperband = HyperBand(scope, search_spaces, halving_rate=0.3, num_min_samples=4)
 
@@ -926,9 +694,7 @@ Space types:
 - `LOG`: Logarithmic spacing (good for learning rates)
 - `LINEAR`: Linear spacing (default)
 
-### Distributed Hyperparameter Search
-
-Ato supports distributed hyperparameter optimization out of the box:
+### Distributed Search
 
 ```python
 from ato.hyperopt.hyperband import DistributedHyperBand
@@ -965,11 +731,37 @@ if __name__ == '__main__':
         print(f"Best config: {result.config}")
 ```
 
-**Key features**:
-- Automatic work distribution across GPUs
-- Synchronized config selection via `broadcast_object_from_root`
-- Results aggregation with `all_gather_object`
-- Compatible with PyTorch DDP, FSDP, DeepSpeed
+### Extensible Design
+
+Ato's hyperopt module is built for extensibility:
+
+| Component | Purpose |
+|-----------|---------|
+| `GridSpaceMixIn` | Parameter sampling logic (reusable) |
+| `HyperOpt` | Base optimization class |
+| `DistributedMixIn` | Distributed training support (optional) |
+
+**Example: Implement custom search algorithm**
+
+```python
+from ato.hyperopt.base import GridSpaceMixIn, HyperOpt
+
+class RandomSearch(GridSpaceMixIn, HyperOpt):
+    def main(self, func):
+        # Reuse GridSpaceMixIn.prepare_distributions()
+        configs = self.prepare_distributions(self.config, self.search_spaces)
+
+        # Implement random sampling
+        import random
+        random.shuffle(configs)
+
+        results = []
+        for config in configs[:10]:  # Sample 10 random configs
+            metric = func(config)
+            results.append((config, metric))
+
+        return max(results, key=lambda x: x[1])
+```
 
 ---
 
@@ -997,33 +789,34 @@ my_project/
 ```python
 # configs/default.py
 from ato.scope import Scope
+from ato.adict import ADict
 
 scope = Scope()
 
 @scope.observe(default=True)
-def defaults(cfg):
+def defaults(config):
     # Data
-    cfg.data = ADict(
+    config.data = ADict(
         dataset='cifar10',
         batch_size=32,
         num_workers=4
     )
 
     # Model
-    cfg.model = ADict(
+    config.model = ADict(
         backbone='resnet50',
         pretrained=True
     )
 
     # Training
-    cfg.train = ADict(
+    config.train = ADict(
         lr=0.001,
         epochs=100,
         optimizer='adam'
     )
 
     # Experiment tracking
-    cfg.experiment = ADict(
+    config.experiment = ADict(
         project_name='my_project',
         sql=ADict(db_path='sqlite:///experiments.db')
     )
@@ -1037,14 +830,14 @@ from ato.db_routers.sql.manager import SQLLogger
 from configs.default import scope
 
 @scope
-def train(cfg):
+def train(config):
     # Setup experiment tracking
-    logger = SQLLogger(cfg)
-    run_id = logger.run(tags=[cfg.model.backbone, cfg.data.dataset])
+    logger = SQLLogger(config)
+    run_id = logger.run(tags=[config.model.backbone, config.data.dataset])
 
     try:
         # Training loop
-        for epoch in range(cfg.train.epochs):
+        for epoch in range(config.train.epochs):
             loss = train_epoch()
             acc = validate()
 
@@ -1082,12 +875,6 @@ See `pyproject.toml` for full dependencies.
 
 ---
 
-## License
-
-MIT License
-
----
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit issues or pull requests.
@@ -1100,82 +887,92 @@ cd ato
 pip install -e .
 ```
 
+### Quality Assurance
+
+Ato's design philosophy — **structural neutrality** and **debuggable composition** — extends to our testing practices.
+
+**Release Policy:**
+- **All 100+ unit tests must pass before any release**
+- No exceptions, no workarounds
+- Tests cover every module: ADict, Scope, MultiScope, SQLTracker, HyperBand
+
+**Why this matters:**
+When you build on Ato, you're trusting it to stay out of your way. That means zero regressions, predictable behavior, and reliable APIs. Comprehensive test coverage ensures that each component works independently and composes correctly.
+
+Run tests locally:
+```bash
+python -m pytest unit_tests/
+```
+
 ---
 
-## Comparison with Other Tools
-
-| Feature | Ato | MLflow | W&B | Hydra |
-|---------|--------|--------|-----|-------|
-| **Core Features** |
-| Zero setup | ✅ | ❌ | ❌ | ✅ |
-| Offline-first | ✅ | Partial | ❌ | ✅ |
-| Config priority system | ✅ Explicit | Partial (Tags) | Partial (Run params) | ✅ Override |
-| **True namespace isolation** | **✅ MultiScope** | **❌** | **❌** | **❌ Config groups only** |
-| **Config merge visualization** | **✅ `manual`** | **❌** | **❌** | **Partial (`--cfg` tree)** |
-| Structural hashing | ✅ | ❌ | ❌ | ❌ |
-| Built-in HyperOpt | ✅ Hyperband | ❌ | ✅ Sweeps | Plugins (Optuna) |
-| CLI-first design | ✅ | ❌ | ❌ | ✅ |
-| **Compatibility** |
-| Framework agnostic | ✅ | ✅ | ✅ | ✅ |
-| Distributed training | ✅ Native + DDP/FSDP⁽¹⁾ | ✅ | ✅ | ✅ |
-| Distributed HyperOpt | ✅ `DistributedHyperBand` | ❌ | Partial | Plugins |
-| Hydra-style composition | ✅ `compose_hierarchy` | N/A | N/A | Native |
-| OpenMMLab configs | ✅ `load_mm_config` | ❌ | ❌ | ❌ |
-| **Visualization & UI** |
-| Web dashboard | 🔜 Planned | ✅ | ✅ | ❌ |
-| Real-time metrics | 🔜 Planned | ✅ | ✅ | ❌ |
-| Interactive plots | 🔜 Planned | ✅ | ✅ | ❌ |
-| Metric comparison UI | 🔜 Planned | ✅ | ✅ | ❌ |
-| **Advanced Features** |
-| Model registry | 🔜 Planned | ✅ | ✅ | ❌ |
-| Dataset versioning | 🔜 Planned | Partial | ✅ | ❌ |
-| Team collaboration | ✅ MultiScope⁽²⁾ | ✅ Platform | ✅ Platform | ❌ |
-
-⁽¹⁾ Native distributed hyperparameter optimization via `DistributedHyperBand`. Regular training is compatible with any distributed framework (DDP, FSDP, DeepSpeed) - just integrate logging, no special code needed.
-
-⁽²⁾ Team collaboration via MultiScope: separate config ownership per team (e.g., Team A owns model scope, Team B owns data scope) without naming conflicts.
-
-**Note on config compatibility**: Ato provides built-in support for other config frameworks:
-- **Hydra-style composition**: `compose_hierarchy()` supports config groups, select, overrides - full compatibility
-- **OpenMMLab configs**: `load_mm_config()` handles `_base_` inheritance and `_delete_` keys
-- Migration from existing projects is seamless - just import your configs and go
-
-### Ato vs. Hydra
-
-While Hydra is excellent for config composition, Ato provides unique features:
-
-| Aspect | Hydra | Ato |
-|--------|-------|--------|
-| **Namespace isolation** | Config groups share namespace | ✅ MultiScope with independent namespaces<br/>(no key collisions) |
-| **Priority system** | Single global override system | ✅ Per-scope priority + lazy evaluation |
-| **Config merge debugging** | Tree view (`--cfg`)<br/>Shows final config | ✅ `manual` command<br/>Shows merge order & execution flow |
-| **Experiment tracking** | Requires external tools<br/>(MLflow/W&B) | ✅ Built-in SQL tracker |
-| **Team workflow** | Single config file ownership | ✅ Separate scope ownership per team⁽³⁾ |
-
-⁽³⁾ Example: Team A defines `model_scope`, Team B defines `data_scope`, both can use `model.lr` and `data.lr` without conflicts.
-
-**Use Ato over Hydra when:**
-- Multiple teams need independent config ownership (MultiScope)
-- You want to avoid key collision issues (no manual prefixing needed)
-- You need to debug why a config value was set (`manual` command)
-- You want experiment tracking without adding MLflow/W&B
-- You're migrating from OpenMMLab projects
-
-**Use Hydra when:**
-- You have very deep config hierarchies with complex inheritance
-- You prefer YAML over Python
-- You need the mature plugin ecosystem (Ray, Joblib, etc.)
-- You don't need namespace isolation
-
-**Why not both?**
-- Ato has **built-in Hydra-style composition** via `compose_hierarchy()`
-- You can use Hydra's directory structure and config groups directly in Ato
-- Get MultiScope + experiment tracking + merge debugging on top of Hydra's composition
-- Migration is literally just replacing `hydra.compose()` with `ADict.compose_hierarchy()`
-
-**Ato is for you if:**
-- You want lightweight, offline-first experiment tracking
-- You need **true namespace isolation for team collaboration**
-- **You want to debug config merge order visually** (unique to Ato!)
-- You prefer simple Python over complex frameworks
-- You want reproducibility without overhead
+## Composability
+
+Ato is designed to **compose** with existing tools, not replace them.
+
+### Works Where Other Systems Require Ecosystems
+
+**Config composition:**
+- Import OpenMMLab configs: `config.load_mm_config('mmdet_configs/faster_rcnn.py')`
+- Load Hydra-style hierarchies: `ADict.compose_hierarchy(root='configs', select={'model': 'resnet50'})`
+- Mix with argparse: `Scope(use_external_parser=True)`
+
+**Experiment tracking:**
+- Track locally in SQLite (zero setup)
+- Sync to MLflow/W&B when you need dashboards
+- Or use both: local SQLite + cloud tracking
+
+**Hyperparameter optimization:**
+- Built-in Hyperband
+- Or compose with Optuna/Ray Tune — Ato's configs work with any optimizer
+
+### Three Capabilities Other Tools Don't Provide
+
+1. **MultiScope** — True namespace isolation with independent priority systems
+2. **`manual` command** — Visualize exact config merge order for debugging
+3. **Structural hashing** — Track when experiment **architecture** changes, not just values
+
+### When to Use Ato
+
+**Use Ato when:**
+- You want zero boilerplate config management
+- You need to debug why a config value isn't what you expect
+- You're working on multi-team projects with namespace conflicts
+- You want local-first experiment tracking
+- You're migrating between config/tracking systems
+
+**Ato works alongside:**
+- Hydra (config composition)
+- MLflow/W&B (cloud tracking)
+- Optuna/Ray Tune (advanced hyperparameter search)
+- PyTorch/TensorFlow/JAX (any ML framework)
+
+---
+
+## Roadmap
+
+Ato's design constraint is **structural neutrality** — adding capabilities without creating dependencies.
+
+### Planned: Local Dashboard (Optional Module)
+
+A lightweight HTML dashboard for teams that want visual exploration without committing to cloud platforms:
+
+**What it adds:**
+- Metric comparison & trends (read-only view of SQLite data)
+- Run history & artifact browsing
+- Config diff visualization
+- Interactive hyperparameter analysis
+
+**Design constraints:**
+- No hard dependency — Ato core works 100% without the dashboard
+- Separate process — doesn't block or modify runs
+- Zero lock-in — delete it anytime, training code doesn't change
+- Composable — use alongside MLflow/W&B
+
+**Guiding principle:** Ato remains a set of **independent, composable tools** — not a platform you commit to.
+
+---
+
+## License
+
+MIT License