Metadata-Version: 2.4
Name: comfyui-python-client
Version: 0.1.2
Summary: Add your description here
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: websocket-client
Requires-Dist: requests
Requires-Dist: httpx

# comfyui-python-client

ComfyUI REST/WebSocket API를 Python에서 다루기 쉽게 감싼 경량 클라이언트입니다.

- 기본 서버: `127.0.0.1:8188`
- 지원 기능: 프롬프트 실행/대기, 히스토리, 큐 제어, 이미지 업/다운로드, 시스템/모델/템플릿/사용자 API
- 클라이언트 구성: 동기(`ComfyClient`/`SyncComfyClient`) + 비동기(`AsyncComfyClient`)

## 요구사항

- Python `>= 3.12`
- 실행 중인 ComfyUI 서버

## 설치

패키지 루트(`packages/comfyui-python-client`)에서:

```bash
pip install -e .
```

## 빠른 시작

```python
from comfy_sdk import ComfyUI
import json

client = ComfyUI(host="127.0.0.1", port=8188)

# 1) 연결 확인
stats = client.system.stats()
print(stats)

# 2) 워크플로우 전송
with open("workflow_api.json", "r", encoding="utf-8") as f:
    workflow = json.load(f)

res = client.prompt.send(workflow)
print("prompt_id:", res.prompt_id)

# 3) 완료 대기 후 히스토리 조회
history = client.prompt.wait(res.prompt_id)
print(history)
```

## 비동기 클라이언트 예시

```python
import asyncio
from comfy_sdk import AsyncComfyClient

async def main():
    client = AsyncComfyClient(host="127.0.0.1", port=8188)

    stats = await client.get_system_stats()
    print(stats)

    # 필요 시 워크플로우 실행/대기
    # res = await client.queue_prompt(workflow)
    # history = await client.wait_for_completion(res.prompt_id)

    await client.close()

asyncio.run(main())
```

## API 개요

`ComfyUI` 인스턴스는 아래 리소스를 제공합니다.

- `client.prompt`
  - `send(workflow)`
  - `retrieve(prompt_id)`
  - `wait(prompt_id)`
  - `history()`, `delete(prompt_id)`, `clear()`
- `client.images`
  - `upload(data, name, overwrite=False)`
  - `download(filename, subfolder="", folder_type="output")`
  - `upload_mask(data, name, original_ref, overwrite=False, mask_type="mask")`
  - `metadata(filename, subfolder="", folder_type="output")`
- `client.system`
  - `stats()`, `extensions()`, `embeddings()`, `features()`
  - `free(unload_models=False, free_memory=False)`
- `client.queue`
  - `status()`, `interrupt()`, `clear()`
- `client.models`
  - `list(folder=None)` (`checkpoints`, `loras` 등)
- `client.templates`
  - `list()`
- `client.users`
  - `list()`, `create(username)`
- `client.userdata`
  - `get(file)`, `move(file, dest)`

## 이미지 업로드 예시

```python
from comfy_sdk import ComfyUI

client = ComfyUI()

with open("input.png", "rb") as f:
    image_bytes = f.read()

result = client.images.upload(image_bytes, "input.png", overwrite=True)
print(result)
```

## 참고

- `prompt.wait(prompt_id)`는 내부적으로 WebSocket(`ws://<host>:<port>/ws`)을 사용합니다.
- ComfyUI가 실행 중이 아니면 요청이 실패하므로 먼저 서버 상태를 확인하세요.
