synapse-sdk 1.0.0a13__py3-none-any.whl → 2025.11.7__py3-none-any.whl

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/features/utils/network.md

@@ -0,0 +1,378 @@
+---
+id: network
+title: Network Utilities
+sidebar_position: 4
+---
+
+# Network Utilities
+
+스트리밍, 유효성 검사 및 연결 관리를 위한 포괄적인 네트워킹 유틸리티입니다.
+
+## 개요
+
+`synapse_sdk.utils.network` 모듈은 Ray 및 기타 클라이언트에서 안전하고 강력한 스트리밍 작업 및 입력 유효성 검사를 위해 사용하는 필수 네트워킹 구성 요소를 제공합니다.
+
+## StreamLimits
+
+리소스 고갈을 방지하기 위한 스트리밍 작업 제한을 위한 구성 클래스입니다.
+
+### Constructor
+
+```python
+from synapse_sdk.utils.network import StreamLimits
+
+limits = StreamLimits(
+    max_messages=10000,
+    max_lines=50000,
+    max_bytes=50 * 1024 * 1024,  # 50MB
+    max_message_size=10240,      # 10KB
+    queue_size=1000,
+    exception_queue_size=10
+)
+```
+
+### Parameters
+
+- `max_messages` (int): 처리할 최대 메시지 수 (기본값: 10,000)
+- `max_lines` (int): 스트리밍할 최대 라인 수 (기본값: 50,000)
+- `max_bytes` (int): 처리할 최대 총 바이트 (기본값: 50MB)
+- `max_message_size` (int): 메시지당 최대 크기 (기본값: 10KB)
+- `queue_size` (int): 메시지 버퍼링을 위한 내부 큐 크기 (기본값: 1,000)
+- `exception_queue_size` (int): 예외 처리를 위한 큐 크기 (기본값: 10)
+
+### 사용법
+
+```python
+# 대용량 스트리밍을 위한 사용자 정의 제한
+custom_limits = StreamLimits(
+    max_messages=50000,
+    max_lines=100000,
+    max_bytes=100 * 1024 * 1024  # 100MB
+)
+
+# 스트림 매니저와 함께 사용
+websocket_manager = WebSocketStreamManager(thread_pool, custom_limits)
+```
+
+## WebSocketStreamManager
+
+자동 오류 처리 및 리소스 정리를 통한 실시간 로그 스트리밍을 위해 WebSocket 연결을 관리합니다.
+
+### Constructor
+
+```python
+from synapse_sdk.utils.network import WebSocketStreamManager
+from concurrent.futures import ThreadPoolExecutor
+
+thread_pool = ThreadPoolExecutor(max_workers=5)
+limits = StreamLimits()
+manager = WebSocketStreamManager(thread_pool, limits)
+```
+
+### Methods
+
+#### `stream_logs(ws_url, headers, timeout, context)`
+
+WebSocket 엔드포인트에서 로그를 스트리밍합니다.
+
+```python
+# 오류 처리가 있는 로그 스트리밍
+try:
+    for log_line in manager.stream_logs(
+        ws_url="wss://ray-cluster:8265/logs/ws/",
+        headers={"Authorization": "Bearer token"},
+        timeout=30.0,
+        context="job job-12345"
+    ):
+        print(log_line.strip())
+except ClientError as e:
+    print(f"스트리밍 실패: {e}")
+```
+
+### 오류 처리
+
+- **500**: WebSocket 라이브러리 사용 불가
+- **503**: 연결 실패
+- **408**: 연결 timeout
+- **429**: 스트림 제한 초과
+
+## HTTPStreamManager
+
+신뢰할 수 있는 로그 스트리밍을 위해 청크 전송 인코딩을 사용하여 HTTP 스트리밍 연결을 관리합니다.
+
+### Constructor
+
+```python
+from synapse_sdk.utils.network import HTTPStreamManager
+import requests
+
+session = requests.Session()
+limits = StreamLimits()
+manager = HTTPStreamManager(session, limits)
+```
+
+### Methods
+
+#### `stream_logs(url, headers, timeout, context)`
+
+청크 전송 인코딩을 사용하여 HTTP 엔드포인트에서 로그를 스트리밍합니다.
+
+```python
+# 사용자 정의 timeout으로 로그 스트리밍
+for log_line in manager.stream_logs(
+    url="http://ray-cluster:8265/logs/stream",
+    headers={"Authorization": "Bearer token"},
+    timeout=(5, 60),  # (connect, read) timeout
+    context="job job-12345"
+):
+    if 'ERROR' in log_line:
+        print(f"오류 감지: {log_line}")
+```
+
+### 기능
+
+- **자동 리소스 정리**: HTTP 응답이 적절하게 닫힘
+- **라인 크기 필터링**: 대용량 라인 (>10KB)이 자동으로 필터링됨
+- **스트림 제한**: 메모리 고갈 방지
+- **오류 복구**: 적절한 정리를 통한 강력한 오류 처리
+
+### 오류 처리
+
+- **503**: 연결 거부 또는 네트워크 오류
+- **408**: 연결 또는 읽기 timeout
+- **404**: 엔드포인트를 찾을 수 없음
+- **429**: 스트림 제한 초과
+- **500**: 예상치 못한 스트리밍 오류
+
+## 유효성 검사 함수
+
+### `validate_resource_id(resource_id, resource_name='resource')`
+
+주입 공격을 방지하기 위해 리소스 식별자를 유효성 검사합니다.
+
+```python
+from synapse_sdk.utils.network import validate_resource_id
+
+# 유효한 사용
+job_id = validate_resource_id('job-12345', 'job')
+node_id = validate_resource_id('node_abc_123', 'node')
+
+# 잘못된 사용은 ClientError를 발생시킴
+try:
+    validate_resource_id('job/../malicious', 'job')
+except ClientError as e:
+    print(f"잘못된 ID: {e}")  # Status 400
+```
+
+#### 유효성 검사 규칙
+
+- 비어있으면 안됨
+- 영숫자, 하이픈, 밑줄만 허용
+- 최대 길이: 100자
+- 패턴: `^[a-zA-Z0-9\-_]+$`
+
+#### Parameters
+
+- `resource_id` (Any): 유효성 검사할 ID (문자열로 변환됨)
+- `resource_name` (str): 오류 메시지를 위한 이름 (기본값: 'resource')
+
+#### Returns
+
+- `str`: 유효성 검사된 리소스 ID
+
+#### Raises
+
+- `ClientError` (400): 유효성 검사 실패 시
+
+### `validate_timeout(timeout, max_timeout=300)`
+
+경계 확인을 통한 timeout 값 유효성 검사입니다.
+
+```python
+from synapse_sdk.utils.network import validate_timeout
+
+# 유효한 timeout
+timeout = validate_timeout(30)      # 30초
+timeout = validate_timeout(10.5)    # 10.5초
+
+# 잘못된 timeout은 ClientError를 발생시킴
+try:
+    validate_timeout(-1)     # 음수 timeout
+    validate_timeout(500)    # 최대값 초과
+except ClientError as e:
+    print(f"잘못된 timeout: {e}")  # Status 400
+```
+
+#### Parameters
+
+- `timeout` (int|float): 초 단위 timeout 값
+- `max_timeout` (int): 허용되는 최대 timeout (기본값: 300)
+
+#### Returns
+
+- `float`: 유효성 검사된 timeout 값
+
+#### Raises
+
+- `ClientError` (400): timeout이 유효하지 않은 경우
+
+## URL Utilities
+
+### `http_to_websocket_url(http_url)`
+
+HTTP URL을 WebSocket URL로 변환합니다.
+
+```python
+from synapse_sdk.utils.network import http_to_websocket_url
+
+# URL 변환
+ws_url = http_to_websocket_url("http://ray-cluster:8265/logs/")
+# 결과: "ws://ray-cluster:8265/logs/"
+
+wss_url = http_to_websocket_url("https://ray-cluster:8265/logs/")
+# 결과: "wss://ray-cluster:8265/logs/"
+```
+
+#### Parameters
+
+- `http_url` (str): HTTP 또는 HTTPS URL
+
+#### Returns
+
+- `str`: WebSocket URL (ws:// 또는 wss://)
+
+## 오류 Utilities
+
+### `sanitize_error_message(message, context)`
+
+디버깅 컨텍스트를 유지하면서 정보 유출을 방지하기 위해 오류 메시지를 정제합니다.
+
+```python
+from synapse_sdk.utils.network import sanitize_error_message
+
+# 로깅을 위한 오류 정제
+clean_message = sanitize_error_message(
+    "Connection failed: Invalid token abc123",
+    "job job-12345"
+)
+# 결과: 컨텍스트가 포함된 정제된 오류 메시지
+```
+
+#### Parameters
+
+- `message` (str): 원본 오류 메시지
+- `context` (str): 디버깅을 위한 컨텍스트 (예: "job job-12345")
+
+#### Returns
+
+- `str`: 정제된 오류 메시지
+
+## 완전한 예제
+
+```python
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from synapse_sdk.utils.network import (
+    StreamLimits,
+    WebSocketStreamManager,
+    HTTPStreamManager,
+    validate_resource_id,
+    validate_timeout,
+    http_to_websocket_url
+)
+
+class StreamingExample:
+    def __init__(self):
+        # 구성 요소 설정
+        self.thread_pool = ThreadPoolExecutor(max_workers=3)
+        self.limits = StreamLimits(max_lines=10000)
+        self.ws_manager = WebSocketStreamManager(self.thread_pool, self.limits)
+
+        # HTTP 스트리밍을 위한 HTTP 세션
+        import requests
+        self.session = requests.Session()
+        self.http_manager = HTTPStreamManager(self.session, self.limits)
+
+    def stream_job_logs(self, job_id, protocol='websocket'):
+        # 입력 유효성 검사
+        validated_id = validate_resource_id(job_id, 'job')
+        timeout = validate_timeout(30)
+
+        if protocol == 'websocket':
+            return self._websocket_stream(validated_id, timeout)
+        else:
+            return self._http_stream(validated_id, timeout)
+
+    def _websocket_stream(self, job_id, timeout):
+        url = f"http://ray-cluster:8265/jobs/{job_id}/logs/"
+        ws_url = http_to_websocket_url(url)
+        headers = {"Authorization": "Bearer token"}
+        context = f"job {job_id}"
+
+        return self.ws_manager.stream_logs(ws_url, headers, timeout, context)
+
+    def _http_stream(self, job_id, timeout):
+        url = f"http://ray-cluster:8265/jobs/{job_id}/logs/stream"
+        headers = {"Authorization": "Bearer token"}
+        timeout_tuple = (5, timeout)
+        context = f"job {job_id}"
+
+        return self.http_manager.stream_logs(url, headers, timeout_tuple, context)
+
+# 사용법
+example = StreamingExample()
+
+# WebSocket으로 스트리밍
+for log_line in example.stream_job_logs('job-12345', 'websocket'):
+    print(log_line.strip())
+
+# HTTP 폴백으로 스트리밍
+for log_line in example.stream_job_logs('job-12345', 'http'):
+    print(log_line.strip())
+```
+
+## 모범 사례
+
+### 1. 리소스 관리
+
+```python
+# 항상 적절한 정리 사용
+thread_pool = ThreadPoolExecutor(max_workers=5)
+try:
+    manager = WebSocketStreamManager(thread_pool, StreamLimits())
+    # 매니저 사용...
+finally:
+    thread_pool.shutdown(wait=True)
+```
+
+### 2. 오류 처리
+
+```python
+from synapse_sdk.clients.exceptions import ClientError
+
+try:
+    job_id = validate_resource_id(user_input, 'job')
+    timeout = validate_timeout(user_timeout)
+    # 유효성 검사된 입력으로 진행...
+except ClientError as e:
+    logger.error(f"유효성 검사 실패: {e}")
+    return error_response(e.status, str(e))
+```
+
+### 3. 스트림 제한 구성
+
+```python
+# 사용 사례에 따라 제한 구성
+production_limits = StreamLimits(
+    max_messages=20000,      # 프로덕션을 위해 더 높게
+    max_lines=100000,        # 더 많은 라인 허용
+    max_bytes=200 * 1024 * 1024,  # 큰 로그를 위해 200MB
+    queue_size=2000          # 더 큰 버퍼
+)
+```
+
+## 참고
+
+- [RayClient](../../api/clients/ray.md) - 네트워크 유틸리티의 주요 소비자
+- [File Utils](./file.md) - 파일 작업 및 처리
+- [Storage](./storage.md) - Storage 제공자

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/features/utils/storage.md

@@ -0,0 +1,60 @@
+---
+id: storage
+title: Storage Providers
+sidebar_position: 2
+---
+
+# Storage Providers
+
+여러 클라우드 제공자를 지원하는 스토리지 추상화 레이어입니다.
+
+## 지원되는 제공자
+
+### Amazon S3
+
+Amazon Simple Storage Service 통합입니다.
+
+```python
+from synapse_sdk.utils.storage.providers.s3 import S3Provider
+
+provider = S3Provider(
+    bucket="my-bucket",
+    region="us-west-2"
+)
+```
+
+### Google Cloud Storage
+
+Google Cloud Storage 통합입니다.
+
+```python
+from synapse_sdk.utils.storage.providers.gcp import GCPProvider
+
+provider = GCPProvider(
+    bucket="my-bucket",
+    project="my-project"
+)
+```
+
+### SFTP
+
+Secure File Transfer Protocol 지원입니다.
+
+```python
+from synapse_sdk.utils.storage.providers.sftp import SFTPProvider
+
+provider = SFTPProvider(
+    host="sftp.example.com",
+    username="user"
+)
+```
+
+## 사용법
+
+```python
+from synapse_sdk.utils.storage import get_storage
+
+# URL에서 자동 제공자 감지
+storage = get_storage("s3://my-bucket/file.csv")
+local_path = storage.download()
+```

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/features/utils/types.md

@@ -0,0 +1,51 @@
+---
+id: types
+title: Custom Types
+sidebar_position: 3
+---
+
+# Custom Types
+
+SDK 전반에 걸쳐 사용되는 사용자 정의 타입 및 Pydantic 필드입니다.
+
+## FileField
+
+자동 다운로드 기능이 있는 파일 URL 처리를 위한 사용자 정의 Pydantic 필드입니다.
+
+```python
+from synapse_sdk.types import FileField
+from pydantic import BaseModel
+
+class MyParams(BaseModel):
+    input_file: FileField  # 파일을 자동으로 다운로드
+
+def process(params: MyParams):
+    file_path = params.input_file  # 로컬 파일 경로
+    # 파일 처리...
+```
+
+### 기능
+
+- URL에서 자동 파일 다운로드
+- 임시 파일 관리
+- 다양한 파일 형식 지원
+- 파일 존재 여부 유효성 검사
+
+## 사용 예제
+
+```python
+# 플러그인 매개변수에서
+class ProcessParams(BaseModel):
+    data_file: FileField
+    config_file: FileField = None  # 선택적 파일
+
+# FileField는 자동으로:
+# 1. URL에서 파일 다운로드
+# 2. 파일 존재 여부 유효성 검사
+# 3. 로컬 파일 경로 반환
+# 4. 임시 파일 정리
+```
+
+## 타입 유효성 검사
+
+SDK 전반에 걸쳐 타입 안전성을 보장하기 위한 사용자 정의 유효성 검사기입니다.

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

@@ -0,0 +1,94 @@
+---
+id: installation
+title: 설치 & 설정
+sidebar_position: 2
+---
+
+# 설치 & 설정
+
+Synapse SDK를 몇 분 안에 시작해보세요.
+
+## 사전 요구사항
+
+Synapse SDK를 설치하기 전에 다음을 확인하세요:
+
+- **Python 3.10 이상** 설치됨
+
+## 설치 방법
+
+### PyPI에서 설치
+
+Synapse SDK를 설치하는 가장 쉬운 방법은 pip를 사용하는 것입니다:
+
+```bash
+pip install synapse-sdk
+```
+
+### 선택적 종속성과 함께 설치
+
+추가 기능을 위해 extras와 함께 설치하세요:
+
+```bash
+# 모든 종속성과 함께 설치 (분산 컴퓨팅, 최적화 라이브러리)
+pip install synapse-sdk[all]
+
+# 대시보드 종속성과 함께 설치 (FastAPI, Uvicorn)
+pip install synapse-sdk[devtools]
+
+# 둘 다 설치
+pip install "synapse-sdk[all,devtools]"
+```
+
+### 소스에서 설치
+
+최신 개발 버전을 가져오려면:
+
+```bash
+git clone https://github.com/datamaker/synapse-sdk.git
+cd synapse-sdk
+pip install -e .
+
+# 선택적 종속성과 함께
+pip install -e ".[all,devtools]"
+```
+
+## 설치 확인
+
+설치 후 모든 것이 작동하는지 확인하세요:
+
+```bash
+# 버전 확인
+synapse --version
+
+# 대화형 CLI 실행
+synapse
+
+# devtools와 함께 실행
+synapse --dev-tools
+```
+
+## 문제 해결
+
+### 일반적인 문제들
+
+1. **ImportError: No module named 'synapse_sdk'**
+   - 가상 환경을 활성화했는지 확인하세요
+   - Python 경로 확인: `python -c "import sys; print(sys.path)"`
+
+2. **백엔드 연결 시간 초과**
+   - API 토큰이 올바른지 확인하세요
+   - 네트워크 연결을 확인하세요
+   - 백엔드 URL에 접근 가능한지 확인하세요
+
+### 도움 받기
+
+문제가 발생하면:
+
+1. [문제 해결 가이드](./troubleshooting.md)를 확인하세요
+2. [GitHub Issues](https://github.com/datamaker/synapse-sdk/issues) 검색
+3. [Discord 커뮤니티](https://discord.gg/synapse-sdk)에 참여하세요
+
+## 다음 단계
+
+- [빠른 시작 가이드](./quickstart.md) 따라하기
+- [핵심 개념](./concepts/index.md)에 대해 학습하기

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

@@ -0,0 +1,47 @@
+---
+id: introduction
+title: 소개
+sidebar_position: 1
+---
+
+# Synapse SDK
+
+ML 및 데이터 처리 플러그인을 구축하세요.
+
+## 개요
+
+Synapse SDK는...
+
+### 주요 기능
+
+- **🚀 플러그인 개발 및 테스트**: Synapse용 카테고리별로 구성된 모듈화되고 재사용 가능한 컴포넌트 개발
+- **⚡ 분산 컴퓨팅**: 확장 가능한 분산 실행을 위해 구축됨
+- **🔧 다중 실행 모드**: Job, Task 및 REST API 지원
+- **📦 격리된 런타임 환경**: 각 플러그인은 종속성 관리와 함께 자체 환경에서 실행됨
+- **📊 진행률 추적**: 내장된 진행률 모니터링 및 메트릭 보고
+
+### 플러그인 카테고리
+
+SDK는 플러그인을 특정 카테고리로 구성합니다:
+
+1. **신경망** (`NEURAL_NET`): ML 모델 학습, 추론 및 배포
+2. **내보내기** (`EXPORT`): 데이터 내보내기 및 변환 작업
+3. **업로드** (`UPLOAD`): 파일 및 데이터 업로드 기능
+4. **스마트 도구** (`SMART_TOOL`): 지능형 자동화 도구
+5. **사후 어노테이션** (`POST_ANNOTATION`): 데이터 어노테이션 후 후처리
+6. **사전 어노테이션** (`PRE_ANNOTATION`): 데이터 어노테이션 전 전처리
+7. **데이터 검증** (`DATA_VALIDATION`): 데이터 품질 및 검증 확인
+
+## 시작하기
+
+Synapse SDK를 시작하려면:
+
+1. [SDK 설치](./installation.md)
+2. [빠른 시작 가이드 따라하기](./quickstart.md)
+3. [API 참조 탐색](./api/index.md)
+4. [예제 확인](./examples/index.md)
+
+## 다음 단계
+
+- [핵심 개념](./concepts/index.md) 학습하기
+- [백엔드 연결](./configuration.md) 구성하기