ml-dash 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

ml_dash-0.5.1.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.3
+Name: ml-dash
+Version: 0.5.1
+Summary: ML experiment metricing and data storage
+Keywords: machine-learning,experiment-metricing,mlops,data-storage
+Author: Ge Yang, Tom Tao
+License: MIT License
+         
+         Copyright (c) 2025 Ge Yang, Tom Tao
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
+Requires-Dist: sphinx>=7.2.0 ; extra == 'dev'
+Requires-Dist: furo>=2024.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-autodoc-typehints>=2.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-autobuild>=2024.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-copybutton>=0.5.0 ; extra == 'dev'
+Requires-Dist: sphinx-design>=0.5.0 ; extra == 'dev'
+Requires-Dist: sphinx-tabs>=3.4.0 ; extra == 'dev'
+Requires-Dist: sphinxcontrib-mermaid>=0.9.0 ; extra == 'dev'
+Requires-Dist: sphinxext-opengraph>=0.9.0 ; extra == 'dev'
+Requires-Dist: myst-parser>=2.0.0 ; extra == 'dev'
+Requires-Dist: linkify-it-py>=2.0.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.3.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.9.0 ; extra == 'dev'
+Requires-Python: >=3.9
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# ML-Dash
+
+A simple and flexible SDK for ML experiment metricing and data storage.
+
+## Features
+
+- **Three Usage Styles**: Decorator, context manager, or direct instantiation
+- **Dual Operation Modes**: Remote (API server) or local (filesystem)
+- **Auto-creation**: Automatically creates namespace, project, and folder hierarchy
+- **Upsert Behavior**: Updates existing experiments or creates new ones
+- **Experiment Lifecycle**: Automatic status tracking (RUNNING, COMPLETED, FAILED, CANCELLED)
+- **Organized File Storage**: Prefix-based file organization with unique snowflake IDs
+- **Rich Metadata**: Tags, bindrs, descriptions, and custom metadata support
+- **Simple API**: Minimal configuration, maximum flexibility
+
+## Installation
+
+<table>
+<tr>
+<td>Using uv (recommended)</td>
+<td>Using pip</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv add ml-dash
+```
+
+</td>
+<td>
+
+```bash
+pip install ml-dash
+```
+
+</td>
+</tr>
+</table>
+
+## Quick Start
+
+### Remote Mode (with API Server)
+
+```python
+from ml_dash import Experiment
+
+with Experiment(
+    name="my-experiment",
+    project="my-project",
+    remote="https://cu3thurmv3.us-east-1.awsapprunner.com",
+    api_key="your-jwt-token"
+) as experiment:
+    print(f"Experiment ID: {experiment.id}")
+```
+
+### Local Mode (Filesystem)
+
+```python
+from ml_dash import Experiment
+
+with Experiment(
+    name="my-experiment",
+    project="my-project",
+    local_path=".ml-dash"
+) as experiment:
+    pass  # Your code here
+```
+
+See [examples/](examples/) for more complete examples.
+
+## Development Setup
+
+### Installing Dev Dependencies
+
+To contribute to ML-Dash or run tests, install the development dependencies:
+
+<table>
+<tr>
+<td>Using uv (recommended)</td>
+<td>Using pip</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv sync --extra dev
+```
+
+</td>
+<td>
+
+```bash
+pip install -e ".[dev]"
+```
+
+</td>
+</tr>
+</table>
+
+This installs:
+- `pytest>=8.0.0` - Testing framework
+- `pytest-asyncio>=0.23.0` - Async test support
+- `sphinx>=7.2.0` - Documentation builder
+- `sphinx-rtd-theme>=2.0.0` - Read the Docs theme
+- `sphinx-autobuild>=2024.0.0` - Live preview for documentation
+- `myst-parser>=2.0.0` - Markdown support for Sphinx
+- `ruff>=0.3.0` - Linter and formatter
+- `mypy>=1.9.0` - Type checker
+
+### Running Tests
+
+<table>
+<tr>
+<td>Using uv</td>
+<td>Using pytest directly</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv run pytest
+```
+
+</td>
+<td>
+
+```bash
+pytest
+```
+
+</td>
+</tr>
+</table>
+
+### Building Documentation
+
+Documentation is built using Sphinx with Read the Docs theme.
+
+<table>
+<tr>
+<td>Build docs</td>
+<td>Live preview</td>
+<td>Clean build</td>
+</tr>
+<tr>
+<td>
+
+```bash
+uv run python -m sphinx -b html docs docs/_build/html
+```
+
+</td>
+<td>
+
+```bash
+uv run sphinx-autobuild docs docs/_build/html
+```
+
+</td>
+<td>
+
+```bash
+rm -rf docs/_build
+```
+
+</td>
+</tr>
+</table>
+
+The live preview command starts a local server and automatically rebuilds when files change.
+
+Alternatively, you can use the Makefile from within the docs directory:
+
+```bash
+cd docs
+make html          # Build HTML documentation
+make clean         # Clean build files
+```
+
+For maintainers, to build and publish a new release: `uv build && uv publish`

ml_dash-0.5.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+ml_dash/__init__.py,sha256=5tT0Lmf0SS3J7BOwJGVai8FOjdpjKGBJCEYL5nXnkLA,1384
+ml_dash/client.py,sha256=vhWcS5o2n3o4apEjVeLmu7flCEzxBbBOoLSQNcAx_ew,17267
+ml_dash/experiment.py,sha256=x1jtQD1QroNjNULOxZiGtX5oFLi3ZXDaFbGHWt0yMJU,28652
+ml_dash/files.py,sha256=WKWbcug6XADwZruYQio1EdSstmfTsty9-2-t2KPWz38,9719
+ml_dash/log.py,sha256=0yXaNnFwYeBI3tRLHX3kkqWRpg0MbSGwmgjnOfsElCk,5350
+ml_dash/metric.py,sha256=PcEd6_HTLDpf-kBIDeQq2LlTRAS7xDx6EvSBpin5iuY,6456
+ml_dash/params.py,sha256=W-JkY1Mz7KdmvDjQ0HFV2QnpBov7Gf4dl70fuBnXTdo,5974
+ml_dash/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ml_dash/storage.py,sha256=UTuux2nfclLrrtlkC6TsOvDB_wIbSDvYGg8Gtbvk6mc,30471
+ml_dash-0.5.1.dist-info/WHEEL,sha256=X16MKk8bp2DRsAuyteHJ-9qOjzmnY0x1aj0P1ftqqWA,78
+ml_dash-0.5.1.dist-info/METADATA,sha256=TBTqi4lJNoFO2eyztYJZptQypUSVTDVUdbGS0EnQZ2k,6067
+ml_dash-0.5.1.dist-info/RECORD,,

{ml_dash-0.4.0.dist-info → ml_dash-0.5.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.24
+Generator: uv 0.9.2
 Root-Is-Purelib: true
 Tag: py3-none-any

ml_dash/ARCHITECTURE.md

@@ -1,382 +0,0 @@
-# ML-Logger Architecture
-
-## Class Hierarchy and Composition
-
-<details open>
-<summary><strong>🏗️ System Overview</strong></summary>
-
-```
-ML-Logger System
-│
-├── Storage Backends (remove existing implementations awaiting design)
-    add local logger, s3, gcp, ml_dash, as empty files. Also include an empty base class.
-├── Logger Components (file and data types)  
-├── ML_Logger (Main Interface)
-└── Supporting and Utility Classes
-```
-
-</details>
-
-<details>
-<summary><strong>💾 Storage Backends</strong> (Where to store)</summary>
-
-```
-Storage Backends
-│
-├── StorageBackend (Abstract Base)
-│   ├── exists()
-│   ├── write_bytes()
-│   ├── read_bytes()
-│   ├── write_text()
-│   ├── read_text()
-│   ├── append_text()
-│   ├── list_dir()
-│   └── get_url()
-│
-├── LocalBackend(StorageBackend)
-│   └── Implements file system operations
-│
-├── S3Backend(StorageBackend)
-│   └── Implements AWS S3 operations
-│
-└── GCPBackend(StorageBackend)
-    └── Implements Google Cloud Storage operations
-```
-
-</details>
-
-<details>
-<summary><strong>📝 Logger Components</strong> (What to log)</summary>
-
-```
-Experiment
-│
-├── logs: TextLogger
-│   ├── log(level, message)
-│   ├── error(message)
-│   ├── warning(message)
-│   ├── info(message)
-│   └── debug(message)
-│
-├── metrics: ScalarLogger (accessed via experiment.metrics)
-│   ├── log(step, **metrics) - Log metrics immediately
-│   ├── collect(step, **metrics) - Collect for later aggregation
-│   ├── flush(_aggregation, step) - Aggregate and log collected metrics
-│   ├── get_summary(name, frequency)
-│   ├── __call__(namespace) - Return namespaced logger
-│   └── Uses: ScalarCache, Series
-│
-├── files: ArtifactLogger (accessed via experiment.files)
-│   ├── save(data, filename) - Save generic data
-│   ├── save_pkl(data, filename) - Save pickle data
-│   ├── save_image(name, image) - Save image
-│   ├── save_video(name, video, fps) - Save video
-│   ├── save_audio(name, audio) - Save audio
-│   ├── savefig(fig, filename) - Save matplotlib figure
-│   ├── load_torch(filename) - Load PyTorch data
-│   ├── make_video(pattern, output, fps, codec, quality, sort) - Create video from frames
-│   ├── __call__(namespace) - Return namespaced logger
-│   └── File management and artifact storage
-│
-├── params: ParameterIndex
-│   ├── set(params) - Set/overwrite parameters
-│   ├── extend(params) - Merge with existing parameters
-│   ├── update(key, value) - Update single parameter
-│   ├── read() - Read all parameters
-│   └── Manages experiment configuration
-│
-└── charts: ChartBuilder  # PLANNING PHASE, subject to changes.
-    ├── line_chart(query)
-    ├── scatter_plot(query)
-    ├── bar_chart(query)
-    └── video/images(query)
-```
-
-</details>
-
-<details>
-<summary><strong>🎯 Composite Logger</strong> (Main Interface)</summary>
-
-```
-MLLogger
-├── __init__(backend: StorageBackend)
-├── params: ParameterIndex - Parameter management
-├── metrics: ScalarLogger - Metrics logging
-├── readme: MarkdownLogger - Rich Text logging (PLANNING PHASE)
-├── files: ArtifactLogger - File and artifact management
-├── logs: TextLogger - Text logging
-│
-├── Convenience Methods: (can just hide under logs)
-│   ├── error() -> text.error()
-│   ├── warning() -> text.warning()
-│   ├── info() -> text.info()
-│   └── debug() -> text.debug()
-│
-└── Context Managers:
-    ├── experiment(name)
-    └── run(id)
-```
-
-</details>
-
-<details>
-<summary><strong>⚙️ Supporting Classes</strong></summary>
-
-```
-Supporting Classes
-│
-└── Serialization (serdes/) (NOT USED)
-    ├── serialize()
-    ├── deserialize()
-    └── Type registry with $t, $s keys
-```
-
-</details>
-
-## Usage Examples
-
-<details>
-<summary><strong>📊 Logging Different Data Types</strong></summary>
-
-```python
-# Text logging (errors, warnings, info) experiment.logs.error("Training failed") experiment.logs.warning("Low GPU memory") experiment.logs.info("Starting epoch 1")
-
-# Parameter logging experiment.params.set(learning_rate=0.001, batch_size=32)
-
-# Metrics logging experiment.metrics.log(step=100, loss=0.523, accuracy=0.95)
-
-# Collect metrics for aggregation experiment.metrics.collect(step=101, loss=0.521) experiment.metrics.flush(_aggregation="mean", step=100)
-
-# Namespaced metrics experiment.metrics("train").log(step=100, loss=0.5) experiment.metrics("val").log(step=100, accuracy=0.95)
-
-# File operations experiment.files.save_image("confusion_matrix", image_array) experiment.files.save(model_state, "checkpoint.pt") experiment.files("checkpoints").save(model_state, "model_epoch_10.pt")
-```
-
-</details>
-
-<details>
-<summary><strong>🎛️ Direct Component Access</strong></summary>
-
-```python
-# Access components directly for advanced usage experiment.logs.error("Direct text logging") experiment.metrics.log(step=50, lr=0.001) experiment.files.save_video("training_progress", video_array, fps=30)
-
-# Namespaced file operations experiment.files("videos").save_video("training_progress", video_array, fps=30) experiment.files("checkpoints").save(model_state, "model.pt")
-
-# Get statistics
-stats = experiment.metrics.get_stats("loss")
-percentile_95 = experiment.metrics.get_percentile("loss", 95)
-```
-
-</details>
-
-## File Organization
-
-<details>
-<summary><strong>📁 Project Structure</strong></summary>
-
-```
-ml-logger/
-├── src/ml_logger/
-│   ├── __init__.py
-│   ├── experiment.py          # Main MLLogger class
-│   │
-│   ├── backends/
-│   │   ├── __init__.py
-│   │   ├── base.py        # StorageBackend ABC
-│   │   ├── local.py       # LocalBackend
-│   │   ├── s3.py          # S3Backend
-│   │   └── gcp.py         # GCPBackend
-│   │
-│   ├── loggers/
-│   │   ├── __init__.py
-│   │   ├── text.py        # TextLogger
-│   │   ├── scalar.py      # ScalarLogger
-│   │   └── artifact.py    # ArtifactLogger
-│   │
-│   ├── scalar_cache.py    # ScalarCache, Series, RollingStats
-│   │
-│   └── serdes/
-│       ├── __init__.py
-│       └── ndjson.py      # Serialization with $t, $s
-│
-└── tests/
-    ├── test_backends.py
-    ├── test_loggers.py
-    ├── test_scalar_cache.py
-    └── test_integration.py
-```
-
-</details>
-
-## Advanced Features
-
-<details>
-<summary><strong>📈 Statistical Features</strong></summary>
-
-### Rolling Statistics
-- **Window-based metrics**: Configurable window size for recent data
-- **Automatic calculation**: Mean, variance, std, min, max
-- **Percentiles**: p0, p1, p5, p10, p20, p25, p40, p50, p60, p75, p80, p90, p95, p99, p100
-
-### Summary Frequencies
-Automatic summaries at: 1, 5, 10, 15, 20, 25, 30, 40, 50, 75, 80, 100, 120, 150, 200, 250, 300, 400, 500, 600, 1000, 1200, 1500, 2000, 2500, ...
-
-```python
-# Access statistics
-stats = experiment.scalars.get_stats("loss")
-print(f"Mean: {stats.mean}, Std: {stats.std}")
-
-# Get percentiles
-p95 = experiment.scalars.get_percentile("accuracy", 95)
-
-# Get summaries at specific frequencies
-summaries = experiment.scalars.get_summary("loss", frequency=100)
-```
-
-</details>
-
-<details>
-<summary><strong>🔄 Serialization System</strong></summary>
-
-### Type-Annotated Serialization
-- Uses `$t` for type keys
-- Uses `$s` for shape keys (arrays)
-- Recursive serialization for nested structures
-- Supports: primitives, datetime, numpy, Path, bytes, collections
-
-```python
-from ml_dash.serdes import serialize, deserialize
-
-# Serialize complex objects
-data = {
-    "array": np.array([[1, 2], [3, 4]]),
-    "date": datetime.now(),
-    "path": Path("/tmp/file.txt")
-}
-serialized = serialize(data)
-
-# Deserialize back
-original = deserialize(serialized)
-```
-
-</details>
-
-## Examples
-
-<details>
-<summary><strong>🤖 ML Training Example</strong></summary>
-
-```python
-# train.py - Define your training function
-from ml_dash import get_logger
-
-
-@logger.run
-def train(config):
-    """Training function that will be wrapped by the experiment."""
-    model = create_model(config.model_type)
-    optimizer = torch.optim.Adam(model.parameters(), lr=config.lr)
-
-    best_acc = 0
-    for epoch in range(config.epochs):
-        # Training loop
-        for batch_idx, (data, target) in enumerate(train_loader):
-            loss = train_step(model, data, target, optimizer)
-
-            step = epoch * len(train_loader) + batch_idx
-            with experiment.step(step):
-                # Log metrics
-                experiment.log_metric("train/loss", loss.item())
-
-                # Log histograms periodically
-                if step % 100 == 0:
-                    experiment.log_histogram("gradients", get_gradients(model))
-
-                # Save visualizations
-                if step % 500 == 0:
-                    fig = plot_predictions(model, data)
-                    experiment.log_image("predictions", fig)
-
-        # Validation
-        val_loss, val_acc = validate(model, val_loader)
-        experiment.log_metrics({
-            "val/loss": val_loss,
-            "val/accuracy": val_acc
-        }, step=epoch)
-
-        # Save checkpoint
-        if val_acc > best_acc:
-            experiment.log_model("best_model", model.state_dict())
-            best_acc = val_acc
-
-    # Final summary
-    experiment.info(f"Training completed. Best accuracy: {best_acc}")
-    return {"best_accuracy": best_acc}
-
-```
-
-**experiment.py** - Launch experiments with different configs:
-
-```python
-from ml_dash import get_logger
-from train import train
-
-# Initialize logger
-experiment = get_logger("s3://experiments/mnist")
-
-# Define experiment configurations
-configs = [
-    {"model_type": "CNN", "lr": 0.001, "batch_size": 32, "epochs": 100},
-    {"model_type": "CNN", "lr": 0.01, "batch_size": 64, "epochs": 100},
-    {"model_type": "ResNet", "lr": 0.001, "batch_size": 32, "epochs": 150},
-]
-
-# Run experiment with multiple configurations
-with experiment.experiment("model_comparison"):
-    for i, config in enumerate(configs):
-        # Each config gets its own run
-        run_name = f"{config['model_type']}_lr{config['lr']}"
-
-        # The decorator handles run creation and lifecycle
-        result = train(
-            config=config,
-            _run_name=run_name,
-            _hyperparams=config,
-            _tags=["baseline", config["model_type"].lower()]
-        )
-
-        print(f"Run {run_name} completed with accuracy: {result['best_accuracy']}")
-```
-
-</details>
-
-<details>
-<summary><strong>🔍 Debugging Example</strong></summary>
-
-```python
-# Setup logger with debug level
- experiment =get_logger("./debug_logs") experiment.logs.set_level(LogLevel.DEBUG)
-
-try:
-    # Your code here
-    result = risky_operation()
-    experiment.debug(f"Operation result: {result}")
-    
-except Exception as e:
-    # Log exception with full traceback
-    experiment.exception("Operation failed", exc_info=True)
-    
-    # Log additional context
-    experiment.error("Failed at step", step=current_step, 
-                input_shape=data.shape)
-    
-    # Save problematic data for debugging
-    experiment.log_file("failed_input", "debug_data.pkl")
-    
-finally:
-    # Get recent logs
-    errors = experiment.get_logs(level="ERROR", limit=50)
-    print(f"Found {len(errors)} errors")
-```
-
-</details>

ml_dash/autolog.py

@@ -1,32 +0,0 @@
-"""Auto-configured experiment for ML-Logger.
-
-This module provides a pre-configured global `experiment` instance that can be
-imported and used immediately without manual setup.
-
-Example:
-    from ml_dash.autolog import experiment
-
-    # No setup needed!
-    experiment.params.set(learning_rate=0.001)
-    experiment.metrics.log(step=0, loss=0.5)
-    experiment.files.save(model.state_dict(), "checkpoint.pt")
-
-Configuration:
-    The auto-experiment is configured from environment variables:
-    - ML_LOGGER_NAMESPACE: User/team namespace (default: "default")
-    - ML_LOGGER_WORKSPACE: Project workspace (default: "experiments")
-    - ML_LOGGER_PREFIX: Experiment prefix (default: auto-generated timestamp+uuid)
-    - ML_LOGGER_REMOTE: Remote server URL (optional)
-
-    Or from ~/.ml-logger/config.yaml:
-        namespace: alice
-        workspace: my-project
-        remote: http://localhost:3001
-"""
-
-from .run import Experiment
-
-# Auto-configured global experiment instance
-experiment = Experiment._auto_configure()
-
-__all__ = ["experiment"]

ml_dash/backends/__init__.py

@@ -1,11 +0,0 @@
-"""Storage backends for ML-Logger."""
-
-from .base import StorageBackend
-from .local_backend import LocalBackend
-from .dash_backend import DashBackend
-
-__all__ = [
-    "StorageBackend",
-    "LocalBackend",
-    "DashBackend",
-]