Metadata-Version: 2.4
Name: edi-maas-sdk
Version: 0.1.5
Summary: MaaS Platform Python SDK for model and dataset management
Author: MaaS Platform Team
License: MIT
Keywords: maas,model,dataset,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: tqdm>=4.66

# edi-maas-sdk

MaaS Platform Python SDK — HTTP client for model and dataset management.

## Install

```bash
pip install edi-maas-sdk
```

## Quick Start

```python
from edi_maas_sdk import DatasetCategory, DatasetFormat, DatasetSplit, EdiApi

api = EdiApi(endpoint="https://maas.example.com/maas-service", api_key="edik-...")

# List models
repos = api.list_repos("models")
for r in repos:
    print(r.name, r.status)

# Create a model (display_name required; name is auto-generated)
result = api.create_repo("models", display_name="My Model", description="A fine-tuned model")

# Create a dataset (display_name required, name auto-generated; optional enums)
result = api.create_repo(
    "datasets",
    display_name="My Dataset",
    dataset_category=DatasetCategory.TEXT_CORPUS,
    format=DatasetFormat.PARQUET,
    split=DatasetSplit.TRAIN,
    tags=["nlp"],
)

# List versions
refs = api.list_repo_refs("models", org_id="acme", name=result.name)
for ref in refs:
    print(ref.id, ref.version_name)

# Create a new named version (e.g. for a new release)
new_ref = api.create_version("models", org_id="acme", name=result.name, version="v2.0.0", message="add v2 artifacts")

# Upload files into a specific version (targets that version's S3 prefix)
api.upload_file("models", org_id="acme", name=result.name, file_path="./weights.bin", version="v2.0.0")
api.upload_folder("models", org_id="acme", name=result.name, local_dir="./artifacts", version="v2.0.0")

# Browse files
files = api.list_repo_tree("models", org_id="acme", name=result.name, version=refs[0].version_name, recursive=True)
for f in files:
    print(f.type, f.path, f.size)

# Download (returns presigned URL; optional expires in seconds, max 3600)
info = api.file_download("models", org_id="acme", name=result.name, version=refs[0].version_name, path="pytorch_model.bin", expires=1800)
print(info.url, info.expires_in)

# Upload (pre-signed S3 multipart direct upload, streamed part-by-part)
api.upload_file("models", org_id="acme", name=result.name, file_path="./weights.bin", on_progress=lambda rel, done, total: print(f"{rel}: {done}/{total}"))

# Upload a whole folder (filename = path relative to folder)
api.upload_folder("models", org_id="acme", name=result.name, local_dir="./artifacts", on_progress=print)
```

## Command-line Interface

The `maas` console script wraps the SDK for scripting. All subcommands share `--endpoint`, `--api-key` (or `MAAS_SDK_API_KEY`), `--org-id`, `--name`, `--repo-type`.

```bash
# Create a new named version
maas create-version --org-id acme --name repo-01hxxxx --version v2.0.0 --message "v2 release"

# Upload into a specific version
maas upload-file --org-id acme --name repo-01hxxxx --repo-type models --file ./weights.bin --version v2.0.0
maas upload-folder --org-id acme --name repo-01hxxxx --repo-type models --dir ./artifacts --version v2.0.0

# Download a file from a specific version
maas download-file --org-id acme --name repo-01hxxxx --repo-type models --version v2.0.0 --path pytorch_model.bin --output ./pytorch_model.bin
```

`create-version` and `download-file` require `--version`; `upload-file` / `upload-folder` accept an optional `--version` (omitting it targets the default version). `--no-progress` disables the progress bar.

## Configuration

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `MAAS_ENDPOINT` | MaaS service base URL | `http://localhost:8000/maas-service` |
| `MAAS_SDK_API_KEY` | SDK API key | (required) |

## API Reference

### `EdiApi(endpoint=None, api_key=None)`

Create a client. Reads `MAAS_ENDPOINT` and `MAAS_SDK_API_KEY` from environment if not provided.

### Methods

| Method | Description |
|--------|-------------|
| `create_repo(repo_type, display_name, model_category?, dataset_category?, format?, split?, tags?)` | Create a model or dataset (name is auto-generated) |
| `create_version(repo_type, *, org_id, name, version, message?)` | Create a new named version (e.g. `v2.0.0`) |
| `list_repos(repo_type, keyword?, page_no?, page_size?)` | List repos |
| `list_repo_refs(repo_type, *, org_id, name)` | List versions |
| `list_repo_tree(repo_type, *, org_id, name, version, path?, recursive?)` | Browse files |
| `file_download(repo_type, *, org_id, name, version, path, expires?)` | Get presigned download URL (expires in seconds, max 3600) |
| `upload_file(repo_type, *, org_id, name, file_path, relative_path?, version?, on_progress?)` | Upload a single file (presigned S3 multipart, streamed; optional progress callback `on_progress(rel, done, total)`; `version` targets a specific version) |
| `upload_folder(repo_type, *, org_id, name, local_dir, version?, on_progress?)` | Upload a whole folder (relative paths preserved; optional progress callback; `version` targets a specific version). `ValueError` if the directory is missing or empty |

### Enums

`create_repo` accepts typed enums for category / format / split fields. The server validates these and rejects unknown values with HTTP 422.

| Enum | Values |
|------|--------|
| `ModelCategory` | `llm`, `embedding`, `image`, `vision`, `audio`, `rerank`, `video` |
| `DatasetCategory` | `text_corpus`, `instruction_tuning`, `image_caption`, `image_generation`, `lora_training`, `object_detection`, `image_classification`, `image_segmentation`, `other` |
| `DatasetFormat` | `parquet`, `jsonl`, `csv`, `arrow`, `image_folder`, `text_folder`, `custom` |
| `DatasetSplit` | `train`, `validation`, `test`, `train+validation`, `all`, `custom` |

## License

MIT
