Dialogue Manager API¶

이 폴더는 Graph Builder를 HTTP로 사용하는 client를 위한 문서입니다.

실제 요청·응답 예제: Endpoints
모든 field와 기본값: Schemas
API에서 runtime까지의 흐름: Schema Flow

내부 Policy나 class 구조는 Graph Builder Runtime에서 분리해 설명합니다.

기본 정보¶

개발 서버:

python -m dm.api.app --host 0.0.0.0 --port 59212

기본 URL:

http://localhost:59212

환경에 따라 reverse proxy가 /dm prefix를 추가할 수 있습니다. 실제 OpenAPI의 /docs 또는 배포 route를 먼저 확인합니다.

일반 호출 순서¶

sequenceDiagram
    participant C as Client
    participant API as FastAPI
    participant DM as DialogManager
    participant DST as DSTManager

    C->>API: POST /v1/session 또는 /v1/session/json
    API->>DM: session 설정 + user context
    DM->>DST: DialogueState 생성
    DST-->>C: session_id + initial response

    loop 대화
        C->>API: POST /v1/message
        API->>DM: text + STT confidence
        DM->>DST: process_turn
        DST-->>C: response + node + turn_count
    end

    C->>API: GET /v1/session/{session_id}
    API-->>C: 현재 state와 TTL

Endpoint 역할¶

Endpoint	역할	상세
`POST /v1/session`	등록된 Scenario 이름으로 session 생성	Session 생성
`POST /v1/session/json`	요청의 Scenario JSON으로 session 생성	JSON Session
`POST /v1/session/validate`	Scenario 구조 검증	Validation
`POST /v1/message`	session의 다음 사용자 턴 처리	Message
`GET /v1/session/{session_id}`	현재 session 상태 조회	Session 조회
`GET /`	Service 이름과 version 확인	서비스 정보

Session 생성에서 결정되는 값¶

Session 생성 요청은 다음 runtime 설정을 고정합니다.

Scenario와 bot-first 여부
NLG/NLU model과 사용자 system prompt
사용자 위치·locale·timezone·profile
max_fallback_retries
stt_confidence_threshold
종료 payload에 slot/history를 포함할지 여부

정확한 field type과 기본값은 Schemas를 기준으로 합니다.

Message 처리에서 사용하는 값¶

현재 runtime이 직접 사용하는 값:

Field	역할
`session_id`	처리할 session 선택
`message_input.text`	사용자 발화
`message_input.confidence`	session의 STT threshold와 비교

현재 schema에는 있지만 대화 처리에 사용하지 않는 값:

user_input
message_input.duration
message_input.emotion
message_input.requery_required
message_input.requery_context

이 구분은 Schemas의 Consumed 열에서 유지합니다.

STT confidence 주의사항¶

message_input.confidence <= session.stt_confidence_threshold
→ LLM NLU 생략
→ not_understood fallback

Session API threshold 기본값은 -0.7입니다.
MessageInput.confidence 기본값은 0.0입니다.
비교는 경계값을 포함합니다.
Threshold가 0이면 confidence를 생략한 message도 fallback됩니다.

여기서 message_input.confidence는 client가 보낸 STT 인식 신뢰도입니다. LLM 또는 규칙 NLU가 산출하는 NLUResult.confidence와 다른 값이며, API에는 NLU confidence를 직접 보내는 field가 없습니다. STT gate를 통과한 뒤에만 규칙 NLU 또는 LLM NLU가 별도의 NLU confidence를 만듭니다.

Fallback 표현과 turn count 규칙은 Policy, API payload 예제는 Endpoints를 참고합니다.

빈 message_input.text도 schema와 route는 허용합니다. Runtime은 이를 no_input으로 분류하고 고정 responses.no_input을 바로 반환하지 않고 현재 대화 문맥으로 LLM 문장을 생성합니다. 선언 문구와 코드 기본 문구는 LLM 실패 시 fallback입니다.

Session 저장과 동시성¶

API의 DialogManager, session 설정, graph runtime, 기본 ContextStore는 Python process 내부 메모리에 있습니다. 같은 session의 생성·turn·조회·completion option 조회는 session별 RLock으로 직렬화되지만 lock과 저장 데이터는 worker/Pod 사이에 공유되지 않습니다. 현재 API는 use_redis=false이며 process 재시작 후 session을 복구할 수 없습니다.

DialogueState의 기본 TTL은 저장할 때마다 3,600초로 갱신되지만 background cleanup scheduler는 없습니다. 만료 state는 load/info/list 또는 명시적 cleanup 때 제거됩니다. 반면 session 설정의 24시간 TTL 정리와 graph runtime 정리는 자동으로 함께 실행되지 않으므로, TTL을 완전한 session lifecycle 보장으로 해석하면 안 됩니다. 자세한 내용은 Memory를 참고합니다.

session_complete=true는 state 표시이지 /v1/message를 거부하는 transport guard가 아닙니다. 완료된 session ID로도 후속 message가 처리되며, terminal node의 재개 transition이 맞으면 current_node가 다른 node로 이동할 수 있습니다. 다만 현재 일반 runtime은 이때 is_complete를 false로 되돌리지 않으므로 완료 표시는 유지되고 final_data도 다시 생성될 수 있습니다. Client는 완료 응답 뒤 전송을 중단해야 합니다.

Response를 읽는 기준¶

일반 message response의 핵심 field:

Field	의미
`session_id`	현재 session
`response`	사용자에게 전달할 봇 문장
`current_node`	이번 턴 transition까지 적용한 다음 node
`turn_count`	fallback 재시도를 제외한 논리적 turn 수
`processing_time_ms`	server 처리 시간
`session_complete`	대화 완료 여부
`final_data`	완료 시 선택적으로 포함되는 slot/history

내부 details, 전체 context와 error detail은 public message response에서 제거됩니다. 전체 response schema는 Schemas를 참고합니다.

단, GET /v1/session/{session_id}는 별도의 운영용 조회 contract로 현재 slots와 내부 context를 그대로 반환합니다. 인증 middleware가 없으므로 public client에 직접 노출하지 말고 신뢰된 backend 경계에서만 사용해야 합니다.

오류 확인 순서¶

HTTP status를 확인합니다.
JSON body의 error, status, detail을 확인합니다.
Session이 존재하는지 GET /v1/session/{session_id}로 확인합니다.
Skill fallback이면 Graph Builder와 Skill Runtime 양쪽 로그를 확인합니다.

Scenario validation 실패는 transport 오류와 다를 수 있습니다. Endpoint별 status와 예외 형태는 Endpoints의 오류 예제를 기준으로 합니다.

OpenAPI¶

서버 실행 후:

http://localhost:59212/docs

정적 OpenAPI JSON 생성:

python scripts/openapi.py --output-path docs/api/openapi.json

문서 역할¶

파일	소유하는 정보
`README.md`	API 시작점, lifecycle, 문서 탐색
`endpoints.md`	Endpoint별 실행 가능한 요청·응답 예제
`schemas.md`	Field type, default, validation, consumed 여부
`schema_flow.md`	API model이 내부 runtime과 Skill payload로 변환되는 과정

같은 payload를 여러 문서에 복제하지 않습니다. 호출 예제는 endpoints.md, field 정의는 schemas.md를 수정합니다.