Metadata-Version: 2.4
Name: ai-teammate-skill-sdk
Version: 0.1.0
Summary: Skill SDK for AI Teammate - Add custom tools to your AI agents
Project-URL: Homepage, https://ai-teammate.net
Project-URL: Documentation, https://ai-teammate.net/docs/skill-sdk
Project-URL: Repository, https://github.com/mobiolabs2025/ai-teammate-skill-sdk
Author-email: MobioLabs <dev@mobiolabs.net>
License-Expression: MIT
Keywords: agent,ai,sdk,skill,tool,webhook
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.23.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.22.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# AI Teammate Skill SDK

AI Teammate 에이전트에 **커스텀 도구(스킬)**를 추가하기 위한 Python SDK.

외부 API나 커스텀 로직을 스킬 서비스로 패키징하면, AI Teammate 플랫폼이 웹훅으로 호출합니다.

```
[사용자] → [AI Teammate] → [Skill Server (이 SDK)] → [외부 시스템]
```

## 설치

```bash
pip install ai-teammate-skill-sdk
```

## 빠른 시작

### 방법 1: 커스텀 코드로 스킬 만들기

```python
# my_skill.py
from ai_teammate_skill import Skill, tool

class LibrarySkill(Skill):
    name = "library"
    description = "도서관 도서 검색 및 대출 관리"

    @tool("search_books", description="도서 검색")
    async def search_books(self, query: str, category: str = "") -> str:
        # 실제 API 호출 로직
        return f"'{query}' 검색 결과: ..."

    @tool("check_availability", description="도서 대출 가능 여부 확인")
    async def check_availability(self, book_id: str) -> str:
        return f"도서 {book_id}: 대출 가능"

LibrarySkill().serve(port=9001)
```

### 방법 2: OpenAPI spec에서 자동 생성

```python
from ai_teammate_skill import Skill

skill = Skill.from_openapi("https://api.example.com/openapi.json")
skill.serve(port=9001)
```

로컬 파일도 지원합니다:

```python
skill = Skill.from_openapi("./my-api-spec.yaml")
skill.serve(port=9001)
```

## CLI 사용법

```bash
# 스킬 로드 및 도구 목록 확인
skill test ./my_skill.py

# 제출 요건 검증 (이름, 설명, 타입 힌트 등)
skill validate ./my_skill.py

# 로컬 웹훅 서버 실행
skill serve ./my_skill.py --port 9001

# 인증 토큰 설정
skill serve ./my_skill.py --secret my-secret-token
```

## 웹훅 프로토콜

스킬 서버는 두 가지 엔드포인트를 제공합니다:

### GET /manifest

스킬 정보와 도구 목록을 반환합니다.

```json
{
  "name": "library",
  "description": "도서관 도서 검색 및 대출 관리",
  "version": "0.1.0",
  "tools": [
    {
      "name": "search_books",
      "description": "도서 검색",
      "parameters": [
        { "name": "query", "type": "string", "required": true },
        { "name": "category", "type": "string", "required": false, "default": "" }
      ]
    }
  ]
}
```

### POST /execute

도구를 실행합니다.

**요청:**
```json
{
  "tool": "search_books",
  "arguments": { "query": "파이썬", "category": "프로그래밍" },
  "context": { "agent_id": "...", "end_user_id": "..." }
}
```

**응답:**
```json
{
  "result": "검색 결과: ...",
  "status": "success"
}
```

### GET /health

서버 상태를 확인합니다.

## 테스트

코드에서 직접 스킬을 테스트할 수 있습니다:

```python
from ai_teammate_skill import SkillTestClient
from my_skill import LibrarySkill

client = SkillTestClient(LibrarySkill())

# 도구 목록 확인
print(client.list_tools())  # ['search_books', 'check_availability']

# 도구 호출
result = client.call("search_books", query="파이썬")
print(result)
```

## AI Teammate에 연결하기

1. 스킬 서버를 배포합니다 (예: `https://my-skill.example.com`)
2. [AI Teammate Studio](https://ai-teammate.net)에서 에이전트 설정 → 스킬 연동
3. 웹훅 URL과 인증 정보를 입력합니다
4. 연결 테스트 후 활성화합니다

## 예제

- [`examples/hello_skill/`](examples/hello_skill/) — 최소 예제 (커스텀)
- [`examples/openapi_skill/`](examples/openapi_skill/) — OpenAPI spec에서 자동 생성

## 라이선스

MIT
