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

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

@@ -0,0 +1,306 @@
+---
+id: contributing
+title: 기여하기
+sidebar_position: 12
+---
+
+# Synapse SDK에 기여하기
+
+Synapse SDK에 기여해 주셔서 감사합니다! 이 가이드는 프로젝트 기여를 시작하는 데 도움이 됩니다.
+
+## 개발 환경 설정
+
+### 사전 요구사항
+
+- Python 3.8 이상
+- Git
+- 가상 환경 도구 (venv, conda 등)
+
+### 시작하기
+
+1. **저장소 포크 및 복제**
+   ```bash
+   git clone https://github.com/yourusername/synapse-sdk.git
+   cd synapse-sdk
+   ```
+
+2. **가상 환경 생성**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Windows: .venv\Scripts\activate
+   ```
+
+3. **의존성 설치**
+   ```bash
+   pip install -r requirements.txt
+   pip install -r requirements.test.txt
+   ```
+
+## 코드 포맷팅 및 품질
+
+### Ruff 포맷팅
+
+코드 포맷팅 및 린팅에 **Ruff**를 사용합니다. 모든 기여는 우리의 포맷팅 표준을 따라야 합니다.
+
+#### 필수 명령어
+
+코드 변경 사항을 제출하기 전에 다음 명령어를 실행하세요:
+
+```bash
+# 모든 Python 코드 포맷팅
+ruff format .
+
+# 린팅 문제 수정
+ruff check --fix .
+
+# 남은 문제 확인
+ruff check .
+```
+
+#### 포맷팅 워크플로우
+
+1. **변경사항 작성** - Python 코드를 작성하거나 수정
+2. **Ruff로 포맷팅** - `ruff format .`을 실행하여 일관된 포맷팅 적용
+3. **린팅 문제 수정** - `ruff check --fix .`를 실행하여 코드 품질 문제 해결
+4. **변경사항 확인** - 포맷팅된 코드를 검토하여 정확성 보장
+5. **변경사항 커밋** - 적절히 포맷팅된 코드로 커밋 생성
+
+#### IDE 통합
+
+IDE가 Ruff를 자동으로 실행하도록 설정하세요:
+
+- **VS Code**: Ruff 확장 프로그램 설치
+- **PyCharm**: Ruff를 외부 도구로 설정
+- **Vim/Neovim**: ruff-lsp 또는 유사한 플러그인 사용
+
+### 코드 스타일 가이드라인
+
+- **줄 길이**: `pyproject.toml`의 프로젝트별 설정 따르기
+- **Import 정렬**: Ruff가 import 정리를 처리하도록 함
+- **타입 힌트**: 적절한 곳에 타입 어노테이션 사용
+- **독스트링**: Google 스타일 독스트링 형식 따르기
+- **주석**: 복잡한 로직에 대해 명확하고 간결한 주석 작성
+
+## 테스팅
+
+### 테스트 실행
+
+```bash
+# 모든 테스트 실행
+pytest
+
+# 특정 테스트 파일 실행
+pytest tests/plugins/utils/test_config.py
+
+# 커버리지와 함께 실행
+pytest --cov=synapse_sdk
+```
+
+### 테스트 작성
+
+- 모든 새로운 기능에 대해 테스트 작성
+- 시나리오를 설명하는 서술적 테스트 이름 사용
+- 긍정적 및 부정적 테스트 케이스 모두 포함
+- 외부 의존성을 적절히 모킹
+- 높은 테스트 커버리지 유지
+
+#### 테스트 구조
+
+```python
+class TestMyFeature:
+    """MyFeature 기능 테스트."""
+    
+    def test_feature_success_case(self):
+        """성공적인 기능 작동 테스트."""
+        # Arrange
+        input_data = {"key": "value"}
+        
+        # Act
+        result = my_feature(input_data)
+        
+        # Assert
+        assert result == expected_output
+    
+    def test_feature_error_case(self):
+        """기능 오류 처리 테스트."""
+        with pytest.raises(ValueError, match="Expected error message"):
+            my_feature(invalid_input)
+```
+
+## 플러그인 개발
+
+### 새로운 플러그인 유틸리티 생성
+
+새로운 플러그인 유틸리티를 추가할 때:
+
+1. **적절한 모듈에 추가**:
+   - 설정 유틸리티 → `synapse_sdk/plugins/utils/config.py`
+   - 액션 유틸리티 → `synapse_sdk/plugins/utils/actions.py`
+   - 레지스트리 유틸리티 → `synapse_sdk/plugins/utils/registry.py`
+
+2. **포괄적인 독스트링 포함**:
+   ```python
+   def my_utility_function(param: str) -> Dict[str, Any]:
+       """함수에 대한 간단한 설명.
+       
+       Args:
+           param: 매개변수 설명.
+           
+       Returns:
+           반환값 설명.
+           
+       Raises:
+           ValueError: 입력이 유효하지 않을 때.
+           
+       Examples:
+           >>> my_utility_function("example")
+           {'result': 'processed'}
+       """
+   ```
+
+3. **`__all__` 내보내기에 추가**
+4. **포괄적인 테스트 작성**
+5. **문서 업데이트**
+
+### 플러그인 카테고리
+
+플러그인 카테고리 작업 시:
+
+- 가능하면 기존 카테고리 사용
+- 명명 규칙 따르기: `snake_case`
+- 적절한 검증 및 오류 처리 추가
+- 새 카테고리 추가 시 카테고리 enum 업데이트
+
+## 문서화
+
+### API 문서화
+
+- 모든 공개 함수에 대한 독스트링 업데이트
+- 독스트링에 사용 예제 포함
+- 더 나은 IDE 지원을 위한 타입 힌트 추가
+- 오류 조건 및 예외 문서화
+
+### 사용자 문서화
+
+관련 문서 파일 업데이트:
+
+- **API 참조**: `docs/api/plugins/utils.md`
+- **기능 가이드**: `docs/features/plugins/index.md`
+- **변경 로그**: `docs/changelog.md`
+- **예제**: 실용적인 사용 예제 추가
+
+### 문서화 형식
+
+다음을 포함한 명확하고 간결한 언어 사용:
+
+- 모든 함수에 대한 코드 예제
+- 매개변수 및 반환값 설명
+- 오류 처리 예제
+- 호환성을 깨뜨리는 변경에 대한 마이그레이션 가이드
+
+## Pull Request 프로세스
+
+### 제출 전
+
+1. **포맷팅 및 린팅 실행**:
+   ```bash
+   ruff format .
+   ruff check --fix .
+   ```
+
+2. **모든 테스트 실행**:
+   ```bash
+   pytest
+   ```
+
+3. **필요에 따라 문서 업데이트**
+
+4. **중요한 변경사항에 대한 변경 로그 항목 추가**
+
+### Pull Request 가이드라인
+
+- **명확한 제목**: PR이 달성하는 것 설명
+- **자세한 설명**: 변경사항과 동기 설명
+- **이슈 참조**: 관련 GitHub 이슈에 링크
+- **테스트 커버리지**: 새 코드가 테스트되었는지 확인
+- **문서화**: 사용자 대상 변경사항에 대한 문서 업데이트
+
+### PR 템플릿
+
+```markdown
+## 설명
+변경사항에 대한 간단한 설명
+
+## 변경 유형
+- [ ] 버그 수정
+- [ ] 새로운 기능
+- [ ] 호환성을 깨뜨리는 변경
+- [ ] 문서 업데이트
+
+## 테스트
+- [ ] 로컬에서 테스트 통과
+- [ ] 새 기능에 대한 새 테스트 추가
+- [ ] Ruff로 코드 포맷팅됨
+
+## 문서화
+- [ ] API 문서 업데이트됨
+- [ ] 필요시 사용자 가이드 업데이트됨
+- [ ] 변경 로그 항목 추가됨
+```
+
+## 코드 리뷰
+
+### 리뷰 기준
+
+- **기능성**: 코드가 의도된 대로 작동
+- **품질**: 코딩 표준 및 모범 사례 준수
+- **테스팅**: 적절한 테스트 커버리지
+- **문서화**: 공개 API에 대한 명확한 문서
+- **성능**: 명백한 성능 문제 없음
+- **보안**: 보안 취약점 없음
+
+### 피드백 대응
+
+- 모든 리뷰어 의견 처리
+- 피드백이 불명확하면 설명 요청
+- 요청된 변경사항을 신속히 수행
+- 변경 후 포맷팅 및 테스트 재실행
+
+## 프로젝트 구조
+
+프로젝트 조직 이해:
+
+```
+synapse_sdk/
+├── plugins/
+│   ├── utils/              # 플러그인 유틸리티 (모듈식)
+│   │   ├── config.py       # 설정 유틸리티
+│   │   ├── actions.py      # 액션 관리
+│   │   └── registry.py     # 레지스트리 유틸리티
+│   ├── categories/         # 플러그인 카테고리 구현
+│   └── models.py          # 핵심 플러그인 모델
+├── clients/               # API 클라이언트
+├── utils/                 # 일반 유틸리티
+└── devtools/             # 개발 도구
+
+tests/
+├── plugins/
+│   └── utils/            # 플러그인 유틸리티 테스트
+└── ...                   # 기타 테스트 모듈
+
+docs/                     # 문서
+├── api/                  # API 참조
+├── features/             # 기능 가이드
+└── changelog.md          # 변경 로그
+```
+
+## 도움 받기
+
+- **GitHub Issues**: 버그 신고 또는 기능 요청
+- **Discussions**: 질문하거나 아이디어 논의
+- **문서화**: 먼저 기존 문서 확인
+- **코드 리뷰**: 리뷰 중 설명 요청
+
+## 라이센스
+
+Synapse SDK에 기여함으로써 귀하의 기여가 프로젝트와 동일한 라이센스(MIT 라이센스) 하에 라이센스될 것에 동의합니다.

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

@@ -0,0 +1,29 @@
+---
+id: index
+title: Examples
+sidebar_position: 1
+---
+
+# Examples
+
+Synapse SDK 사용을 위한 실용적인 예제 및 튜토리얼입니다.
+
+## 시작하기 예제
+
+빠르게 시작할 수 있도록 도움을 주는 기본 예제입니다.
+
+## 플러그인 예제
+
+다양한 사용 사례에 대한 실제 플러그인 예제입니다.
+
+## 통합 예제
+
+Synapse SDK를 다른 도구 및 서비스와 통합하는 예제입니다.
+
+## 고급 예제
+
+복잡한 워크플로우 및 고급 사용 패턴입니다.
+
+## 코드 샘플
+
+일반적인 작업을 위한 즉시 사용 가능한 코드 스니펫입니다.

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

@@ -0,0 +1,179 @@
+---
+id: faq
+title: 자주 묻는 질문
+sidebar_position: 9
+---
+
+# 자주 묻는 질문
+
+Synapse SDK에 대한 일반적인 질문과 답변입니다.
+
+## 설치 및 설정
+
+### Q: 지원되는 Python 버전은 무엇인가요?
+
+Synapse SDK는 **Python 3.10 이상**이 필요합니다.
+
+```bash
+pip install "synapse-sdk[all,devtools]"
+```
+
+### Q: 로컬 개발을 위해 code-server를 어떻게 설치하나요?
+
+여러 가지 옵션이 있습니다:
+
+```bash
+# 권장: 설치 스크립트
+curl -fsSL https://code-server.dev/install.sh | sh
+
+# npm 사용
+npm install -g code-server
+
+# yarn 사용
+yarn global add code-server
+```
+
+더 많은 설치 방법은 다음을 참조하세요: [code-server 설치 가이드](https://coder.com/docs/code-server/latest/install)
+
+## CLI 사용
+
+### Q: Synapse CLI를 어떻게 시작하나요?
+
+간단히 실행하세요:
+
+```bash
+synapse
+```
+
+이것은 모든 Synapse 기능에 액세스할 수 있는 대화형 메뉴를 엽니다.
+
+### Q: Agent와 로컬 code-server의 차이점은 무엇인가요?
+
+- **Agent Code-Server**: 프로젝트 파일이 동기화된 원격 Agent에서 실행됩니다. 플러그인 암호화 및 보안 전송이 포함됩니다.
+- **로컬 Code-Server**: 로컬 머신에서 실행됩니다. 더 빠른 시작, 로컬 환경 및 설정을 사용합니다.
+
+### Q: code-server 포트를 어떻게 설정하나요?
+
+Code-server 포트는 `~/.config/code-server/config.yaml`에서 자동으로 감지됩니다. 설정이 없으면 포트 8070을 기본값으로 사용합니다.
+
+예제 설정:
+
+```yaml
+bind-addr: 127.0.0.1:8070
+auth: password
+password: your-password-here
+cert: false
+```
+
+### Q: Agent 작업공간 경로가 로컬 경로와 다른 이유는 무엇인가요?
+
+Agent는 로컬 프로젝트가 `/home/coder/workspace`에 마운트되는 컨테이너화된 환경에서 실행됩니다. 이는 정상적이며 다양한 개발 환경에서 일관된 경로를 보장합니다.
+
+## Code-Server 문제 해결
+
+### Q: Code-server에서 "사용 불가능" 오류가 표시됩니다
+
+이는 일반적으로 다음을 의미합니다:
+
+1. Agent에 code-server 지원이 활성화되어 있지 않음
+2. 네트워크 연결 문제
+3. Agent가 적절히 설정되지 않음
+
+**해결방법**: code-server 지원으로 Agent를 재설치하거나 Agent 설정을 확인하세요.
+
+### Q: 브라우저가 자동으로 열리지 않습니다
+
+이는 헤드리스 환경이나 디스플레이를 사용할 수 없을 때 발생합니다.
+
+**해결방법**: 제공된 URL(`?folder=` 매개변수 포함)을 브라우저에 수동으로 복사하세요.
+
+### Q: 작업공간에서 플러그인이 감지되지 않습니다
+
+**해결방법**: 디렉토리에 플러그인 메타데이터가 포함된 유효한 `config.yaml` 파일이 있는지 확인하세요:
+
+```yaml
+name: my-plugin
+version: 1.0.0
+description: My awesome plugin
+entry_point: main.py
+```
+
+### Q: 플러그인 암호화는 어떻게 작동하나요?
+
+Agent로 code-server를 열 때 Synapse는:
+
+1. 작업공간에 플러그인이 포함되어 있는지 감지
+2. 플러그인 파일의 ZIP 아카이브 생성
+3. AES-256 암호화를 사용하여 아카이브 암호화
+4. Agent로 안전하게 전송
+5. Agent 작업공간에서 암호 해제 및 추출
+
+이렇게 하면 전송 중 플러그인 코드가 보호됩니다.
+
+## 설정
+
+### Q: 설정 파일은 어디에 저장되나요?
+
+- **Synapse 설정**: `~/.synapse/devtools.yaml`
+- **Code-Server 설정**: `~/.config/code-server/config.yaml`
+
+### Q: 설정을 어떻게 재설정하나요?
+
+```bash
+# 설정 파일 제거
+rm ~/.synapse/devtools.yaml
+rm ~/.config/code-server/config.yaml
+
+# 설정 마법사 실행
+synapse config
+```
+
+### Q: "유효하지 않은 토큰 (401)" 오류가 발생하면 어떻게 하나요?
+
+이는 API 토큰이 만료되었거나 유효하지 않음을 의미합니다.
+
+**해결방법**:
+
+1. Synapse 백엔드에서 새 토큰 생성
+2. `synapse config`를 실행하여 토큰 업데이트
+3. `synapse --dev-tools`로 연결 테스트
+
+## 플러그인 개발
+
+### Q: 새 플러그인을 어떻게 생성하나요?
+
+대화형 플러그인 생성기를 사용하세요:
+
+```bash
+synapse
+# "🔌 Plugin Management" → "Create new plugin" 선택
+```
+
+이것은 예제와 문서가 포함된 완전한 플러그인 구조를 생성합니다.
+
+### Q: 플러그인을 로컬에서 어떻게 테스트하나요?
+
+```bash
+# 로컬 스크립트 실행으로 테스트
+synapse plugin run my_action '{"param": "value"}' --run-by script
+
+# Agent 실행으로 테스트
+synapse plugin run my_action '{"param": "value"}' --run-by agent
+```
+
+게시하기 전에 항상 로컬에서 테스트하여 플러그인이 올바르게 작동하는지 확인하세요.
+
+### Q: 플러그인 게시가 오류와 함께 실패합니다
+
+일반적인 문제:
+
+1. **누락된 의존성**: `requirements.txt`에 필요한 모든 패키지가 포함되어 있는지 확인
+2. **구문 오류**: 먼저 `--run-by script`로 로컬 테스트
+3. **설정 오류**: `config.yaml` 형식과 필수 필드 확인
+4. **백엔드 연결**: 백엔드에 액세스할 수 있고 토큰이 유효한지 확인
+
+**해결방법**: 자세한 오류 정보를 위해 디버그 모드를 사용하세요:
+
+```bash
+synapse plugin publish --debug
+```

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

@@ -0,0 +1,30 @@
+---
+id: converters
+title: 변환기
+sidebar_position: 1
+---
+
+# 변환기
+
+Synapse SDK는 컴퓨터 비전 데이터셋을 위한 포괄적인 데이터 형식 변환 유틸리티를 제공합니다. 이러한 변환기는 머신 러닝 워크플로우에서 일반적으로 사용되는 다양한 어노테이션 형식 간의 원활한 변환을 가능하게 합니다.
+
+## 개요
+
+변환기 시스템은 다음 간의 양방향 변환을 지원합니다:
+
+- **DM 형식** - Synapse Data Manager의 네이티브 어노테이션 형식 (v1 ⟷ v2 마이그레이션 지원)
+- **COCO 형식** - Microsoft Common Objects in Context 형식
+- **Pascal VOC 형식** - Visual Object Classes XML 형식  
+- **YOLO 형식** - You Only Look Once 텍스트 기반 형식
+
+모든 변환기는 분류된 데이터셋(train/valid/test 분할 포함)과 분류되지 않은 데이터셋 모두를 지원합니다. 또한 모든 변환기는 이제 개별 파일 처리를 위한 단일 파일 변환 모드를 지원합니다.
+
+## 지원되는 어노테이션 타입
+
+| 어노테이션 타입 | DM | COCO | Pascal VOC | YOLO |
+|----------------|----|----|-----------|------|
+| 바운딩 박스 | ✅ | ✅ | ✅ | ✅ |
+| 폴리곤 | ✅ | ✅ | ❌ | ✅ |
+| 세그멘테이션 | ✅ | ✅ | ✅ | ❌ |
+| 키포인트 | ✅ | ✅ | ❌ | ✅ |
+| 분류 | ✅ | ✅ | ❌ | ❌ |

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

@@ -0,0 +1,24 @@
+---
+id: features
+title: 기능
+sidebar_position: 5
+---
+
+# 기능
+
+이 섹션에서는 Synapse SDK에서 제공하는 주요 기능과 기능성을 다룹니다.
+
+## [플러그인 시스템](../plugins/plugins.md)
+
+ML 워크플로우 구축 및 관리를 위한 포괄적인 플러그인 프레임워크입니다.
+
+- **[플러그인 카테고리](../plugins/plugins.md#플러그인-카테고리)** - 신경망, 내보내기, 업로드, 스마트 도구 및 검증 플러그인
+- **[실행 방법](../plugins/plugins.md)** - Job, Task 및 REST API 실행 모드
+- **[개발 가이드](../plugins/plugins.md)** - 커스텀 플러그인 생성, 테스트 및 배포
+
+## [데이터 변환기](./converters/index.md)
+
+컴퓨터 비전 데이터셋을 위한 포괄적인 데이터 형식 변환 유틸리티입니다.
+
+- **[형식 변환기](./converters/index.md)** - DM, COCO, Pascal VOC 및 YOLO 형식 간 변환
+- **[버전 마이그레이션](./converters/index.md)** - 버전 간 DM 데이터셋 마이그레이션