yanex 0.1.0__tar.gz

yanex-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive parameter sweep functionality with range(), linspace(), logspace(), and list() syntax
+- Parameter-aware experiment naming for sweep experiments
+- Cross-product parameter expansion for multiple sweep parameters
+- Staging mechanism for deferred experiment execution
+- Interactive experiment comparison with rich console output
+- Git integration for reproducible experiment tracking
+- Comprehensive CLI with run, list, show, compare, archive commands
+- Python API for programmatic experiment management
+- Configuration file support (YAML/JSON) with parameter overrides
+- Artifact and result logging capabilities
+- Time-based and tag-based experiment filtering
+- Thread-local experiment state management
+
+### Changed
+- Modernized package configuration with pyproject.toml
+- Enhanced README with parameter sweep examples
+- Improved error handling and validation throughout
+
+### Fixed
+- Parameter parsing precedence for numeric values
+- Experiment name validation for generated sweep names
+- Scientific notation formatting in experiment names
+- Boolean comparison patterns in codebase
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+- Initial release of Yanex experiment tracking system
+- Core experiment lifecycle management
+- File-based storage backend
+- Command-line interface for experiment management
+- Python API for experiment creation and tracking
+- Git integration for code state tracking
+- Configuration management with parameter overrides
+- Experiment comparison and visualization tools
+- Comprehensive test suite with >90% coverage
+- Documentation and examples
+
+### Security
+- Input validation for all user-provided data
+- Safe file operations with proper error handling
+- Git state verification for experiment reproducibility

yanex-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,253 @@
+# Contributing to Yanex
+
+Thank you for your interest in contributing to Yanex! We welcome contributions from the community and are excited to work with you.
+
+## Getting Started
+
+### Development Setup
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/rueckstiess/yanex.git
+   cd yanex
+   ```
+
+2. **Set up development environment**
+   ```bash
+   # Create virtual environment
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   
+   # Install development dependencies
+   pip install -e ".[dev]"
+   # Or using requirements files
+   pip install -r requirements.txt -r requirements-dev.txt
+   ```
+
+3. **Verify installation**
+   ```bash
+   # Run tests
+   pytest
+   
+   # Check code style
+   ruff check .
+   ruff format --check .
+   
+   # Type checking
+   mypy yanex/
+   ```
+
+## Development Workflow
+
+### Code Style
+
+We use modern Python tooling for consistent code style:
+
+- **Formatting**: `ruff format` (replaces black)
+- **Linting**: `ruff check` (replaces flake8, isort, and more)
+- **Type checking**: `mypy`
+
+Before submitting changes:
+```bash
+# Format code
+ruff format .
+
+# Fix linting issues
+ruff check --fix .
+
+# Run type checking
+mypy yanex/
+```
+
+### Testing
+
+All tests must pass before merging:
+
+```bash
+# Run all tests with coverage
+pytest
+
+# Run specific test files
+pytest tests/core/test_manager.py
+pytest tests/cli/test_run.py
+
+# Run tests matching a pattern
+pytest -k "test_sweep"
+```
+
+**Test Guidelines:**
+- Write tests for all new functionality
+- Include both positive and negative test cases
+- Test edge cases and error conditions
+- Use descriptive test names that explain what's being tested
+
+### Commit Messages
+
+We follow conventional commit format:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat`: New features
+- `fix`: Bug fixes
+- `docs`: Documentation changes
+- `test`: Adding or updating tests
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+- `ci`: CI/CD changes
+
+**Examples:**
+```
+feat(sweeps): add parameter sweep functionality
+fix(cli): handle empty experiment list gracefully
+docs(readme): add parameter sweep examples
+test(core): add tests for experiment manager
+```
+
+## Types of Contributions
+
+### 🐛 Bug Reports
+
+When reporting bugs, please include:
+
+1. **Clear description** of the issue
+2. **Steps to reproduce** the problem
+3. **Expected vs actual behavior**
+4. **Environment information**:
+   - Python version
+   - Yanex version
+   - Operating system
+5. **Minimal code example** if applicable
+
+### 💡 Feature Requests
+
+For new features:
+
+1. **Check existing issues** to avoid duplicates
+2. **Describe the use case** - why is this needed?
+3. **Propose a solution** - how should it work?
+4. **Consider alternatives** - are there other approaches?
+
+### 🔧 Code Contributions
+
+1. **Start with an issue** - discuss before implementing
+2. **Fork and create a branch** from `main`
+3. **Make your changes** following our guidelines
+4. **Add tests** for new functionality
+5. **Update documentation** if needed
+6. **Submit a pull request**
+
+### 📚 Documentation
+
+Documentation improvements are always welcome:
+
+- Fix typos or unclear explanations
+- Add examples and use cases
+- Improve API documentation
+- Write tutorials or guides
+
+## Pull Request Process
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Follow code style guidelines
+   - Add tests for new functionality
+   - Update documentation as needed
+
+3. **Test your changes**
+   ```bash
+   pytest
+   ruff check .
+   mypy yanex/
+   ```
+
+4. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat(scope): your descriptive message"
+   ```
+
+5. **Push and create PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Fill out PR template** with:
+   - Description of changes
+   - Related issues
+   - Testing performed
+   - Breaking changes (if any)
+
+### PR Review Process
+
+- All PRs require review before merging
+- CI tests must pass
+- Code coverage should not decrease
+- Documentation must be updated for public APIs
+
+
+## Architecture Overview
+
+Understanding the codebase structure:
+
+```
+yanex/
+├── core/          # Core experiment tracking logic
+│   ├── manager.py     # Experiment lifecycle management
+│   ├── storage.py     # File system storage backend
+│   ├── config.py      # Configuration and parameter handling
+│   └── ...
+├── cli/           # Command-line interface
+│   ├── commands/      # Individual CLI commands
+│   └── main.py        # CLI entry point
+├── api.py         # Public Python API
+└── utils/         # Shared utilities
+```
+
+**Key Components:**
+- **ExperimentManager**: Orchestrates experiment lifecycle
+- **Storage**: Handles file operations and metadata
+- **Config**: Parameter parsing and sweep expansion
+- **CLI**: User-facing command interface
+
+## Release Process
+
+We use semantic versioning (MAJOR.MINOR.PATCH):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes
+
+Releases are managed by maintainers and follow this process:
+1. Update version in `pyproject.toml`
+2. Update `CHANGELOG.md`
+3. Create release tag
+4. Publish to PyPI
+
+## Getting Help
+
+- **Questions**: Open a GitHub discussion
+- **Bugs**: Create an issue with the bug template
+- **Features**: Open an issue with the feature template
+- **Chat**: [Add Discord/Slack link if available]
+
+## Code of Conduct
+
+We are committed to providing a welcoming and inclusive environment. Please:
+
+- Be respectful and constructive
+- Welcome newcomers and help them learn
+- Focus on what's best for the community
+- Show empathy towards other contributors
+
+Thank you for contributing to Yanex! 🚀

yanex-0.1.0/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/MANIFEST.in

@@ -0,0 +1,37 @@
+# Include documentation files
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include requirements.txt
+include requirements-dev.txt
+
+# Include configuration files
+include pyproject.toml
+include Makefile
+
+# Include documentation directory
+recursive-include docs *.md
+
+# Include examples
+recursive-include examples *.py *.yaml *.yml *.json
+
+# Exclude test files from distribution
+exclude tests
+recursive-exclude tests *
+
+# Exclude development files
+exclude .gitignore
+exclude .coverage
+exclude .pytest_cache
+recursive-exclude htmlcov *
+recursive-exclude yanex.egg-info *
+recursive-exclude planning *
+
+# Exclude temporary files
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.pyd
+global-exclude __pycache__
+global-exclude .DS_Store
+global-exclude *.so

yanex-0.1.0/Makefile

@@ -0,0 +1,40 @@
+.PHONY: install test lint format clean build
+
+# Development setup
+install:
+	pip install -e ".[dev]"
+
+# Testing
+test:
+	pytest
+
+test-cov:
+	pytest --cov=yanex --cov-report=html --cov-report=term-missing
+
+# Code quality
+lint:
+	ruff check yanex tests
+	mypy yanex
+
+format:
+	ruff format yanex tests
+
+format-check:
+	ruff format --check yanex tests
+
+# Cleanup
+clean:
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	rm -rf htmlcov/
+	rm -rf .coverage
+	find . -type d -name __pycache__ -delete
+	find . -type f -name "*.pyc" -delete
+
+# Build
+build: clean
+	python -m build
+
+# All checks
+check: format-check lint test

yanex-0.1.0/PKG-INFO

@@ -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.
+