Sohri Graph Builder 문서¶

이 페이지는 Graph Builder 문서의 시작점입니다. 필요한 정보에 바로 도달할 수 있도록 독자와 목적별로 문서를 나눕니다.

현재 동작은 docs/graph_builder/, API 계약은 docs/api/, 시나리오 작성 규칙은 docs/scenario/가 각각 기준 문서입니다. docs/refactor/는 변경 당시의 판단을 보존하는 역사 문서이므로 현재 동작의 기준으로 사용하지 않습니다.

Graph Builder가 하는 일¶

시나리오 JSON에 node·slot·전이를 적으면, 런타임이 한 턴마다 다음을 실행합니다.

사용자 입력 → STT confidence gate → NLU → Global Policy (Safety, Fallback)
  → Executor / NLG → Post Policy → 상태 반영 → TransitionEngine → 저장

세션이 bot first이면 이 파이프라인 없이 시작 node의 첫 봇 발화를 먼저 보냅니다. 주제 이탈로 노드를 붙잡지 않습니다. 슬롯에 넣을 값이 없으면 entities를 비우고 진행합니다. 무응답과 이해 불가 응답은 LLM이 맥락에 맞게 생성하며, node의 responses.no_input/not_understood는 LLM 실패 안전망입니다.

무엇을 하시나요?¶

처음 프로젝트를 이해합니다¶

API를 연동합니다¶

시나리오를 작성하거나 수정합니다¶

예제:

SeniMate: 일상·식사·건강 대화
Card Issuance: required slot 기반 업무 흐름
General Conversation: slot 없는 자유 대화

런타임 코드를 수정합니다¶

Graph Builder 런타임 문서 홈
Architecture
DSTManager
수정 계층에 따라 NLU, Policy, Executor, Transition, State
Testing

외부 Skill을 연동합니다¶

시나리오 작성자: Skill 사용 가이드
런타임 개발자: Skill Runtime 내부 연동

배포하고 운영합니다¶

현재 저장소에는 GCP 수동 fallback GitHub Actions workflow가 없고 production Cloud Build trigger/Argo CD 설정은 외부 인프라에 의존합니다. On-prem workflow는 외부 mago-onprem-infra/main의 image tag를 갱신하며 실제 sync는 관리자가 수행합니다. Session runtime은 process-local이므로 Chart는 replica 1을 강제합니다.

문서 영역과 역할¶

영역	기준으로 다루는 내용	다루지 않는 내용
`definition/`	대화 시스템과 Graph Builder의 기초 개념	현재 코드의 세부 실행 순서
`graph_builder/`	현재 런타임 구현과 내부 계약	API 사용 예제, 변경 이력
`api/`	외부 HTTP 계약과 데이터 흐름	내부 클래스별 구현 설명
`scenario/`	Scenario v2 작성 규칙과 실제 예제	공통 runtime 구현
`generator/`	자연어 설명으로 Scenario JSON 생성	런타임 내부 실행 순서
`skills/`	시나리오에서 외부 Skill을 사용하는 방법	HTTP client 내부 구현
`deploy/`	빌드·배포·운영 절차	대화 정책 설계
`refactor/`	과거 문제와 변경 결정의 기록	현재 구현 계약
`release_notes.md`	릴리스별 사용자 영향 변경	상세 설계 설명

현재 구현의 핵심 흐름¶

flowchart LR
    CLIENT["CLI / API"] --> DM["DialogManager"]
    DM --> DST["DSTManager"]
    DST --> NLU["NLU"]
    NLU --> POLICY["Policy"]
    POLICY --> EXEC["Executor"]
    EXEC --> UPDATE["State Update"]
    UPDATE --> ROUTE["TransitionEngine"]
    ROUTE --> SAVE["State Save"]
    SAVE --> CLIENT

세부 흐름은 Architecture에서 설명합니다.

자주 찾는 항목¶

질문	문서
CLI 옵션과 실행 방법은?	프로젝트 README
API session/message payload는?	API Endpoints
STT confidence fallback은?	Policy
no_input/not_understood 문구는 어떻게 선택하나요?	FallbackPolicy
fallback counter와 turn count는?	Dialogue State
node가 왜 이동했나요?	Transition
slot을 어떻게 정의하나요?	Scenario 작성 가이드
말로 시나리오 JSON을 만들려면?	시나리오 생성기
날씨 Skill은 어떻게 호출하나요?	Skill 사용 가이드
테스트는 어떻게 실행하나요?	Testing

문서 유지 원칙¶

하나의 사실은 한 기준 문서에서만 자세히 설명합니다.
다른 문서에서는 요약 후 기준 문서로 연결합니다.
현재 구현과 과거 설계 기록을 섞지 않습니다.
코드 변경 시 해당 역할을 소유한 문서를 먼저 갱신합니다.
명령은 실행 환경과 필수 환경변수를 함께 적습니다.
기본값, 경계 조건, 예외 동작은 테스트와 같은 의미로 기록합니다.

구현과 문서가 충돌하면 다음 순서로 확인합니다.

현재 코드와 테스트
docs/graph_builder/, docs/api/, docs/scenario/
docs/release_notes.md
docs/refactor/