yanex 0.1.0__py3-none-any.whl

yanex/utils/validation.py

@@ -0,0 +1,165 @@
+"""
+Input validation utilities.
+"""
+
+import re
+from pathlib import Path
+from typing import Any, Dict
+
+from .exceptions import ValidationError
+
+
+def validate_experiment_name(name: str) -> str:
+    """
+    Validate experiment name.
+
+    Args:
+        name: Experiment name to validate
+
+    Returns:
+        Validated name
+
+    Raises:
+        ValidationError: If name is invalid
+    """
+    if not name or not name.strip():
+        raise ValidationError("Experiment name cannot be empty")
+
+    name = name.strip()
+
+    # Check length
+    if len(name) > 100:
+        raise ValidationError("Experiment name cannot exceed 100 characters")
+
+    # Check for invalid characters (basic validation)
+    if not re.match(r"^[a-zA-Z0-9_\-\s]+$", name):
+        raise ValidationError(
+            "Experiment name can only contain letters, numbers, spaces, hyphens, and underscores"
+        )
+
+    return name
+
+
+def validate_experiment_id(experiment_id: str) -> str:
+    """
+    Validate experiment ID format.
+
+    Args:
+        experiment_id: ID to validate
+
+    Returns:
+        Validated ID
+
+    Raises:
+        ValidationError: If ID format is invalid
+    """
+    if not re.match(r"^[a-f0-9]{8}$", experiment_id):
+        raise ValidationError(
+            f"Invalid experiment ID format: {experiment_id}. "
+            "Expected 8-character hex string (e.g., 'a1b2c3d4')"
+        )
+
+    return experiment_id
+
+
+def validate_tags(tags: list[str]) -> list[str]:
+    """
+    Validate experiment tags.
+
+    Args:
+        tags: List of tags to validate
+
+    Returns:
+        Validated and cleaned tags
+
+    Raises:
+        ValidationError: If any tag is invalid
+    """
+    if not isinstance(tags, list):
+        raise ValidationError("Tags must be a list")
+
+    validated_tags = []
+    for tag in tags:
+        if not isinstance(tag, str):
+            raise ValidationError(f"Tag must be a string: {tag}")
+
+        tag = tag.strip()
+        if not tag:
+            continue  # Skip empty tags
+
+        if len(tag) > 50:
+            raise ValidationError(f"Tag too long (max 50 chars): {tag}")
+
+        if not re.match(r"^[a-zA-Z0-9_\-]+$", tag):
+            raise ValidationError(
+                f"Tag contains invalid characters: {tag}. "
+                "Only letters, numbers, hyphens, and underscores allowed"
+            )
+
+        validated_tags.append(tag)
+
+    return validated_tags
+
+
+def validate_script_path(script_path: Path) -> Path:
+    """
+    Validate experiment script path.
+
+    Args:
+        script_path: Path to script file
+
+    Returns:
+        Validated path
+
+    Raises:
+        ValidationError: If script path is invalid
+    """
+    if not script_path.exists():
+        raise ValidationError(f"Script file does not exist: {script_path}")
+
+    if not script_path.is_file():
+        raise ValidationError(f"Script path is not a file: {script_path}")
+
+    if script_path.suffix != ".py":
+        raise ValidationError(f"Script must be a Python file (.py): {script_path}")
+
+    return script_path
+
+
+def validate_config_data(config_data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Validate configuration data structure.
+
+    Args:
+        config_data: Configuration dictionary
+
+    Returns:
+        Validated configuration
+
+    Raises:
+        ValidationError: If configuration is invalid
+    """
+    if not isinstance(config_data, dict):
+        raise ValidationError("Configuration must be a dictionary")
+
+    # Basic validation - ensure values are JSON serializable types
+    allowed_types = (str, int, float, bool, list, dict, type(None))
+
+    def validate_value(key: str, value: Any) -> None:
+        if not isinstance(value, allowed_types):
+            raise ValidationError(
+                f"Configuration value for '{key}' must be JSON serializable, "
+                f"got {type(value).__name__}"
+            )
+
+        if isinstance(value, dict):
+            for subkey, subvalue in value.items():
+                validate_value(f"{key}.{subkey}", subvalue)
+        elif isinstance(value, list):
+            for i, item in enumerate(value):
+                validate_value(f"{key}[{i}]", item)
+
+    for key, value in config_data.items():
+        validate_value(key, value)
+
+    return config_data

yanex-0.1.0.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: yanex
+Version: 0.1.0
+Summary: Yet Another Experiment Tracker - A lightweight experiment tracking harness
+Author: Thomas
+Author-email: Thomas <from+gitgub@tomr.au>
+License: MIT
+Project-URL: Homepage, https://github.com/rueckstiess/yanex
+Project-URL: Repository, https://github.com/rueckstiess/yanex
+Project-URL: Documentation, https://github.com/rueckstiess/yanex/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/rueckstiess/yanex/issues
+Keywords: experiment,tracking,machine-learning,research,reproducibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=12.0.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: dateparser>=1.1.0
+Requires-Dist: textual>=0.45.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib>=3.5.0; extra == "matplotlib"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# Yanex - Yet Another Experiment Tracker
+
+A lightweight, Git-aware experiment tracking system for Python that makes reproducible research effortless.
+
+## Why Yanex?
+
+**Stop losing track of your experiments.** Yanex automatically tracks parameters, results, and code state so you can focus on what matters - your research.
+
+```python
+import yanex
+
+# read parameters from config file or CLI arguments
+lr = yanex.get_param('lr', default=0.001)
+epochs = yanex.get_param('epochs', default=10)
+
+# access nested parameters with dot notation
+model_lr = yanex.get_param('model.learning_rate', default=0.001)
+optimizer_type = yanex.get_param('model.optimizer.type', default='adam')
+
+# your experiment code
+# ...
+
+# log results, artifacts and figures
+yanex.log_results({"step": epoch, "loss", loss, "accuracy": accuracy})
+yanex.log_artifact("model.pth", model_path)
+yanex.log_matplotlib_figure(fig, "loss_curve.png")
+```
+
+Run from the command line:
+
+```bash
+# Run with yanex CLI for automatic tracking
+yanex run train.py --name "my-experiment" --tag testing --param lr=0.001 --param epochs=10
+```
+
+That's it. Yanex tracks the experiment, saves the logged results and files, stdout and stderr outptus, Python environment
+information, and even the Git state of your code repository. You can then compare results, search experiments, and reproduce them with ease.
+
+## Key Features
+
+- 🔒 **Reproducible**: Automatic Git state tracking ensures every experiment is reproducible
+- 📊 **Interactive Comparison**: Compare experiments side-by-side with an interactive table
+- ⚙️ **Flexible Parameters**: YAML configs with CLI overrides for easy experimentation and syntax for parameter sweeps
+- 📈 **Rich Logging**: Track metrics, artifacts, and figures
+- 🔍 **Powerful Search**: Find experiments by status, parameters, tags, or time ranges
+- 📦 **Zero Dependencies**: No external services required - works offline
+
+## Quick Start
+
+### Install
+```bash
+pip install yanex
+```
+
+### 1. Run Your First Experiment
+
+```python
+# experiment.py
+import yanex
+
+params = yanex.get_params()
+print(f"Learning rate: {params.get('learning_rate', 0.001)}")
+
+# Simulate training
+accuracy = 0.85 + (params.get('learning_rate', 0.001) * 10)
+
+yanex.log_results({
+    "accuracy": accuracy,
+    "loss": 1 - accuracy
+})
+```
+
+```bash
+# Run with default parameters
+yanex run experiment.py
+
+# Override parameters
+yanex run experiment.py --param learning_rate=0.01 --param epochs=50
+
+# Add tags for organization
+yanex run experiment.py --tag baseline --tag "quick-test"
+```
+
+### 2. Compare Results
+
+```bash
+# Interactive comparison table
+yanex compare
+
+# Compare specific experiments
+yanex compare exp1 exp2 exp3
+
+# Filter and compare
+yanex compare --status completed --tag baseline
+```
+
+### 3. Track Everything
+
+List, search, and manage your experiments:
+
+```bash
+# List recent experiments
+yanex list
+
+# Find experiments by criteria
+yanex list --status completed --tag production
+yanex list --started-after "1 week ago"
+
+# Show detailed experiment info
+yanex show exp_id
+
+# Archive old experiments
+yanex archive --started-before "1 month ago"
+```
+
+## Two Ways to Use Yanex
+
+Yanex supports two usage patterns:
+
+### 1. CLI-First (Recommended)
+Write scripts that work both standalone and with yanex tracking:
+
+```python
+# train.py - Works both ways!
+import yanex
+
+params = yanex.get_params()  # Gets parameters or defaults
+lr = params.get('learning_rate', 0.001)
+
+# Your training code
+accuracy = train_model(lr=lr)
+
+# Logging works in both contexts
+yanex.log_results({"accuracy": accuracy})
+```
+
+```bash
+# Run standalone (no tracking)
+python train.py
+
+# Run with yanex (full tracking)
+yanex run train.py --param learning_rate=0.01
+```
+
+### 2. Explicit Experiment Creation (Advanced)
+For Jupyter notebook usage, or when you need fine control:
+
+```python
+import yanex
+from pathlib import Path
+
+with yanex.create_experiment(
+    script_path=Path(__file__),
+    name="my-experiment",
+    config={"learning_rate": 0.01}
+) as exp:
+    # Your code here
+    exp.log_results({"accuracy": 0.95})
+```
+
+> **Note:** Don't mix both patterns! Use CLI-first for most cases, explicit creation for advanced scenarios.
+
+
+## Configuration Files
+
+Create `config.yaml` for default parameters:
+
+```yaml
+# config.yaml
+model:
+  learning_rate: 0.001
+  batch_size: 32
+  epochs: 100
+
+data:
+  dataset: "cifar10"
+  augmentation: true
+
+training:
+  optimizer: "adam"
+  scheduler: "cosine"
+```
+
+
+## Documentation
+
+📚 **[Complete Documentation](docs/README.md)** - Detailed guides and API reference
+
+**Quick Links:**
+- [CLI Commands](docs/cli-commands.md) - All yanex commands with examples
+- [Python API](docs/python-api.md) - Complete Python API reference  
+- [Configuration](docs/configuration.md) - Parameter management and config files
+- [Comparison Tool](docs/compare.md) - Interactive experiment comparison
+- [Best Practices](docs/best-practices.md) - Tips for effective experiment tracking
+
+
+## Contributing
+
+Yanex is open source and welcomes contributions! See our [contributing guidelines](CONTRIBUTING.md) for details.
+
+**Built with assistance from [Claude](https://claude.ai).**
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

yanex-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+yanex/__init__.py,sha256=cLkL_PqB9yEfN6IezrwBhUSZMO27GfYF0Lj-ZEplOr8,1656
+yanex/api.py,sha256=NCn62gBayaDqGpDMx3YHbsaaYVdDUdPNQ8qBse5kLMA,15872
+yanex/cli/__init__.py,sha256=cSwcfp10naAJ7h_0cMP69rcKjkNf8skMUm1o-ilpRoM,42
+yanex/cli/_utils.py,sha256=21IaSR5Q4w3fuHRFLAs4n01ot9YjDiZEbVB_f3P7bk0,3581
+yanex/cli/main.py,sha256=9OpGsMdMbb2N02vYXTXGCoE6wSEHdlPWutuRUcM8kII,1406
+yanex/cli/commands/__init__.py,sha256=oXtVFCrTNmapQnpHRhK-EZPv5ZVLXhdVzW0giuk4II8,37
+yanex/cli/commands/archive.py,sha256=klbgZl_iDz12qTd87WJirp0QVIp7sxdoAg_lbc9yOCY,6178
+yanex/cli/commands/compare.py,sha256=x2uv0q_z40eufkMj1xLb60dwPruzfBnausMZeml0sB4,10650
+yanex/cli/commands/confirm.py,sha256=tFvUFAZXPQIBU68pi_LLi_LL5B4MLb8FrScdNKbwZHo,6633
+yanex/cli/commands/delete.py,sha256=a0j5dkG6s-Qvm4pIl5Y4C46_CDwTfg_A-OD_jb8x_0U,7145
+yanex/cli/commands/list.py,sha256=QTPBzd6Twc9l3SPFdDXtqXnn-N1INhJKc5qmE-I5mGo,7826
+yanex/cli/commands/run.py,sha256=X2Q2UP9ayQ62kP33rosMQfbsj9y8GxEeFS9mQIrKomM,20728
+yanex/cli/commands/show.py,sha256=D9GxhmzWg56iEN2AwRIUX1SbStnwEYpMT7vYgLJ1ctU,21380
+yanex/cli/commands/unarchive.py,sha256=HSqYuyMkhWv8N0-UxBDXfZfCwBJc1PB2MXhImQTmlck,6178
+yanex/cli/commands/update.py,sha256=pR8v2cF4YKYVY71qhhquw-F6SO6Tq3-ZFnnOS5t06M8,9412
+yanex/cli/filters/__init__.py,sha256=ljd8rJJTW-jq6CRmXiF7WtRBwH76kesjbCQH3OMZZjo,180
+yanex/cli/filters/base.py,sha256=jteG3xTOtfsn5HydOwGlaG_lyDrnP9mLYW5xOzTO1QM,10523
+yanex/cli/filters/time_utils.py,sha256=ow8BmwObVASt5fP2lbLOrUVydxXiBYt448DHrNic6dQ,5395
+yanex/cli/formatters/__init__.py,sha256=ont-oEcZPuSFDy6xYjQCbUOpt-oSDtjBlfkXslNiFIk,149
+yanex/cli/formatters/console.py,sha256=WGhSr5Od2PGZRxNE_DoSfSVh2aPNbuUrcDRNPt_fdug,10829
+yanex/core/__init__.py,sha256=5TDyT1B2UzH0pKUEXv0qq-owBURx85PNmtPR-T-Qgow,82
+yanex/core/comparison.py,sha256=1RsDULYDapFCgrtqKn3D0Al_Ve6VW-CR_iNIKn3hbBM,18607
+yanex/core/config.py,sha256=P5e6RP9a366r5gMEzmmsMsMyEGiCqFd2acQphPZ1CSs,17633
+yanex/core/constants.py,sha256=5dJDeH9kowrtsl_4koZmUsneDalPENaiiKpKg8Bf9x8,287
+yanex/core/environment.py,sha256=hEd67ci1N267JZk9V1NMfgbC-iD--lkVPWXS9CJx6jo,4009
+yanex/core/git_utils.py,sha256=I1ODxpImjbuiuXYqALixYJzyUwJ4lVDLRO7NnaF1jEM,3873
+yanex/core/manager.py,sha256=FW61YUv5yxxdQQdHV6im8Tgdo_S6s8ngPKzhfpiaP30,19227
+yanex/core/storage.py,sha256=bfjt2WoJeEj4tupY7pBA-cRhGiavTzxQherIPYNszw4,21255
+yanex/ui/__init__.py,sha256=kSrnufTm8RgL3zFSmm8z0UG4uHYJ8ukLJapKGAFXR1s,26
+yanex/ui/compare_table.py,sha256=hnnyMTIYGS_uUDLzaO9xVfU3-LCqw7MG6FzzJN5NOZk,17453
+yanex/utils/__init__.py,sha256=VKx8CJQrl6fOsufYs2w_0OUrFUfzNFNOyvztrBskHiU,49
+yanex/utils/exceptions.py,sha256=-DN-0PEQRC2Gm-Jbix2LIRdfDmbZF0eETcunMQrKzYs,1632
+yanex/utils/validation.py,sha256=H4uMSni16KX1gXgKKlTXqzTdGmwKZZLJi7qm8MX-ips,4216
+yanex-0.1.0.dist-info/licenses/LICENSE,sha256=rZEeAJISICOoGdJ3WfS4JVLrbzkNKKM0h4p521HTD0s,1074
+yanex-0.1.0.dist-info/METADATA,sha256=zVbt5yvJZnFfqDBX47be-zI2PVGB2UuEsxdqEg8as3s,6985
+yanex-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+yanex-0.1.0.dist-info/entry_points.txt,sha256=XcqUiw6toVUyeDuZ1_TYr33ghcaAjjndaanhIaRT9qE,45
+yanex-0.1.0.dist-info/top_level.txt,sha256=j6GpTPgyijbV2tyrZQxT7ZHEdZkvTBxjYY2VKcJMJ7Y,6
+yanex-0.1.0.dist-info/RECORD,,

yanex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yanex-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yanex = yanex.cli.main:cli

yanex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Rueckstiess
+
+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.

yanex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yanex