simplemlplatform 1.0.1
A lightweight MLOps SDK for experiment tracking and model registry
License: MIT
Requires Python: >=3.8
Keywords: mlops, machine learning, experiment tracking, model registry

# SimpleML SDK

A lightweight Python SDK for the SimpleML MLOps platform. Track experiments, log metrics, manage artifacts, and register models with ease.

## Installation

```bash
pip install simplemlplatform
```

## Quick Start

### Basic Configuration

```python
import simpleml

# Configure with your API key (endpoint is pre-configured)
simpleml.configure(api_key="your_api_key_here")

# Start tracking
experiment = simpleml.get_or_create_experiment("my-experiment")
run = experiment.start_run()

# Log metrics
run.log_metrics({
    "accuracy": 0.95,
    "loss": 0.05
})

# Log hyperparameters
run.log_params({
    "learning_rate": 0.001,
    "batch_size": 32,
    "epochs": 100
})

# Upload artifacts
run.upload_artifact("model.pkl", artifact_type="model")

# Complete the run
run.complete()
```

### Configuration

```python
import simpleml

# Simple configuration - endpoint is pre-configured for the SaaS platform
simpleml.configure(api_key="your_api_key_here")
```

## Features

- **Experiment Tracking**: Organize your ML experiments
- **Metrics Logging**: Track training and validation metrics over time
- **Artifact Management**: Upload and manage model files, plots, and data
- **Model Registry**: Register and version your models
- **Simple Setup**: Pre-configured production endpoint, just add your API key
- **Lightweight**: Minimal dependencies, fast setup

## API Reference

### Configuration

```python
simpleml.configure(
    api_key="your_api_key_here"   # Required: Your API key (endpoint is pre-configured)
)
```

### Experiments

```python
# Get or create experiment
experiment = simpleml.get_or_create_experiment(
    name="image-classification",
    description="CIFAR-10 classification experiment",
    tags={"dataset": "cifar10", "model": "resnet"}
)

# Get existing experiment
experiment = simpleml.get_experiment("exp-123")

# List experiments
experiments = simpleml.list_experiments()
```

### Runs

```python
# Start a run
run = experiment.start_run(
    name="run-1",
    hyperparameters={"lr": 0.001, "batch_size": 32},
    tags={"optimizer": "adam"}
)

# Get existing run
run = simpleml.get_run("run-123")
```

### Metrics

```python
# Log metrics (always use batch method)
run.log_metrics({
    "train_loss": 0.1,
    "val_loss": 0.15,
    "accuracy": 0.95
}, step=100)
```

### Artifacts

```python
# Upload file
run.upload_artifact("model.pkl", artifact_type="model")

# Upload with custom name
run.upload_artifact("./plots/confusion_matrix.png", 
                   filename="confusion_matrix.png",
                   artifact_type="plot")

# List artifacts
artifacts = run.list_artifacts()

# Download artifact
run.download_artifact("artifact-123", "./downloads/model.pkl")
```

### Models

```python
# Register model from run
model = run.register_model(
    model_name="cifar10-classifier",
    artifacts=["model.pkl", "config.json"],
    description="ResNet model for CIFAR-10",
    stage="staging"
)

# List models
models = simpleml.list_models()

# Update model stage
simpleml.update_model_stage("cifar10-classifier", "v1", "production")
```

## Context Manager Usage

```python
import simpleml

simpleml.configure(api_key="your_api_key_here")

with simpleml.start_run("my-experiment") as run:
    # Your training code here
    for epoch in range(10):
        loss = train_epoch()
        accuracy = validate()
        
        run.log_metrics({
            "loss": loss,
            "accuracy": accuracy
        }, step=epoch)
    
    # Upload model
    run.upload_artifact("model.pkl", artifact_type="model")
    
    # Register model if performance is good
    if accuracy > 0.9:
        run.register_model("my-model", ["model.pkl"])
```

## Environment Variables

You can also configure using environment variables:

```bash
export SIMPLEML_API_KEY="your_api_key_here"
```

## Error Handling

```python
from simpleml.exceptions import SimpleMLError, AuthenticationError, NotFoundError

try:
    run = simpleml.get_run("invalid-run-id")
except NotFoundError:
    print("Run not found")
except AuthenticationError:
    print("Invalid API key")
except SimpleMLError as e:
    print(f"SimpleML error: {e}")
```

## License

MIT License - see LICENSE file for details.