Metadata-Version: 2.4
Name: simplemlplatform
Version: 1.0.0
Summary: A lightweight MLOps SDK for experiment tracking and model registry
Home-page: https://github.com/simpleml/simpleml-sdk
Author: SimpleML Team
Author-email: SimpleML Team <team@simpleml.com>
Maintainer-email: SimpleML Team <team@simpleml.com>
License: MIT
Project-URL: Homepage, https://github.com/simpleml/simpleml-sdk
Project-URL: Documentation, https://simpleml.readthedocs.io
Project-URL: Repository, https://github.com/simpleml/simpleml-sdk
Project-URL: Bug Reports, https://github.com/simpleml/simpleml-sdk/issues
Keywords: mlops,machine learning,experiment tracking,model registry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: boto3>=1.20.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: python-ulid>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 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 simpleml
```

## Quick Start

### Auto-configuration with CloudFormation Stack

```python
import simpleml

# Auto-configure using your deployed stack
simpleml.configure(stack_name="your-simpleml-stack")

# 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()
```

### Manual Configuration

```python
import simpleml

# Manual configuration
simpleml.configure(
    api_endpoint="https://your-api.execute-api.region.amazonaws.com/Prod",
    api_key="sk_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
- **Auto-configuration**: Automatically detect endpoints from CloudFormation
- **Lightweight**: Minimal dependencies, fast setup

## API Reference

### Configuration

```python
simpleml.configure(
    stack_name="my-stack",          # Auto-detect from stack
    region="us-west-2",             # AWS region
    api_endpoint="https://...",     # Manual endpoint
    api_key="sk_...",              # API key
    tenant_id="tenant-123"         # Tenant ID (optional)
)
```

### 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(stack_name="my-stack")

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_ENDPOINT="https://your-api.execute-api.region.amazonaws.com/Prod"
export SIMPLEML_API_KEY="sk_your_api_key_here"
export SIMPLEML_TENANT_ID="tenant-123"
```

## 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.
