synapse-sdk 1.0.0b12__py3-none-any.whl → 1.0.0b14__py3-none-any.whl

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/api/clients/ray.md

@@ -0,0 +1,321 @@
+---
+id: ray
+title: RayClient
+sidebar_position: 4
+---
+
+# RayClient
+
+Apache Ray 클러스터 관리 및 모니터링 기능을 위한 클라이언트입니다.
+
+## 개요
+
+`RayClientMixin`은 작업 관리, 실시간 로그 스트리밍, 노드 모니터링, Ray Serve 애플리케이션 제어를 포함한 포괄적인 Ray 클러스터 작업을 제공합니다. Ray 전용 기능으로 `BaseClient`를 확장하는 mixin 클래스로 설계되었습니다.
+
+## 주요 기능
+
+- **Job 라이프사이클 관리**: Ray 작업 생성, 모니터링 및 관리
+- **실시간 로그 스트리밍**: WebSocket 및 HTTP 기반 로그 테일링
+- **노드 및 태스크 모니터링**: 클러스터 리소스 및 태스크 실행 모니터링
+- **Ray Serve 통합**: Ray Serve 애플리케이션 배포 및 관리
+- **강력한 오류 처리**: 입력 유효성 검사 및 정제된 오류 메시지
+- **리소스 관리**: 자동 정리 및 연결 추적
+
+## Constructor
+
+```python
+# RayClientMixin은 일반적으로 mixin으로 사용됩니다
+class RayClient(RayClientMixin):
+    def __init__(self, base_url: str, timeout: dict = None):
+        super().__init__(base_url, timeout)
+```
+
+### Parameters
+
+- `base_url` (str): Ray 클러스터 대시보드 URL (예: "http://ray-head:8265")
+- `timeout` (dict, 선택사항): 연결 및 읽기 timeout 설정
+
+## 사용법
+
+```python
+from synapse_sdk.clients.agent.ray import RayClientMixin
+from synapse_sdk.clients.base import BaseClient
+
+class RayClient(RayClientMixin, BaseClient):
+    pass
+
+client = RayClient(base_url="http://ray-head:8265")
+
+# 모든 작업 나열
+jobs = client.list_jobs()
+
+# 특정 작업 세부정보 가져오기
+job = client.get_job('job-12345')
+
+# 실시간으로 로그 스트리밍
+for log_line in client.tail_job_logs('job-12345'):
+    print(log_line.strip())
+```
+
+## Job 작업
+
+### `get_job(pk)`
+
+특정 작업에 대한 세부정보를 검색합니다.
+
+```python
+job = client.get_job('job-12345')
+print(f"Job 상태: {job['status']}")
+```
+
+### `list_jobs()`
+
+Ray 클러스터의 모든 작업을 나열합니다.
+
+```python
+jobs = client.list_jobs()
+for job in jobs['results']:
+    print(f"Job {job['id']}: {job['status']}")
+```
+
+### `list_job_logs(pk)`
+
+작업에 대한 정적 로그 항목을 가져옵니다.
+
+```python
+logs = client.list_job_logs('job-12345')
+```
+
+## 실시간 로그 스트리밍
+
+### `tail_job_logs(pk, stream_timeout=10, protocol='stream')`
+
+WebSocket 또는 HTTP 프로토콜을 사용하여 작업 로그를 스트리밍합니다.
+
+```python
+# HTTP 스트리밍 (기본값, 호환성 높음)
+for log_line in client.tail_job_logs('job-12345', protocol='stream'):
+    print(log_line.strip())
+
+# WebSocket 스트리밍 (낮은 지연시간)
+for log_line in client.tail_job_logs('job-12345', protocol='websocket'):
+    print(log_line.strip())
+
+# 사용자 정의 timeout으로
+for log_line in client.tail_job_logs('job-12345', stream_timeout=30):
+    if 'ERROR' in log_line:
+        break
+```
+
+### `websocket_tail_job_logs(pk, stream_timeout=10)`
+
+가장 낮은 지연시간을 위해 WebSocket을 통해 로그를 스트리밍합니다.
+
+```python
+try:
+    for log_line in client.websocket_tail_job_logs('job-12345'):
+        print(log_line.strip())
+        if 'COMPLETED' in log_line:
+            break
+except ClientError as e:
+    print(f"WebSocket 스트리밍 실패: {e}")
+```
+
+### `stream_tail_job_logs(pk, stream_timeout=10)`
+
+HTTP chunked transfer encoding을 통해 로그를 스트리밍합니다.
+
+```python
+for log_line in client.stream_tail_job_logs('job-12345', stream_timeout=60):
+    if 'FAILED' in log_line:
+        print(f"Job 실패: {log_line}")
+        break
+```
+
+## 노드 작업
+
+### `get_node(pk)`
+
+특정 클러스터 노드에 대한 세부정보를 가져옵니다.
+
+```python
+node = client.get_node('node-abc123')
+print(f"노드 상태: {node['alive']}")
+```
+
+### `list_nodes()`
+
+Ray 클러스터의 모든 노드를 나열합니다.
+
+```python
+nodes = client.list_nodes()
+for node in nodes['results']:
+    print(f"노드 {node['node_id']}: {node['state']}")
+```
+
+## 태스크 작업
+
+### `get_task(pk)`
+
+특정 태스크에 대한 세부정보를 검색합니다.
+
+```python
+task = client.get_task('task-xyz789')
+```
+
+### `list_tasks()`
+
+클러스터의 모든 태스크를 나열합니다.
+
+```python
+tasks = client.list_tasks()
+```
+
+## Ray Serve 작업
+
+### `get_serve_application(pk)`
+
+Ray Serve 애플리케이션에 대한 세부정보를 가져옵니다.
+
+```python
+app = client.get_serve_application('app-123')
+print(f"애플리케이션 상태: {app['status']}")
+```
+
+### `list_serve_applications()`
+
+모든 Ray Serve 애플리케이션을 나열합니다.
+
+```python
+apps = client.list_serve_applications()
+```
+
+### `delete_serve_application(pk)`
+
+Ray Serve 애플리케이션을 삭제합니다.
+
+```python
+client.delete_serve_application('app-123')
+```
+
+## 오류 처리
+
+모든 메서드에는 특정 `ClientError` 예외와 함께 강력한 오류 처리가 포함됩니다:
+
+```python
+from synapse_sdk.clients.exceptions import ClientError
+
+try:
+    for log_line in client.tail_job_logs('invalid-job'):
+        print(log_line)
+except ClientError as e:
+    if e.status == 400:
+        print("잘못된 작업 ID 또는 매개변수")
+    elif e.status == 404:
+        print("작업을 찾을 수 없음")
+    elif e.status == 503:
+        print("Ray 클러스터 연결 실패")
+    else:
+        print(f"예상치 못한 오류: {e}")
+```
+
+### 일반적인 오류 코드
+
+- **400**: 잘못된 매개변수 (job ID, timeout, protocol)
+- **404**: 리소스를 찾을 수 없음 (job, node, task, application)
+- **408**: 연결 또는 읽기 timeout
+- **429**: 스트림 제한 초과
+- **500**: WebSocket 라이브러리 사용 불가 또는 내부 오류
+- **503**: Ray 클러스터 연결 실패
+
+## 리소스 관리
+
+RayClient에는 자동 리소스 관리가 포함됩니다:
+
+- **Thread Pool**: 동시 작업을 위한 5개 작업자 스레드
+- **연결 추적**: 활성 연결을 위한 WeakSet
+- **스트림 제한**: 메모리 고갈 방지
+- **자동 정리**: 소멸 시 리소스 정리
+
+### 스트림 제한
+
+로그 스트리밍을 위한 기본 제한:
+
+- 최대 메시지: 10,000
+- 최대 라인: 50,000
+- 최대 바이트: 50MB
+- 최대 메시지 크기: 10KB
+- Queue 크기: 1,000
+
+## 모범 사례
+
+### 1. 프로토콜 선택
+
+```python
+# 사용 가능한 경우 가장 낮은 지연시간을 위해 WebSocket 사용
+try:
+    logs = client.tail_job_logs(job_id, protocol='websocket')
+except ClientError:
+    # HTTP 스트리밍으로 폴백
+    logs = client.tail_job_logs(job_id, protocol='stream')
+```
+
+### 2. Timeout 관리
+
+```python
+# 장기 실행 작업에 적절한 timeout 사용
+for log_line in client.tail_job_logs(job_id, stream_timeout=300):
+    process_log_line(log_line)
+```
+
+### 3. 오류 복구
+
+```python
+import time
+
+def robust_log_streaming(client, job_id, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            for log_line in client.tail_job_logs(job_id):
+                yield log_line
+            break
+        except ClientError as e:
+            if e.status == 503 and attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # 지수 백오프
+                continue
+            raise
+```
+
+### 4. 리소스 정리
+
+```python
+# 적절한 정리를 위한 컨텍스트 매니저
+class RayClientContext:
+    def __init__(self, base_url):
+        self.client = RayClient(base_url)
+
+    def __enter__(self):
+        return self.client
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # RayClient.__del__()에 의해 자동으로 정리 처리
+        pass
+
+with RayClientContext("http://ray-head:8265") as client:
+    for log_line in client.tail_job_logs('job-12345'):
+        print(log_line.strip())
+```
+
+## 스레드 안전성
+
+RayClient는 적절한 스레드 안전 메커니즘을 통해 동시 사용을 위해 설계되었습니다:
+
+- 백그라운드 작업을 위한 스레드 풀
+- 연결 추적을 위한 WeakSet
+- 적절한 리소스 정리 메커니즘
+
+## 참고
+
+- [AgentClient](./agent.md) - Agent 전용 작업을 위한 클라이언트
+- [BaseClient](./base.md) - 기본 클라이언트 구현
+- [Network Utilities](../utils/network.md) - 스트리밍 및 유효성 검사 유틸리티

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/api/index.md

@@ -0,0 +1,52 @@
+---
+id: index
+title: API 참조
+sidebar_position: 1
+---
+
+# API 참조
+
+Synapse SDK 클래스 및 함수에 대한 완전한 참조 문서입니다.
+
+## 개요
+
+Synapse SDK API는 다음 주요 모듈로 구성됩니다:
+
+### [클라이언트](./clients/backend.md)
+백엔드 서비스 및 에이전트와 상호작용하기 위한 클라이언트 클래스들.
+
+- **[BackendClient](./clients/backend.md)** - 백엔드 작업을 위한 메인 클라이언트
+- **[AgentClient](./clients/agent.md)** - 에이전트 특정 작업을 위한 클라이언트
+- **[RayClient](./clients/ray.md)** - Ray 클러스터 관리 및 모니터링을 위한 클라이언트
+- **[BaseClient](./clients/base.md)** - 모든 클라이언트의 기본 클래스
+
+핵심 플러그인 시스템 컴포넌트들.
+
+### [유틸리티](./utils/file.md)
+도우미 함수 및 유틸리티들.
+
+- **[파일 유틸](./utils/file.md)** - 파일 작업 및 처리
+- **[네트워크](./utils/network.md)** - 스트리밍, 검증 및 연결 관리
+- **[스토리지](./utils/storage.md)** - 스토리지 제공자들 (S3, GCS, SFTP)
+- **[타입](./utils/types.md)** - 커스텀 타입 및 필드
+
+## 빠른 참조
+
+### 클라이언트 생성
+
+```python
+from synapse_sdk.clients.backend import BackendClient
+
+client = BackendClient(
+    base_url="https://api.synapse.sh",
+    api_token="your-api-token"
+)
+```
+
+### 플러그인 실행
+
+### 플러그인 액션 생성
+
+## 타입 어노테이션
+
+## 파일 처리

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/api/utils/file.md

@@ -0,0 +1,195 @@
+---
+id: file
+title: 파일 유틸리티
+sidebar_position: 1
+---
+
+# 파일 유틸리티
+
+파일 작업 및 처리 유틸리티입니다.
+
+## 파일 작업
+
+### 아카이브 함수
+
+플러그인 아카이브를 생성하고 추출하는 함수입니다.
+
+### 다운로드 함수
+
+URL에서 파일을 다운로드하는 유틸리티입니다.
+
+```python
+from synapse_sdk.utils.file import download_file
+
+local_path = download_file(url, destination)
+```
+
+### 업로드 함수
+
+청크 업로드 지원을 포함한 파일 업로드 유틸리티입니다.
+
+## 청크 파일 작업
+
+### read_file_in_chunks
+
+효율적인 메모리 사용을 위해 파일을 청크 단위로 읽습니다. 대용량 파일이나 업로드 또는 해싱을 위해 파일을 청크 단위로 처리할 때 특히 유용합니다.
+
+```python
+from synapse_sdk.utils.file import read_file_in_chunks
+
+# 기본 50MB 청크로 파일 읽기
+for chunk in read_file_in_chunks('/path/to/large_file.bin'):
+    process_chunk(chunk)
+
+# 사용자 정의 청크 크기로 읽기 (10MB)
+for chunk in read_file_in_chunks('/path/to/file.bin', chunk_size=1024*1024*10):
+    upload_chunk(chunk)
+```
+
+**매개변수:**
+
+- `file_path` (str | Path): 읽을 파일의 경로
+- `chunk_size` (int, 선택사항): 각 청크의 바이트 크기. 기본값은 50MB (52,428,800바이트)
+
+**반환값:**
+
+- 파일 내용 청크를 바이트로 생성하는 제너레이터
+
+**예외:**
+
+- `FileNotFoundError`: 파일이 존재하지 않는 경우
+- `PermissionError`: 권한으로 인해 파일을 읽을 수 없는 경우
+- `OSError`: 파일 읽기 시 OS 수준 오류가 발생한 경우
+
+### 사용 사례
+
+**대용량 파일 처리**: 메모리에 맞지 않는 대용량 파일을 효율적으로 처리합니다:
+
+```python
+import hashlib
+
+def calculate_hash_for_large_file(file_path):
+    hash_md5 = hashlib.md5()
+    for chunk in read_file_in_chunks(file_path):
+        hash_md5.update(chunk)
+    return hash_md5.hexdigest()
+```
+
+**청크 업로드 통합**: 이 함수는 `CoreClientMixin.create_chunked_upload` 메서드와 완벽하게 통합됩니다:
+
+```python
+from synapse_sdk.clients.backend.core import CoreClientMixin
+
+client = CoreClientMixin(base_url='https://api.example.com')
+result = client.create_chunked_upload('/path/to/large_file.zip')
+```
+
+**모범 사례:**
+
+- 최적의 업로드 성능을 위해 기본 청크 크기(50MB) 사용
+- 사용 가능한 메모리와 네트워크 조건에 따라 청크 크기 조정
+- 매우 큰 파일(>1GB)의 경우, 더 나은 진행 상황 추적을 위해 작은 청크 사용 고려
+- 파일 작업 시 항상 예외 처리
+
+## 체크섬 함수
+
+### get_checksum_from_file
+
+Django 의존성 없이 파일 형태 객체의 체크섬을 계산합니다. 이 함수는 `read()` 메서드가 있는 모든 파일 형태 객체와 함께 작동하며, Django의 File 객체, BytesIO, StringIO, 일반 파일 객체와 호환됩니다.
+
+```python
+import hashlib
+from io import BytesIO
+from synapse_sdk.utils.file import get_checksum_from_file
+
+# BytesIO와 기본 사용법 (기본값은 SHA1)
+data = BytesIO(b'Hello, world!')
+checksum = get_checksum_from_file(data)
+print(checksum)  # 16진수 문자열로 된 SHA1 해시
+
+# 다른 해시 알고리즘 사용
+checksum_md5 = get_checksum_from_file(data, digest_mod=hashlib.md5)
+checksum_sha256 = get_checksum_from_file(data, digest_mod=hashlib.sha256)
+
+# 실제 파일 객체와 함께 사용
+with open('/path/to/file.txt', 'rb') as f:
+    checksum = get_checksum_from_file(f)
+
+# StringIO와 함께 사용 (텍스트 파일)
+from io import StringIO
+text_data = StringIO('Hello, world!')
+checksum = get_checksum_from_file(text_data)  # 자동으로 UTF-8로 인코딩
+```
+
+**매개변수:**
+
+- `file` (IO[Any]): 청크 단위로 읽기를 지원하는 read() 메서드가 있는 파일 형태 객체
+- `digest_mod` (Callable[[], Any], 선택사항): hashlib의 해시 알고리즘. 기본값은 `hashlib.sha1`
+
+**반환값:**
+
+- `str`: 파일 내용의 16진수 다이제스트
+
+**주요 기능:**
+
+- **메모리 효율적**: 대용량 파일을 처리하기 위해 4KB 청크로 파일 읽기
+- **자동 파일 포인터 리셋**: 파일 객체가 시킹을 지원하는 경우 시작 위치로 리셋
+- **텍스트/바이너리 무관**: 텍스트(StringIO)와 바이너리(BytesIO) 파일 객체 모두 처리
+- **Django 의존성 없음**: Django File 객체와 호환되면서도 Django 없이 작동
+- **유연한 해시 알고리즘**: 모든 hashlib 알고리즘 지원 (SHA1, SHA256, MD5 등)
+
+**사용 사례:**
+
+**Django 파일 객체 호환성**: Django를 요구하지 않으면서도 Django의 File 객체와 함께 작동합니다:
+
+```python
+# Django File 형태 동작 시뮬레이션
+class FileWrapper:
+    def __init__(self, data):
+        self._data = data
+        self._pos = 0
+
+    def read(self, size=None):
+        if size is None:
+            result = self._data[self._pos:]
+            self._pos = len(self._data)
+        else:
+            result = self._data[self._pos:self._pos + size]
+            self._pos += len(result)
+        return result
+
+file_obj = FileWrapper(b'File content')
+checksum = get_checksum_from_file(file_obj)
+```
+
+**대용량 파일 처리**: 대용량 파일의 체크섬을 효율적으로 계산합니다:
+
+```python
+# 메모리 효율성을 갖춘 대용량 파일 처리
+with open('/path/to/large_file.bin', 'rb') as large_file:
+    checksum = get_checksum_from_file(large_file, digest_mod=hashlib.sha256)
+```
+
+**다중 해시 알고리즘**: 같은 파일에 대해 다른 체크섬을 계산합니다:
+
+```python
+algorithms = [
+    ('MD5', hashlib.md5),
+    ('SHA1', hashlib.sha1),
+    ('SHA256', hashlib.sha256),
+]
+
+with open('/path/to/file.bin', 'rb') as f:
+    checksums = {}
+    for name, algo in algorithms:
+        f.seek(0)  # 파일 포인터 리셋
+        checksums[name] = get_checksum_from_file(f, digest_mod=algo)
+```
+
+## 경로 유틸리티
+
+경로 조작 및 검증을 위한 함수입니다.
+
+## 임시 파일
+
+임시 파일 관리 및 정리를 위한 유틸리티입니다.