whatap-python 2.1.0__py3-none-any.whl

whatap/llm/evaluators/builtins/llm_judge.py

@@ -0,0 +1,516 @@
+"""LLM-as-a-judge 평가자의 베이스 + 어댑터.
+
+LLM judge 평가자는 자체적으로 다른 LLM 을 호출해 평가를 수행한다.
+- 비용이 비싸므로 보통 샘플링과 함께 사용한다 (whatap.conf 의 llm_eval_sample_rate).
+- 워커 스레드의 재귀 가드 (LlmEvaluatorTask._safe_run_one 의 thread-local) 가
+  judge 의 LLM 호출이 다시 평가 큐에 들어가는 것을 자동 차단한다.
+
+사용:
+    1) judge_fn 을 직접 작성하거나 make_openai_judge() 로 만든 뒤,
+    2) HallucinationEvaluator/AnswerRelevanceEvaluator/ToxicityEvaluator 등에 주입.
+
+    >>> judge = make_openai_judge(model='gpt-4o-mini')
+    >>> register_evaluator(HallucinationEvaluator(judge_fn=judge))
+"""
+import json
+import re
+
+from whatap import logging
+from whatap.llm.evaluators.base import BaseEvaluator, EvaluatorResult
+
+
+# 사용자가 set_default_judge_fn() 으로 등록하는 전역 fallback judge.
+# user 의 client 캡처가 안 되는 환경 (CLI 스크립트 등) 에서만 사용.
+_default_judge_fn = [None]
+
+
+def set_default_judge_fn(judge_fn):
+    """전역 default judge_fn 등록 (앱 시작 시 한 번).
+
+    각 evaluator 의 judge 결정 우선순위:
+        1) evaluator 인스턴스에 명시된 judge_fn
+        2) 이 함수로 등록한 전역 default
+        3) ctx.provider 기반 자동 판별 (api.openai.com → OpenAI, api.anthropic.com → Anthropic)
+
+    로컬 vLLM 서버 / Azure OpenAI / 자체 호스팅 LLM 등 ctx.provider 가 알려진 클라우드와
+    매칭 안 되는 환경에서는 이 default 를 등록하지 않으면 judge_error 가 발생한다.
+
+    Example:
+        from whatap.llm.evaluators.builtins import set_default_judge_fn, make_openai_judge
+
+        # 앱 시작 시 한 번
+        set_default_judge_fn(make_openai_judge(
+            base_url='http://localhost:8002/v1',
+            api_key='EMPTY',
+            model='qwen-7b',
+        ))
+    """
+    if judge_fn is not None and not callable(judge_fn):
+        raise TypeError('judge_fn must be callable')
+    _default_judge_fn[0] = judge_fn
+
+
+def get_default_judge_fn():
+    """현재 등록된 전역 default judge_fn 반환 (없으면 None)."""
+    return _default_judge_fn[0]
+
+
+class LLMJudgeBase(BaseEvaluator):
+    """LLM 을 사용해 평가를 수행하는 베이스 클래스.
+
+    서브클래스는 ``make_prompt(ctx)`` 와 ``parse_judgment(raw)`` 만 구현하면 된다.
+
+    judge LLM 호출 방식 — 우선순위:
+    1) ``judge_fn`` 명시 — ``(system, user) -> str`` callable. 완전 커스텀 케이스.
+    2) ``model`` 만 명시 — provider 는 평가 대상의 ctx.provider 에서 자동 판별.
+       (OpenAI 면 OpenAI, Anthropic 이면 Anthropic 으로 자동 dispatch)
+    3) 둘 다 미지정 — provider 자동 판별 + 모델은 작은 default
+       (OpenAI: gpt-4o-mini, Anthropic: claude-3-5-haiku-latest).
+
+    인증은 환경변수 (OPENAI_API_KEY / ANTHROPIC_API_KEY) 가 자동 사용된다 —
+    사용자 앱이 이미 쓰고 있는 키 그대로. 별도 발급 불필요.
+    """
+
+    # LLM judge 호출이 발생하는 평가자임을 표시. ``LlmEvaluatorTask._run_one`` 이
+    # ``EvalStat`` (judge 호출 통계 — call_count/failures/latency_sum) 에 카운트
+    # 할지 여부를 결정. 규칙 기반 평가자 (PIILeak / URLScan / 사용자 custom 등)
+    # 는 BaseEvaluator 의 default False 이므로 EvalStat 에 안 잡힘 (점수 히스토그램
+    # 에는 정상 송출).
+    USES_LLM_JUDGE = True
+
+    LABEL = None
+    METRIC_TYPE = None
+
+    # 기본 모델 (provider 별).
+    _DEFAULT_OPENAI_MODEL = 'gpt-4o-mini'
+    _DEFAULT_ANTHROPIC_MODEL = 'claude-3-5-haiku-latest'
+
+    def __init__(self, judge_fn=None, model=None):
+        if judge_fn is not None and not callable(judge_fn):
+            raise TypeError('judge_fn must be callable')
+        self._judge_fn = judge_fn
+        self._model = model
+        # auto-resolved judge_fn 캐시 (provider 별).
+        self._auto_cache = {}
+
+    def make_prompt(self, ctx):
+        """평가 프롬프트 생성. 반환값: (system_prompt, user_prompt) 튜플."""
+        raise NotImplementedError
+
+    def parse_judgment(self, raw):
+        """judge 의 raw 응답을 EvaluatorResult 로 변환."""
+        raise NotImplementedError
+
+    def _resolve_judge_fn(self, ctx):
+        """judge_fn 결정 우선순위:
+
+        1) evaluator 에 명시된 judge_fn
+        2) set_default_judge_fn() 으로 등록한 전역 default
+        3) **interceptor 가 캡처한 ctx.client 의 base_url/api_key 자동 재사용**
+           (사용자 앱이 쓰는 그 client 의 인증/엔드포인트 그대로 — 별도 등록 불필요)
+        4) ctx.provider 기반 자동 판별 (api.openai.com / api.anthropic.com 만 매칭)
+
+        대부분의 경우 (3) 에서 해결 — 사용자가 OpenAI/AsyncOpenAI/Anthropic 등 어떤
+        client 를 쓰고 있든 그 인증 정보를 그대로 받아 평가 LLM 호출도 같은 백엔드로 보냄.
+        """
+        if self._judge_fn is not None:
+            return self._judge_fn
+
+        # 1) 전역 default
+        default = get_default_judge_fn()
+        if default is not None:
+            return default
+
+        # 2) interceptor 가 캡처한 사용자 client + event loop 그대로 재사용
+        captured = getattr(ctx, 'client', None)
+        captured_loop = getattr(ctx, 'event_loop', None)
+        if captured is not None:
+            judge_model = self._model or getattr(ctx, 'model', None) or self._DEFAULT_OPENAI_MODEL
+            judge_fn = _judge_fn_from_captured_client(captured, model=judge_model,
+                                                     event_loop=captured_loop)
+            if judge_fn is not None:
+                return judge_fn
+
+        # 3) ctx.provider 문자열 기반 클라우드 매칭
+        provider = (getattr(ctx, 'provider', '') or '').lower()
+        if 'anthropic' in provider:
+            key = 'anthropic'
+        elif 'openai.com' in provider or 'azure.com' in provider:
+            key = 'openai'
+        else:
+            return None
+
+        if key in self._auto_cache:
+            return self._auto_cache[key]
+
+        if key == 'anthropic':
+            judge_fn = make_anthropic_judge(
+                model=self._model or self._DEFAULT_ANTHROPIC_MODEL,
+            )
+        else:
+            judge_fn = make_openai_judge(
+                model=self._model or self._DEFAULT_OPENAI_MODEL,
+            )
+        self._auto_cache[key] = judge_fn
+        return judge_fn
+
+    def evaluate(self, ctx):
+        judge_fn = self._resolve_judge_fn(ctx)
+        if judge_fn is None:
+            logging.warning(
+                '[LLM] judge evaluator %s skipped: no judge_fn resolvable for provider=%r. '
+                'Set one via evaluator(judge_fn=...) or set_default_judge_fn().'
+                % (self.LABEL, getattr(ctx, 'provider', '')),
+                extra={'id': 'LLM062'},
+            )
+            return EvaluatorResult(
+                value='no_judge_configured',
+                reasoning='No judge_fn for provider=%s. Use set_default_judge_fn().'
+                          % getattr(ctx, 'provider', '?'),
+                metric_type='categorical',
+                metadata={'provider': getattr(ctx, 'provider', '')},
+            )
+        try:
+            system, user = self.make_prompt(ctx)
+            raw = judge_fn(system, user)
+            if not isinstance(raw, str):
+                raw = str(raw) if raw is not None else ''
+            return self.parse_judgment(raw)
+        except Exception as e:
+            logging.warning('[LLM] judge evaluator %s exception: %s' % (self.LABEL, e),
+                            extra={'id': 'LLM060'})
+            return EvaluatorResult(
+                value='judge_error',
+                reasoning='%s: %s' % (type(e).__name__, e),
+                metric_type='categorical',
+                metadata={'error_type': type(e).__name__, 'error_message': str(e)},
+            )
+
+
+def _judge_fn_from_captured_client(captured, model, temperature=0.0, max_tokens=2048,
+                                   event_loop=None):
+    """interceptor 가 캡처한 user 의 client 를 그대로 재사용해 judge_fn 을 만든다.
+
+    핵심: **새 sync client / httpx.Client 생성 안 함.** user 가 만들어 쓰던 그
+    OpenAI / AsyncOpenAI / Anthropic / AsyncAnthropic 인스턴스를 그대로 호출.
+
+    sync client (OpenAI / Anthropic) → 워커 스레드에서 그대로 ``client.method(...)`` 호출.
+    async client (AsyncOpenAI / AsyncAnthropic) → ``run_coroutine_threadsafe`` 로 user 의
+        running event loop 에 dispatch → 그 loop 에서 user 의 AsyncClient 가 호출됨.
+
+    `event_loop` 가 None 이면 (sync 호출이었거나 capture 실패) async client 는 호출 불가
+    → None 반환.
+    """
+    import inspect
+    cls_name = type(captured).__name__
+
+    # async 여부 판별 — 클래스명 prefix + create 메서드가 coroutine 인지
+    is_async = cls_name.startswith('Async')
+    if not is_async:
+        try:
+            if 'Anthropic' in cls_name:
+                m = captured.messages.create
+            else:
+                m = captured.chat.completions.create
+            if inspect.iscoroutinefunction(m):
+                is_async = True
+        except Exception:
+            pass
+
+    # ── sync user client → 워커 스레드에서 직접 호출 ──
+    if not is_async:
+        if 'Anthropic' in cls_name:
+            return make_anthropic_judge(client=captured, model=model,
+                                        temperature=temperature, max_tokens=max_tokens)
+        return make_openai_judge(client=captured, model=model,
+                                 temperature=temperature, max_tokens=max_tokens)
+
+    # ── async user client → user loop 에 dispatch ──
+    if event_loop is None:
+        # loop capture 실패 — async client 그대로 호출 불가
+        return None
+
+    return _make_async_dispatched_judge(captured, model, temperature, max_tokens,
+                                        event_loop=event_loop,
+                                        kind='anthropic' if 'Anthropic' in cls_name else 'openai')
+
+
+def _make_async_dispatched_judge(async_client, model, temperature, max_tokens,
+                                 event_loop, kind):
+    """async user client 를 user 의 running loop 에 dispatch 해서 호출하는 sync judge_fn.
+
+    매 호출마다 ``run_coroutine_threadsafe(coro, event_loop).result()`` — coro 는 user 의
+    loop 에서 실행되어 user 의 AsyncClient (그 loop 에 binding) 그대로 사용.
+    별도 client 생성 / httpx pool 생성 없음 → 누적 leak 0.
+
+    Dispatched coro 는 task context 시작 시 trace context 를 None 으로 명시 set:
+    user loop 이 다른 request 처리 중일 때 그 ctx 를 inherit 하면 intercept 가
+    엉뚱한 txid 로 발화하므로 차단.
+    """
+    import asyncio
+    from whatap.counter.tasks.llm_evaluator_task import _eval_worker_cv, _get_eval_worker_state
+
+    def _setup_dispatched_ctx(state):
+        """dispatched coro 시작 시 컨텍스트 정리:
+        - trace ctx 를 None 으로 set — user loop 이 다른 request 처리 중일 때 그 ctx 를
+          inherit 해서 intercept 가 엉뚱한 txid 로 발화하는 것 차단
+        - _eval_worker_cv 를 worker 의 state dict 로 set — dispatched task 의 context 에
+          parent ids 까지 propagate. 이 task 안의 LLM 호출 intercept 가 evaluator worker
+          로 인지하고 (옵션 시) parent ids override 까지 정상 동작.
+
+        반환: (cv_token, trace_token_or_None) — coro 종료 시 reset 용. set 실패 시 None.
+        ContextVar 는 task 종료 시 자동 정리되지만, ``loop.run_until_complete`` 처럼
+        같은 task 컨텍스트가 user 코드로 이어지는 케이스에서 누출 방지를 위한 명시 reset.
+        """
+        trace_token = None
+        try:
+            from whatap.trace.trace_context_manager import TraceContextManager
+            trace_token = TraceContextManager.whatap_coroutine_context.set(None)
+        except Exception:
+            pass
+        cv_token = None
+        try:
+            cv_token = _eval_worker_cv.set(state if state else {'in_eval': True})
+        except Exception:
+            pass
+        return cv_token, trace_token
+
+    def _reset_dispatched_ctx(cv_token, trace_token):
+        if cv_token is not None:
+            try:
+                _eval_worker_cv.reset(cv_token)
+            except Exception:
+                pass
+        if trace_token is not None:
+            try:
+                from whatap.trace.trace_context_manager import TraceContextManager
+                TraceContextManager.whatap_coroutine_context.reset(trace_token)
+            except Exception:
+                pass
+
+    if kind == 'anthropic':
+        async def _call(state, system, user):
+            cv_tok, tr_tok = _setup_dispatched_ctx(state)
+            try:
+                resp = await async_client.messages.create(
+                    model=model, system=system,
+                    messages=[{'role': 'user', 'content': user}],
+                    max_tokens=max_tokens, temperature=temperature,
+                )
+                for block in resp.content:
+                    if getattr(block, 'type', None) == 'text':
+                        return block.text or ''
+                return ''
+            finally:
+                _reset_dispatched_ctx(cv_tok, tr_tok)
+    else:
+        async def _call(state, system, user):
+            cv_tok, tr_tok = _setup_dispatched_ctx(state)
+            try:
+                resp = await async_client.chat.completions.create(
+                    model=model,
+                    messages=[
+                        {'role': 'system', 'content': system},
+                        {'role': 'user', 'content': user},
+                    ],
+                    temperature=temperature, max_tokens=max_tokens,
+                )
+                return resp.choices[0].message.content or ''
+            finally:
+                _reset_dispatched_ctx(cv_tok, tr_tok)
+
+    def judge_fn(system, user):
+        if not event_loop.is_running():
+            raise RuntimeError(
+                'captured event loop is no longer running — user app likely shut down'
+            )
+        # judge_fn 호출 시점 (worker thread) 에 state 캡처 → dispatched coro 에 closure
+        # 로 전달. parent_txid/step_id/index 가 user loop thread 까지 propagate 됨.
+        state = _get_eval_worker_state()
+        future = asyncio.run_coroutine_threadsafe(_call(state, system, user), event_loop)
+        # user app 의 loop hang / backpressure 로 평가 워커가 무기한 블록되는 것 차단.
+        # 초과 시 future 를 취소해 user loop 에 떠다니는 좀비 task 도 정리.
+        timeout = _judge_timeout_sec()
+        try:
+            return future.result(timeout=timeout) if timeout else future.result()
+        except Exception:
+            try:
+                future.cancel()
+            except Exception:
+                pass
+            raise
+    return judge_fn
+
+
+def _judge_timeout_sec():
+    """conf.llm_eval_judge_timeout_sec 을 안전 변환. 0/음수/잘못된 값 → None (무제한).
+
+    Configure.setProperty 가 string 으로 들고있을 수 있어 (reload 패턴) 변환 우회.
+    """
+    from whatap.conf.configure import Configure as conf
+    raw = getattr(conf, 'llm_eval_judge_timeout_sec', 30)
+    try:
+        v = float(raw)
+    except (TypeError, ValueError):
+        return 30.0
+    return v if v > 0 else None
+
+
+def make_openai_judge(client=None, model='gpt-4o-mini', api_key=None, base_url=None,
+                      temperature=0.0, max_tokens=2048):
+    """OpenAI 호환 API 를 사용하는 judge_fn 을 생성한다.
+
+    :param client: 기존 ``openai.OpenAI`` 인스턴스. 주면 그대로 재사용.
+    :param model:  평가용 모델.
+    :param base_url: OpenAI 호환 엔드포인트 (client 미지정 시).
+    """
+    _client_ref = [client]
+
+    def judge_fn(system, user):
+        c = _client_ref[0]
+        if c is None:
+            import openai
+            client_kwargs = {}
+            if api_key:
+                client_kwargs['api_key'] = api_key
+            if base_url:
+                client_kwargs['base_url'] = base_url
+            c = openai.OpenAI(**client_kwargs)
+            _client_ref[0] = c
+        resp = c.chat.completions.create(
+            model=model,
+            messages=[
+                {'role': 'system', 'content': system},
+                {'role': 'user', 'content': user},
+            ],
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return resp.choices[0].message.content or ''
+    return judge_fn
+
+
+def make_anthropic_judge(client=None, model='claude-3-5-haiku-latest', api_key=None,
+                         max_tokens=2048, temperature=0.0):
+    """Anthropic 을 사용하는 judge_fn 을 생성한다."""
+    _client_ref = [client]
+
+    def judge_fn(system, user):
+        c = _client_ref[0]
+        if c is None:
+            import anthropic
+            client_kwargs = {}
+            if api_key:
+                client_kwargs['api_key'] = api_key
+            c = anthropic.Anthropic(**client_kwargs)
+            _client_ref[0] = c
+        resp = c.messages.create(
+            model=model,
+            system=system,
+            messages=[{'role': 'user', 'content': user}],
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+        for block in resp.content:
+            if getattr(block, 'type', None) == 'text':
+                return block.text or ''
+        return ''
+    return judge_fn
+
+
+# ── parsing helpers ──
+
+_JSON_BLOCK = re.compile(r'\{.*\}', re.DOTALL)
+
+
+def _salvage_truncated_object(text):
+    """잘린 (truncated) JSON 객체에서 **완전하게 끝난 top-level 항목만** 살려낸다.
+
+    judge 응답이 토큰 한도 등으로 중간에서 끊기면 닫는 ``}`` 가 없어 정상 파싱이
+    전부 실패한다 → 5 aspect 점수가 통째로 날아감. 이 함수는 마지막 안전망:
+    outer 객체를 스캔하다 depth 1 (top-level) 에서 만난 마지막 콤마까지를 잘라
+    ``}`` 로 닫아 — 그 전까지 **완전히 끝난 key:value 쌍** 들만 복구한다.
+    중간에 끊긴 마지막 항목은 버린다.
+
+    flat 객체 (개별 aspect judge: ``{"score":..,"reasoning":..}``) 와 중첩 객체
+    (combined judge: ``{"hallucination":{..},"toxicity":{..}}``) 모두에 동작 —
+    top-level 콤마만 경계로 본다.
+
+    :return: 복구된 dict, 또는 복구 불가 시 None.
+    """
+    start = text.find('{')
+    if start < 0:
+        return None
+    s = text[start:]
+    in_str = False
+    esc = False
+    depth = 0
+    last_safe = None   # depth 1 의 마지막 콤마 인덱스 — s[:last_safe] + '}' 가 valid
+    for i, ch in enumerate(s):
+        if in_str:
+            if esc:
+                esc = False
+            elif ch == '\\':
+                esc = True
+            elif ch == '"':
+                in_str = False
+            continue
+        if ch == '"':
+            in_str = True
+        elif ch == '{' or ch == '[':
+            depth += 1
+        elif ch == '}' or ch == ']':
+            depth -= 1
+            if depth == 0:
+                # outer 객체가 정상적으로 닫혔다 (truncation 아님) → 그대로 파싱
+                try:
+                    return json.loads(s[:i + 1])
+                except ValueError:
+                    return None
+        elif ch == ',' and depth == 1:
+            last_safe = i   # 이 콤마 앞까지가 완전히 끝난 쌍들
+    if last_safe is None:
+        return None
+    try:
+        return json.loads(s[:last_safe] + '}')
+    except ValueError:
+        return None
+
+
+def parse_json_response(raw):
+    """judge 의 raw 텍스트에서 JSON 객체를 추출 + 파싱.
+
+    LLM 응답은 ```json ... ``` 펜스나 prefix/suffix 가 붙는 경우가 많아서
+    가장 외곽의 {...} 를 정규식으로 잡아낸 뒤 파싱한다. 그래도 실패하면 (응답이
+    중간에서 잘린 경우) ``_salvage_truncated_object`` 로 완전히 끝난 항목만 복구한다.
+    """
+    if not raw:
+        raise ValueError('empty judge response')
+    text = raw.strip()
+    if text.startswith('```'):
+        first_nl = text.find('\n')
+        if first_nl > 0:
+            text = text[first_nl + 1:]
+        if text.endswith('```'):
+            text = text[:-3]
+        text = text.strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    m = _JSON_BLOCK.search(text)
+    if m:
+        try:
+            return json.loads(m.group(0))
+        except json.JSONDecodeError:
+            pass
+    # 마지막 안전망: 잘린 JSON 에서 완전히 끝난 top-level 항목만 복구.
+    salvaged = _salvage_truncated_object(text)
+    if salvaged:
+        logging.warning(
+            '[LLM] recovered truncated judge JSON — %d top-level key(s) salvaged, '
+            'rest dropped (response likely hit max_tokens)' % len(salvaged),
+            extra={'id': 'LLM065'},
+        )
+        return salvaged
+    raise ValueError('no JSON object found in judge response: %r' % raw[:200])