whatap-python 2.2.1rc1__tar.gz → 2.3.0rc3__tar.gz

{whatap_python-2.2.1rc1 → whatap_python-2.3.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whatap-python
-Version: 2.2.1rc1
+Version: 2.3.0rc3
 Summary: Monitoring and Profiling Service
 Home-page: https://www.whatap.io
 Author: whatap

{whatap_python-2.2.1rc1 → whatap_python-2.3.0rc3}/setup.py

@@ -20,7 +20,9 @@ setup(name=build.name,
       url='https://www.whatap.io',
       packages=find_packages(exclude=('sample','sample.*')),
       package_data={
-          'whatap': ['LICENSE', '*.rst', '*.conf', '*.json', 'agent/*/*/whatap_python', 'agent/windows/*.exe']
+          'whatap': ['LICENSE', '*.rst', '*.conf', '*.json', 'agent/*/*/whatap_python', 'agent/windows/*.exe',
+                     'skills/whatap-python-install/*.md',
+                     'skills/whatap-python-install/references/*.md']
       },
       entry_points={
           'console_scripts': [
@@ -28,6 +30,8 @@ setup(name=build.name,
               'whatap-stop-agent=whatap.scripts:stop_agent',
               'whatap-setting-config=whatap.scripts:setting_config',
               'whatap-llm-setting-config=whatap.scripts:llm_setting_config',
+              'whatap-doctor=whatap.doctor:main',
+              'whatap-install-agent-guide=whatap.scripts:install_agent_guide',
 
               'whatap-start-batch-agent=whatap:start_batch_agent',
           ],

{whatap_python-2.2.1rc1 → whatap_python-2.3.0rc3}/whatap/__init__.py

@@ -378,11 +378,20 @@ def _is_instrumentation_ignored(definition_key, ignore_set):
 def hooks(home):
     ignore_set = _build_ignore_instrumentation_set()
     skipped_keys = []
+    # LLM 계측은 llm_enabled 일 때만 **등록**한다. instrument_* 함수들도 각자
+    # llm_enabled 를 보고 되돌아가지만, 등록만 해둬도 대상 모듈이 로드되는 순간
+    # import 훅이 ``whatap.llm.*`` 서브트리를 통째로 끌어온다 — 켜지도 않은 기능
+    # 때문에. ``botocore.client``(Bedrock) 처럼 LLM 과 무관한 앱도 흔히 쓰는 모듈이
+    # 대상에 들어오면서 이 비용이 실제로 문제가 된다.
+    # conf.init() 이 hooks() 보다 먼저 돌므로 여기서 llm_enabled 는 이미 확정이다.
+    llm_enabled = bool(getattr(conf, 'llm_enabled', False))
     try:
         for key, value_list in DEFINITION.items():
             if _is_instrumentation_ignored(key, ignore_set):
                 skipped_keys.append(key)
                 continue
+            if key.startswith('llm.') and not llm_enabled:
+                continue
             for value in value_list:
                 if len(value) >= 3 and isinstance(value[2], str):
                     module_path = value[2]
@@ -553,9 +562,13 @@ def agent():
                 llm_accesskey = (preview_whatap_conf("llm_accesskey")
                                  or os.environ.get("llm_accesskey"))
                 if llm_accesskey:
-                    t = threading.Thread(target=go, kwargs={'llm': True})
-                    t.setDaemon(True)
-                    t.start()
+                    if sys.platform.startswith('linux'):
+                        # APM 과 같은 이유로 소유 기록까지 호출 스레드에서 끝낸다.
+                        go(llm=True)
+                    else:
+                        t = threading.Thread(target=go, kwargs={'llm': True})
+                        t.setDaemon(True)
+                        t.start()
                 else:
                     whatap_print("WHATAP: llm_enabled=true 이나 llm_accesskey 가 "
                                  "없어 LLM 에이전트 기동을 건너뜁니다")
@@ -569,31 +582,89 @@ ARCH = {
     'ARM': 'arm',
     'AArch64': 'arm64',
     'arm64': 'arm64',
-    'aarch64': 'arm64'
+    'aarch64': 'arm64',
+    # Windows 의 platform.machine() 은 **대문자**로 돌려준다('AMD64'/'ARM64').
+    # Windows 는 arch 하위 디렉토리를 쓰지 않아 지금은 이 표를 안 타지만, 빠져 있으면
+    # 누가 조회하는 순간 KeyError 로 기동이 통째로 죽는 종류의 구멍이라 채워 둔다.
+    'AMD64': 'amd64',
+    'ARM64': 'arm64',
+    'i386': '386',
 }
 
 AGENT_NAME = 'whatap_python'
 
 
+def agent_binary_name():
+    """OS 별 에이전트 실행 파일 이름."""
+    return AGENT_NAME + '.exe' if sys.platform == 'win32' else AGENT_NAME
+
+
+def llm_agent_reldir():
+    """LLM 전용 ``whatap_python`` 이 놓이는 ``$WHATAP_HOME`` 하위 상대경로.
+
+    Unix 계열은 ``<os>/<arch>`` (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64).
+    **Windows 는 arch 하위를 쓰지 않는다** — x64 하나면 ARM64 Windows 에서도 에뮬레이션
+    으로 돌아서 아키텍처별 빌드를 나눌 이유가 없다. 번들 APM 쪽
+    ``whatap/agent/windows/`` 가 평평한 것과 같은 이유이고, 같은 모양이다.
+
+    반환: ``(상대경로, 사유)``. 상대경로가 None 이면 사유에 왜 못 구하는지가 담긴다.
+    """
+    system = platform.system().lower()
+    if sys.platform == 'win32':
+        return system, ''
+    machine = platform.machine()
+    arch = ARCH.get(machine)
+    if not arch:
+        return None, ('unsupported architecture {0!r} for the LLM agent '
+                      '(known: {1})'.format(machine, ', '.join(sorted(set(ARCH.values())))))
+    return os.path.join(system, arch), ''
+
+
+def llm_agent_path():
+    """LLM 전용 ``whatap_python`` 의 배포 위치. @see ``llm_agent_reldir``
 
-def _native_agent_spec(opts):
-    from whatap.util.native_process import AgentSpec
-    source = os.path.join(os.path.dirname(__file__), 'agent', 'linux',
-                          ARCH[platform.machine()], AGENT_NAME)
+    반환: ``(경로, 사유)``. 경로가 None 이면 사유에 왜 못 쓰는지가 담긴다.
+    """
+    reldir, reason = llm_agent_reldir()
+    if reldir is None:
+        return None, reason
+    home_path = os.environ.get('WHATAP_HOME')
+    if not home_path:
+        return None, 'WHATAP_HOME is not set'
+    path = os.path.join(home_path, reldir, agent_binary_name())
+    if not os.path.exists(path):
+        return None, ('LLM agent binary not found: {0} '
+                      '(place the LLM {1} under $WHATAP_HOME/{2}/)'.format(
+                          path, agent_binary_name(), reldir.replace(os.sep, '/')))
+    return path, ''
+
+
+
+def _native_agent_spec(opts, llm_executable=None):
+    from whatap.util.native_process import APM, LLM, AgentSpec
+    if llm_executable:
+        # LLM 은 llm_agent_path() 의 전용 바이너리를 제자리에서 실행한다(@see _start_go).
+        source, mode = llm_executable, LLM
+    else:
+        source = os.path.join(os.path.dirname(__file__), 'agent', 'linux',
+                              ARCH[platform.machine()], AGENT_NAME)
+        mode = APM
     env = os.environ.copy()
     env.update(opts)
-    return AgentSpec(os.environ['WHATAP_HOME'], source, env)
+    return AgentSpec(os.environ['WHATAP_HOME'], source, env, mode=mode)
 
 
-def _native_agent_log_path():
-    return os.path.join(os.environ.get('WHATAP_HOME', '.'), 'logs', AGENT_NAME + '.log')
+def _native_agent_log_path(llm=False):
+    # LLM 은 별개 프로세스라 기동 실패 원인이 APM 로그와 섞이지 않게 나눈다.
+    name = AGENT_NAME + ('.llm.log' if llm else '.log')
+    return os.path.join(os.environ.get('WHATAP_HOME', '.'), 'logs', name)
 
 
-def _open_native_agent_log():
+def _open_native_agent_log(llm=False):
     # managed 경로는 PIPE 를 읽지 않으므로 네이티브 stdout/stderr 를 파일로 남겨
     # 기동 직후 실패 원인을 추적할 수 있게 한다.
     try:
-        log_path = _native_agent_log_path()
+        log_path = _native_agent_log_path(llm)
         os.makedirs(os.path.dirname(log_path), exist_ok=True)
         return open(log_path, 'ab')
     except Exception as e:
@@ -602,44 +673,61 @@ def _open_native_agent_log():
 
 
 def go(batch=False, opts={}, llm=False):
-    if sys.platform.startswith('linux') and not batch and not llm:
+    if sys.platform.startswith('linux') and not batch:
         from whatap.util.native_process import FAILED, ensure_agent_running
+        label = 'LLM' if llm else 'APM'
+        log_prefix = 'WHATAP_LLM_AGENT' if llm else 'WHATAP_AGENT'
+        llm_executable = None
+        if llm:
+            # 바이너리가 없으면 락·/proc 탐색 전에 기존처럼 건너뛴다.
+            llm_executable, reason = llm_agent_path()
+            if llm_executable is None:
+                whatap_error_log(
+                    'WHATAP: skipping LLM agent start — {0}'.format(reason),
+                    log_id='WHATAP_LLM_AGENT_UNAVAILABLE')
+                return
 
         def on_child_exit(pid, exit_code):
             whatap_error_log(
-                'WHATAP: native APM exited (PID: {}, exit code: {}, log: {})'.format(
-                    pid, exit_code, _native_agent_log_path()),
-                log_id='WHATAP_AGENT_EXITED')
+                'WHATAP: native {} exited (PID: {}, exit code: {}, log: {})'.format(
+                    label, pid, exit_code, _native_agent_log_path(llm)),
+                log_id=log_prefix + '_EXITED')
 
         try:
-            spec = _native_agent_spec(opts)
+            spec = _native_agent_spec(opts, llm_executable)
             result = ensure_agent_running(
                 spec, lambda: _start_go(batch, opts, llm, managed=True),
                 on_child_exit=on_child_exit)
             if result.status == FAILED:
-                whatap_error_log('WHATAP: native APM startup failed',
-                                 log_id='WHATAP_AGENT_START_FAILED')
+                whatap_error_log('WHATAP: native {} startup failed'.format(label),
+                                 log_id=log_prefix + '_START_FAILED')
             else:
-                whatap_print('WHATAP: native APM {} (PID: {})'.format(
-                    result.status, result.pid))
+                whatap_print('WHATAP: native {} {} (PID: {})'.format(
+                    label, result.status, result.pid))
         except Exception as e:
-            whatap_error_log('WHATAP: native APM startup failed: {}'.format(e),
-                             log_id='WHATAP_AGENT_START_FAILED')
+            whatap_error_log('WHATAP: native {} startup failed: {}'.format(label, e),
+                             log_id=log_prefix + '_START_FAILED')
         return
     return _start_go(batch, opts, llm)
 
 
 def _start_go(batch=False, opts={}, llm=False, managed=False):
-    # LLM 에이전트는 Linux/macOS 를 지원한다(전용 whatap_python 이
-    # $WHATAP_HOME/<os>/<arch> 에 배포됨 — linux/darwin × amd64/arm64).
-    # 그 외 OS(Windows 등)는 전용 바이너리가 없으므로 우회적 "binary not found"
-    # 대신 명시적으로 LLM 기동을 차단하고 알린다.
-    if llm and platform.system().lower() not in ('linux', 'darwin'):
-        whatap_error_log(
-            'WHATAP: LLM agent is supported on Linux/macOS only '
-            '(current OS: {0}); skipping LLM agent start'.format(platform.system()),
-            log_id='WHATAP_LLM_UNSUPPORTED_OS')
-        return
+    # LLM 에이전트는 전용 whatap_python 이 $WHATAP_HOME 하위에 따로 배포된다
+    # (unix 는 <os>/<arch>, windows 는 windows/ — @see llm_agent_reldir).
+    # **OS 로 막지 않는다** — 그 자리에 바이너리가 놓였는지로 판단한다(그래야 windows
+    # 빌드가 배포되는 순간 코드 변경 없이 살아난다).
+    #
+    # 여기서 미리 걸러야 하는 이유: 그냥 흘려보내면 배포 분기로 빠져 **번들 APM
+    # 바이너리**를 골라 ``--llm`` 으로 띄우고, 심지어 APM 과 같은
+    # ``$WHATAP_HOME/whatap_python`` 에 배포해 서로를 덮는다(둘은 다른 바이너리다).
+    llm_agent_cmd = None
+    if llm:
+        llm_agent_cmd, reason = llm_agent_path()
+        if llm_agent_cmd is None:
+            whatap_error_log(
+                'WHATAP: skipping LLM agent start — {0}'.format(reason),
+                log_id='WHATAP_LLM_AGENT_UNAVAILABLE')
+            return
 
     newenv=os.environ.copy()
     newenv['WHATAP_VERSION'] = build.version
@@ -700,24 +788,20 @@ def _start_go(batch=False, opts={}, llm=False, managed=False):
         home_path= os.environ.get(home)
 
         # Windows uses .exe extension
-        agent_binary_name = AGENT_NAME + '.exe' if sys.platform == 'win32' else AGENT_NAME
+        binary_name = agent_binary_name()
 
-        # LLM mode (Unix/Linux) runs a dedicated whatap_python binary that ships
-        # separately under $WHATAP_HOME/<os>/<arch>/ (e.g. $WHATAP_HOME/linux/amd64).
-        # It is executed in place from there rather than deployed from the bundled
-        # package into $WHATAP_HOME/whatap_python, which the APM agent uses (the two
-        # are now distinct binaries and would otherwise clobber each other).
-        run_in_place = llm and sys.platform != 'win32'
+        # LLM mode runs a dedicated whatap_python binary that ships separately under
+        # $WHATAP_HOME (unix: <os>/<arch>, windows: windows/ — @see llm_agent_reldir).
+        # It is executed in place from there rather than deployed
+        # from the bundled package into $WHATAP_HOME/whatap_python, which the APM
+        # agent uses (the two are distinct binaries and would otherwise clobber each
+        # other). **OS 로 가르지 않는다** — Windows 만 빼면 거기서 APM 바이너리를
+        # 골라 --llm 으로 띄우고 APM 의 배포 경로까지 덮어쓴다.
+        run_in_place = llm
 
         if run_in_place:
-            source_cwd = os.path.join(home_path, platform.system().lower(), ARCH[platform.machine()])
-            source_agent = os.path.join(source_cwd, agent_binary_name)
-            if not os.path.exists(source_agent):
-                raise FileNotFoundError(
-                    'LLM agent binary not found: {0} '
-                    '(place the LLM {1} under $WHATAP_HOME/{2}/{3}/)'.format(
-                        source_agent, agent_binary_name,
-                        platform.system().lower(), ARCH[platform.machine()]))
+            # 경로·존재 확인은 _start_go() 진입부의 llm_agent_path() 가 이미 했다(단일 소스).
+            source_agent = llm_agent_cmd
             # Ensure executable (best effort; ignore on read-only locations)
             if not os.access(source_agent, os.X_OK):
                 try:
@@ -726,7 +810,7 @@ def _start_go(batch=False, opts={}, llm=False, managed=False):
                     whatap_print('WHATAP: chmod LLM agent binary failed: %s' % e)
             agent_cmd = source_agent
         else:
-            dest_agent = os.path.join(home_path, agent_binary_name)
+            dest_agent = os.path.join(home_path, binary_name)
 
             # Try to remove existing binary
             # Windows: File may still be locked even after waiting, ignore error and use existing binary
@@ -753,7 +837,7 @@ def _start_go(batch=False, opts={}, llm=False, managed=False):
                 source_cwd = os.path.join(os.path.join(os.path.dirname(__file__), 'agent'), platform.system().lower(),
                                           ARCH[platform.machine()])
 
-            source_agent = os.path.join(source_cwd, agent_binary_name)
+            source_agent = os.path.join(source_cwd, binary_name)
 
             # Deploy agent binary only if needed
             if needs_deployment:
@@ -770,9 +854,9 @@ def _start_go(batch=False, opts={}, llm=False, managed=False):
 
             # Windows uses absolute path, Unix/Linux uses relative path
             if sys.platform == 'win32':
-                agent_cmd = os.path.join(home_path, agent_binary_name)
+                agent_cmd = os.path.join(home_path, binary_name)
             else:
-                agent_cmd = './{0}'.format(agent_binary_name)
+                agent_cmd = './{0}'.format(binary_name)
 
         sockfile_path = os.path.join(home_path, 'run')
         if not os.path.exists(sockfile_path):
@@ -833,7 +917,7 @@ def _start_go(batch=False, opts={}, llm=False, managed=False):
                                            creationflags=DETACHED_PROCESS,
                                            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
         elif managed:
-            go_out = _open_native_agent_log()
+            go_out = _open_native_agent_log(llm)
             try:
                 process = subprocess.Popen(cmd_args,
                                            cwd=home_path, env=newenv,
@@ -1188,6 +1272,26 @@ def _config_port():
 
 
 def configLlmPort():
+    if sys.platform.startswith('linux') and preview_whatap_conf('llm_enabled') == 'true':
+        # 바이너리가 없으면 go(llm=True) 도 건너뛰므로 지킬 LLM 에이전트가 없다.
+        llm_executable = llm_agent_path()[0]
+        if llm_executable:
+            from whatap.util.native_process import LLM, acquire_start_lock, configured_channel, find_existing_agent
+            try:
+                spec = _native_agent_spec({}, llm_executable)
+                with acquire_start_lock(spec):
+                    if find_existing_agent(spec):
+                        # configPort() 와 같은 계약: 살아 있는 LLM 에이전트의 채널을 다시 쓰지 않는다.
+                        return configured_channel(spec.home, spec.environment,
+                                                  include_unix=False, mode=LLM)[1]
+                    return _config_llm_port()
+            except Exception as e:
+                # 락 타임아웃/다중 인스턴스 등은 CLI 를 죽이지 말고 기존 포트 할당으로 폴백
+                whatap_print('WHATAP: live LLM agent check skipped, falling back to port file: %s' % e)
+    return _config_llm_port()
+
+
+def _config_llm_port():
     # force_llm_net_udp_port가 설정된 경우 lock 파일 무시하고 해당 포트 강제 사용
     force_port_str = preview_whatap_conf("force_llm_net_udp_port")
     if force_port_str and force_port_str not in ('false', 'False'):

whatap_python-2.3.0rc3/whatap/build.py

@@ -0,0 +1,4 @@
+app = 'Python'
+name = 'whatap-python'
+version = '2.3.0rc3'
+release_date = '20261111'

{whatap_python-2.2.1rc1 → whatap_python-2.3.0rc3}/whatap/conf/configuration.py

@@ -39,7 +39,7 @@ Configuration = {
     # 해당 메서드 실행이 워크플로우가 되고 내부 LLM 호출은 스텝. workflow_plugin 참조.
     "workflow_method_patterns": "",
     # 트랜잭션(서비스) 진입점으로 자동 래핑할 메서드 패턴 (module:Class.method, 콤마 구분).
-    # 해당 메서드 호출이 하나의 트랜잭션이 된다(= @method_profiling 의 conf 버전).
+    # 해당 메서드 호출이 하나의 트랜잭션이 된다(구 @method_profiling 데코레이터 대체).
     # 프레임워크 자동계측이 안 되는 진입점용. hook_service_patterns 모듈 참조.
     "hook_service_patterns": "",
 
@@ -144,6 +144,26 @@ Configuration = {
     # APM Go Agent 가 떠 있는 배포(apm_enabled=true)에서만 의미가 있다.
     "llm_apm_txn_enabled": False,
 
+    # ── LLM 계측 킬스위치 (문제 발생 시 에이전트 다운그레이드 없이 되돌릴 레버) ──
+    #
+    # **여기 등록돼 있어야 whatap.conf 의 false 가 먹는다.** ``Configure.setProperty`` 는
+    # 이 표에 bool 기본값이 있는 키만 문자열 'false' → False 로 강제 변환한다. 미등록 키는
+    # ``'false'`` 문자열로 남고 ``bool('false') == True`` 라 게이트가 계속 열려 있다
+    # (실측으로 확인: 등록 키는 False, 미등록 키는 'false'/truthy).
+    #
+    # llm_workflow_enabled : 워크플로우/에이전트 경계 계측 전체 (구 키 llm_trajectory_enabled
+    #                        와 AND — 어느 쪽을 false 로 줘도 꺼진다)
+    # mtrace_kanban_enabled: hermes 칸반 카드 경계 전파
+    # llm_thread_pool_propagation_enabled:
+    #                        Thread/ThreadPoolExecutor 컨텍스트 전파 몽키패치
+    # llm_httpc_step_enabled: 워크플로우 안의 httpc 스텝을 **전부** LLM 채널에도 싣는다
+    #                        (APM 쪽은 무관하게 그대로). false 면 LLM API httpc 만.
+    "llm_workflow_enabled": True,
+    "llm_trajectory_enabled": True,
+    "mtrace_kanban_enabled": True,
+    "llm_thread_pool_propagation_enabled": True,
+    "llm_httpc_step_enabled": True,
+
     # 프로세스 종료 시 송출 큐를 비우는 최대 대기(초, 0 이면 대기 안 함). sender 스레드는
     # daemon 이라 exit 시 즉사하므로, 원샷 CLI 에이전트처럼 단명하는 프로세스는 마지막
     # TX_END 가 큐에 남은 채 사라질 수 있다. standalone 모듈은 자체 atexit 로 이걸
@@ -369,6 +389,52 @@ Configuration = {
     # (llm_actx_bands)만 붙는다.
     "llm_traj_actx_enabled": True,
 
+    # ── LLM 트래젝토리 제어 (ParamPack 905) ──
+    # 실행 중인 트래젝토리(mtid 가족)를 서버에서 중지시킨다. 스코프는 트랜잭션 되감기가
+    # 아니라 **진행 중 LLM 호출 끊기 + 이후 LLM 호출 차단** 이다 — 앱은 평범한 연결오류를
+    # 받고 스스로 응답한다(되감기는 gthread 에서 클라이언트 60초 행을 만들었다).
+    #
+    # llm_control_enabled: 기능 킬스위치. false 면 표시도 끊기도 하지 않고 905 에
+    #   204(지원하지 않음)로 답한다 — 400(대상 없음)으로 답하면 "왜 안 되지" 를 데이터
+    #   문제로 오독하게 된다.
+    # llm_control_async_cut_enabled: async 호출을 우리 태스크로 감쌀지. 코루틴은 소켓이
+    #   스택에 없어(sync 는 있다) 취소 핸들을 **미리** 만들어 두는 것이 유일한 수단이라,
+    #   중지 요청이 없어도 모든 async LLM 호출에 적용된다. 의심스러운 환경(비-asyncio
+    #   런타임 등)에서 이것만 끄면 async 는 "이후 호출 차단" 만 남는다(진행 중 호출은
+    #   그대로 끝난다). sync 경로는 이 값과 무관하게 동작한다.
+    # llm_control_stop_transaction_enabled: 중지 스코프. true(기본)면 진행 중 LLM 호출을
+    #   끊은 뒤 **그 트랜잭션을 실행 중인 주체까지 끝낸다**(async=태스크 취소,
+    #   sync=스레드에 BaseException 주입). false 면 LLM 호출만 끊고 앱은 계속 돈다
+    #   (이후 LLM 호출은 전부 실패하므로 LLM 작업량은 0).
+    #   **끄는 것이 나은 경우: gunicorn gthread 워커.** 이전 PoC 실측에서 그 조합만 응답
+    #   없이 클라이언트가 60초 대기했다(sync/uvicorn 은 그 요청 500, 워커·옆 요청 무사).
+    "llm_control_enabled": True,
+    # llm_control_stop_thread_enabled: sync 스레드에 **예외 주입**까지 할 것인가(기본 off).
+    #   다른 종료 수단과 안전성이 다르다 — asyncio 취소는 await 지점, greenlet kill 은
+    #   switch 지점, 협조적 체크포인트는 우리 프레임에서 발동하지만, 스레드 주입만
+    #   **임의 바이트코드**에서 터진다(실측: 수동 락 구간에 걸리면 락이 영구 점유되고,
+    #   블로킹 시스템콜 중에는 아예 발동하지 않는다). 끄더라도 sync 앱은 협조적
+    #   체크포인트로 멈춘다 — 계측 경계(LLM 호출/HTTP/워크플로우)를 지나면 끝난다.
+    #   비계측 블로킹에 갇힌 스레드까지 강제 종료해야 하는 운영자만 켠다.
+    "llm_control_stop_transaction_enabled": True,
+    "llm_control_stop_thread_enabled": False,
+    "llm_control_async_cut_enabled": True,
+    # llm_blocked_users: **사용자 단위 차단**(콤마 구분 user_id 목록). 905 가 서버에서
+    #   mtid 하나를 지목하는 일회성 사건이라면, 이쪽은 **설정이 곧 상태**다 — 여기 올라
+    #   있는 동안 그 사용자의 LLM 호출은 계속 막히고, 빼면 즉시 풀린다(설정 핫리로드
+    #   주기 30초). 집행 지점은 905 와 같다: 새 호출은 가드에서, SDK/앱 재시도는 httpc
+    #   체크포인트에서, 진행 중 호출은 1초 틱 스윕에서 끊는다.
+    #   대상 값은 ``ctx.login_id`` — set_user_id()/llm_user_header/llm_user_meta_key/
+    #   hermes 4경로로 채워지는 그 user_id 이고, 로그싱크 팩의 user_id 태그와 같은 값이라
+    #   화면에서 본 값을 그대로 옮겨 적으면 된다. 대소문자 무시, 미식별('0')은 대상 아님.
+    #     llm_blocked_users=u-1024,abuse@example.com
+    #   **해제는 줄을 지우는 게 아니라 값을 비우는 것**(`llm_blocked_users=`)이다. 핫리로드
+    #   (`Configure.load`)는 파일에 있는 키만 다시 세팅하고 사라진 키를 기본값으로 되돌리지
+    #   않는다 — 줄을 지우면 재기동 전까지 마지막 값이 그대로 남아 계속 차단된다.
+    "llm_blocked_users": "",
+
+    # >>> LLM-EVAL: 평가(Evaluation) 설정 키 — 평가 기능을 떼면 이 블록째 지운다
+    # (whatap/llm/evaluators/REMOVAL.md).
     # ── LLM Evaluation ──
     # 평가 파이프라인 마스터 토글. false면 enqueue/worker가 동작하지 않음.
     "llm_eval_enabled": False,
@@ -417,28 +483,53 @@ Configuration = {
     # 평가자만 적용되고 이 전역 목록은 적용되지 않는다.
     "llm_eval_evaluators": "",
 
+    # 정형 평가자(pii_leak / url_scan)의 스캔 범위. 기본은 output_text(모델 응답)만 —
+    # "모델이 응답에 PII/URL 을 흘렸나(leak)" 관점이라 사용자가 프롬프트에 넣은 값은
+    # 대상이 아니다. true 로 두면 같은 LLM 호출을 input+output 한 덩어리로 보고
+    # input_text 도 함께 스캔 — 입력에만 있어도(예: 프롬프트에 붙은 카드번호/URL) 검출된다
+    # (프롬프트-사이드 DLP). LLM judge(combined_judge 등)에는 영향 없음.
+    "llm_eval_scan_input": False,
+
     # ── conf 기반 default judge (앱 코드 0) ──
     # llm-as-judge 평가자(combined_judge 등)는 평가용 LLM 호출에 자체 자격증명이 필요하다.
-    # judge 해석 순서: ① evaluator(judge_fn=) → ② set_default_judge_fn() → ③ 계측이
-    # 캡처한 사용자 client 인스턴스 재사용 → ④ ctx.provider 매칭 후 환경변수 키.
-    # 요청 스코프(요청마다 client 생성·종료) 앱이나 OAuth 전용 환경에서는 ③(평가는 요청이
-    # 끝난 뒤 비동기로 도는데 그 시점엔 client 가 이미 닫힘)·④(환경변수 키 없음)가 모두
-    # 막혀, 앱에서 set_default_judge_fn 을 직접 호출해야만 했다. 아래 키를 채우면
-    # 부트스트랩이 그 값으로 default judge 를 자동 등록해 — 앱 코드 수정 없이 conf 만으로 —
-    # 평가가 돈다. 코드로 set_default_judge_fn 을 이미 호출했으면 그쪽이 우선(conf 미적용).
+    # judge 해석 순서: ① evaluator(judge_fn=) → ② set_default_judge_fn() / 아래 conf →
+    # ③ 계측이 사용자 호출에서 떠 둔 엔드포인트·자격증명 스냅샷 → ④ ctx.provider 매칭 후
+    # 환경변수 키. 보통 ③ 이 자동으로 풀린다(앱과 같은 엔드포인트·자격증명·모델). OAuth 라
+    # 평문 키가 없거나 다른 모델·엔드포인트로 평가하려면 아래 키를 채운다 — 부트스트랩이 그
+    # 값으로 default judge 를 자동 등록해 앱 코드 수정 없이 conf 만으로 평가가 돈다.
+    # 코드로 set_default_judge_fn 을 이미 호출했으면 그쪽이 우선(conf 미적용).
+    #
+    # Bedrock: Bedrock 을 부르는 앱(boto3·aioboto3·AnthropicBedrock·LiteLLM)은 ③ 으로
+    # judge 도 Bedrock Runtime(Converse)으로 간다 — 앱과 같은 리전·엔드포인트·자격증명·모델.
+    # 다른 앱(OpenAI 등)도 judge 만 Bedrock 으로 보내려면 provider=bedrock + model(+region).
     #
-    #   llm_eval_judge_provider    : "openai" | "anthropic". 미지정 시 base_url 이 있으면
-    #                                openai(호환)로 간주, 없으면 자동 등록 안 함(③/④ 유지).
+    #   llm_eval_judge_provider    : "openai" | "anthropic" | "bedrock". 미지정 시 base_url 이
+    #                                있으면 openai(호환)로 간주, 없으면 자동 등록 안 함(③/④ 유지).
     #   llm_eval_judge_model       : judge 모델. 미지정 시 provider 별 default
-    #                                (openai=gpt-4o-mini, anthropic=claude-3-5-haiku-latest).
+    #                                (openai=gpt-4o-mini, anthropic=claude-haiku-5-5).
+    #                                provider 나 base_url 과 함께 넣어야 적용된다 — 모델만
+    #                                넣으면 무시하고 LLM056 경고(③ 은 계속 앱 모델로 평가).
+    #                                bedrock 은 **필수** — modelId 또는 추론 프로파일 ID
+    #                                (예: us.anthropic.claude-haiku-4-5-20251001-v1:0). 계정·리전마다
+    #                                열린 모델이 달라 기본값을 두지 않는다.
     #   llm_eval_judge_api_key_env : judge 키가 담긴 환경변수 이름(권장 — 키를 설정 파일에
     #                                직접 두지 않음). 예: "WHATAP_LLM_EVAL_JUDGE_API_KEY".
     #   llm_eval_judge_api_key     : (대안) judge API 키 직접 지정. _env 가 있으면 그쪽 우선.
-    #                                로컬 vLLM 등 키가 불필요하면 "EMPTY".
+    #                                로컬 vLLM 등 키가 불필요하면 "EMPTY". bedrock 엔 쓰지 않는다
+    #                                (AWS 자격증명으로 서명 — env / 프로파일 / IAM 역할).
     #   llm_eval_judge_base_url    : (선택) OpenAI 호환 엔드포인트 / 프록시 / 내부 게이트웨이.
+    #                                bedrock 이면 Bedrock Runtime endpoint_url(VPC 엔드포인트 등).
+    #   llm_eval_judge_region      : (bedrock) AWS 리전. 미지정 시 AWS 기본 해석
+    #                                (AWS_DEFAULT_REGION / ~/.aws/config — botocore 는
+    #                                AWS_REGION 을 읽지 않는다).
+    #   llm_eval_judge_aws_profile : (bedrock) ~/.aws 프로파일 이름. 미지정 시 AWS 기본 자격증명
+    #                                체인(env → 공유 자격증명 파일 → IAM 역할).
     "llm_eval_judge_provider": "",
     "llm_eval_judge_model": "",
     "llm_eval_judge_api_key_env": "",
     "llm_eval_judge_api_key": "",
     "llm_eval_judge_base_url": "",
+    "llm_eval_judge_region": "",
+    "llm_eval_judge_aws_profile": "",
+    # <<< LLM-EVAL
 }