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/api/clients/backend.md

@@ -0,0 +1,420 @@
+---
+id: backend
+title: BackendClient
+sidebar_position: 10
+---
+
+# BackendClient
+
+Synapse 백엔드 API와 상호작용하기 위한 메인 클라이언트입니다.
+
+## 개요
+
+`BackendClient`는 데이터 관리, 플러그인 실행, 어노테이션, 머신러닝 워크플로를 포함한 모든 백엔드 작업에 대한 포괄적인 액세스를 제공합니다. 여러 전문화된 믹스인의 기능을 통합합니다:
+
+- **AnnotationClientMixin**: 작업 및 어노테이션 관리
+- **CoreClientMixin**: 파일 업로드 및 핵심 작업
+- **DataCollectionClientMixin**: 데이터 수집 및 파일 관리
+- **HITLClientMixin**: Human-in-the-loop 할당 작업
+- **IntegrationClientMixin**: 플러그인 및 작업 관리
+- **MLClientMixin**: 머신러닝 모델 및 정답 데이터 작업
+
+## 생성자
+
+```python
+BackendClient(
+    base_url: str,
+    api_token: str = None,
+    agent_token: str = None,
+    timeout: dict = None
+)
+```
+
+### 매개변수
+
+- **base_url** (`str`): Synapse 백엔드 API의 기본 URL
+- **api_token** (`str`, 선택사항): API 인증 토큰. `SYNAPSE_API_TOKEN` 환경변수로도 설정 가능
+- **agent_token** (`str`, 선택사항): 에이전트 인증 토큰. `SYNAPSE_AGENT_TOKEN` 환경변수로도 설정 가능
+- **timeout** (`dict`, 선택사항): 사용자 정의 타임아웃 설정. 기본값은 `{'connect': 5, 'read': 30}`
+
+### 예제
+
+```python
+from synapse_sdk.clients.backend import BackendClient
+
+# 토큰을 명시적으로 지정하여 클라이언트 생성
+client = BackendClient(
+    base_url="https://api.synapse.sh",
+    api_token="your-api-token"
+)
+
+# 또는 환경변수 사용
+import os
+os.environ['SYNAPSE_API_TOKEN'] = "your-api-token"
+client = BackendClient(base_url="https://api.synapse.sh")
+```
+
+## API 메서드
+
+### 어노테이션 작업
+
+#### `get_project(pk)`
+
+ID로 프로젝트 상세정보를 가져옵니다.
+
+```python
+project = client.get_project(123)
+```
+
+#### `get_task(pk, params)`
+
+선택적 매개변수와 함께 작업 상세정보를 가져옵니다.
+
+```python
+task = client.get_task(456, params={'expand': 'data_unit'})
+```
+
+#### `annotate_task_data(pk, data)`
+
+작업에 대한 어노테이션 데이터를 제출합니다.
+
+```python
+result = client.annotate_task_data(456, {
+    'annotations': [
+        {'type': 'bbox', 'coordinates': [10, 10, 100, 100]}
+    ]
+})
+```
+
+#### `list_tasks(params=None, url_conversion=None, list_all=False)`
+
+필터링 및 페이지네이션과 함께 작업 목록을 가져옵니다.
+
+```python
+# 프로젝트의 작업 가져오기
+tasks = client.list_tasks(params={'project': 123})
+
+# 모든 작업 가져오기 (페이지네이션 자동 처리)
+all_tasks = client.list_tasks(list_all=True)
+```
+
+#### `create_tasks(data)`
+
+새로운 작업를 생성합니다.
+
+```python
+new_tasks = client.create_tasks([
+    {'project': 123, 'data_unit': 789},
+    {'project': 123, 'data_unit': 790}
+])
+```
+
+#### `set_tags_tasks(data, params=None)`
+
+여러 작업에 태그를 설정합니다.
+
+```python
+client.set_tags_tasks({
+    'task_ids': [456, 457],
+    'tag_ids': [1, 2, 3]
+})
+```
+
+### 핵심 작업
+
+#### `create_chunked_upload(file_path)`
+
+최적 성능을 위해 청크 업로드를 사용하여 대용량 파일을 업로드합니다.
+
+```python
+from pathlib import Path
+
+result = client.create_chunked_upload(Path('/path/to/large_file.zip'))
+print(f"업로드 완료: {result}")
+```
+
+**기능:**
+
+- 최적 성능을 위한 50MB 청크 사용
+- 자동 재시도 및 재개 기능
+- MD5 무결성 검증
+- 진행률 추적 지원
+
+### 데이터 수집 작업
+
+#### `list_data_collection()`
+
+사용 가능한 모든 데이터 컬렉션을 나열합니다.
+
+```python
+collections = client.list_data_collection()
+```
+
+#### `get_data_collection(data_collection_id)`
+
+특정 데이터 컬렉션에 대한 상세 정보를 가져옵니다.
+
+```python
+collection = client.get_data_collection(123)
+file_specs = collection['file_specifications']
+```
+
+#### `create_data_file(file_path, use_chunked_upload=False)`
+
+백엔드에 데이터 파일을 생성하고 업로드합니다.
+
+```python
+from pathlib import Path
+
+# 일반 업로드
+data_file = client.create_data_file(Path('/path/to/file.jpg'))
+
+# 대용량 파일을 위한 청크 업로드
+large_file = client.create_data_file(
+    Path('/path/to/large_file.zip'),
+    use_chunked_upload=True
+)
+```
+
+#### `upload_data_file(organized_file, collection_id, use_chunked_upload=False)`
+
+정리된 파일 데이터를 컬렉션에 업로드합니다.
+
+```python
+result = client.upload_data_file(
+    organized_file={'files': {...}, 'meta': {...}},
+    collection_id=123,
+    use_chunked_upload=False
+)
+```
+
+#### `create_data_units(uploaded_files)`
+
+업로드된 파일에서 데이터 유닛을 생성합니다.
+
+```python
+data_units = client.create_data_units([
+    {'id': 1, 'file': {...}},
+    {'id': 2, 'file': {...}}
+])
+```
+
+### HITL (Human-in-the-Loop) 작업
+
+#### `get_assignment(pk)`
+
+ID로 할당 상세정보를 가져옵니다.
+
+```python
+assignment = client.get_assignment(789)
+```
+
+#### `list_assignments(params=None, url_conversion=None, list_all=False)`
+
+필터링 옵션과 함께 할당 목록을 가져옵니다.
+
+```python
+# 프로젝트의 할당 가져오기
+assignments = client.list_assignments(params={'project': 123})
+
+# 모든 할당 가져오기
+all_assignments = client.list_assignments(list_all=True)
+```
+
+#### `set_tags_assignments(data, params=None)`
+
+여러 할당에 태그를 설정합니다.
+
+```python
+client.set_tags_assignments({
+    'assignment_ids': [789, 790],
+    'tag_ids': [1, 2]
+})
+```
+
+### 통합 작업
+
+#### `health_check_agent(token)`
+
+에이전트 상태를 확인합니다.
+
+```python
+status = client.health_check_agent('agent-token-123')
+```
+
+#### `get_plugin(pk)` / `create_plugin(data)` / `update_plugin(pk, data)`
+
+플러그인을 관리합니다.
+
+```python
+# 플러그인 가져오기
+plugin = client.get_plugin(123)
+
+# 플러그인 생성
+new_plugin = client.create_plugin({
+    'name': 'My Plugin',
+    'description': 'Plugin description'
+})
+
+# 플러그인 업데이트
+updated = client.update_plugin(123, {'description': 'Updated description'})
+```
+
+#### `run_plugin(pk, data)`
+
+제공된 데이터로 플러그인을 실행합니다.
+
+```python
+result = client.run_plugin(123, {
+    'parameters': {'input': 'value'},
+    'context': {...}
+})
+```
+
+#### 플러그인 릴리스 관리
+
+```python
+# 플러그인 릴리스 생성
+release = client.create_plugin_release({
+    'plugin': 123,
+    'version': '1.0.0',
+    'file': open('/path/to/plugin.zip', 'rb')
+})
+
+# 릴리스 상세정보 가져오기
+release_info = client.get_plugin_release(456)
+```
+
+#### 작업 관리
+
+```python
+# 작업 목록
+jobs = client.list_jobs(params={'status': 'running'})
+
+# 작업 상세정보 가져오기
+job = client.get_job(789, params={'expand': 'logs'})
+
+# 작업 상태 업데이트
+client.update_job(789, {'status': 'completed'})
+
+# 작업 콘솔 로그 가져오기
+logs = client.list_job_console_logs(789)
+```
+
+#### 스토리지 작업
+
+```python
+# 스토리지 목록
+storages = client.list_storages()
+
+# 스토리지 상세정보 가져오기
+storage = client.get_storage(123)
+
+# 스토리지 생성
+new_storage = client.create_storage({
+    'name': 'My Storage',
+    'provider': 'amazon_s3',
+    'configuration': {...}
+})
+```
+
+### 머신러닝 작업
+
+#### `list_models(params=None)` / `get_model(pk, params=None, url_conversion=None)`
+
+ML 모델을 관리합니다.
+
+```python
+# 모델 목록
+models = client.list_models(params={'project': 123})
+
+# 모델 상세정보 가져오기
+model = client.get_model(456, params={'expand': 'metrics'})
+```
+
+#### `create_model(data)`
+
+파일 업로드와 함께 새로운 ML 모델을 생성합니다.
+
+```python
+new_model = client.create_model({
+    'name': 'My Model',
+    'project': 123,
+    'file': '/path/to/model.pkl'
+})
+```
+
+#### 정답 데이터 작업
+
+```python
+# 정답 이벤트 목록
+events = client.list_ground_truth_events(
+    params={'ground_truth_dataset_versions': [123]},
+    list_all=True
+)
+
+# 정답 버전 가져오기
+version = client.get_ground_truth_version(123)
+```
+
+## 스토리지 모델
+
+백엔드 클라이언트는 스토리지 작업을 위한 사전 정의된 모델을 포함합니다:
+
+### StorageCategory
+
+- `INTERNAL`: 내부 스토리지 시스템
+- `EXTERNAL`: 외부 스토리지 제공업체
+
+### StorageProvider
+
+- `AMAZON_S3`: Amazon S3
+- `AZURE`: Microsoft Azure Blob Storage
+- `DIGITAL_OCEAN`: DigitalOcean Spaces
+- `FILE_SYSTEM`: 로컬 파일 시스템
+- `FTP` / `SFTP`: FTP 프로토콜
+- `MINIO`: MinIO 스토리지
+- `GCP`: Google Cloud Storage
+
+## 오류 처리
+
+모든 API 메서드는 다양한 오류 조건에 대해 `ClientError` 예외를 발생시킬 수 있습니다:
+
+```python
+from synapse_sdk.clients.exceptions import ClientError
+
+try:
+    project = client.get_project(999)
+except ClientError as e:
+    print(f"API 오류: {e}")
+    print(f"상태 코드: {e.status_code}")
+    print(f"응답: {e.response}")
+```
+
+## 페이지네이션
+
+`list_all=True`를 지원하는 메서드는 자동으로 페이지네이션을 처리합니다:
+
+```python
+# 수동 페이지네이션
+tasks_page1 = client.list_tasks(params={'page': 1, 'page_size': 100})
+
+# 자동 페이지네이션 (권장)
+all_tasks = client.list_tasks(list_all=True)
+```
+
+## URL 변환
+
+일부 메서드는 파일 필드에 대한 URL 변환을 지원합니다:
+
+```python
+# 사용자 정의 URL 변환
+tasks = client.list_tasks(
+    url_conversion={'files': lambda url: f"https://cdn.example.com{url}"}
+)
+```
+
+## 참고
+
+- [AgentClient](./agent.md) - 에이전트별 작업용
+- [BaseClient](./base.md) - 기본 클라이언트 구현

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

@@ -0,0 +1,257 @@
+---
+id: base
+title: BaseClient
+sidebar_position: 3
+---
+
+# BaseClient
+
+핵심 HTTP 작업 및 페이지네이션 기능을 제공하는 모든 Synapse SDK 클라이언트의 기본 클래스입니다.
+
+## 개요
+
+`BaseClient`는 다른 모든 클라이언트에서 사용하는 HTTP 작업, 오류 처리, 요청 관리 및 페이지네이션을 위한 공통 기능을 제공합니다. 자동 파일 URL 변환 기능과 함께 효율적인 페이지네이션 처리를 구현합니다.
+
+## 기능
+
+- 재시도 로직이 있는 HTTP 요청 처리
+- 자동 timeout 관리
+- 제너레이터를 사용한 효율적인 페이지네이션
+- 파일 URL을 로컬 경로로 자동 변환
+- Pydantic 모델 유효성 검사
+- 연결 풀링
+
+## 핵심 HTTP 메서드
+
+BaseClient는 모든 클라이언트 믹스인에서 내부적으로 사용하는 저수준 HTTP 메서드를 제공합니다:
+
+- `_get()` - 선택적 응답 모델 검증을 포함한 GET 요청
+- `_post()` - 요청/응답 검증을 포함한 POST 요청
+- `_put()` - 모델 검증을 포함한 PUT 요청
+- `_patch()` - 모델 검증을 포함한 PATCH 요청
+- `_delete()` - 모델 검증을 포함한 DELETE 요청
+
+이러한 메서드는 일반적으로 직접 호출되지 않습니다. 대신 클라이언트 믹스인에서 제공하는 상위 수준 메서드를 사용하세요.
+
+## 페이지네이션 메서드
+
+### `_list(path, url_conversion=None, list_all=False, params=None, **kwargs)`
+
+선택적 자동 페이지네이션 및 파일 URL 변환 기능을 갖춘 페이지네이션 API 엔드포인트에서 리소스를 나열합니다.
+
+**매개변수:**
+
+- `path` (str): 요청할 URL 경로
+- `url_conversion` (dict, optional): 파일 URL을 로컬 경로로 변환하기 위한 설정
+  - 구조: `{'files_fields': ['field1', 'field2'], 'is_list': True}`
+  - 자동으로 파일을 다운로드하고 URL을 로컬 경로로 대체
+- `list_all` (bool): True인 경우 제너레이터를 사용하여 모든 페이지의 모든 결과 반환
+- `params` (dict, optional): 쿼리 매개변수 (필터, 정렬 등)
+- `**kwargs`: 추가 요청 인자
+
+**반환값:**
+
+- `list_all=False`인 경우: `results`, `count`, `next`, `previous`를 포함한 딕셔너리
+- `list_all=True`인 경우: `(generator, total_count)` 튜플
+
+**예제:**
+
+```python
+# 첫 페이지만 가져오기
+response = client._list('api/tasks/')
+tasks = response['results']  # 첫 페이지의 작업들
+total = response['count']     # 전체 작업 수
+
+# 제너레이터를 사용하여 모든 결과 가져오기 (메모리 효율적)
+generator, total_count = client._list('api/tasks/', list_all=True)
+all_tasks = list(generator)  # 자동으로 모든 페이지 가져오기
+
+# 필터와 함께 사용
+params = {'status': 'pending', 'priority': 'high'}
+response = client._list('api/tasks/', params=params)
+
+# 파일 필드에 url_conversion 사용
+url_conversion = {'files_fields': ['files'], 'is_list': True}
+generator, count = client._list(
+    'api/data_units/',
+    url_conversion=url_conversion,
+    list_all=True,
+    params={'status': 'active'}
+)
+# 'files' 필드의 파일 URL이 자동으로 다운로드되어 로컬 경로로 변환됨
+for unit in generator:
+    print(unit['files'])  # URL이 아닌 로컬 파일 경로
+```
+
+### `_list_all(path, url_conversion=None, params=None, **kwargs)`
+
+페이지네이션된 API 엔드포인트에서 모든 결과를 생성하는 제너레이터입니다.
+
+이 메서드는 `list_all=True`일 때 `_list()`에 의해 내부적으로 호출됩니다. `next` URL을 따라가며 자동으로 페이지네이션을 처리하고, 깊은 페이지네이션에서 스택 오버플로우를 방지하기 위해 재귀 대신 반복적 접근 방식(while 루프)을 사용합니다.
+
+**주요 개선사항 (SYN-5757):**
+
+1. **page_size 중복 제거**: `page_size` 매개변수는 첫 번째 요청에만 추가됩니다. 후속 요청은 이미 모든 필요한 매개변수를 포함하는 `next` URL을 직접 사용합니다.
+
+2. **적절한 params 처리**: 사용자가 지정한 쿼리 매개변수가 첫 번째 요청에 올바르게 전달되고 `next` URL을 통해 페이지네이션 전체에 보존됩니다.
+
+3. **모든 페이지에 url_conversion 적용**: URL 변환이 첫 번째 페이지뿐만 아니라 모든 페이지에 적용됩니다.
+
+4. **재귀 대신 반복**: 더 나은 메모리 효율성과 대용량 데이터셋에서 스택 오버플로우 방지를 위해 재귀 대신 while 루프를 사용합니다.
+
+**매개변수:**
+
+- `path` (str): 초기 URL 경로
+- `url_conversion` (dict, optional): 모든 페이지에 적용
+- `params` (dict, optional): 첫 번째 요청에만 사용되는 쿼리 매개변수
+- `**kwargs`: 추가 요청 인자
+
+**생성:**
+
+모든 페이지의 개별 결과 항목을 지연 방식으로 가져옵니다.
+
+**예제:**
+
+```python
+# 기본: 모든 작업 반복
+for task in client._list_all('api/tasks/'):
+    process_task(task)
+
+# 필터와 함께
+params = {'status': 'pending'}
+for task in client._list_all('api/tasks/', params=params):
+    print(task['id'])
+
+# 중첩된 파일 필드에 url_conversion 사용
+url_conversion = {'files_fields': ['data.files', 'metadata.attachments'], 'is_list': True}
+for item in client._list_all('api/items/', url_conversion=url_conversion):
+    print(item['data']['files'])  # 로컬 경로
+
+# 모든 결과 수집 (대용량 데이터셋의 경우 메모리 집약적)
+all_results = list(client._list_all('api/tasks/'))
+```
+
+## 파일 다운로드를 위한 URL 변환
+
+`url_conversion` 매개변수는 API 응답에서 URL로 참조되는 파일의 자동 다운로드를 활성화합니다. 이는 파일 참조를 포함하는 데이터 유닛, 작업 또는 모든 리소스로 작업할 때 특히 유용합니다.
+
+### URL 변환 구조
+
+```python
+url_conversion = {
+    'files_fields': ['files', 'images', 'data.attachments'],  # 필드 경로
+    'is_list': True  # 항목 목록을 처리하는지 여부
+}
+```
+
+- `files_fields`: 필드 경로 목록 (중첩 필드를 위한 점 표기법 지원)
+- `is_list`: 페이지네이션된 목록 응답의 경우 `True`로 설정
+
+### 작동 방식
+
+1. API가 파일 URL이 포함된 응답 반환
+2. `url_conversion`이 URL을 포함하는 필드 식별
+3. 파일이 임시 디렉토리에 자동으로 다운로드됨
+4. URL이 로컬 파일 경로로 대체됨
+5. 코드가 URL 대신 로컬 경로가 포함된 응답 수신
+
+### 예제
+
+```python
+# 단순 파일 필드
+url_conversion = {'files_fields': ['image_url'], 'is_list': True}
+generator, count = client._list(
+    'api/photos/',
+    url_conversion=url_conversion,
+    list_all=True
+)
+for photo in generator:
+    # photo['image_url']은 이제 URL이 아닌 로컬 Path 객체
+    with open(photo['image_url'], 'rb') as f:
+        process_image(f)
+
+# 여러 파일 필드
+url_conversion = {
+    'files_fields': ['thumbnail', 'full_image', 'raw_data'],
+    'is_list': True
+}
+
+# 점 표기법을 사용한 중첩 필드
+url_conversion = {
+    'files_fields': ['data.files', 'metadata.preview', 'annotations.image'],
+    'is_list': True
+}
+
+# 더 나은 성능을 위한 비동기 다운로드
+from synapse_sdk.utils.file import files_url_to_path_from_objs
+
+results = client._list('api/data_units/')['results']
+files_url_to_path_from_objs(
+    results,
+    files_fields=['files'],
+    is_list=True,
+    is_async=True  # 모든 파일 동시 다운로드
+)
+```
+
+## 성능 고려사항
+
+### 메모리 효율성
+
+대용량 데이터셋으로 작업할 때는 모든 결과를 메모리에 로드하는 대신 제너레이터를 사용하세요:
+
+```python
+# ❌ 메모리 집약적 - 모든 결과 로드
+all_tasks = list(client._list('api/tasks/', list_all=True)[0])
+
+# ✅ 메모리 효율적 - 한 번에 하나씩 처리
+generator, _ = client._list('api/tasks/', list_all=True)
+for task in generator:
+    process_task(task)
+    # 작업이 처리되고 가비지 컬렉션될 수 있음
+```
+
+### 페이지네이션 모범 사례
+
+1. **한 페이지보다 큰 데이터셋에는 list_all=True 사용**
+2. **기본값(100)이 최적이 아닌 경우 params에서 적절한 page_size 설정**
+3. **파일을 처리해야 할 때만 url_conversion 사용**
+4. **항목당 여러 파일이 있는 경우 비동기 다운로드 고려**
+
+```python
+# 대용량 데이터셋을 위한 최적 페이지네이션
+params = {'page_size': 50}  # 더 빠른 첫 응답을 위한 작은 페이지
+generator, total = client._list(
+    'api/large_dataset/',
+    list_all=True,
+    params=params
+)
+
+# 진행 상황 추적과 함께 처리
+from tqdm import tqdm
+for item in tqdm(generator, total=total):
+    process_item(item)
+```
+
+## 클라이언트 믹스인에서의 사용
+
+BaseClient 페이지네이션 메서드는 모든 클라이언트 믹스인에서 내부적으로 사용됩니다:
+
+```python
+# DataCollectionClientMixin
+def list_data_units(self, params=None, url_conversion=None, list_all=False):
+    return self._list('data_units/', params=params,
+                     url_conversion=url_conversion, list_all=list_all)
+
+# AnnotationClientMixin
+def list_tasks(self, params=None, url_conversion=None, list_all=False):
+    return self._list('sdk/tasks/', params=params,
+                     url_conversion=url_conversion, list_all=list_all)
+```
+
+## 참고
+
+- [BackendClient](./backend.md) - 메인 클라이언트 구현
+- [AgentClient](./agent.md) - Agent 전용 작업
+- [DataCollectionClientMixin](./data-collection-mixin.md) - 데이터 및 파일 작업
+- [AnnotationClientMixin](./annotation-mixin.md) - 작업 및 주석 관리