Metadata-Version: 2.4
Name: wyolo
Version: 1.0.0
Summary: Professional YOLO training library with MLOps integration
Project-URL: Homepage, https://github.com/wisrovi/wyoloservice2_worker
Project-URL: Documentation, https://wyolo.readthedocs.io/
Project-URL: Repository, https://github.com/wisrovi/wyoloservice2_worker.git
Project-URL: Bug Tracker, https://github.com/wisrovi/wyoloservice2_worker/issues
Author-email: William Steve Rodriguez Villamizar <wisrovi.rodriguez@gmail.com>
Maintainer-email: William Steve Rodriguez Villamizar <wisrovi.rodriguez@gmail.com>
License: MIT License
        
        Copyright (c) 2024 William Steve Rodriguez Villamizar
        
        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.
License-File: LICENSE
Keywords: computer-vision,machine-learning,mlflow,mlops,yolo
Classifier: Development Status :: 4 - Beta
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 :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: click>=8.0.0
Requires-Dist: dvc>=2.0.0
Requires-Dist: gputil>=1.4.0
Requires-Dist: loguru>=0.6.0
Requires-Dist: mlflow>=2.0.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: python-slugify>=6.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: redis>=4.0.0
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: wredis>=0.1.0
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: build>=0.8.0; extra == 'dev'
Requires-Dist: bump2version>=1.0.0; extra == 'dev'
Requires-Dist: flake8>=5.0.0; extra == 'dev'
Requires-Dist: isort>=5.10.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=2.20.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.8.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=8.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.4.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.19.0; extra == 'docs'
Provides-Extra: tune
Requires-Dist: ray[tune]>=2.0.0; extra == 'tune'
Description-Content-Type: text/markdown

# wyolo: Professional YOLO MLOps Framework

[![Pylint Score](https://img.shields.io/badge/Pylint-9.5%2B-green.svg)](https://www.pylint.org/)
[![Security: Bandit](https://img.shields.io/badge/Security-Bandit-yellow.svg)](https://github.com/PyCQA/bandit)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**wyolo** is a high-performance, enterprise-grade Python library designed to orchestrate the entire lifecycle of YOLO and RT-DETR models. By integrating native MLOps capabilities, `wyolo` transforms experimental computer vision into production-ready automated pipelines.

---

### 1. 🚶 Diagram Walkthrough
The following diagram illustrates the high-level execution flow from user request to model registration.

```mermaid
graph TD
    A[User/Worker Request] --> B{Configuration Loader}
    B --> C[Environment Validator]
    C -->|Success| D[GPU/Batch Optimizer]
    C -->|Failure| E[Error Capture & Notification]
    D --> F[Dataset Synchronization - DVC]
    F --> G[YOLO/RT-DETR Training Loop]
    G --> H[Metrics & Logs - MLflow]
    H --> I[Artifact Storage - MinIO/S3]
    I --> J[Model Registry]
    J --> K[Execution Completed]
```

---

### 2. 🗺️ System Workflow
Detailed sequence of events during a critical training operation, highlighting the interaction between core components.

```mermaid
sequenceDiagram
    participant U as User/Worker
    participant TW as TrainerWrapper
    participant MM as MLflowManager
    participant ULY as Ultralytics Engine
    participant S3 as MinIO Storage

    U->>TW: Initialize(config)
    TW->>MM: Setup Experiment & Run
    TW->>ULY: Start Training(hyperparameters)
    loop Every Epoch
        ULY-->>TW: Metrics Update
        TW->>MM: Log Metrics (mAP, Loss)
    end
    ULY-->>TW: Final Model (.pt)
    TW->>S3: Upload Artifacts
    TW->>MM: Register Model Version
    MM-->>U: Final Status & Registry Link
```

---

### 3. 🏗️ Architecture Components
Static structure and dependencies of the `wyolo` ecosystem.

```mermaid
mindmap
  root((wyolo System))
    Core Layer
      TrainerWrapper
      MLflowManager
      GPUUtils
    App Layer (Worker)
      State Machine
      Check States (GPU, Dataset)
      Train State
    External Integrations
      Ultralytics (YOLOv8, RT-DETR)
      MLflow (Tracking, Registry)
      DVC (Data Versioning)
      Redis (Messaging)
    Infrastructure
      Docker (Containerization)
      MinIO/S3 (Storage)
```

---

### 4. ⚙️ Container Lifecycle

#### a. Build Process
The construction of the production-ready artifact follows a multi-stage approach:
1.  **Base Image Selection:** Utilizes NVIDIA CUDA-enabled Python images for GPU acceleration.
2.  **Dependency Resolution:** Installation of system-level libraries (`libgl1-mesa-glx`) and project dependencies via `pip`.
3.  **Code Injection:** Surgical copying of the `src/` directory and configuration templates.
4.  **Environment Sanitization:** Setting of non-root users and file permissions for secure execution.

#### b. Runtime Process
From instantiation to operational readiness:
1.  **Entrypoint Execution:** The container starts via `train_service.sh`.
2.  **State Initialization:** The `main.py` state machine loads the specific configuration.
3.  **Resource Discovery:** Automatic detection of CUDA devices and available VRAM.
4.  **Data Mounting:** CIFS/NFS mounts or DVC pulls to ensure dataset availability.
5.  **Steady State:** The worker enters the training loop, reporting heartbeats to Redis/MLflow.

---

### 5. 📂 File-by-File Guide

| Path | Purpose |
|:---|:---|
| `src/wyolo/core/` | Core logic for trainer wrappers, MLflow management, and GPU utilities. |
| `src/wyolo/app/` | Production worker implementation using a robust state-machine architecture. |
| `src/wyolo/trainer/` | Specialized model-type implementations and elemental DTOs. |
| `src/wyolo/docker/` | Orchestration scripts and requirements for containerized environments. |
| `pyproject.toml` | Project metadata, build system configuration, and dependency locks. |
| `Makefile` | Standardized automation for installation, testing, and documentation. |
| `tests/` | Comprehensive test suite ensuring behavioral and structural integrity. |

---

## 🛠 Technical Stack
- **Engine:** [Ultralytics](https://github.com/ultralytics/ultralytics) (YOLOv8, RT-DETR).
- **Tracking:** [MLflow](https://mlflow.org/).
- **Versioning:** [DVC](https://dvc.org/).
- **Backend:** Python 3.8+ with [Loguru](https://github.com/Delgan/loguru) for logging.
- **Containerization:** Docker with NVIDIA Container Toolkit.
- **Quality:** Pytest, Pylint, Bandit.

---

## 🚀 Installation & Setup

### Environment Preparation
```bash
# Clone the repository
git clone https://github.com/wisrovi/wyoloservice2_worker.git
cd wyoloservice2_worker

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate
```

### Automation with Makefile
```bash
# Install all dependencies (including dev)
make install

# Run security and linting checks
make lint

# Execute test suite
make test
```

---

## 📈 Configuration & Usage

### Configuration (YAML)
Create a `config.yaml` to define your experiment:
```yaml
model: yolov8n.pt
type: detect
train:
  epochs: 100
  imgsz: 640
mlflow:
  uri: "http://your-mlflow-server"
```

### Execution
```bash
# Run training via CLI
wyolo-train --config_path config.yaml --fitness map50
```

---

## 👨‍💻 Author
**William Rodríguez - wisrovi**  
*Technology Evangelist & AI Solutions Architect*  
[LinkedIn Profile](https://es.linkedin.com/in/wisrovi-rodriguez)

---

## 📄 Bibliography & Source Resources
- [Ultralytics Documentation](https://docs.ultralytics.com/)
- [MLflow Guide](https://mlflow.org/docs/latest/index.html)
- [DVC Official Tutorials](https://dvc.org/doc)
