SYSTEM_OVERVIEW.md

Coconut AI 시스템 개요

🎯 시스템 목적

반향어(echolalia)를 기능적 의사소통으로 변환하는 AI 기반 언어치료 서비스

---

📊 전체 프로세스

1단계: 사용자 입력

사용자가 텍스트 입력
예: "아이스크림"

2단계: 입력 검증

보안 검증:
- 길이 확인 (1000자 이하)
- 프롬프트 주입 탐지
- 특수 문자 필터링
- 목적 검증 (반향어 분석)

3단계: 반향어 감지 (하이브리드)

3-1. 룰베이스 빠른 감지

패턴 1: 쉼표 반복
  "아이스크림, 아이스크림" → True, 0.9

패턴 2: 완전 일치
  발화 == 컨텍스트 → True, 0.9
  
패턴 3: 단어 반복
  "아이스크림 아이스크림" → True, 0.8

신뢰도 >= 0.8 → 즉시 반환 (1ms)

3-2. AI 분석 (루트 1 실패 시)

GPT-4o-mini 호출
- System: 언어치료 전문가 역할
- Input: 발화 + 컨텍스트 + 상황
- Output: is_echo, confidence, anchor, reason
- 시간: ~2초

4단계: 3단계 변환

4-1. AI 변환

GPT-4o-mini 호출
- System: 반향어 변환 규칙
- Input: 반향어 + 상황
- Output: L1, L2, L3 변환

4-2. 폴백 시스템

AI 실패 시 룰베이스 사전 정의 패턴 사용
예: "아이스크림" → 미리 정의된 변환 사용

5단계: 결과 출력

빠른 분석 모드

- 신뢰도 색상 표시 (빨강/주황/초록)
- 핵심 요약
- 3단계 변환 (색상별)

상세 분석 모드

- 전체 보고서
- 맥락 분석
- 권장사항

---

🔒 보안 시스템

입력 검증

1. 길이 제한: 1000자
2. 프롬프트 주입 탐지: 15개 패턴
3. 특수 문자 필터: 30% 이하

한도 제어

전역 제한:
- 일일 호출: 500회
- 일일 토큰: 200K (~$10)

세션 제한:
- 세션당: 100회

사용량 추적:
- 실시간 모니터링
- 50회마다 로그
- 일일 자동 초기화

---

💰 비용 관리

토큰 사용량

1회 분석:
- detect_echo: ~300 토큰
- shape_echolalia: ~170 토큰
- 총: ~470 토큰

비용:
- 1회: ~$0.0004
- 500회/일: ~$0.20
- 1달: ~$6

비용 절감

하이브리드 방식:
- 40% 룰베이스 즉시 감지 → AI 호출 없음
- 비용 절감: 55%

결과:
- AI만: $0.04/100회
- 하이브리드: $0.018/100회

---

🎯 L1, L2, L3 변환

L1: 최소 수준

길이: ≤12자
특징: 핵심 메시지만
예: "아이스크림을 먹고 싶어요"

L2: 확장 수준

길이: 12-20자
특징: 구체적 정보 추가
예: "밥을 먹고 나서 아이스크림을 먹고 싶어요"

L3: 자기표현 수준

길이: 20-30자
특징: 감정/상태 표현
예: "지금은 밥을 먹을 시간이니까 나중에 아이스크림을 먹어요"

---

🔧 기술 스택

백엔드:
- Python
- Gradio (UI)
- OpenAI API (GPT-4o-mini)

데이터베이스:
- SQLite3

보안:
- 입력 검증
- 토큰 제어
- 사용량 추적

---

📈 성능

처리 시간

평균: 1.1초
- 룰베이스: 1ms (40%)
- AI: 2000ms (45%)
- 폴백: 500ms (5%)

정확도

룰베이스: 80% (명확한 패턴)
AI: 95% (복잡한 케이스)
하이브리드: 90% (종합)

비용 효율성

AI만: 100% 비용
하이브리드: 45% 비용
절감: 55%

---

✅ 주요 기능

1. 텍스트 분석

- 반향어 감지
- 신뢰도 표시
- 3단계 변환

2. 빠른/상세 모드

- 빠른 분석: 핵심만
- 상세 분석: 전체 리포트

3. 프로필 관리

- 아동 정보 저장
- CARS 검사
- 분석 이력

4. 보안 시스템

- 입력 검증
- 한도 제어
- 사용량 추적

---

🎓 사용 흐름

1. 사용자 접속
2. 프로필 선택 (선택)
3. 텍스트 입력
4. 분석 모드 선택 (빠른/상세)
5. 분석 실행
6. 결과 확인
7. 저장 (프로필 선택 시)

---

🔬 기술 특징

하이브리드 탐지

루트 1: 룰베이스 (빠름, 무료)
루트 2: AI (정확, 유료)
결합: 성능+정확도 최적화

폴백 시스템

AI 실패 → 룰베이스 사용
100% 성공률 보장

Zero-Shot 프롬프팅

예시 없이 지시만 제공
토큰 절약
효율적 동작

---

📊 데이터 흐름

입력 검증
   ↓
룰베이스 감지 (신뢰도 >= 0.8?)
   ├─ Yes → 즉시 반환
   └─ No → AI 분석
       ↓
AI 감지 결과
   ↓
변환 생성 (AI 또는 룰베이스)
   ↓
출력 포맷팅
   ↓
사용자에게 표시

---

시스템 개요 완료