Sohri Graph Builder¶

Scenario v2 JSON을 실행해 NLU, 대화 상태, Policy, 응답 생성과 node routing을 처리하는 Dialogue Manager 런타임입니다.

처음 읽기: docs/README.md
현재 런타임 구조: docs/graph_builder/README.md
API 연동: docs/api/README.md
Scenario 작성: docs/scenario/guideline.md
시나리오 생성: docs/generator/README.md
배포·운영: docs/deploy/README.md

빠른 시작¶

설치¶

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

개발과 테스트 의존성:

python -m pip install -r requirements-dev.txt

기본 환경변수¶

프로젝트 루트의 .env 또는 현재 shell에 설정합니다.

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
CORE_DEFAULT_LLM=gpt-4o
CORE_NLU_LLM=gpt-4o-mini

Azure OpenAI를 사용하는 기존 환경은 다음 변수를 사용할 수 있습니다.

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_KEY=your-api-key
AZURE_OPENAI_VERSION=2024-12-01-preview

전체 환경변수와 Skill Runtime 설정은 배포 문서와 Skill Runtime 문서를 참고합니다.

CLI 실행¶

프로젝트 루트에서 실행합니다.

python -m cli.chatbot --scenario dm/scenario/senimate.json

자주 사용하는 명령:

# 턴 상세 정보
python -m cli.chatbot \
  --scenario dm/scenario/senimate.json \
  --output-level detailed

# Scenario 검증
python -m cli.chatbot \
  --scenario dm/scenario/senimate.json \
  --validate-only

# Node 목록
python -m cli.chatbot \
  --scenario dm/scenario/senimate.json \
  --list-nodes

# 특정 node에서 반복 테스트
python -m cli.chatbot \
  --scenario dm/scenario/senimate.json \
  --node daily_life_check \
  --output-level detailed

Validation은 JSON/그래프 구조뿐 아니라 Runtime이 소비하지 않는 params 키도 거부합니다. 예를 들어 free_conversation은 지원하지 않으므로 제거해야 합니다. 허용 목록은 dm/graph/scenario_contract.py에서 관리합니다.

주요 CLI 옵션¶

옵션	기본값	역할
`--scenario <path>`	필수	실행할 Scenario JSON
`--output-level <level>`	`compact`	`chat`, `compact`, `detailed`, `debug`
`--llm-choice <model>`	`CORE_DEFAULT_LLM`	NLG model
`--nlu-llm-choice <model>`	`CORE_NLU_LLM`	NLU model
`--max-fallback-retries <count>`	node 또는 `3`	세션 fallback 재시도 override
`--stt-confidence-threshold <score>`	`0`	세션 STT fallback 기준
`--locale <locale>`	빈 값	세션 사용자 locale
`--date-time <ISO 8601>`	서버 현재 일시	날짜 기반 Skill에 전달할 일시
`--location <place>`	빈 값	문자열 위치
`--latitude`, `--longitude`	빈 값	WGS84 좌표. 반드시 함께 입력
`--completion-history`	비활성	종료 payload에 전체 대화 포함
`--redis`	비활성	Redis context store 사용
`--bot-first`	Scenario 설정	봇 선행 발화 강제
`--validate-only`	비활성	검증 후 종료
`--node <node_id>`	빈 값	특정 node 집중 테스트

전체 옵션과 진단 방법은 검증과 테스트를 기준으로 관리합니다.

Skill 시나리오 테스트¶

senimate_weather.json(위치 기반 날씨)과 senimate_days.json(공휴일·절기)은 greeting node에서 Skill Runtime을 호출합니다. 그래프만 확인할 때는 --validate-only로 충분하고, 실제 Skill 응답을 보려면 SKILL_RUNTIME_BASE_URL이 필요합니다.

# 그래프 검증
python -m cli.chatbot \
  --scenario dm/scenario/senimate_weather.json \
  --validate-only

python -m cli.chatbot \
  --scenario dm/scenario/senimate_days.json \
  --validate-only

# Node 목록
python -m cli.chatbot \
  --scenario dm/scenario/senimate_weather.json \
  --list-nodes

python -m cli.chatbot \
  --scenario dm/scenario/senimate_days.json \
  --list-nodes

호스트에서 Skill까지 포함해 대화 테스트하는 예입니다. 9213은 별도 Skill Runtime 배포가 해당 포트를 공개한 환경을 가정합니다.

# 위치 기반 날씨
SKILL_RUNTIME_BASE_URL=http://localhost:9213 \
python -m cli.chatbot \
  --scenario dm/scenario/senimate_weather.json \
  --locale ko-KR \
  --latitude 37.5172 \
  --longitude 127.0473 \
  --output-level detailed

# 날짜 기반 공휴일·절기
SKILL_RUNTIME_BASE_URL=http://localhost:9213 \
python -m cli.chatbot \
  --scenario dm/scenario/senimate_days.json \
  --locale ko-KR \
  --date-time 2026-08-15T09:00:00+09:00 \
  --output-level detailed

동일한 Docker network의 container에서는 내부 DNS를 사용합니다.

export SKILL_RUNTIME_BASE_URL=http://sohri-skill-runtime:59213

--location과 좌표 옵션은 동시에 사용할 수 없습니다. --date-time을 생략하면 서버 현재 일시를 사용합니다. 자세한 연결 조건과 오류 확인은 Skill 사용 가이드를 참고합니다.

API 서버¶

python -m dm.api.app

옵션 지정:

python -m dm.api.app \
  --host 0.0.0.0 \
  --port 59212 \
  --reload \
  --log-level debug

주요 endpoint:

POST /v1/session: 등록된 Scenario로 session 생성
POST /v1/session/json: 요청의 Scenario JSON으로 session 생성
POST /v1/message: 사용자 메시지 처리
GET /v1/session/{session_id}: session 상태 조회
POST /v1/session/validate: Scenario JSON 검증
GET /: Service 이름과 version 조회

Payload와 응답 계약은 API 문서에서 설명합니다.

STT confidence와 fallback¶

API의 message_input.confidence가 session의 stt_confidence_threshold 이하이면 일반 LLM NLU를 생략하고 이해 불가 fallback으로 처리합니다.

중요한 차이:

API session threshold 기본값: -0.7
CLI session threshold 기본값: 0
API MessageInput.confidence 기본값: 0.0
키보드 CLI 입력은 confidence를 전달하지 않으므로 STT gate를 적용하지 않음

Threshold를 0으로 설정한 API session에서 confidence를 생략하면 0.0 <= 0이므로 fallback됩니다. 정확한 counter, 재질문과 turn count 규칙은 Policy에서만 상세히 설명합니다.

no_input과 not_understood에서 Scenario response를 고정 출력하지 않습니다. FallbackPolicy가 전체 맥락으로 LLM 응답을 만들고, responses.no_input/responses.not_understood는 LLM 호출 실패 시에만 안전망으로 사용합니다. 재시도 예산 소진은 Policy의 직접 종료가 아니라 graph routing으로 처리됩니다.

테스트¶

# 전체 테스트
python -m pytest dm/tests

# 특정 파일
python -m pytest dm/tests/test_skill_runtime_client.py

# 상세 출력
python -m pytest dm/tests -v

배포 계약 요약¶

GCP development는 외부 Cloud Build trigger가 cloudbuild.yaml을 실행해 image와 deploy/values-dev.yaml tag를 갱신하는 구조입니다.
Production trigger와 GCP Argo CD sync policy는 이 저장소에서 보장하지 않습니다. 현재 GCP용 수동 GitHub Actions fallback workflow도 없습니다.
On-prem workflow는 image를 push하고 외부 mago-onprem-infra/main의 서비스별 image.yaml을 갱신합니다. Kubernetes sync는 관리자가 수행합니다.
Session runtime이 process memory에 있으므로 Helm validation은 replica 1과 multi-replica HPA 금지를 강제합니다.

현재 제한과 workflow/test 불일치는 배포 가이드를 확인합니다.

HTML 문서 사이트¶

python -m pip install -r requirements-docs.txt
python scripts/build_docs_site.py

기본 출력 경로:

/home/galois/mago-services/www/sohri/graph_builder

www/sohri는 여러 Sohri 구성 요소가 함께 사용하는 상위 문서 공간입니다. 이 빌드는 graph_builder 하위 폴더만 정리하며 Skill Runtime 등 다른 구성 요소의 형제 폴더는 변경하지 않습니다.

HTML에서도 저장소 구조를 유지합니다.

www/sohri/
├── index.html
└── graph_builder/
    ├── index.html             # 저장소 README
    └── docs/
        ├── index.html         # docs/README.md
        ├── api/
        ├── graph_builder/
        ├── scenario/
        ├── generator/
        ├── skills/
        └── deploy/

8180 포트로 제공합니다.

python -m http.server 8180 \
  --bind 0.0.0.0 \
  --directory /home/galois/mago-services/www

다른 PC에서는 다음 주소로 접속합니다.

http://<서버-IP>:8180/sohri/
http://<서버-IP>:8180/sohri/graph_builder/
http://<서버-IP>:8180/sohri/graph_builder/docs/

프로젝트 구조¶

sohri-graph-builder/
├── cli/                 # 대화형 CLI
├── dm/
│   ├── api/             # FastAPI routes와 schema
│   ├── core/            # DST, NLU, policy, executor, transition
│   ├── scenario/        # Scenario JSON
│   ├── service/         # DialogManager
│   ├── skills/          # Skill Runtime HTTP contract
│   ├── storage/         # Context store
│   └── tests/           # Test suite
├── docs/                # 역할별 기술 문서
├── deploy/              # Helm과 배포 설정
└── scripts/             # 문서·검증·simulation 도구

문서 기준¶

필요한 내용	기준 문서
프로젝트 설치·실행	이 README
전체 문서 탐색	`docs/README.md`
현재 runtime 내부 계약	`docs/graph_builder/`
HTTP 계약	`docs/api/`
Scenario 작성	`docs/scenario/`
시나리오 생성	`docs/generator/`
Skill 사용	`docs/skills/`
배포·운영	`docs/deploy/`
과거 설계 결정	`docs/refactor/`