ato 2.0.0__py3-none-any.whl → 2.0.3__py3-none-any.whl

{ato-2.0.0.dist-info → ato-2.0.3.dist-info}/METADATA

@@ -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.0.3
+Summary: A frameworkless integration layer for ML pipelines. Ato doesn't compete with frameworks — it restores freedom between them.
 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,37 +32,95 @@ 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.
+## A frameworkless integration layer for Python and ML pipelines
 
----
+**Ato doesn't compete with frameworks — it restores freedom between them.**
+
+Every framework tries to own your workflow.
+Ato doesn't. It just gives you the **handles to connect them**.
+
+Unlike Hydra, MLflow, or W&B — which build ecosystems —
+Ato provides **structural boundaries** that let you compose, track, and optimize
+without surrendering control to any single system.
+
+You can:
+- **Chain** configs from multiple sources (Hydra YAML, OpenMMLab, raw Python)
+- **Merge** them with explicit priority control — and **debug** the exact merge order
+- **Track** experiments in SQLite with zero setup — or sync to MLflow/W&B when you need dashboards
+- **Optimize** hyperparameters with built-in Hyperband — or use Optuna/Ray Tune alongside
+
+Ato keeps everything **transparent** and **Pythonic**.
+No magic. No vendor lock-in. Just composable pieces you control.
+
+<details>
+<summary><strong>Design Philosophy</strong></summary>
+
+Ato was designed from a simple realization:
+**frameworks solve composition, but they also create coupling.**
+
+When I built Ato, I didn't know Hydra existed.
+But I did know I wanted something that wouldn't **own** my workflow —
+something that could **compose** with whatever came next.
+
+That constraint led to three design principles:
+
+1. **Structural neutrality** — Ato has no opinion on your stack.
+   It's a layer, not a platform.
 
-**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.
+2. **Explicit boundaries** — Each module (ADict, Scope, SQLTracker, HyperOpt) is independent.
+   Use one, use all, or mix with other tools. No forced dependencies.
+
+3. **Debuggable composition** — When configs merge from 5 sources, you should see **why** a value was set.
+   Ato's `manual` command shows the exact merge order — a feature no other tool has.
+
+This isn't minimalism for its own sake.
+It's **structural restraint** — interfering only where necessary,
+and staying out of the way everywhere else.
+
+</details>
+
+---
 
 ## Why Ato?
 
-### Core Differentiators
+Ato solves a problem that frameworks create: **workflow ownership**.
+
+| Framework Approach | Ato's Approach |
+|-------------------|----------------|
+| Hydra owns config composition | Ato **composes** Hydra configs + raw Python + CLI args |
+| MLflow owns experiment tracking | Ato tracks locally in SQLite, **or** syncs to MLflow |
+| W&B owns hyperparameter search | Ato provides Hyperband, **or** you use Optuna/Ray |
+| Each framework wants to be **the** system | Ato is **a layer** you control |
+
+**Ato is for teams who want:**
+- Config flexibility without framework lock-in
+- Experiment tracking without mandatory cloud platforms
+- Hyperparameter optimization without opaque black boxes
+- The ability to **change tools** without rewriting pipelines
+
+### What Makes Ato Structurally Different
+
+These aren't features — they're **architectural decisions** that frameworks can't replicate without breaking their own abstractions:
 
-- **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
+| Capability | Why Frameworks Can't Do This | What It Enables |
+|------------|------------------------------|-----------------|
+| **MultiScope** (namespace isolation) | Frameworks use global config namespaces | Multiple teams can own separate config scopes without key collisions. No `model_lr` vs `data_lr` prefixing needed. |
+| **`manual` command** (merge order debugging) | Frameworks show final configs, not merge logic | See **why** a value was set — trace exact merge order across defaults, named configs, CLI args, and lazy evaluation. |
+| **Structural hashing** | Frameworks track values, not structure | Detect when experiment **architecture** changes (not just hyperparameters). Critical for reproducibility. |
+| **Offline-first tracking** | Frameworks assume centralized platforms | Zero-setup SQLite tracking. No servers, no auth, no vendor lock-in. Sync to MLflow/W&B only when needed. |
 
 ### Developer Experience
 
-- **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
+- **Zero boilerplate** — Auto-nested configs (`cfg.model.backbone.depth = 50` just works), lazy evaluation, attribute access
+- **CLI-first** — Override any config from command line without touching code: `python train.py model.backbone=%resnet101%`
+- **Framework agnostic** — Works with PyTorch, TensorFlow, JAX, or pure Python. No framework-specific decorators or magic.
 
 ## Quick Start
 
 ```bash
-pip install ato-python
+pip install ato
 ```
 
 ### 30-Second Example
@@ -99,7 +157,8 @@ if __name__ == '__main__':
 - [SQL Tracker: Experiment Tracking](#sql-tracker-experiment-tracking)
 - [Hyperparameter Optimization](#hyperparameter-optimization)
 - [Best Practices](#best-practices)
-- [Comparison with Hydra](#ato-vs-hydra)
+- [Roadmap](#roadmap-expanding-boundaries-without-breaking-neutrality)
+- [Working with Existing Tools](#working-with-existing-tools)
 
 ---
 
@@ -1088,6 +1147,52 @@ MIT License
 
 ---
 
+## Roadmap: Expanding Boundaries Without Breaking Neutrality
+
+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 MLflow/W&B:
+
+**What it adds:**
+- Metric comparison & trends (read-only view of SQLite data)
+- Run history & artifact browsing
+- Config diff visualization (including structural hash changes)
+- Interactive hyperparameter analysis
+
+**Design constraints:**
+- **No hard dependency** — Ato core works 100% without the dashboard
+- **Separate process** — Dashboard reads from SQLite; doesn't block or modify runs
+- **Zero lock-in** — Remove the dashboard, and your training code doesn't change
+- **Composable** — Use it alongside MLflow/W&B, or replace either one
+
+### Why This Fits Ato's Philosophy
+
+The dashboard is **not** a platform — it's a **view** into data you already own (SQLite).
+
+| What It Doesn't Do | Why That Matters |
+|--------------------|------------------|
+| Doesn't store data | You can delete it without losing experiments |
+| Doesn't require auth | No accounts, no vendors, no network calls |
+| Doesn't modify configs | Pure read-only visualization |
+| Doesn't couple to Ato's core | Works with any SQLite database |
+
+This preserves Ato's design principle: **provide handles, not ownership.**
+
+### Modular Adoption Path
+
+| What You Need | What You Use |
+|---------------|--------------|
+| Just configs | `ADict` + `Scope` — no DB, no UI |
+| Headless tracking | Add SQLTracker — still no UI |
+| Local visualization | Add dashboard daemon — run/stop anytime |
+| Team collaboration | Sync to MLflow/W&B dashboards |
+
+**Guiding principle:** Ato remains a set of **independent, composable tools** — not a platform you commit to.
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit issues or pull requests.
@@ -1102,80 +1207,108 @@ pip install -e .
 
 ---
 
-## 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
+## Working with Existing Tools
+
+**Ato is an integration layer, not a replacement.**
+
+It's designed to **compose** with Hydra, MLflow, W&B, and whatever tools you already use.
+The goal isn't to compete — it's to **give you handles** for connecting systems without coupling your workflow to any single platform.
+
+### Composition Strategy
+
+Ato provides three structural capabilities that frameworks don't:
+
+| What Ato Adds | Why It Matters | How It Composes |
+|---------------|----------------|-----------------|
+| **MultiScope** | True namespace isolation | Multiple config sources (Hydra, raw Python, CLI) coexist without key collisions |
+| **`manual` command** | Config merge order visualization | Debug **why** a value was set — see exact merge order across all sources |
+| **Offline-first tracking** | Zero-setup SQLite tracking | Track locally, **then** sync to MLflow/W&B only when you need dashboards |
+
+These aren't "features" — they're **structural boundaries** that let you compose tools freely.
+
+### Ato + Hydra: Designed to Compose
+
+Ato has **native Hydra composition** via `compose_hierarchy()`:
+
+```python
+from ato.adict import ADict
+
+# Load Hydra-style configs directly
+config = ADict.compose_hierarchy(
+    root='configs',
+    config_filename='config',
+    select={'model': 'resnet50', 'data': 'imagenet'},
+    overrides={'model.lr': 0.01}
+)
+
+# Now add Ato's structural boundaries:
+# - MultiScope for independent namespaces
+# - `manual` command to debug merge order
+# - SQLite tracking without MLflow overhead
+```
+
+**You're not replacing Hydra** — you're **extending** it with namespace isolation and debuggable composition.
+
+### Integration Matrix
+
+Ato is designed to work **between** frameworks:
+
+| Tool | What It Owns | What Ato Adds |
+|------|--------------|---------------|
+| **Hydra** | Config composition from YAML | MultiScope (namespace isolation) + merge debugging |
+| **MLflow** | Centralized experiment platform | Local-first SQLite tracking + structural hashing |
+| **W&B** | Cloud-based tracking + dashboards | Offline tracking + sync when ready |
+| **OpenMMLab** | Config inheritance (`_base_`) | Direct import via `load_mm_config()` |
+| **Optuna/Ray Tune** | Advanced hyperparameter search | Built-in Hyperband + composable with their optimizers |
+
+### Composition Patterns
+
+**Pattern 1: Ato as the integration layer**
+```
+Hydra (config source) → Ato (composition + tracking) → MLflow (dashboards)
+```
+
+**Pattern 2: Ato for local development**
+```
+Local experiments: Ato (full stack)
+Production: Ato → MLflow (centralized tracking)
+```
+
+**Pattern 3: Gradual adoption**
+```
+Start: Ato alone (zero dependencies)
+Scale: Add Hydra for complex configs
+Collaborate: Sync to W&B for team dashboards
+```
+
+### When to Use What
+
+**Use Ato alone** when:
+- You want zero external dependencies
+- You need namespace isolation (MultiScope)
+- You want to debug config merge order
+
+**Compose with Hydra** when:
+- Your team already has Hydra YAML configs
+- You need deep config hierarchies + namespace isolation
+- You want to see **why** a Hydra config set a value (`manual` command)
+
+**Compose with MLflow/W&B** when:
+- You want local-first tracking with optional cloud sync
+- You need structural hashing + offline SQLite
+- You're migrating between tracking platforms
+
+**You don't need Ato** if:
+- You're fully committed to a single framework ecosystem
+- You don't need debuggable config composition
+- You never switch between tools
+
+### What Ato Doesn't Do
+
+Ato intentionally **doesn't** build an ecosystem:
+- No web dashboards → Use MLflow/W&B
+- No model registry → Use MLflow
+- No dataset versioning → Use DVC/W&B
+- No plugin marketplace → Use Hydra
+
+**Ato's goal:** Stay out of your way. Provide handles. Let you change tools without rewriting code.

{ato-2.0.0.dist-info → ato-2.0.3.dist-info}/RECORD

@@ -11,8 +11,8 @@ ato/db_routers/sql/schema.py,sha256=3eRF1oMnoebEh1QA39aqgcnTSe0h9JAXBfExAD0sPGY,
 ato/hyperopt/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ato/hyperopt/base.py,sha256=Wtu3l9FPB32exoUYEHKQf3r19U_l24_i-rle429uFbY,5188
 ato/hyperopt/hyperband.py,sha256=05qGvff0UAec4bTaaiCFa-FBRG0fIdVATaZu4vUiV5M,4233
-ato-2.0.0.dist-info/licenses/LICENSE,sha256=xrPRlaFeOLIYXHXJOsc7dhA2h1Jrcjw8t63M7OcVN6c,1071
-ato-2.0.0.dist-info/METADATA,sha256=ae_EKGvwbsq2cbslgjIXiIEA1mz8tLpXO3377ggKN2I,33292
-ato-2.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ato-2.0.0.dist-info/top_level.txt,sha256=Ea_cEtrnO1ir26dBT1CK_Mj6vK36sd9oSAu6WjtQkAU,4
-ato-2.0.0.dist-info/RECORD,,
+ato-2.0.3.dist-info/licenses/LICENSE,sha256=xrPRlaFeOLIYXHXJOsc7dhA2h1Jrcjw8t63M7OcVN6c,1071
+ato-2.0.3.dist-info/METADATA,sha256=676RCPgQwliZ2DTDxb91AIvR__jq_h2YFauwzSjwEWQ,37901
+ato-2.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ato-2.0.3.dist-info/top_level.txt,sha256=Ea_cEtrnO1ir26dBT1CK_Mj6vK36sd9oSAu6WjtQkAU,4
+ato-2.0.3.dist-info/RECORD,,