whatap-python 2.2.0__py3-none-any.whl → 2.2.1__py3-none-any.whl

whatap/doctor.py

@@ -0,0 +1,402 @@
+# -*- coding: utf-8 -*-
+"""whatap-doctor -- 에이전트-중립 설치 진단/검증 도구.
+
+이 도구는 특정 AI 에이전트에 묶이지 않는다. Claude Code, Codex, 사람이 직접
+치는 터미널, CI 스크립트 어디서든 똑같이 실행되며 표준 라이브러리만 쓴다.
+
+호출 방법(둘 다 동일):
+    $ whatap-doctor
+    $ python -m whatap.doctor
+
+하는 일:
+    - Python / OS / 프레임워크 / 앱 기동 방식 탐지
+    - whatap.conf 존재 및 필수 키(license, host, app_name) 확인
+    - 에이전트 프로세스 기동 여부 확인
+    - "지금 상태 → 다음에 할 명령" 을 스스로 안내
+
+종료코드:
+    0  설치가 완료되어 데이터 수집 중(또는 검증 통과)
+    1  다음 조치가 필요함(설치/설정/기동)
+"""
+from __future__ import print_function
+
+import os
+import platform
+import re
+import subprocess
+import sys
+
+try:
+    from importlib.util import find_spec as _find_spec
+except Exception:  # pragma: no cover - 매우 오래된 파이썬
+    _find_spec = None
+
+CONF_NAME = "whatap.conf"
+AGENT_NAME = "whatap_python"
+APM_REQUIRED_KEYS = ("license", "whatap.server.host", "app_name")
+KNOWN_FRAMEWORKS = (
+    "django", "flask", "fastapi", "starlette", "sanic",
+    "tornado", "bottle", "pyramid", "falcon", "aiohttp",
+)
+# 계측이 자동으로 LLM 트랜잭션/스텝을 수집하는 대상 SDK/프레임워크.
+KNOWN_LLM_SDKS = ("openai", "anthropic", "langgraph", "langchain")
+
+OK, WARN, FAIL = "ok", "warn", "fail"
+_MARK = {OK: "✓", WARN: "!", FAIL: "✗"}  # ✓ ! ✗
+
+
+def _color(text, status):
+    if os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+        return text
+    code = {OK: "32", WARN: "33", FAIL: "31"}.get(status, "0")
+    return "\033[{0}m{1}\033[0m".format(code, text)
+
+
+class Result(object):
+    __slots__ = ("status", "label", "detail", "hint")
+
+    def __init__(self, status, label, detail="", hint=""):
+        self.status = status
+        self.label = label
+        self.detail = detail
+        self.hint = hint
+
+    def line(self):
+        mark = _color("[{0}]".format(_MARK[self.status]), self.status)
+        text = "{0} {1}".format(mark, self.label)
+        if self.detail:
+            text += ": {0}".format(self.detail)
+        return text
+
+
+# ---------------------------------------------------------------------------
+# 탐지 (detect)
+# ---------------------------------------------------------------------------
+
+def resolve_home():
+    """whatap.conf 가 있어야 할 디렉토리. 규약상 WHATAP_HOME, 없으면 CWD."""
+    return os.environ.get("WHATAP_HOME", os.getcwd())
+
+
+def read_conf(home):
+    """whatap.conf 를 평문으로 파싱한다(패키지 내부 API에 의존하지 않음)."""
+    path = os.path.join(home, CONF_NAME)
+    conf = {}
+    if not os.path.isfile(path):
+        return None, path
+    try:
+        with open(path) as f:
+            for raw in f:
+                line = raw.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, val = line.split("=", 1)
+                conf[key.strip()] = val.strip()
+    except Exception as e:
+        return {"__error__": str(e)}, path
+    return conf, path
+
+
+def _spec_exists(name):
+    if _find_spec is None:
+        return False
+    try:
+        return _find_spec(name) is not None
+    except Exception:
+        return False
+
+
+def detect_python():
+    v = sys.version_info
+    ver = "{0}.{1}.{2}".format(v[0], v[1], v[2])
+    if v[0] < 3 or (v[0] == 3 and v[1] < 8):
+        return Result(
+            WARN, "Python", ver,
+            hint="3.8 미만은 콘솔 스크립트가 깨질 수 있음 → auto-attach 방식 권장 "
+                 "(INSTALL.md '기동 연결' 참고)")
+    return Result(OK, "Python", ver)
+
+
+def detect_os():
+    return Result(OK, "OS/Arch", "{0} {1}".format(platform.system(), platform.machine()))
+
+
+def _read_version(spec):
+    """whatap/build.py 의 version 을 __init__ 실행 없이 텍스트로 읽는다."""
+    try:
+        locs = list(getattr(spec, "submodule_search_locations", None) or [])
+        for base in locs:
+            build_py = os.path.join(base, "build.py")
+            if os.path.isfile(build_py):
+                with open(build_py) as f:
+                    for line in f:
+                        if line.strip().startswith("version"):
+                            return line.split("=", 1)[1].strip().strip("'\"")
+    except Exception:
+        pass
+    return "unknown"
+
+
+def detect_package():
+    """whatap 패키지 존재만 확인한다 -- import 하지 않아 부작용/무거운 초기화가 없다."""
+    if _find_spec is None:
+        return Result(WARN, "whatap-python", "확인 불가(importlib 없음)"), True
+    try:
+        spec = _find_spec("whatap")
+    except Exception:
+        spec = None
+    if spec is None:
+        return Result(
+            FAIL, "whatap-python", "미설치",
+            hint="pip install whatap-python  (LLM 관측이면 'whatap-python[llm]')"), False
+    return Result(OK, "whatap-python", "v{0}".format(_read_version(spec))), True
+
+
+def detect_framework():
+    found = [fw for fw in KNOWN_FRAMEWORKS if _spec_exists(fw)]
+    signals = []
+    cwd = os.getcwd()
+    if os.path.isfile(os.path.join(cwd, "manage.py")):
+        signals.append("manage.py(Django)")
+    if _spec_exists("gunicorn"):
+        signals.append("gunicorn")
+    if _spec_exists("uvicorn"):
+        signals.append("uvicorn")
+    if _spec_exists("celery"):
+        signals.append("celery")
+    parts = found + signals
+    if not parts:
+        return Result(WARN, "프레임워크", "자동 판별 실패",
+                      hint="INSTALL.md 의 프레임워크별 기동 연결법을 직접 골라 적용")
+    return Result(OK, "프레임워크", ", ".join(parts))
+
+
+def detect_start_method():
+    cwd = os.getcwd()
+    hits = []
+    for name in ("Procfile", "Dockerfile", "docker-compose.yml", "manage.py"):
+        if os.path.isfile(os.path.join(cwd, name)):
+            hits.append(name)
+    if not hits:
+        return Result(WARN, "기동 지점", "판별 실패",
+                      hint="앱 실행 명령을 확인해 whatap-start-agent 프리픽스 또는 "
+                           "PYTHONPATH+sitecustomize auto-attach 로 연결")
+    return Result(OK, "기동 지점", ", ".join(hits))
+
+
+# ---------------------------------------------------------------------------
+# 설정/기동 확인 (verify)
+# ---------------------------------------------------------------------------
+
+def check_conf(conf, path):
+    """APM/LLM 어느 모드로 켜졌는지에 따라 필수 키를 다르게 검증한다."""
+    if conf is None:
+        return Result(FAIL, "whatap.conf", "없음 ({0})".format(path),
+                      hint="whatap-llm-setting-config --host <LLM 수집서버> --license <LLM 키> "
+                           "--app_name <앱이름> --app_process_name <프로세스명>  "
+                           "(APM 지표도 함께면 whatap-setting-config)")
+    if "__error__" in conf:
+        return Result(FAIL, "whatap.conf", "읽기 실패: {0}".format(conf["__error__"]))
+
+    apm_on = conf.get("apm_enabled", "true") != "false"
+    llm_on = conf.get("llm_enabled", "false") == "true"
+
+    missing = []
+    if apm_on:
+        missing += [k for k in APM_REQUIRED_KEYS if not conf.get(k)]
+    if llm_on:
+        if not (conf.get("llm_accesskey") or conf.get("license")):
+            missing.append("llm_accesskey|license")
+        if not (conf.get("llm.whatap.server.host") or conf.get("whatap.server.host")):
+            missing.append("llm.whatap.server.host|whatap.server.host")
+        if not conf.get("app_name"):
+            missing.append("app_name")
+
+    seen = set()
+    missing = [m for m in missing if not (m in seen or seen.add(m))]
+    mode = "+".join([m for m, on in (("APM", apm_on), ("LLM", llm_on)) if on]) or "none"
+
+    if missing:
+        return Result(FAIL, "whatap.conf", "필수 키 누락({0}): {1}".format(mode, ", ".join(missing)),
+                      hint="whatap-setting-config / whatap-llm-setting-config 로 누락 값을 채우세요")
+    return Result(OK, "whatap.conf", "{0} 설정됨".format(mode))
+
+
+def _llm_sdk_result(found):
+    if not found:
+        return Result(OK, "LLM SDK", "감지 안 됨(LLM 관측 대상 아님)")
+    return Result(OK, "LLM SDK", ", ".join(found))
+
+
+def check_llm_features(conf, sdk_present):
+    """LLM 관측 on/off 와 Evaluation 상태를 요약한다(비용 경고 포함)."""
+    if conf is None or "__error__" in conf:
+        return None
+    llm_on = conf.get("llm_enabled", "false") == "true"
+    if not llm_on:
+        if sdk_present:
+            return Result(WARN, "LLM 관측", "off (LLM SDK 감지됨)",
+                          hint="whatap-llm-setting-config 로 켜면 LLM 트랜잭션/스텝이 자동 수집됨 "
+                               "(references/llm-observability.md)")
+        return Result(OK, "LLM 관측", "off")
+
+    if conf.get("llm_eval_enabled", "false") == "true":
+        evs = conf.get("llm_eval_evaluators", "combined_judge, pii_leak, url_scan")
+        return Result(WARN, "LLM Evaluation", "on / evaluators={0}".format(evs),
+                      hint="judge LLM 호출만큼 토큰·비용이 추가 발생. combined_judge 권장, "
+                           "필요시 llm_eval_sample_rate 로 비율 조절 (references/llm-evaluation.md)")
+    return Result(OK, "LLM 관측", "on (Evaluation off)",
+                  hint="응답 품질 평가가 필요하면 llm_eval_enabled=true (references/llm-evaluation.md)")
+
+
+def check_process():
+    if platform.system() == "Windows":
+        cmd = ["tasklist"]
+    else:
+        cmd = ["ps", "-e"]
+    try:
+        out = subprocess.check_output(cmd, stderr=subprocess.STDOUT)
+        out = out.decode("utf-8", "replace")
+    except Exception:
+        return Result(WARN, "에이전트 프로세스", "확인 불가(ps/tasklist 실행 실패)")
+    if AGENT_NAME in out:
+        return Result(OK, "에이전트 프로세스", "{0} 실행 중".format(AGENT_NAME))
+    return Result(WARN, "에이전트 프로세스", "미기동",
+                  hint="앱을 whatap-start-agent 로 기동하거나 auto-attach 로 앱과 함께 뜨게 하세요")
+
+
+# ---------------------------------------------------------------------------
+# 계측 인벤토리 (--scan): 고객 소스에 들어간 LLM API 사용/편집을 전수 추적
+# ---------------------------------------------------------------------------
+
+_SCAN_SKIP_DIRS = set([
+    "node_modules", ".venv", "venv", "env", "__pycache__", "site-packages",
+    ".tox", "build", "dist", ".mypy_cache", ".pytest_cache", ".eggs",
+])
+
+_SCAN_PATTERNS = [
+    ("import", re.compile(r"(from\s+whatap\.llm[\w.]*\s+import|import\s+whatap\.llm)")),
+    ("workflow/agent", re.compile(r"@(workflow|agent|agent_name)\b|with\s+(workflow|agent|agent_name)\s*\(")),
+    ("session/user", re.compile(r"set_(session|user)_id\s*\(|with\s+(session|user)\s*\(")),
+    ("operation/prompt", re.compile(r"@prompt_meta\b|with\s+prompt_meta_scope\s*\(")),
+    ("evaluation", re.compile(r"@evaluate_with\b|evaluate_with\s*\(|with\s+evaluation_scope\s*\(")),
+    ("marker", re.compile(r"#\s*whatap")),
+]
+
+
+def inventory_scan(root):
+    """프로젝트 .py 파일에서 whatap.llm API 사용과 '# whatap' 마커를 찾아 나열한다."""
+    hits = []
+    for cur, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in _SCAN_SKIP_DIRS and not d.startswith(".")]
+        for name in files:
+            if not name.endswith(".py"):
+                continue
+            path = os.path.join(cur, name)
+            try:
+                with open(path) as f:
+                    lines = f.readlines()
+            except Exception:
+                continue
+            for i, line in enumerate(lines, 1):
+                for cat, rx in _SCAN_PATTERNS:
+                    if rx.search(line):
+                        hits.append((os.path.relpath(path, root), i, cat, line.strip()))
+                        break
+    return hits
+
+
+def _scan_main(root):
+    hits = inventory_scan(root)
+    if not hits:
+        print("WhaTap LLM 계측 인벤토리 — 소스에서 whatap.llm API 사용을 찾지 못함.")
+        print("(자동 계측/conf 기반이면 코드 편집이 없는 것이 정상입니다.)")
+        return 0
+    print("WhaTap LLM 계측 인벤토리  (root={0}, {1}건)".format(root, len(hits)))
+    print("-" * 60)
+    cur_file = None
+    for path, lineno, cat, text in hits:
+        if path != cur_file:
+            print("  {0}".format(path))
+            cur_file = path
+        print("    {0}: [{1}] {2}".format(lineno, cat, text))
+    print("-" * 60)
+    print("위가 고객 소스에 들어간 LLM 계측의 전부입니다. '# whatap' 마커로도 grep 가능.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+def run_checks():
+    home = resolve_home()
+    pkg_result, installed = detect_package()
+    llm_sdks = [s for s in KNOWN_LLM_SDKS if _spec_exists(s)]
+    checks = [
+        detect_python(),
+        detect_os(),
+        pkg_result,
+        detect_framework(),
+        detect_start_method(),
+        _llm_sdk_result(llm_sdks),
+    ]
+    if installed:
+        conf, path = read_conf(home)
+        checks.append(check_conf(conf, path))
+        checks.append(check_process())
+        feat = check_llm_features(conf, bool(llm_sdks))
+        if feat is not None:
+            checks.append(feat)
+    return checks
+
+
+def _next_action(checks):
+    for c in checks:
+        if c.status == FAIL and c.hint:
+            return "다음: {0}".format(c.hint)
+    warn = [c for c in checks if c.status == WARN and c.hint]
+    if warn:
+        return "다음: {0}".format(warn[0].hint)
+    return None
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    as_json = "--json" in argv
+
+    if "--scan" in argv:
+        return _scan_main(os.getcwd())
+
+    checks = run_checks()
+
+    if as_json:
+        import json
+        payload = {
+            "home": resolve_home(),
+            "checks": [
+                {"status": c.status, "label": c.label, "detail": c.detail, "hint": c.hint}
+                for c in checks
+            ],
+        }
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print("WhaTap Python 에이전트 진단  (WHATAP_HOME={0})".format(resolve_home()))
+        print("-" * 60)
+        for c in checks:
+            print("  " + c.line())
+            if c.hint and c.status != OK:
+                print("      → {0}".format(c.hint))
+        print("-" * 60)
+        nxt = _next_action(checks)
+        if nxt:
+            print(nxt)
+        else:
+            print("모든 항목 통과 — 데이터 수집 준비 완료.")
+
+    failed = any(c.status == FAIL for c in checks)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

whatap/llm/control/__init__.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+"""LLM 트래젝토리 제어(ParamPack 905) — 실행 중 LLM 호출 끊기.
+
+계층은 셋이다.
+
+    trajectory.py   가족(mtid) 상태와 905 실행부 — 무엇을 끊을지, 어떤 status 를 답할지
+    cut.py          끊는 수단 — sync 소켓 shutdown / async 태스크 cancel
+    guard.py        프로바이더 호출 지점 seam — 인터셉터가 SDK 를 부르는 한 줄
+
+바깥에서 쓰는 것은 여기 re-export 된 이름들뿐이다:
+
+    stop_trajectory(mtid)   905 진입점 (udp_session)
+    guard_sync/guard_async  프로바이더 인터셉터
+    block_reason            집행 지점 공용 판정자 — 막을 이유(문구) 또는 None
+    enforce_blocked_users   차단 사용자의 진행 중 호출 끊기 (LlmStatTask 1초 틱)
+"""
+from whatap.llm.control.trajectory import (
+    STATUS_OK,
+    STATUS_IN_PROGRESS,
+    STATUS_UNSUPPORTED,
+    STATUS_NO_TARGET,
+    STATUS_ERROR,
+    stop_trajectory,
+    block_reason,
+    has_any_block,
+    stop_exception,
+    emit_stop_step,
+    should_terminate,
+    is_stopped_ctx,
+    is_blocked_user,
+    blocked_users,
+    enforce_blocked_users,
+    is_enabled,
+    stop_message,
+)
+from whatap.llm.control.guard import guard_sync, guard_async, stopped_error
+
+__all__ = [
+    'STATUS_OK',
+    'STATUS_IN_PROGRESS',
+    'STATUS_UNSUPPORTED',
+    'STATUS_NO_TARGET',
+    'STATUS_ERROR',
+    'stop_trajectory',
+    'block_reason',
+    'has_any_block',
+    'stop_exception',
+    'emit_stop_step',
+    'should_terminate',
+    'is_stopped_ctx',
+    'is_blocked_user',
+    'blocked_users',
+    'enforce_blocked_users',
+    'is_enabled',
+    'stop_message',
+    'guard_sync',
+    'guard_async',
+    'stopped_error',
+]