# ZeliAI Python SDK

> 16개+ AI 모델을 하나의 API로. GPT-5, Claude, Gemini, Grok — 모든 모델을 `pip install zeliai` 한 줄로.

[![PyPI](https://img.shields.io/pypi/v/zeliai)](https://pypi.org/project/zeliai/)
[![Python](https://img.shields.io/pypi/pyversions/zeliai)](https://pypi.org/project/zeliai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## 설치

```bash
pip install zeliai
```

## 빠른 시작

```python
from zeliai import ZeliAI

client = ZeliAI(api_key="zeliai-xxxx...")

# 채팅
response = client.chat("파이썬으로 퀵소트 설명해줘", model="gpt-5.2")
print(response.content)
```

## 인증

API 키를 직접 전달하거나 환경변수로 설정하세요:

```bash
export ZELIAI_API_KEY="zeliai-xxxx..."
```

```python
# 환경변수 자동 감지
client = ZeliAI()
```

## API 가이드

### 💬 채팅

```python
# 기본 채팅
response = client.chat("안녕하세요!")
print(response.content)

# 모델 지정
response = client.chat("설명해줘", model="claude-opus-4.5")

# 시스템 지시
response = client.chat(
    "매출 데이터 분석해줘",
    model="gemini-3-pro",
    system="당신은 전문 데이터 분석가입니다. 한국어로 답변하세요."
)

# 대화 이어가기 (세션)
r1 = client.chat("내 이름은 지민이야", model="gpt-5.2")
r2 = client.chat("내 이름이 뭐라고 했지?", model="gpt-5.2", session_id=r1.session_id)
```

### 🌊 스트리밍

```python
for chunk in client.chat_stream("긴 이야기를 해줘", model="gpt-5.2"):
    print(chunk, end="", flush=True)
```

### 🔍 검색

```python
result = client.search("2026년 AI 트렌드")
print(result.ai_summary)
for r in result.results:
    print(f"  📄 {r.title}: {r.url}")
```

### 📄 문서 Q&A

```python
result = client.document_qa(
    question="이 계약서의 만료일은 언제인가요?",
    file_path="contract.pdf",
    model="gpt-5.2"
)
print(result.answer)
```

### 📊 모델 & 사용량

```python
# 사용 가능한 모델
for m in client.models():
    print(f"{m.id}: {m.description}")

# 사용량 확인
usage = client.usage()
print(f"총 요청: {usage.total_requests}, 총 토큰: {usage.total_tokens}")

# 서버 상태
print(client.health())
```

## 예외 처리

```python
from zeliai import ZeliAI, AuthenticationError, RateLimitError, ModelNotFoundError

try:
    response = client.chat("테스트")
except AuthenticationError:
    print("❌ API 키가 유효하지 않습니다")
except RateLimitError:
    print("⏳ 요청 한도 초과. 잠시 후 다시 시도하세요")
except ModelNotFoundError as e:
    print(f"🤖 {e.message}")
```

## 지원 모델

| Provider | Models | Model ID |
|----------|--------|----------|
| **OpenAI** | GPT-5.2, GPT-5, GPT-5 Mini, GPT-5 Nano | `gpt-5.2`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano` |
| **Anthropic** | Claude Opus 4.5, Opus 4.1, Sonnet 4 | `claude-opus-4.5`, `claude-opus-4.1`, `claude-sonnet-4` |
| **Google** | Gemini 3 Pro, 2.5 Pro, 2.5 Flash | `gemini-3-pro`, `gemini-2.5-pro`, `gemini-2.5-flash` |
| **xAI** | Grok-4, Grok-4.1 FR, Grok Code | `grok-4`, `grok-4.1-fast`, `grok-code-fast` |

전체 모델 목록: `client.models()`

## Context Manager

```python
with ZeliAI(api_key="zeliai-xxxx...") as client:
    response = client.chat("안녕!")
    print(response.content)
# 자동 리소스 정리
```

## License

MIT

---

**ZeliAI** — [zeliai.com](https://zeliai.com)  
문의: dev@zeliai.com
