Metadata-Version: 2.3
Name: gitlab-ml
Version: 0.2.2
Summary: CLI tool for managing machine learning models in GitLab's Model Registry
Author: Ahmet Öner
Requires-Python: >=3.9,<4.0
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
Requires-Dist: PyYAML (>=6.0.1,<7.0.0)
Requires-Dist: aiohttp (>=3.9.3,<4.0.0)
Requires-Dist: gql[aiohttp] (>=3.5.0,<4.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: mlflow-skinny (>=2.10.2,<3.0.0)
Requires-Dist: pydantic (>=2.6.1,<3.0.0)
Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: python-gitlab (>=5.6.0,<6.0.0)
Requires-Dist: questionary (>=2.0.1,<3.0.0)
Requires-Dist: rich (>=13.7.0,<14.0.0)
Requires-Dist: semver (>=3.0.2,<4.0.0)
Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
Description-Content-Type: text/markdown

# GitLab ML CLI

A command-line interface tool for managing machine learning models in GitLab's Model Registry. This tool provides a seamless experience for ML teams to version, track, and deploy their models using GitLab's infrastructure.

## Features

- **Model Registry Management**:
  - Create, delete, and list models
  - Manage model metadata and tags
  - Track model lineage and dependencies
- **Model Versioning**:
  - Upload new model versions with semantic versioning
  - Download specific versions for deployment
- **Access Control**:
  - GitLab authentication and authorization

## Installation

### Using pip

```bash
pip install gitlab-ml
```

### Using Poetry

```bash
poetry add gitlab-ml
```

### From Source

```bash
git clone https://gitlab.com/ahmetoner/gitlab-ml.git
cd gitlab-ml
poetry install
```

## Configuration

### Configuration File

Create a configuration file at `~/.config/gitlab-ml/config.yml`:

```yaml
gitlab:
  # GitLab instance URL
  url: "https://gitlab.com"
  
  # Personal access token with api scope
  token: "your-personal-access-token"
  
  # Default project for model registry
  default_project: "group/project"
```

### Environment Variables

Alternative to config file, you can use environment variables:

```bash
# Required settings
export GITLAB_ML_TOKEN="your-personal-access-token"
export GITLAB_ML_URL="https://gitlab.com"
export GITLAB_ML_PROJECT="group/project"
```

## Usage

### Model Management

```bash
# List all models with different output formats
gitlab-ml models list
gitlab-ml models list --format json
gitlab-ml models list --format yaml

# Create a new model
gitlab-ml models create my-model \
    --description "My ML model"

# Delete a model (with confirmation)
gitlab-ml models delete my-model

# Force delete without confirmation
gitlab-ml models delete my-model --force
```

### Version Management

```bash
# Upload a new model version
gitlab-ml models upload my-model 1.0.0 ./model.pkl

# Upload a directory of model artifacts
gitlab-ml models upload my-model 1.0.0 ./model_dir

# Download a specific version
gitlab-ml models download my-model 1.0.0 \
    --output ./models/
```

## Development

1. Clone the repository:

   ```bash
   git clone https://gitlab.com/ahmetoner/gitlab-ml.git
   cd gitlab-ml
   ```

2. Install development dependencies:

   ```bash
   poetry install --with dev
   ```

3. Activate virtual environment:

   ```bash
   poetry shell
   ```

4. Run tests:

   ```bash
   # Run all tests
   poetry run pytest
   
   # Run with coverage
   poetry run pytest --cov=gitlab_ml
   
   # Run specific test file
   poetry run pytest tests/test_models.py
   ```

5. Code formatting and linting:

   ```bash
   # Format code
   poetry run black .
   poetry run isort .
   
   # Run linters
   poetry run mypy .
   poetry run ruff .
   ```

## Troubleshooting

### Common Issues

1. Authentication Errors

   ```
   Error: GitLab authentication failed
   ```

   - Verify your token has the correct permissions (api scope)
   - Check if token is expired
   - Ensure GitLab URL is correct

2. Project Access

   ```
   Error: Project not found or no access
   ```

   - Verify project path is correct
   - Check if you have sufficient permissions
   - Ensure project exists and is accessible

3. Upload Failures

   ```
   Error: Failed to upload model version
   ```

   - Check file permissions
   - Verify disk space
   - Ensure version follows semver format

## API Documentation

### Python API

```python
from pathlib import Path
from gitlab_ml.api.client import get_gitlab_client, GitLabClient
from gitlab_ml.api.models import ModelRegistry

# Initialize client with custom URL and token
client = GitLabClient(
    url="https://gitlab.example.com",  # Your GitLab instance URL
    token="glpat-xxxxxxxxxxxx"         # Your GitLab personal access token
)
registry = ModelRegistry(client)

# Or use environment variables
import os
os.environ["GITLAB_URL"] = "https://gitlab.example.com"
os.environ["GITLAB_TOKEN"] = "glpat-xxxxxxxxxxxx"
client = get_gitlab_client()
registry = ModelRegistry(client)

# List models
models = registry.list_models()

# Upload model
registry.upload_version(
    model_name="my-model",
    version="1.0.0",
    path=Path("./model.pkl")
)

# Download model
registry.download_version(
    model_name="ml-model-new",
    version="1.2.2",
    output_dir=Path("./downloaded_model")
)
```

### REST API Integration

The CLI integrates with GitLab's REST and GraphQL APIs. For custom integrations, refer to:

- [GitLab REST API Documentation](https://docs.gitlab.com/ee/api/)
- [GitLab GraphQL API Documentation](https://docs.gitlab.com/ee/api/graphql/)

## Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a merge request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

