# 의도 파악 3단계 아키텍처 전환 계획

**작성일**: 2025-11-26  
**작성자**: Auto (Claude)  
**상태**: 구현 완료 (2025-11-26)  
**관련 문서**:
- `251017_intent_analysis_improvement_plan.md` - 의도 분석 개선 플랜
- `251023_happybell80_의도_런타임_하이브리드_임베딩_베이지안_동적학습.md` - 의도 런타임 설계
- `311_FastAPI_구조_원칙.md` - 코드 작성 원칙

---

## 1. 문제 발견

### 1.1 현재 구조의 근본적 문제

**발견된 문제**:
- IntentType이 스킬/액션과 직접 1:1 매핑되어 있음
- 의도 파악이 곧 스킬 선택으로 이어지는 구조
- 진정한 "의도 파악(무엇을 원하는가)" → "행동 계획(어떻게 할 것인가)" → "스킬 선택(어떤 도구를 쓸 것인가)"의 단계적 분리가 없음

**실제 문제 사례**:
```
사용자: "12월 10일 11시 종합운동장에서 뵙겠습니다. 준비물: 노트북,휴대폰 일정등록"
로빙: "네, 종합운동장 미팅 일정을 12월 10일 11시에 등록해 드릴게요. 구글 캘린더에 등록해드릴까요?"
사용자: "그래"
로빙: "안녕하세요! 무엇을 도와드릴까요? 😊"  # ❌ 일반 인사로 돌아감
```

**원인 분석**:
- "구글 캘린더에 등록해드릴까요?" 응답이 `calendar_event` intent로 저장됨
- "그래" 같은 동의 메시지가 `_confirm`으로 끝나는 intent를 찾지 못함
- `calendar_event`는 approval 대상이 아니어서 `calendar_approval`로 변환되지 않음

### 1.2 아키텍처 구조적 문제

**현재 구조**:
```
IntentType (스킬/액션과 직접 매핑)
  ↓
decide_skill_sequence() → 스킬 선택
```

**문제점**:
- 의도 파악이 스킬 선택에 가까움
- 새로운 의도 추가 시 스킬도 함께 정의해야 함
- 의도와 구현이 강하게 결합됨

---

## 2. 개선 방향

### 2.1 3단계 구조 설계

**목표**: 의도 파악 → 행동 계획 → 스킬 선택의 단계적 접근

```
1단계: 의도 파악 (IntentAnalyzer)
  - 추상적 목표 파악 (일정 관리, 정보 검색, 커뮤니케이션 등)
  - LLM 기반 제로샷 의도 분석 (무한한 의도 처리 가능)
  - 사용자가 무엇을 원하는지 추상적 수준에서 이해

2단계: 행동 계획 (ActionPlanner)
  - 구체적 행동 결정 (등록/조회/삭제/수정 등)
  - 의도를 달성하기 위한 구체적 행동 계획
  - 여러 행동이 필요한 경우 순서 및 우선순위 결정

3단계: 스킬 선택 (SkillSelector)
  - 적절한 도구 선택 (calendar_skill.create_event 등)
  - 행동을 수행할 적절한 스킬 선택
  - 스킬 실행 가능 여부 확인
```

### 2.2 3단계 구조의 장점

- **의도와 구현의 분리**: 같은 의도라도 다른 행동/스킬로 구현 가능
- **확장성**: 새로운 스킬 추가 시 기존 의도 재사용 가능
- **유연성**: 행동 계획 단계에서 여러 대안 고려 가능
- **명확성**: 각 단계의 책임이 명확히 분리됨
- **무한한 의도 처리**: LLM 기반으로 아직 구현되지 않은 의도도 파악 가능

---

## 3. 구현 계획

### 3.1 폴더 구조

```
app/services/brain/
├── intent/                    # 신규 폴더
│   ├── __init__.py
│   ├── schemas.py            # IntentGoal, ActionPlan, SkillSequence
│   ├── intent_analyzer.py    # 1단계: 의도 파악
│   ├── action_planner.py     # 2단계: 행동 계획
│   ├── skill_selector.py     # 3단계: 스킬 선택
│   ├── intent_graph.py       # 기존 파일 이동
│   └── semantic_classifier.py # 기존 파일 이동
├── decision_engine.py         # 래퍼로 유지 (하위 호환성)
├── brain_service.py           # 3단계 파이프라인 호출
└── ...
```

### 3.2 데이터 구조 정의

**Pydantic 모델** (`app/services/brain/intent/schemas.py`):

```python
from pydantic import BaseModel
from typing import Optional, List, Dict, Any
from enum import Enum

class IntentCategory(str, Enum):
    """추상적 의도 카테고리"""
    SCHEDULE_MANAGEMENT = "schedule_management"  # 일정 관리
    INFORMATION_RETRIEVAL = "information_retrieval"  # 정보 검색
    COMMUNICATION = "communication"  # 커뮤니케이션
    DOCUMENT_PROCESSING = "document_processing"  # 문서 처리
    TASK_EXECUTION = "task_execution"  # 작업 실행
    GENERAL_INQUIRY = "general_inquiry"  # 일반 질의
    UNKNOWN = "unknown"

class IntentGoal(BaseModel):
    """1단계: 의도 파악 결과"""
    category: IntentCategory  # 추상적 카테고리
    description: str  # LLM이 파악한 의도 설명
    confidence: float  # 신뢰도 (0.0 ~ 1.0)
    raw_intent: Optional[str] = None  # LLM 원본 출력 (디버깅용)
    context_hints: Dict[str, Any] = {}  # 컨텍스트 힌트

class ActionType(str, Enum):
    """구체적 행동 타입"""
    CREATE_EVENT = "create_event"
    QUERY_EVENTS = "query_events"
    DELETE_EVENT = "delete_event"
    UPDATE_EVENT = "update_event"
    SEARCH_WEB = "search_web"
    SEARCH_MEMORY = "search_memory"
    SEND_EMAIL = "send_email"
    READ_EMAIL = "read_email"
    ANALYZE_DOCUMENT = "analyze_document"
    CLARIFY = "clarify"
    CHAT = "chat"

class ActionPlan(BaseModel):
    """2단계: 행동 계획 결과"""
    actions: List[Dict[str, Any]]  # 행동 목록
    requires_clarification: bool = False
    clarification_message: Optional[str] = None

class SkillSequence(BaseModel):
    """3단계: 스킬 선택 결과 (기존 execution_plan과 호환)"""
    skills: List[Dict[str, Any]]  # 스킬 목록
    intent: Dict[str, Any]  # 원본 의도 정보 (하위 호환성)
```

### 3.3 데이터 흐름

```
IntentAnalyzer.analyze() → IntentGoal
    ↓
ActionPlanner.plan(IntentGoal) → ActionPlan
    ↓
SkillSelector.select(ActionPlan) → SkillSequence
    ↓
기존 execution_plan 형식으로 변환 (하위 호환성)
```

### 3.4 하위 호환성 유지

**기존 DecisionEngine 클래스는 래퍼로 유지**:
- 내부적으로 3단계 파이프라인 호출
- 기존 API 인터페이스 유지
- 점진적 마이그레이션 가능

---

## 4. TDD 시나리오

### 시나리오 1: 일정 등록 동의 처리 (현재 문제 해결)
```
사용자: "12월 10일 11시 종합운동장에서 뵙겠습니다. 준비물: 노트북,휴대폰 일정등록"
로빙: "네, 종합운동장 미팅 일정을 12월 10일 11시에 등록해 드릴게요. 구글 캘린더에 등록해드릴까요?"
사용자: "그래"
→ IntentGoal: {category: SCHEDULE_MANAGEMENT, description: "일정 등록 승인"}
→ ActionPlan: {actions: [{type: CREATE_EVENT, goal: "구글 캘린더에 일정 등록"}]}
→ SkillSequence: {skills: [{skill: "CALENDAR", action: "create_event"}]}
→ 성공: 일정 등록 완료
```

### 시나리오 2: 아직 구현되지 않은 의도 처리
```
사용자: "내일 오후 2시 회의실 예약해줘"
→ IntentGoal: {category: SCHEDULE_MANAGEMENT, description: "회의실 예약 요청"}
→ ActionPlan: {actions: [{type: CREATE_EVENT, goal: "회의실 예약"}]}
→ SkillSelector: 회의실 예약 스킬 없음 감지
→ 로빙: "죄송합니다. 회의실 예약 기능은 아직 준비 중입니다. 구글 캘린더에 일정만 등록해드릴까요?"
```

### 시나리오 3: 복합 의도 처리
```
사용자: "리버스마운틴 유사 기업 찾아서 가치평가 보고서 이메일로 보내줘"
→ IntentGoal: {category: INFORMATION_RETRIEVAL, description: "기업 검색 및 분석 후 이메일 발송"}
→ ActionPlan: {actions: [
  {type: SEARCH_WEB, goal: "리버스마운틴 유사 기업 검색", priority: 1},
  {type: ANALYZE_DOCUMENT, goal: "가치평가 분석", priority: 2},
  {type: SEND_EMAIL, goal: "보고서 이메일 발송", priority: 3}
]}
→ SkillSequence: {skills: [
  {skill: "TOOL", action: "web_search"},
  {skill: "LLM", action: "analyze"},
  {skill: "EMAIL", action: "compose"}
]}
```

### 시나리오 4: 맥락 기반 의도 파악
```
사용자: "아까 말한 그 기업 투자 단계는?"
→ IntentGoal: {category: INFORMATION_RETRIEVAL, description: "이전 대화에서 언급된 기업의 투자 단계 조회", context_hints: {reference: "previous_conversation"}}
→ ActionPlan: {actions: [{type: SEARCH_MEMORY, goal: "이전 대화에서 기업 정보 검색"}]}
→ SkillSequence: {skills: [{skill: "LLM", action: "search_memory"}]}
→ 성공: ChromaDB에서 관련 대화 검색 후 답변
```

### 시나리오 5: 모호한 의도 명확화
```
사용자: "이메일 보내줘"
→ IntentGoal: {category: COMMUNICATION, description: "이메일 발송 요청", confidence: 0.6}
→ ActionPlan: {
  requires_clarification: True,
  clarification_message: "누구에게 보내실까요? 어떤 내용을 보내실까요?"
}
→ SkillSequence: {skills: []}
→ 로빙: "누구에게 보내실까요? 어떤 내용을 보내실까요?"
```

---

## 5. 수정 범위

### 5.1 수정 필요한 부분

**백엔드 (rb8001)**:
- `app/services/brain/decision_engine.py` → 3단계 파이프라인으로 재구성
- `app/services/brain/intent/` 폴더 신규 생성
- `app/services/brain/brain_service.py` → 3단계 파이프라인 호출

### 5.2 수정 불필요한 부분

- **Gateway (robeing-gateway)**: 변경 불필요, JWT 검증/프록시 역할 유지
- **프론트엔드**: 변경 불필요, API 인터페이스 동일
- **DB 스키마**: 변경 불필요, 의도/행동 계획은 런타임 처리

---

## 6. 구현 순서

### Phase 1: 구조 설계 및 스키마 정의 (1일)
1. `app/services/brain/intent/` 폴더 생성
2. `schemas.py` 작성 (IntentGoal, ActionPlan, SkillSequence)
3. 기존 파일 이동 (intent_graph.py, semantic_classifier.py)

### Phase 2: IntentAnalyzer 구현 (2일)
1. LLM 기반 제로샷 의도 분석
2. IntentCategory 분류
3. TDD 테스트 작성

### Phase 3: ActionPlanner 구현 (2일)
1. IntentGoal → ActionPlan 변환 로직
2. 복합 행동 처리
3. Clarify 로직

### Phase 4: SkillSelector 구현 (2일)
1. ActionPlan → SkillSequence 변환
2. 기존 execution_plan 형식으로 변환
3. 하위 호환성 유지

### Phase 5: 통합 및 테스트 (2일)
1. DecisionEngine 래퍼 구현
2. 기존 테스트 통과 확인
3. TDD 시나리오 검증

---

## 7. 참고 사항

### 7.1 코드 작성 원칙 준수
- 계층 분리: router → services → state
- 파일 크기: 한 파일 최대 300줄
- 의존성 방향: 단방향 흐름

### 7.2 하위 호환성
- 기존 DecisionEngine API 유지
- 기존 execution_plan 형식 유지
- 점진적 마이그레이션 가능

---

**작성 완료**: 2025-11-26  
**다음 단계**: Phase 1 구현 시작

---

## 8. 구현 완료 (2025-11-26)

### 8.1 구현 내용

**완료된 작업**:
1. ✅ IntentAnalyzer 구현 (`app/services/brain/intent/intent_analyzer.py`)
   - LLM 기반 제로샷 의도 분석 (async)
   - 키워드 기반 폴백 분석 (sync)
   - IntentCategory 분류 지원

2. ✅ ActionPlanner 확장 (`app/services/brain/intent/action_planner.py`)
   - 모든 IntentCategory에 대한 ActionType 매핑
   - SCHEDULE_MANAGEMENT: CREATE_EVENT, QUERY_EVENTS, DELETE_EVENT, UPDATE_EVENT
   - INFORMATION_RETRIEVAL: SEARCH_WEB, SEARCH_MEMORY
   - COMMUNICATION: SEND_EMAIL, READ_EMAIL
   - DOCUMENT_PROCESSING: ANALYZE_DOCUMENT
   - TASK_EXECUTION, GENERAL_INQUIRY: CHAT
   - UNKNOWN: CLARIFY

3. ✅ SkillSelector 확장 (`app/services/brain/intent/skill_selector.py`)
   - 모든 ActionType에 대한 스킬 매핑
   - CALENDAR, EMAIL, TOOL, LLM 스킬 지원

4. ✅ DecisionEngine 통합 (`app/services/brain/decision_engine.py`)
   - `_build_intent_pipeline_sync`: 동기 버전 (폴백 분석)
   - `_build_intent_pipeline`: 비동기 버전 (LLM 기반)
   - `create_execution_plan`에 `intent_pipeline` 메타데이터 추가

5. ✅ 테스트 통과
   - ActionPlanner 테스트 통과
   - SkillSelector 테스트 통과
   - DecisionEngine 통합 테스트 통과

### 8.2 배포 상태

- **커밋**: `1b57c86` - "feat: 3단계 의도 파악 아키텍처 구현"
- **배포 완료**: 2025-11-26 19:17
- **컨테이너 상태**: 정상 (healthy)

### 8.3 하위 호환성

- 기존 `decide_skill_sequence` 메서드 유지 (하위 호환성)
- 새로운 3단계 파이프라인은 `execution_plan["intent_pipeline"]` 메타데이터로 제공
- 점진적 마이그레이션을 위해 두 시스템 병행

### 8.4 중복 코드 확인

- `decide_skill_sequence`와 `SkillSelector` 모두 IntentType/ActionType → Skill 매핑 포함
- 의도적 중복: 하위 호환성 및 점진적 마이그레이션을 위해 병행 유지
- 주석 추가로 의도 명확화

---

## 9. DB/베이지안 방법 통합 방안

### 9.1 문제

5가지 TDD 시나리오 테스트 결과 시나리오 2~5가 미비:
- 시나리오 2: 미구현 의도 처리 - clarify 없음
- 시나리오 3: 복합 의도 처리 - 단일 액션만 생성
- 시나리오 4: 맥락 기반 의도 파악 - UNKNOWN 분류
- 시나리오 5: 모호한 의도 명확화 - clarify 없음

### 9.2 해결 방안

기존 DB/베이지안 방법(`intent_prototypes`, `intent_thresholds`, `intent_path_stats`)을 3단계 아키텍처에 통합:
- **IntentAnalyzer**: `SemanticIntentClassifier` 재사용, 임베딩 기반 후보 축소
- **ActionPlanner**: `intent_path_stats`의 Beta(α,β)로 액션 우선순위 조정, 복합 의도 파싱
- **SkillSelector**: 스킬별 실행 성공률 추적, 미구현 스킬 감지

**상세 내용**: `251126_intent_3step_db_bayesian_integration.md` 참고

---

## 10. 리스크 및 추가 고려사항

- **회귀 및 승인/컨펌 흐름 붕괴 리스크**  
  - 기존 DecisionEngine이 암묵적으로 처리하던 승인/취소/컨펌, 예외 케이스들이 IntentGoal → ActionPlan → SkillSequence 분리 과정에서 깨질 수 있음 (예: 같은 입력인데 캘린더/이메일 오작동).  
  - 실제 서비스 대화 로그를 기반으로 한 리플레이 테스트 세트, A/B 플래그(구 구조/신 구조 토글), 빠른 롤백 전략을 설계한 뒤 단계적으로 트래픽을 전환해야 함.

- **LLM 기반 1단계 도입에 따른 비용/레이턴시/안정성 이슈**  
  - 모든 발화가 최소 1회 LLM을 타면 레이턴시·비용·비결정성이 커지므로, 고빈도·단순 패턴(“그래”, “응”, 일정 단문 등)은 규칙/통계 모델로 단축 경로를 두고, 각 단계별 confidence 기준과 실패 시 폴백 전략(UNKNOWN → 안전한 일반 대화/질문 재확인)을 명시적으로 정의해야 함.  
  - LLM 프롬프트/파라미터 변경에 따른 드리프트를 감시할 수 있도록, IntentAnalyzer 입력/출력(카테고리, 설명, confidence)을 구조화된 로그로 남기고 모니터링 지표(오탐/미탐 비율, 평균 응답 시간 등)를 운영 레벨에서 관리해야 함.

- **학습·개선 루프까지 포함한 설계**  
  - 3단계 분리는 파일 구조 정리가 아니라, 각 단계에서 생성되는 신호를 intent_review/active_learning과 연결해 시간이 지날수록 의도→행동→스킬 품질이 자동 개선되도록 만드는 것이 핵심.  
  - IntentGoal/ActionPlan/SkillSequence 및 실제 실행 결과(성공/실패, 사용자 피드백)를 표준 스키마로 저장하고, 이를 기반으로 한 오프라인 평가·액티브 러닝·온라인 튜닝 루프를 설계해야 함.