Metadata-Version: 2.4
Name: mlngi
Version: 0.1.0
Summary: MLNGI Python SDK - ML 실험 추적 및 모델 관리
Author-email: NGI Corp <dev@ngi.co.kr>
License: Proprietary
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"

# MLNGI Python SDK

ML 실험 추적 및 모델 관리를 위한 Python SDK입니다.

## 설치

```bash
cd sdk
pip install -e .
```

## 빠른 시작

### 1. 환경 변수 설정

```bash
export MLNGI_TRACKING_URI=http://localhost:8000/api/v1
export MLNGI_API_KEY=mlngi_xxxxxxxx  # 또는 MLNGI_TOKEN
```

### 2. 실험 추적

```python
import mlngi

# 서버 연결
mlngi.set_tracking_uri("http://localhost:8000/api/v1")

# 실험 설정 (없으면 자동 생성)
mlngi.set_experiment("image-classification")

# Run 실행
with mlngi.start_run(name="resnet50-v1"):
    # 파라미터 기록
    mlngi.log_param("learning_rate", 0.001)
    mlngi.log_param("batch_size", 32)
    mlngi.log_param("epochs", 100)

    # 또는 한 번에
    mlngi.log_params({
        "optimizer": "adam",
        "model": "resnet50",
    })

    # 학습 루프
    for epoch in range(100):
        loss = 1.0 / (epoch + 1)  # 예시
        accuracy = 1 - loss

        # 메트릭 기록
        mlngi.log_metric("loss", loss, step=epoch)
        mlngi.log_metric("accuracy", accuracy, step=epoch)

        # 또는 한 번에
        mlngi.log_metrics({"loss": loss, "accuracy": accuracy}, step=epoch)

    # 태그 설정
    mlngi.set_tag("model_type", "resnet50")
    mlngi.set_tags({"framework": "pytorch", "dataset": "imagenet"})

# with 블록을 빠져나오면 Run이 자동으로 완료됩니다.
```

### 3. 저수준 클라이언트 사용

```python
from mlngi import MLNGIClient

client = MLNGIClient(
    "http://localhost:8000/api/v1",
    api_key="mlngi_xxxxxxxx"
)

# 프로젝트 목록
projects = client.list_projects()

# 모델 등록
model = client.create_model("my-model", project_id="...")
version = client.create_model_version(model["id"], run_id="...")
client.set_model_alias(model["id"], "champion", version["version"])
```

## API 참조

### 고수준 API (mlngi.*)

| 함수 | 설명 |
|------|------|
| `set_tracking_uri(uri)` | 서버 URI 설정 |
| `set_experiment(name, project_id?)` | 실험 설정 (없으면 자동 생성) |
| `start_run(name?, tags?)` | Run 시작 (with 문 사용) |
| `end_run()` | 활성 Run 종료 |
| `log_param(key, value)` | 파라미터 기록 |
| `log_params(params_dict)` | 여러 파라미터 한 번에 기록 |
| `log_metric(key, value, step?)` | 메트릭 기록 |
| `log_metrics(metrics_dict, step?)` | 여러 메트릭 한 번에 기록 |
| `set_tag(key, value)` | 태그 설정 |
| `set_tags(tags_dict)` | 여러 태그 설정 |
| `active_run()` | 현재 활성 Run 정보 |
| `get_run(run_id)` | Run 정보 조회 |

### 저수준 API (MLNGIClient)

| 메서드 | 설명 |
|--------|------|
| `list_projects()` | 프로젝트 목록 |
| `create_project(name, description)` | 프로젝트 생성 |
| `list_experiments(project_id)` | 실험 목록 |
| `create_experiment(project_id, name)` | 실험 생성 |
| `create_run(experiment_id, name, tags)` | Run 생성 |
| `get_run(run_id)` | Run 조회 |
| `stop_run(run_id)` | Run 종료 |
| `log_metric(run_id, key, value, step)` | 메트릭 기록 |
| `log_param(run_id, key, value)` | 파라미터 기록 |
| `set_tags(run_id, tags)` | 태그 설정 |
| `create_model(name, project_id)` | 모델 등록 |
| `create_model_version(model_id, run_id)` | 모델 버전 생성 |
| `set_model_alias(model_id, alias, version)` | 모델 별칭 설정 |
