Cheez Chat API
Cheez Chat API는 DNM(Dynamic Narrative Map) 엔진을 기반으로 동작하는 멀티테넌트 AI 대화 플랫폼입니다. Express + TypeScript + Firebase Firestore로 구성된 안정적인 인프라 위에, B2B 클라이언트가 실제로 구매하는 AI Feature Layer가 얹혀집니다.
Express + TypeScript
타입 안전 REST API. 멀티테넌트 구조로 고객사별 독립 환경 보장
Firebase Firestore
테넌트·캐릭터·세션·메시지 계층 분리 저장. Admin Dashboard 연동
Gemini / Claude
Narrative OS 방식으로 필요한 컨텍스트만 정확히 전달
18 Plugins
우선순위 기반 실행 파이프라인. 각 플러그인이 독립적으로 컨텍스트 확장
DNM 엔진의 작동 원리
DNM 엔진은 사용자의 현재 위치, 시간, 감정 등 꼭 필요한 정보만 골라서 AI에게 전달합니다.
덕분에 AI가 헛소리하지 않고, 세계관에 맞는 정확한 답변을 합니다.
AI의 기억력에 의존하지 않고, 데이터 기반으로 세계를 유지합니다
설계 원칙
Cheez Chat API의 3가지 핵심 설계 철학입니다.
Composable
모든 기능은 독립 모듈로 설계됩니다. 클라이언트가 필요한 것만 선택해 조합하세요.
Persona(full) + Style(live) + Sensor(live-6)
Progressive
systemPrompt 하나로 시작해 점진적으로 기능을 추가할 수 있습니다. Tier 0부터 Tier 3까지.
Tier 0 → 1 → 2 → 3 점진 도입
Backward Compatible
기존 파라미터만 보내면 기존대로 동작합니다. 새 파라미터는 모두 optional로 설계됩니다.
새 필드는 항상 optional
티어 비교표
Cheez Chat API는 4개 티어로 기능을 제공합니다. 도입 목적과 복잡도에 맞는 티어를 선택하세요.
Basic
flat 프롬프트 기반. 빠른 프로토타이핑과 단순 운세·챗봇 서비스에 적합
Standard
구조화 페르소나 + 스타일 선택. 개성 있는 AI 캐릭터 서비스 구축
Pro
Sensor/Tags + Stats + Lorebook. 감정 추적과 동적 세계관이 필요한 서비스
Enterprise
장기기억 + Realtime Hooks + Full DNM. 몰입형 인터랙티브 스토리 플랫폼
| 기능 모듈 | Tier 0 Basic |
Tier 1 Standard |
Tier 2 Pro |
Tier 3 Enterprise |
|---|---|---|---|---|
| Persona Engine | flat string | 구조화 필드 13개 필드 |
Full Fields | OptimizedPersona 장기 튜닝 |
| Style System | — | normal / romance | 7종 전체 live 포함 |
7종 + 커스텀 |
| Sensor / Tags | — | — | 스타일별 태그 Live-6 센서 |
전체 태그 서버사이드 파싱 |
| Stats Engine | — | — | 기본 스탯 호감도, 신뢰도 |
동적 스탯 커스텀 지표 |
| Lorebook / World | — | — | 키워드 트리거 Lorebook 기본 |
Living World DNM 전체 |
| Memory / Context | 세션 내 | L1 단기기억 | L1 + L2 중기 요약 |
L3 장기기억 GraphContext |
| Realtime Hooks | — | — | — | ✓ beforeAI afterAI hooks |
| Ability System | ✓ 단일 | ✓ 단일 | ✓ 복수 | ✓ 전체 |
| Admin Dashboard | — | 캐릭터 CRUD | 캐릭터 + 모니터링 | 엔터프라이즈 실시간 관리 |
| 18 Plugin System | 기본 (5종) | 확장 (10종) | Full (18종) | Full + 커스텀 |
| 서비스 예시 | OZO 타로·운세 챗봇 |
OZO Pro 구조화 캐릭터 |
팬업 AI 아바타 채팅 |
치즈 인터랙티브 스토리 |
Persona Engine
Cheez 내부의 구조화 캐릭터 시스템을 API로 노출하는 레이어입니다. 평문 systemPrompt 대신 구조화 페르소나 필드를 조합해 일관된 AI 캐릭터를 정의하세요.
| 티어 | 방식 | 지원 필드 | 활용 예 |
|---|---|---|---|
| Tier 0 | flat 프롬프트 | systemPrompt?: string기존 방식 그대로 |
간단한 운세 봇 |
| Tier 1 | 구조화 페르소나 |
corePersona, personality, personalityKeywords,
speechPattern, speechExamples, background,
secret, motivation, dialogueStyle,
forbiddenBehaviors, age, gender, appearance
|
개성 있는 AI 캐릭터 |
| Tier 2 | Full Fields | Tier 1 전체 + 관계 설정, 방송 스타일, 팬 상호작용 규칙 | AI 아바타 채팅 (팬업) |
| Tier 3 | OptimizedPersona |
optimizedPersona.coreTraits,
speechPatterns,
emotionalShifts,
reactionSets,
relationshipMilestones
|
장기 튜닝 캐릭터 (치즈) |
Style System
Cheez 내부의 7개 스토리 스타일을 API 파라미터로 선택하는 레이어입니다. 각 스타일은 전용 프롬프트 레이어와 태그 세트를 함께 활성화합니다.
| Style ID | 스타일명 | 핵심 태그 / 특성 | 티어 |
|---|---|---|---|
normal |
기본 | 호감도 태그만 활성화. 태그 없는 깔끔한 대화 | Tier 1+ |
romance |
로맨스 | 설렘도, 관계온도, 심장박동, 거리감, 감정폭발, 결정적순간, 케미반응 | Tier 1+ |
bl |
BL | 집착도, 질투심, 밀당지수, 독점선언, 위험신호, 관계온도 | Tier 2+ |
system |
시스템창 | 능력발동, 스캔, 상태창, 경험치, 스킬획득, 퀘스트, 호감도 | Tier 2+ |
guideverse |
가이드버스 | 폭주지수, 동조율, 각인상태, 존드랍위험, 공명, 가이딩효과 | Tier 2+ |
omegaverse |
오메가버스 | 페로몬농도, 발정기, 각인, 억제제, 마킹충동, 영역본능 | Tier 2+ |
live |
라이브방송 | 호감도, 속마음, 밀당지수, 피로도, 체력, 방송사고, PM_DM | Tier 2+ |
B2B 테넌트 제어
TenantConfig의 allowedStyles, allowedGenres,
defaultStyle, defaultGenre로 테넌트별 사용 가능한 스타일과 장르를 제한합니다.
팬업은 allowedStyles: ["live"], OZO은 allowedStyles: ["normal"]으로 설정됩니다.
Sensor / Tag System
각 스타일별 태그 세트를 AI 응답에 포함시키고, 클라이언트가 이를 파싱해 UI로 렌더링할 수 있는 레이어입니다. Tier 2부터 활성화됩니다.
태그 포맷
【카테고리 : 내용】 또는
【카테고리 : 내용 | 추가정보 | 추가정보2】 형태로 AI 응답에 포함됩니다.
예시: 【호감도 : +3 | 벨벳 키스 | 따뜻한 인사 반응】
| 스타일 | 핵심 태그 (Core) | 보조 태그 (Sub) |
|---|---|---|
normal |
호감도 | — |
romance |
호감도, 설렘도, 심장박동, 관계온도 | 거리감, 내면독백, 플래그, 감정폭발, 결정적순간, 케미반응 |
bl |
집착도, 질투심, 밀당지수, 심장박동 | 관계온도, 거리감, 내면독백, 감정폭발, 독점선언, 위험신호 |
system |
능력발동, 스캔, 상태창, 경험치, 스킬획득, 퀘스트, 호감도 | — |
guideverse |
폭주지수, 동조율, 각인상태 | 감각과부하, 존드랍위험, 정신체반응, 가이딩효과, 감각확장, 공명 |
omegaverse |
페로몬농도, 발정기, 각인 | 본능충동, 페로몬감지, 억제제, 짝반응, 열전조, 마킹충동, 목덜미반응, 영역본능 |
live |
호감도, 속마음, 밀당지수 | 거리감, 질투은폐, 방송사고, PM_DM, 피로도, 체력, 배고픔, 방송아이디어 |
API 응답의 parsedTags와 parsedSegments 필드를 통해 서버사이드 파싱 결과를 선택적으로 수신할 수 있습니다.
Stats Engine
AI 대화 흐름에 따라 실시간으로 변화하는 수치 지표를 추적·관리하는 모듈입니다. Tier 2부터 활성화되며, 태그 시스템과 연동되어 동작합니다.
호감도, 신뢰도
대화 내용에 따라 ±값으로 자동 변화. Sensor 태그와 연동
커스텀 지표
피로도, 체력, 밀당지수 등 서비스별 커스텀 스탯 정의 가능
StateChangeProcessor
AI 응답 후 StateChangeProcessor가 스탯을 업데이트하고 세션에 영속
AI 말투 자동 조정
호감도 임계값에 따라 AI의 말투와 반응 방식이 자동으로 변화
Lorebook / World
키워드 트리거 기반 세계관 데이터를 AI 컨텍스트에 동적으로 주입하는 모듈입니다. Tier 2는 Lorebook 기본, Tier 3는 DNM Living World 전체가 활성화됩니다.
Lorebook (Tier 2)
키워드가 대화에 등장하면 관련 세계관 항목이 자동으로 AI 컨텍스트에 삽입됩니다. 세계관 일관성을 AI가 임의로 판단하지 않아도 됩니다.
Living World (Tier 3)
DNM 전체 기능이 활성화됩니다. 장소별 세계관, 날씨·시간 시뮬레이션, 실시간 지도 확장, NPC 행동 패턴까지 AI에 전달됩니다.
Narrative OS
대화 기록 전체를 읽는 대신, 현재 상황에 필요한 세계관 데이터만 정확히 AI에 전달합니다. 응답 속도와 일관성이 동시에 향상됩니다.
Memory / Context
AI가 이전 대화를 기억하고 일관된 캐릭터를 유지하기 위한 다층 메모리 시스템입니다.
| 레벨 | 이름 | 티어 | 설명 |
|---|---|---|---|
| Session | 세션 내 기억 | Tier 0+ | 현재 대화 세션 내의 컨텍스트 유지. 세션 종료 시 초기화 |
| L1 | 단기기억 | Tier 1+ | 최근 N개 세션의 핵심 이벤트 저장. 캐릭터와의 관계 지속성 유지 |
| L2 | 중기 요약 | Tier 2+ | 장기 대화 요약 압축 저장. 스탯 변화 기록 포함 |
| L3 | GraphContext | Tier 3 | 관계 그래프 기반 장기기억. 캐릭터 간 관계, 세계관 이벤트 이력 영속 저장 |
Realtime Hooks
AI 응답 전·후 처리 파이프라인에 커스텀 로직을 삽입할 수 있는 Tier 3 전용 기능입니다. 플러그인 오케스트레이터와 연동되어 동작합니다.
프롬프트 주입
AI 요청 전 컨텍스트에 데이터를 추가하거나 프롬프트를 동적으로 수정
응답 후처리
AI 응답 파싱, 태그 추출, 상태 업데이트를 커스텀 로직으로 처리
우선순위 큐
Travel(100), Time(110), Affinity(120), Location(130) 순으로 실행 제어
실시간 이벤트
외부 API 연동, 알림 발송, 지도 확장 트리거 등 서비스별 커스텀 이벤트
Ability System
AI 캐릭터에 특수 능력을 부여하는 모듈입니다. 타로, 사주 등 도메인 특화 능력을 독립 모듈로 분리해 조합합니다.
tarot Ability
78장 타로 카드 기반 운세 로직. ability: "tarot"로 활성화. OZO의 타로 캐릭터에 사용
saju Ability
사주명리 기반 운세 로직. 생년월일 입력 후 오늘의 흐름과 주의점을 캐릭터 말투로 전달
커스텀 Ability
Tier 2+에서 복수 Ability 조합 가능. 서비스별 도메인 로직을 독립 능력 모듈로 정의해 적용
| Ability | 티어 | 구현 방식 | 서비스 예시 |
|---|---|---|---|
ability: "tarot" |
Tier 0+ | 타로 전용 AI 로직 + 응답 체계 | OZO 타로 캐릭터 |
ability: "saju" |
Tier 0+ | 사주 전용 데이터 파이프라인 | OZO 사주 캐릭터 |
| 커스텀 (복수) | Tier 2+ | 독립 능력 모듈 조합 | 서비스별 정의 |
Engine Architecture
Cheez Chat API는 DDD(Domain-Driven Design) 4계층 아키텍처로 설계되었습니다. 각 계층이 명확히 분리되어 테넌트 독립성과 확장성을 보장합니다.
Presentation Layer
아이소메트릭 뷰와 유저 인터페이스를 통해 몰입형 시각화를 제공합니다.
Application Layer
사용자 대화와 이벤트를 오케스트레이션하여 서사의 흐름을 제어합니다.
Infrastructure Layer
데이터 영속성, 외부 AI 서비스 연동 및 기상 시뮬레이션을 처리합니다.
Domain Layer
엔티티와 도메인 서비스를 통해 세계관의 핵심 규칙과 인과율을 보장합니다.
실행 흐름
사용자 메시지가 처리되는 전체 과정 — 입력부터 응답까지 6단계.
사용자 입력
메시지 입력 및 전송. B2B 클라이언트 앱이 REST API 호출
컨텍스트 수집
Repository를 통해 캐릭터·세션·대화 기록·세계관 데이터 로드
플러그인 실행
우선순위에 따라 18개 플러그인 실행. Persona·Style·Sensor·Lorebook 적용
AI 응답 생성
Narrative OS 방식으로 구성된 프롬프트를 AI 모델(Gemini/Claude)에 전달
상태 변경 처리
StateChangeProcessor가 호감도·스탯·세계관 상태를 업데이트하고 영속
응답 반환
갱신된 세계 상태 + parsedTags + parsedSegments와 함께 클라이언트에 반환
프롬프트 섹션 우선순위
| 섹션 | Priority | 내용 |
|---|---|---|
| CORE_IDENTITY | 100 | 캐릭터 핵심 정체성 (Persona Engine 결과) |
| CHARACTER_INFO | 90 | 외모, 배경, 말투 등 구조화 필드 |
| CONTEXT | 80 | 현재 세션 상태, 스탯, 감정 상태 |
| LOCATION | 70 | 현재 위치, Lorebook 트리거 결과 |
| RELATIONSHIPS | 60 | 캐릭터 관계도, 메모리 요약 |
| RULES | 50 | 금지 행동, 스타일 가이드, 안전 필터 |
도입 문의
Cheez Chat API 도입 문의, PoC, 견적 요청은 아래 이메일로 연락해 주세요.
티어별 기능 상담, 커스텀 Ability 개발, 엔터프라이즈 계약 모두 가능합니다.