whatap-python 2.1.0__py3-none-any.whl

whatap/io/data_outputx.py

@@ -0,0 +1,262 @@
+import io
+import math
+import struct
+
+from whatap import PY2, PY3
+from whatap.pack.pack import Pack
+
+from whatap.value.null_value import NullValue
+
+BYTE_MIN_VALUE = -128
+BYTE_MAX_VALUE = 127
+SHORT_MIN_VALUE = -32768
+SHORT_MAX_VALUE = 32767
+INT3_MIN_VALUE = -0x800000
+INT3_MAX_VALUE = 0x007fffff
+INT_MIN_VALUE = -0x80000000
+INT_MAX_VALUE = 0x7fffffff
+LONG5_MIN_VALUE = -0x8000000000
+LONG5_MAX_VALUE = 0x0000007fffffffff
+LONG_MIN_VALUE = -0x8000000000000000
+LONG_MAX_VALUE = 0x7fffffffffffffff
+
+
+class DataOutputX(object):
+    def __init__(self, size=None):
+        if size:
+            self.buffer = io.BytesIO(bytearray(size))
+        else:
+            self.buffer = io.BytesIO()
+
+    @staticmethod
+    def toInt(buf, pos):
+        ch1 = buf[pos] & 0xff
+        ch2 = buf[pos + 1] & 0xff
+        ch3 = buf[pos + 2] & 0xff
+        ch4 = buf[pos + 3] & 0xff
+        return ((ch1 << 24) + (ch2 << 16) + (ch3 << 8) + (ch4 << 0))
+
+    def writePack(self, v, ln_fmt):
+        self.writeShort(v.getPackType())
+        v.write(self)
+        if ln_fmt:
+            remainder = len(self.buffer.getvalue()) % ln_fmt
+            if remainder:
+                self.write(bytearray(int(math.floor(ln_fmt - remainder))))
+        return self
+
+    def writeStep(self, step):
+        self.writeByte(step.getStepType())
+        step.write(self)
+        return self
+
+    @classmethod
+    def toBytes(cls, v, ln_fmt=None):
+        if isinstance(v, Pack):
+            return cls().writePack(v, ln_fmt).toByteArray()
+
+        buf = bytearray(4)
+        buf[0] = ((v % 0x100000000) >> 24) & 0xff
+        buf[1] = ((v % 0x100000000) >> 16) & 0xff
+        buf[2] = ((v % 0x100000000) >> 8) & 0xff
+        buf[3] = ((v % 0x100000000) >> 0) & 0xff
+        return buf
+
+    @classmethod
+    def toBytesLong(cls, v):
+        buf = bytearray(8)
+        buf[0] = ((v % 0x100000000) >> 56) & 0xff
+        buf[1] = ((v % 0x100000000) >> 48) & 0xff
+        buf[2] = ((v % 0x100000000) >> 40) & 0xff
+        buf[3] = ((v % 0x100000000) >> 32) & 0xff
+        buf[4] = ((v % 0x100000000) >> 24) & 0xff
+        buf[5] = ((v % 0x100000000) >> 16) & 0xff
+        buf[6] = ((v % 0x100000000) >> 8) & 0xff
+        buf[7] = ((v % 0x100000000) >> 0) & 0xff
+        return buf
+
+    def set(self, dest, pos, src):
+        dest[pos:pos + len(src)] = src[0:]
+        return dest
+
+    def writeIntBytes(self, b):
+        if not b or not len(b):
+            self.writeInt(0)
+        else:
+            self.writeInt(len(b))
+            self.write(b)
+        return self
+
+    def writeBoolean(self, v):
+        self.buffer.write(struct.pack('>?', v))
+        return self
+
+    def writeByte(self, v):
+        v = v & 0xFF
+        self.buffer.write(struct.pack('>B', v))
+        return self
+
+    def writeShort(self, v):
+        v = v & 0xFFFF
+        self.buffer.write(struct.pack('>H', v))
+        return self
+
+    def writeInt3(self, v):
+        v1 = (v >> 16) & 0xFF
+        v2 = (v >> 8) & 0xFF
+        v3 = (v >> 0) & 0xFF
+        self.buffer.write(struct.pack('>BBB', v1, v2, v3))
+        return self
+
+    def writeInt(self, v):
+        v = v & 0xFFFFFFFF
+        self.buffer.write(struct.pack('>I', v))
+        return self
+
+    def writeLong5(self, v):
+        v1 = ((v >> 32) & 0xFF)
+        v2 = ((v >> 24) & 0xFF)
+        v3 = ((v >> 16) & 0xFF)
+        v4 = ((v >> 8) & 0xFF)
+        v5 = ((v >> 0) & 0xFF)
+        self.buffer.write(struct.pack('>BBBBB', v1, v2, v3, v4, v5))
+        return self
+
+    def writeLong(self, v):
+        v = v & 0xFFFFFFFFFFFFFFFF
+        self.buffer.write(struct.pack('>Q', v))
+        return self
+
+    def writeFloat(self, v):
+        self.buffer.write(struct.pack('>f', v))
+        return self
+
+    def writeDouble(self, v):
+        self.buffer.write(struct.pack('>d', v))
+        return self
+
+    def writeDecimal(self, v):
+        if v == 0:
+            self.writeByte(0)
+        elif BYTE_MIN_VALUE <= v <= BYTE_MAX_VALUE:
+            self.writeByte(1)
+            self.writeByte(v)
+        elif SHORT_MIN_VALUE <= v <= SHORT_MAX_VALUE:
+            self.writeByte(2)
+            self.writeShort(v)
+        elif INT3_MIN_VALUE <= v <= INT3_MAX_VALUE:
+            self.writeByte(3)
+            self.writeInt3(v)
+        elif INT_MIN_VALUE <= v <= INT_MAX_VALUE:
+            self.writeByte(4)
+            self.writeInt(v)
+        elif LONG5_MIN_VALUE <= v <= LONG5_MAX_VALUE:
+            self.writeByte(5)
+            self.writeLong5(v)
+        elif LONG_MIN_VALUE <= v <= LONG_MAX_VALUE:
+            self.writeByte(8)
+            self.writeLong(v)
+        return self
+
+    def write(self, v):
+        self.buffer.write(v)
+        return self
+
+    def writeBlob(self, v):
+        ln = len(v)
+        if not v or not ln:
+            self.writeByte(0)
+        else:
+            if ln <= 253:
+                self.writeByte(ln)
+                self.write(v)
+            elif ln <= 65535:
+                self.writeByte(255)
+                self.writeShort(ln)
+                self.write(v)
+            else:
+                self.writeByte(254)
+                self.writeInt(ln)
+                self.write(v)
+        return self
+
+    def writeText(self, v):
+        if not v:
+            self.writeByte(0)
+        else:
+            self.writeBlob(v.encode("utf-8"))
+        return self
+
+    def writeUTF(self, v):
+        v = v.encode('utf-8')
+        if len(v) > 65535:
+            v = v[:65535]
+
+        self.buffer.write(struct.pack('>H', len(v)))
+        self.buffer.write(v)
+        return self
+
+    def writeValue(self, v):
+        if not v:
+            v = NullValue()
+
+        self.writeByte(v.getValueType())
+        v.write(self)
+        return self
+
+    def toByteArray(self):
+        return self.buffer.getvalue()
+
+    def flush(self):
+        self.buffer.flush()
+
+    def writeFloatArray(self, vv):
+        if not vv:
+            self.writeShort(0)
+        else:
+            self.writeShort(len(vv))
+            for v in vv:
+                self.writeFloat(v)
+        return self
+
+    def writeIntArray(self, vv):
+        if not vv:
+            self.writeShort(0)
+        else:
+            self.writeShort(len(vv))
+            for v in vv:
+                self.writeInt(v)
+        return self
+
+    def writeLongArray(self, vv):
+        if not vv:
+            self.writeShort(0)
+        else:
+            self.writeShort(len(vv))
+            for v in vv:
+                self.writeLong(v)
+        return self
+
+    def writeDecimalArray(self, vv):
+        if not vv:
+            self.writeShort(0)
+        else:
+            self.writeShort(len(vv))
+            for v in vv:
+                self.writeDecimal(v)
+        return self
+
+    def writeToPos(self, pos, v):
+        if PY3:
+            struct.pack_into('>I', self.buffer.getbuffer(), pos, v)
+        else:
+            b = io.BytesIO()
+            b.write(struct.pack('>I', v & 0xFFFFFFFF))
+
+            buffer_arr = bytearray(self.buffer.getvalue())
+            buffer_arr[pos:pos + 4] = b.getvalue()
+            self.buffer = io.BytesIO(buffer_arr)
+
+    def size(self):
+        return self.buffer.getbuffer().nbytes
+        

whatap/llm/__init__.py

@@ -0,0 +1,17 @@
+from whatap.llm.log_sink_packs.llm_step_status import LlmStepStatus
+
+# Public API: prompt 메타 (이름/버전) 데코레이터 + 컨텍스트 매니저.
+# LLM API 호출 시 메트릭/pack 의 ``operation_type`` 태그에 name 이, ``prompt_version``
+# 태그에 version 이 자동 인라인. 미적용 시 default/v1.
+from whatap.llm.prompt_meta import (
+    prompt_meta,
+    prompt_meta_scope,
+    get_prompt_meta,
+)
+
+__all__ = [
+    'LlmStepStatus',
+    'prompt_meta',
+    'prompt_meta_scope',
+    'get_prompt_meta',
+]

whatap/llm/definitions.py

@@ -0,0 +1,43 @@
+"""LLM 패키지에서 사용하는 상수 및 매핑 데이터 정의."""
+LOG_SINK_CATEGORY = '#LlmCallLog'
+
+PROVIDER_TOKEN_FIELDS = {
+    'openai': [
+        'input_tokens', 'output_tokens', 'total_tokens_count',
+        'cached_tokens', 'reasoning_tokens',
+        'audio_input_tokens', 'audio_output_tokens',
+        'accepted_prediction_tokens', 'rejected_prediction_tokens',
+        'embedding_count', 'dimensions', 'similarity',
+    ],
+    'anthropic': [
+        'input_tokens', 'output_tokens', 'total_tokens_count',
+        'cache_creation_input_tokens', 'cache_read_input_tokens',
+    ],
+}
+
+DEFAULT_TOKEN_FIELDS = ['input_tokens', 'output_tokens', 'total_tokens_count']
+
+OPENAI_URL_OPERATION_MAP = [
+    ("/v1/chat/completions", "chat"),
+    ("/v1/responses", "response"),
+    ("/v1/completions", "completion"),
+    ("/v1/embeddings", "embedding"),
+    ("/v1/images/generations", "image_generation"),
+    ("/v1/images/edits", "image_edit"),
+    ("/v1/audio/transcriptions", "audio_transcription"),
+    ("/v1/audio/translations", "audio_translation"),
+    ("/v1/audio/speech", "audio_speech"),
+    ("/v1/moderations", "moderation"),
+    ("/v1/fine_tuning", "fine_tuning"),
+    ("/v1/files", "file"),
+    ("/v1/assistants", "assistant"),
+    ("/v1/threads", "thread"),
+    ("/v1/vector_stores", "vector_store"),
+    ("/v1/batches", "batch"),
+]
+
+ANTHROPIC_URL_OPERATION_MAP = [
+    ("/v1/messages", "chat"),
+]
+
+URL_OPERATION_MAP = OPENAI_URL_OPERATION_MAP + ANTHROPIC_URL_OPERATION_MAP

whatap/llm/evaluators/__init__.py

@@ -0,0 +1,136 @@
+"""WhatAP LLM Evaluation SDK 공개 API.
+
+권장 사용 패턴 — 데코레이터 / 컨텍스트 매니저로 트랜잭션·함수 단위 적용:
+    from whatap.llm.evaluators import evaluate_with, evaluation_scope
+    from whatap.llm.evaluators.builtins import HallucinationEvaluator, RefusalEvaluator
+
+    @evaluate_with(HallucinationEvaluator(judge_fn=judge), RefusalEvaluator())
+    def chat(question):
+        return client.chat.completions.create(...).choices[0].message.content
+
+    # 또는
+    def chat(question):
+        with evaluation_scope(HallucinationEvaluator(judge_fn=judge)):
+            return client.chat.completions.create(...).choices[0].message.content
+
+전역 always-on (앱 전체 LLM 호출에 무조건 적용 — PII 검사 등에 적합):
+    from whatap.llm.evaluators import register_evaluator
+    register_evaluator(PIILeakEvaluator())   # 앱 시작 시 한 번
+
+명시 평가 (사용자 피드백 등 시점이 다른 평가):
+    from whatap.llm.evaluators import submit_evaluation
+    submit_evaluation(label='user_thumbs', value=1.0, txid=req.txid, step_id=req.step_id)
+
+활성화:
+    whatap.conf 에 ``llm_eval_enabled=true`` 또는
+    환경변수 ``WHATAP_LLM_EVAL_ENABLED=true``.
+"""
+import time
+
+from whatap import logging
+
+from whatap.llm.evaluators.base import (
+    BaseEvaluator,
+    EvaluatorContext,
+    EvaluatorResult,
+)
+from whatap.llm.evaluators.registry import (
+    EvaluatorRegistry,
+    register_evaluator,
+    unregister_evaluator,
+)
+from whatap.llm.evaluators.scope import (
+    evaluate_with,
+    evaluation_scope,
+)
+
+
+def submit_evaluation(label, value, metric_type=None, reasoning=None,
+                      metadata=None, txid=None, step_id=None, index=None):
+    """사용자가 명시적으로 평가 결과를 송출한다.
+
+    데이터독 ``LLMObs.submit_evaluation()`` 의 등가물.
+    호출 시점의 TraceContext 에서 (txid, step_id, index) 를 자동 추출하므로
+    LLM 호출 트랜잭션 안에서 호출하면 그대로 결합된다. 다른 스레드/태스크에서 호출
+    한다면 인자로 명시 전달하면 된다.
+
+    :param label: 평가 라벨 (필수, e.g. 'user_satisfaction').
+    :param value: 평가 값 (bool/int/float/str/dict).
+    :param metric_type: 'score'|'categorical'|'boolean'|'json'. 미지정 시 value 타입에서 추론.
+    :param reasoning: 평가 근거 (선택).
+    :param metadata: 임의 dict (선택).
+    :param txid, step_id, index: 결합 키 명시. 미지정 시 현재 TraceContext 에서 자동 추출.
+    """
+    if not label:
+        logging.warning('[LLM] submit_evaluation: missing label', extra={'id': 'LLM050'})
+        return
+    if '.' in label:
+        logging.warning('[LLM] submit_evaluation: label must not contain "." (got %s)' % label,
+                        extra={'id': 'LLM051'})
+        return
+
+    # context binding: 인자로 명시되지 않았으면 TraceContext 에서 추출
+    if txid is None or step_id is None:
+        try:
+            from whatap.trace.trace_context_manager import TraceContextManager
+            ctx = TraceContextManager.getLocalContext()
+            if ctx is not None:
+                if txid is None:
+                    txid = str(ctx.id)
+                if step_id is None:
+                    step_id = str(getattr(ctx, '_llm_step_id', 0))
+                if index is None:
+                    index = getattr(ctx, '_llm_call_index', 0)
+        except Exception:
+            pass
+
+    if txid is None:
+        logging.warning('[LLM] submit_evaluation: no active trace context (label=%s)' % label,
+                        extra={'id': 'LLM052'})
+        return
+
+    # metric_type 자동 추론
+    if metric_type is None:
+        if isinstance(value, bool):
+            metric_type = 'boolean'
+        elif isinstance(value, (int, float)):
+            metric_type = 'score'
+        elif isinstance(value, dict):
+            metric_type = 'json'
+        else:
+            metric_type = 'categorical'
+            if value is not None and not isinstance(value, str):
+                value = str(value)
+
+    try:
+        from whatap.llm.log_sink_packs.llm_step_eval_status import LlmStepEvalStatus
+        from whatap.counter.tasks.llm_evaluator_task import _LABEL_TO_FIELD
+        from whatap.counter.tasks.llm_log_sink_task import dispatch_llm_evaluation_pack
+        pack = LlmStepEvalStatus()
+        pack.txid = str(txid)
+        pack.step_id = str(step_id) if step_id is not None else None
+        pack.index = int(index) if index is not None else 0
+        # Late-binding user feedback — 원본 LLM 호출 메타 (model/tokens/cost) 모름.
+        # eval_success 와 5 점수 필드 중 매핑되는 것만 채움.
+        pack.eval_success = True if metric_type != 'error' else False
+        attr = _LABEL_TO_FIELD.get(label)
+        if attr is not None and isinstance(value, (int, float)) and not isinstance(value, bool):
+            setattr(pack, attr, float(value))
+        dispatch_llm_evaluation_pack(pack)
+    except Exception as e:
+        logging.warning('[LLM] submit_evaluation failed: %s' % e, extra={'id': 'LLM053'})
+
+
+__all__ = [
+    'BaseEvaluator',
+    'EvaluatorContext',
+    'EvaluatorResult',
+    # primary: per-scope application
+    'evaluate_with',
+    'evaluation_scope',
+    # secondary: app-wide always-on
+    'register_evaluator',
+    'unregister_evaluator',
+    # late-binding (e.g. user feedback)
+    'submit_evaluation',
+]

whatap/llm/evaluators/base.py

@@ -0,0 +1,114 @@
+"""LLM 평가자 베이스 타입 정의.
+
+EvaluatorContext  : 평가자에 전달되는 읽기전용 입력 (LLM 호출의 결과 + 결합키).
+EvaluatorResult   : 평가자가 반환하는 표준 결과 컨테이너.
+BaseEvaluator     : 사용자가 상속하여 evaluate() 를 구현하는 베이스 클래스.
+
+데이터독 LLMObs 의 BaseEvaluator + EvaluatorContext + EvaluatorResult 와 같은 역할이며,
+WhatAP 의 (txid, step_id, index) 를 결합키로 사용한다.
+"""
+from collections import namedtuple
+
+
+# frozen 컨테이너로 evaluator가 입력을 변경하지 못하도록 한다.
+EvaluatorContext = namedtuple(
+    'EvaluatorContext',
+    [
+        # ── 결합 키 (LlmStepStatus 와 동일) ──
+        'txid',              # str — TraceContext.id
+        'step_id',            # str — ctx._llm_step_id
+        'index',              # int — 트랜잭션 내 LLM 호출 순번
+
+        # ── LLM 메타 ──
+        'provider',           # str — e.g. 'api.openai.com'
+        'url',                # str — e.g. '/v1/chat/completions'
+        'model',              # str
+        'operation_type',     # str — 'chat'|'embedding'|'completion'|...
+
+        # ── I/O 텍스트 (interceptor 가 추출한 원본) ──
+        'input_text',         # str — prompt 본문
+        'output_text',        # str — completion 본문
+        'system_text',        # str — system message (여러 개면 \n으로 결합)
+        'reasoning_text',     # str — reasoning 본문 (없으면 '')
+        'tool_calls_text',    # str
+        'tool_results_text',  # str
+
+        # ── 결과 메타 ──
+        'success',            # bool
+        'finish_reason',      # str|None
+        'latency_ms',         # int|None
+        'input_tokens',       # int|None
+        'output_tokens',      # int|None
+
+        # ── 평가용 인프라 자동 전파 ──
+        # interceptor 가 캡처한 user 의 LLM client 객체 그대로.
+        # judge 호출은 이 client 인스턴스를 그대로 재사용 — 새 client / httpx 생성 안 함.
+        'client',             # OpenAI|AsyncOpenAI|Anthropic|...|None
+
+        # interceptor 가 async 호출 시점에 캡처한 user 의 running event loop.
+        # AsyncClient 는 loop binding 이 있어 sync 워커에서 그 client 로 호출하려면
+        # 같은 loop 으로 ``run_coroutine_threadsafe`` dispatch 필요. sync 호출이거나
+        # capture 실패하면 None — 그땐 client 가 sync 라 직접 호출 가능.
+        'event_loop',         # asyncio.AbstractEventLoop|None
+    ],
+)
+EvaluatorContext.__new__.__defaults__ = (None,)  # event_loop default
+
+
+class EvaluatorResult(object):
+    """평가 결과 표준 컨테이너.
+
+    evaluator.evaluate() 가 raw value(bool/int/float/str/dict) 를 반환해도
+    LlmEvaluatorTask 가 자동으로 EvaluatorResult 로 래핑한다.
+
+    ``extras`` 는 한 번의 evaluate() 호출에서 여러 라벨의 메트릭을 같이 송출하고
+    싶을 때 사용. 예: CombinedJudgeEvaluator 는 1번의 LLM judge 호출에서
+    hallucination + answer_relevance + toxicity 를 모두 산출하는데, primary 결과
+    (combined_judge) 에 extras={'hallucination': ..., ...} 를 붙여 모두 같은
+    LlmStepStatus pack 에 인라인되도록 한다.
+
+    ``extras`` 의 값은 ``EvaluatorResult`` 인스턴스 또는 ``(value, metric_type,
+    reasoning, metadata)`` 형태의 dict.
+    """
+
+    __slots__ = ('value', 'metric_type', 'reasoning', 'metadata', 'extras')
+
+    def __init__(self, value, metric_type=None, reasoning=None, metadata=None,
+                 extras=None):
+        self.value = value
+        # metric_type 미지정 시 LlmEvaluatorTask 에서 value 타입으로 자동 추론.
+        self.metric_type = metric_type
+        self.reasoning = reasoning
+        self.metadata = metadata or {}
+        # extras: {label: EvaluatorResult or dict}
+        self.extras = extras or {}
+
+
+class BaseEvaluator(object):
+    """모든 평가자의 베이스. 사용자는 LABEL 과 evaluate() 를 구현한다.
+
+    Example:
+        class OutputLengthEvaluator(BaseEvaluator):
+            LABEL = 'output_length'
+            METRIC_TYPE = 'score'
+
+            def evaluate(self, context):
+                return float(len(context.output_text))
+
+    모든 평가자는 평가 워커 스레드 풀에서 비동기로 실행되며, 결과는 별도
+    ``LlmStepEvalStatus`` pack (llm_log_type=llm_step_eval_status) 으로 송출된다.
+    원본 LlmStepStatus 와 동일한 구조 (model/tokens/cost/...) + 평가 점수 5 필드.
+    """
+
+    LABEL = None        # 필수: 샘플러 매칭 키 + 메트릭 라벨. None이면 LlmEvaluatorTask가 거부.
+    METRIC_TYPE = None  # 선택: 'score'|'categorical'|'boolean'|'json'. None이면 자동 추론.
+
+    def evaluate(self, context):
+        """단일 LLM 호출에 대한 평가를 수행한다.
+
+        :param context: EvaluatorContext — 읽기전용 입력.
+        :return: EvaluatorResult, 또는 raw value (bool/int/float/str/dict).
+                 raw value 반환 시 LlmEvaluatorTask 가 EvaluatorResult 로 래핑하며
+                 metric_type 은 value 타입으로 자동 추론된다.
+        """
+        raise NotImplementedError

whatap/llm/evaluators/builtins/__init__.py

@@ -0,0 +1,91 @@
+"""WhatAP LLM Evaluation 빌트인 평가자.
+
+LLM judge 기반 평가자는 별도 LLM 호출(judge call)로 점수를 산출하므로 비용이
+발생한다. ``whatap.conf`` 의 ``llm_eval_sample_rate`` (0.0~1.0) 로 샘플링 비율을
+조정해 비용을 통제한다. 기본 1.0 (항상 실행) — 비용 통제가 필요하면 0.1 같은
+값으로 낮춰서 judge 호출의 1/10 만 실제로 발생시킬 수 있음.
+
+규칙 기반 평가자 (PIILeak / URLScan) 는 LLM 호출이 없어 비용 0 — 매 호출 평가해도 됨.
+
+사용 예 — 함수 데코레이터로 트랜잭션 단위 적용 (권장):
+
+    import openai
+    from whatap.llm.evaluators import evaluate_with
+    from whatap.llm.evaluators.builtins import (
+        CombinedJudgeEvaluator, PIILeakEvaluator, URLScanEvaluator,
+        make_openai_judge,
+    )
+
+    client = openai.OpenAI()
+    judge = make_openai_judge(client=client, model='gpt-4o-mini')
+
+    @evaluate_with(
+        CombinedJudgeEvaluator(judge_fn=judge),  # 5 의미 aspect 1번 호출
+        PIILeakEvaluator(),                      # 정규식, 비용 0
+        URLScanEvaluator(),                      # 정규식, 비용 0
+    )
+    def chat(question: str) -> str:
+        return client.chat.completions.create(
+            model='gpt-4o',
+            messages=[{'role': 'user', 'content': question}],
+        ).choices[0].message.content
+
+평가자 종류:
+
+    LLM judge 기반 (judge call 발생) ─────────────────────────────────
+    HallucinationEvaluator    할루시네이션 0.0~1.0 (faithfulness / self-consistency)
+    AnswerRelevanceEvaluator  질문↔답변 관련성 0.0~1.0
+    ToxicityEvaluator         유해성 0.0~1.0 + 카테고리
+    PromptInjectionEvaluator  prompt injection / system prompt leak 0.0~1.0
+    FactualityEvaluator       검증 가능한 사실 오류 0.0~1.0
+    CombinedJudgeEvaluator    위 5 개를 1번의 judge 호출로 모두 산출 (비용 1/5)
+
+    규칙 기반 (judge call 0회, 비용 0) ───────────────────────────────
+    PIILeakEvaluator          정규식+chksum 으로 PII 노출 탐지
+    URLScanEvaluator          URL 추출 + suspicious 패턴 매칭
+
+Judge LLM 호출 헬퍼:
+
+    make_openai_judge(client=..., model='gpt-4o-mini')
+    make_anthropic_judge(client=..., model='claude-3-5-haiku-latest')
+
+커스텀 judge 작성 시 ``LLMJudgeBase`` 상속하고 ``make_prompt`` / ``parse_judgment`` 만
+구현하면 된다.
+"""
+from whatap.llm.evaluators.builtins.llm_judge import (
+    LLMJudgeBase,
+    make_openai_judge,
+    make_anthropic_judge,
+    parse_json_response,
+    set_default_judge_fn,
+    get_default_judge_fn,
+)
+from whatap.llm.evaluators.builtins.hallucination import HallucinationEvaluator
+from whatap.llm.evaluators.builtins.answer_relevance import AnswerRelevanceEvaluator
+from whatap.llm.evaluators.builtins.toxicity import ToxicityEvaluator
+from whatap.llm.evaluators.builtins.prompt_injection import PromptInjectionEvaluator
+from whatap.llm.evaluators.builtins.factuality import FactualityEvaluator
+from whatap.llm.evaluators.builtins.combined_judge import CombinedJudgeEvaluator
+from whatap.llm.evaluators.builtins.pii_leak import PIILeakEvaluator
+from whatap.llm.evaluators.builtins.url_scan import URLScanEvaluator
+
+
+__all__ = [
+    # judge base + helpers
+    'LLMJudgeBase',
+    'make_openai_judge',
+    'make_anthropic_judge',
+    'parse_json_response',
+    'set_default_judge_fn',
+    'get_default_judge_fn',
+    # LLM judge 기반
+    'HallucinationEvaluator',
+    'AnswerRelevanceEvaluator',
+    'ToxicityEvaluator',
+    'PromptInjectionEvaluator',
+    'FactualityEvaluator',
+    'CombinedJudgeEvaluator',
+    # 규칙 기반 (LLM 호출 X)
+    'PIILeakEvaluator',
+    'URLScanEvaluator',
+]