vpd-permission-poc/poc4_active_source_20260714/SOURCE_README.md

HMM AI 업무 에이전트 소스

생성일: 2026-07-14 GMT

이 폴더는 HMM AI 업무 에이전트 실행 소스다. poc4라는 디렉터리·환경변수 접두어는 기존 배포 호환성을 위한 레거시 경로이며, 서비스의 정식 이름은 HMM AI 업무 에이전트다.

Entrypoint

streamlit run apps/poc4/mcp_discovery_ui.py --server.address 0.0.0.0 --server.port 8622

Runtime

• Python 3.11 이상을 사용합니다.
• 이 개발 서버의 기본 python3가 3.6 계열이면 문법 검증이 실패합니다.
• 배포 서버는 /opt/hmm-poc4/.venv와 Python 3.11을 사용합니다.
• OCI Generative AI SDK 인증은 배포 서버의 /home/opc/.oci/config DEFAULT profile을 사용합니다. private key와 compartment OCID는 Git에 저장하지 않고 서버의 ~/.oci와 .env에서만 관리합니다.

Deployment DB reference

• VPD 개발본 배포 서버의 DB 접속 정보는 /home/opc/kbmcp/.env를 사용합니다.
• DB wallet directory는 /home/opc/wallet/kbaipoc를 사용합니다.
• 이 저장소에는 wallet 파일, DB password, wallet password, 실제 VPD token 원문을 넣지 않습니다.

Included

• apps/poc4/mcp_discovery_ui.py
• src/agent_console/presentation.py
• src/agent_console/profile.py
• src/mcp_tool_router.py
• src/oci_genai_sdk.py
• src/poc3/model_registry.py
• src/poc3/questions.py
• config/mcp_servers.json
• config/poc3_model_profiles.json
• config/vpd_token_presets.json
• config/hmm_demo_scenarios.json — 화면에 표시할 데모 질문. 코드 수정 없이 이 파일만 변경한다.
• config/app_profile.json — 제품명, 문구, 아이콘, 색상을 지정하는 제품 profile
• .env.sample
• requirements.txt
• requirements-langgraph.txt
• scripts/poc4/start_8622_langgraph_tc_ui_nohup.sh
• scripts/poc4/status_8622_langgraph_tc_ui_nohup.sh

Security note

• 실제 .env는 복사하지 않았습니다. .env.sample을 기준으로 새로 만드세요.
• config/vpd_token_presets.json은 파일명 호환성을 유지한 HMM 데모 사용자 목록입니다. 사용자별 mcp_token_env는 배포 환경의 HMM_MCP_BEARER_TOKEN만 참조하며, token 원문은 JSON·Git에 저장하지 않습니다.
• 대화 DB data/poc4_mcp_chat.sqlite3는 개인정보/대화 내용이 포함될 수 있어 복사하지 않았습니다.
• MCP 호출 상세의 JSON/code 영역은 공통 presentation CSS에서 밝은 배경과 어두운 글자를 함께 지정합니다.

구성 원칙

• config/: 운영자가 바꿀 수 있는 MCP, 모델, HMM 데모 사용자 preset, 데모 질문 JSON
• src/poc4/: Streamlit과 분리 가능한 화면 보조 모듈 및 도메인 로직
• apps/poc4/: 레거시 호환 entrypoint. 화면 조립과 사용자 상호작용만 담당하도록 점진적으로 축소
• tests/: 설정 파일과 순수 Python 모듈의 회귀 검증

다른 프로젝트에 적용할 때는 scenario/MCP JSON만 교체하고, 제품명·설명·색상은 AGENT_CONSOLE_* 환경변수로 지정합니다. 환경변수가 없을 때만 config/app_profile.json의 중립 기본값을 사용합니다.