hgzero/ai-python/API-DOCUMENTATION.md

# AI Service API Documentation

## 서비스 정보
- **Base URL**: `http://localhost:8086`
- **프로덕션 URL**: `http://{AKS-IP}:8086` (배포 후)
- **포트**: 8086
- **프로토콜**: HTTP
- **CORS**: 모든 origin 허용 (개발 환경)

## API 엔드포인트

### 1. 실시간 AI 제안사항 스트리밍 (SSE)

**엔드포인트**: `GET /api/ai/suggestions/meetings/{meeting_id}/stream`

**설명**: 회의 중 실시간으로 AI 제안사항을 Server-Sent Events로 스트리밍합니다.

**파라미터**:
| 이름 | 위치 | 타입 | 필수 | 설명 |
|------|------|------|------|------|
| meeting_id | path | string | O | 회의 ID |

**응답 형식**: `text/event-stream`

**SSE 이벤트 구조**:
```
event: ai-suggestion
id: 15
data: {"suggestions":[{"id":"uuid","content":"제안 내용","timestamp":"14:23:45","confidence":0.92}]}
```

**응답 데이터 스키마**:
```typescript
interface SimpleSuggestion {
  id: string;              // 제안 ID (UUID)
  content: string;         // 제안 내용 (1-2문장)
  timestamp: string;       // 타임스탬프 (HH:MM:SS)
  confidence: number;      // 신뢰도 (0.0 ~ 1.0)
}

interface RealtimeSuggestionsResponse {
  suggestions: SimpleSuggestion[];
}
```

**프론트엔드 연동 예시 (JavaScript/TypeScript)**:

```javascript
// EventSource 연결
const meetingId = 'meeting-123';
const eventSource = new EventSource(
  `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream`
);

// AI 제안사항 수신
eventSource.addEventListener('ai-suggestion', (event) => {
  const data = JSON.parse(event.data);

  data.suggestions.forEach(suggestion => {
    console.log('새 제안:', suggestion.content);
    console.log('신뢰도:', suggestion.confidence);
    console.log('시간:', suggestion.timestamp);

    // UI 업데이트
    addSuggestionToUI(suggestion);
  });
});

// 에러 핸들링
eventSource.onerror = (error) => {
  console.error('SSE 연결 오류:', error);
  eventSource.close();
};

// 연결 종료 (회의 종료 시)
function closeSuggestions() {
  eventSource.close();
}
```

**React 예시**:

```tsx
import { useEffect, useState } from 'react';

interface Suggestion {
  id: string;
  content: string;
  timestamp: string;
  confidence: number;
}

function MeetingRoom({ meetingId }: { meetingId: string }) {
  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);

  useEffect(() => {
    const eventSource = new EventSource(
      `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream`
    );

    eventSource.addEventListener('ai-suggestion', (event) => {
      const data = JSON.parse(event.data);
      setSuggestions(prev => [...prev, ...data.suggestions]);
    });

    eventSource.onerror = () => {
      console.error('SSE 연결 오류');
      eventSource.close();
    };

    return () => {
      eventSource.close();
    };
  }, [meetingId]);

  return (
    <div>
      <h2>AI 제안사항</h2>
      {suggestions.map(s => (
        <div key={s.id}>
          <span>{s.timestamp}</span>
          <p>{s.content}</p>
          <small>신뢰도: {(s.confidence * 100).toFixed(0)}%</small>
        </div>
      ))}
    </div>
  );
}
```

### 2. 헬스 체크

**엔드포인트**: `GET /health`

**설명**: 서비스 상태 확인 (Kubernetes probe용)

**응답 예시**:
```json
{
  "status": "healthy",
  "service": "AI Service",
  "port": 8087
}
```

### 3. 서비스 정보

**엔드포인트**: `GET /`

**설명**: 서비스 기본 정보 조회

**응답 예시**:
```json
{
  "service": "AI Service",
  "version": "1.0.0",
  "status": "running",
  "endpoints": {
    "test": "/api/ai/suggestions/test",
    "stream": "/api/ai/suggestions/meetings/{meeting_id}/stream"
  }
}
```

## 동작 흐름

```
1. 회의 시작
   └─> 프론트엔드가 SSE 연결 시작

2. 음성 녹음
   └─> STT 서비스가 텍스트 변환
       └─> Event Hub 발행
           └─> AI 서비스가 Redis에 축적

3. 실시간 분석 (5초마다)
   └─> Redis에서 텍스트 조회
       └─> 임계값(10개 세그먼트) 도달 시
           └─> Claude API 분석
               └─> SSE로 제안사항 전송
                   └─> 프론트엔드 UI 업데이트

4. 회의 종료
   └─> SSE 연결 종료
```

## 주의사항

1. **연결 유지**:
   - SSE 연결은 장시간 유지되므로 네트워크 타임아웃 설정 필요
   - 브라우저는 연결 끊김 시 자동 재연결 시도

2. **CORS**:
   - 개발 환경: 모든 origin 허용
   - 프로덕션: 특정 도메인만 허용하도록 설정 필요

3. **에러 처리**:
   - SSE 연결 실패 시 재시도 로직 구현 권장
   - 네트워크 오류 시 사용자에게 알림

4. **성능**:
   - 한 회의당 하나의 SSE 연결만 유지
   - 불필요한 재연결 방지

## 테스트

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

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

### 브라우저 테스트:
1. 서비스 실행: `python3 main.py`
2. Swagger UI 접속: http://localhost:8087/docs
3. `/api/ai/suggestions/meetings/{meeting_id}/stream` 엔드포인트 테스트

## 환경 변수

프론트엔드에서 API URL을 환경 변수로 관리:

```env
# .env.local
NEXT_PUBLIC_AI_SERVICE_URL=http://localhost:8087
```

```typescript
const AI_SERVICE_URL = process.env.NEXT_PUBLIC_AI_SERVICE_URL || 'http://localhost:8087';

const eventSource = new EventSource(
  `${AI_SERVICE_URL}/api/ai/suggestions/meetings/${meetingId}/stream`
);
```

## FAQ

**Q: SSE vs WebSocket?**
A: SSE는 서버→클라이언트 단방향 통신에 최적화되어 있습니다. 이 서비스는 AI 제안사항을 프론트엔드로 전송만 하므로 SSE가 적합합니다.

**Q: 재연결은 어떻게?**
A: 브라우저의 EventSource는 자동으로 재연결을 시도합니다. 추가 로직 불필요.

**Q: 여러 클라이언트가 동시 연결 가능?**
A: 네, 각 클라이언트는 독립적으로 SSE 연결을 유지합니다.

**Q: 제안사항이 오지 않으면?**
A: Redis에 충분한 텍스트(10개 세그먼트)가 축적되어야 분석이 시작됩니다. 5초마다 체크합니다.

### 3. AI 텍스트 요약 생성

**엔드포인트**: `POST /api/v1/ai/summary/generate`

**설명**: 텍스트를 AI로 요약하여 핵심 내용과 포인트를 추출합니다.

**요청 본문**:
```json
{
  "text": "요약할 텍스트 내용",
  "language": "ko",  // ko: 한국어, en: 영어 (기본값: ko)
  "style": "bullet", // bullet: 불릿포인트, paragraph: 단락형 (기본값: bullet)
  "max_length": 100  // 최대 요약 길이 (단어 수) - 선택사항
}
```

**응답 예시**:
```json
{
  "summary": "• 프로젝트 총 개발 기간 3개월 확정 (디자인 2주, 개발 8주, 테스트 2주)\n• 총 예산 5천만원 배정 (인건비 3천만원, 인프라 1천만원, 기타 1천만원)\n• 주간 회의 일정: 매주 화요일 오전 10시",
  "key_points": [
    "프로젝트 전체 일정 3개월로 확정",
    "개발 단계별 기간: 디자인 2주, 개발 8주, 테스트 2주",
    "총 예산 5천만원 책정",
    "예산 배분: 인건비 60%, 인프라 20%, 기타 20%",
    "정기 회의: 매주 화요일 오전 10시"
  ],
  "word_count": 32,
  "original_word_count": 46,
  "compression_ratio": 0.7,
  "generated_at": "2025-10-29T17:23:49.429982"
}
```

**요청 예시 (curl)**:
```bash
curl -X POST "http://localhost:8086/api/v1/ai/summary/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "오늘 회의에서는 프로젝트 일정과 예산에 대해 논의했습니다...",
    "language": "ko",
    "style": "bullet"
  }'
```

**에러 응답**:
- `400 Bad Request`: 텍스트가 비어있거나 너무 짧은 경우 (최소 20자)
- `400 Bad Request`: 텍스트가 너무 긴 경우 (최대 10,000자)
- `500 Internal Server Error`: AI 처리 중 오류 발생