# AI Service (Python)

실시간 AI 제안사항 서비스 - FastAPI 기반

## 📋 개요

STT 서비스에서 실시간으로 변환된 텍스트를 받아 Claude API로 분석하여 회의 제안사항을 생성하고, SSE(Server-Sent Events)로 프론트엔드에 스트리밍합니다.

## 🏗️ 아키텍처

```
Frontend (회의록 작성 화면)
    ↓ (SSE 연결)
AI Service (Python)
    ↓ (Redis 조회)
Redis (실시간 텍스트 축적)
    ↑ (Event Hub)
STT Service (음성 → 텍스트)
```

## 🚀 실행 방법

### 1. 환경 설정

```bash
# .env 파일 생성
cp .env.example .env

# .env에서 아래 값 설정
CLAUDE_API_KEY=sk-ant-...  # 실제 Claude API 키
```

### 2. 의존성 설치

```bash
# 가상환경 생성 (권장)
python3 -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

# 패키지 설치
pip install -r requirements.txt
```

### 3. 서비스 시작

```bash
# 방법 1: 스크립트 실행
./start.sh

# 방법 2: 직접 실행
python3 main.py
```

### 4. 서비스 확인

```bash
# 헬스 체크
curl http://localhost:8087/health

# SSE 스트림 테스트
curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream
```

## 📡 API 엔드포인트

### SSE 스트리밍

```
GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream
```

**응답 형식 (SSE)**:
```json
event: ai-suggestion
data: {
  "suggestions": [
    {
      "id": "uuid",
      "content": "신제품의 타겟 고객층을 20-30대로 설정...",
      "timestamp": "00:05:23",
      "confidence": 0.92
    }
  ]
}
```

## 🔧 개발 환경

- **Python**: 3.9+
- **Framework**: FastAPI
- **AI**: Anthropic Claude API
- **Cache**: Redis
- **Event**: Azure Event Hub

## 📂 프로젝트 구조

```
ai-python/
├── main.py                    # FastAPI 진입점
├── requirements.txt           # 의존성
├── .env.example              # 환경 변수 예시
├── start.sh                  # 시작 스크립트
└── app/
    ├── config.py             # 환경 설정
    ├── models/
    │   └── response.py       # 응답 모델
    ├── services/
    │   ├── claude_service.py     # Claude API 서비스
    │   ├── redis_service.py      # Redis 서비스
    │   └── eventhub_service.py   # Event Hub 리스너
    └── api/
        └── v1/
            └── suggestions.py    # SSE 엔드포인트
```

## ⚙️ 환경 변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `CLAUDE_API_KEY` | Claude API 키 | (필수) |
| `CLAUDE_MODEL` | Claude 모델 | claude-3-5-sonnet-20241022 |
| `REDIS_HOST` | Redis 호스트 | 20.249.177.114 |
| `REDIS_PORT` | Redis 포트 | 6379 |
| `EVENTHUB_CONNECTION_STRING` | Event Hub 연결 문자열 | (선택) |
| `PORT` | 서비스 포트 | 8087 |

## 🔍 동작 원리

1. **STT → Event Hub**: STT 서비스가 음성을 텍스트로 변환하여 Event Hub에 발행
2. **Event Hub → Redis**: AI 서비스가 Event Hub에서 텍스트를 받아 Redis에 축적 (슬라이딩 윈도우: 최근 5분)
3. **Redis → Claude API**: 임계값(10개 세그먼트) 이상이면 Claude API로 분석
4. **Claude API → Frontend**: 분석 결과를 SSE로 프론트엔드에 스트리밍

## 🧪 테스트

```bash
# Event Hub 없이 SSE만 테스트 (Mock 데이터)
curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream

# 5초마다 샘플 제안사항이 발행됩니다
```

## 📝 개발 가이드

### Claude API 키 발급
1. https://console.anthropic.com/ 접속
2. API Keys 메뉴에서 새 키 생성
3. `.env` 파일에 설정

### Redis 연결 확인
```bash
redis-cli -h 20.249.177.114 -p 6379 -a Hi5Jessica! ping
# 응답: PONG
```

### Event Hub 설정 (선택)
- Event Hub가 없어도 SSE 스트리밍은 동작합니다
- STT 연동 시 필요

## 🚧 TODO

- [ ] Event Hub 연동 테스트
- [ ] 프론트엔드 연동 테스트
- [ ] 에러 핸들링 강화
- [ ] 로깅 개선
- [ ] 성능 모니터링