whatap-python 2.1.0__py3-none-any.whl

whatap/llm/evaluators/registry.py

@@ -0,0 +1,192 @@
+"""평가자 등록소 (전역 싱글톤).
+
+사용자가 등록한 BaseEvaluator 인스턴스 리스트를 보관하고,
+LlmEvaluatorTask 의 dispatcher 스레드가 매 큐 처리 시 이 리스트를 순회한다.
+
+또한 ``bootstrap_from_conf()`` 가 ``conf.llm_eval_evaluators`` (csv) 를 읽어
+빌트인 평가자를 자동 등록한다. LlmEvaluatorTask 시작 시 한 번 호출.
+"""
+import threading
+
+from whatap import logging
+from whatap.conf.configure import Configure as conf
+
+
+# label → builtin evaluator class 의 import path. lazy import — 빌트인 모듈이
+# 아직 로딩 안 됐을 수도 있어서.
+_BUILTIN_LABELS = (
+    'combined_judge',
+    'hallucination',
+    'answer_relevance',
+    'toxicity',
+    'prompt_injection',
+    'factuality',
+    'pii_leak',
+    'url_scan',
+)
+
+# default (conf 미지정 시) 자동 활성 라벨.
+# combined_judge 가 5 의미 aspect (hallucination/answer_relevance/toxicity/
+# prompt_injection/factuality) 를 1번의 judge 호출로 묶어 처리하므로 개별 evaluator
+# 들을 같이 켜면 중복. default 는 combined_judge + 규칙 기반 2 개.
+_DEFAULT_LABELS = ('combined_judge', 'pii_leak', 'url_scan')
+
+
+def _instantiate(label):
+    """label 에 해당하는 빌트인 평가자 인스턴스 생성. judge_fn 미지정으로 두면
+    evaluate 시점에 ``_resolve_judge_fn`` 이 ctx.provider 자동 판별 + 전역 default
+    사용."""
+    try:
+        from whatap.llm.evaluators import builtins as B
+    except Exception as e:
+        logging.warning('[LLM] failed to import builtin evaluators: %s' % e,
+                        extra={'id': 'LLM044'})
+        return None
+
+    cls_map = {
+        'combined_judge': B.CombinedJudgeEvaluator,
+        'hallucination': B.HallucinationEvaluator,
+        'answer_relevance': B.AnswerRelevanceEvaluator,
+        'toxicity': B.ToxicityEvaluator,
+        'prompt_injection': B.PromptInjectionEvaluator,
+        'factuality': B.FactualityEvaluator,
+        'pii_leak': B.PIILeakEvaluator,
+        'url_scan': B.URLScanEvaluator,
+    }
+    cls = cls_map.get(label)
+    if cls is None:
+        logging.warning('[LLM] unknown evaluator label in conf.llm_eval_evaluators: %r '
+                        '(valid: %s)' % (label, ', '.join(_BUILTIN_LABELS)),
+                        extra={'id': 'LLM045'})
+        return None
+    try:
+        return cls()
+    except Exception as e:
+        logging.warning('[LLM] failed to instantiate evaluator %s: %s' % (label, e),
+                        extra={'id': 'LLM046'})
+        return None
+
+
+def _parse_labels(raw):
+    """csv 또는 빈 문자열을 라벨 list 로 파싱. 빈 값은 default."""
+    if raw is None:
+        return list(_DEFAULT_LABELS)
+    s = str(raw).strip()
+    if not s:
+        return list(_DEFAULT_LABELS)
+    out = []
+    for tok in s.split(','):
+        tok = tok.strip().lower()
+        if tok and tok not in out:
+            out.append(tok)
+    return out or list(_DEFAULT_LABELS)
+
+
+class EvaluatorRegistry(object):
+    """전역 평가자 등록소."""
+
+    _instance = None
+    _lock = threading.Lock()
+
+    def __init__(self):
+        self._evaluators = []
+        self._reg_lock = threading.Lock()
+
+    @classmethod
+    def get_instance(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def register(self, evaluator):
+        """평가자 인스턴스를 등록한다. 같은 LABEL 이 이미 있으면 교체.
+
+        :param evaluator: BaseEvaluator 인스턴스.
+        """
+        from whatap.llm.evaluators.base import BaseEvaluator
+        if not isinstance(evaluator, BaseEvaluator):
+            logging.warning('[LLM] register_evaluator: not a BaseEvaluator: %r' % evaluator,
+                            extra={'id': 'LLM040'})
+            return
+        if not evaluator.LABEL:
+            logging.warning('[LLM] register_evaluator: missing LABEL on %r' % evaluator,
+                            extra={'id': 'LLM041'})
+            return
+        with self._reg_lock:
+            self._evaluators = [e for e in self._evaluators if e.LABEL != evaluator.LABEL]
+            self._evaluators.append(evaluator)
+
+    def unregister(self, label):
+        """라벨로 평가자를 제거한다."""
+        with self._reg_lock:
+            self._evaluators = [e for e in self._evaluators if e.LABEL != label]
+
+    def all(self):
+        """현재 등록된 평가자 리스트의 스냅샷을 반환한다."""
+        with self._reg_lock:
+            return list(self._evaluators)
+
+    def is_empty(self):
+        return not self._evaluators
+
+    def clear(self):
+        with self._reg_lock:
+            self._evaluators = []
+
+
+def register_evaluator(evaluator):
+    """공개 API: 평가자 등록."""
+    EvaluatorRegistry.get_instance().register(evaluator)
+
+
+def unregister_evaluator(label):
+    """공개 API: 평가자 제거."""
+    EvaluatorRegistry.get_instance().unregister(label)
+
+
+_bootstrap_done = False
+_bootstrap_lock = threading.Lock()
+
+
+def bootstrap_from_conf():
+    """``conf.llm_eval_evaluators`` 의 csv 라벨 목록으로 빌트인 평가자를 자동 등록.
+
+    이미 사용자가 ``register_evaluator()`` 로 같은 라벨을 등록했으면 register() 가
+    그걸 교체하지 않고 그대로 둔다 (사용자 등록 우선).
+
+    LlmEvaluatorTask._ensure_started() 에서 첫 번째 enqueue 시점에 1회 호출.
+    """
+    global _bootstrap_done
+    if _bootstrap_done:
+        return
+    with _bootstrap_lock:
+        if _bootstrap_done:
+            return
+
+        labels = _parse_labels(getattr(conf, 'llm_eval_evaluators', ''))
+        registry = EvaluatorRegistry.get_instance()
+        already = {e.LABEL for e in registry.all()}
+
+        added = []
+        for label in labels:
+            if label in already:
+                # 사용자가 명시적으로 register 한 거 — 그대로 보존
+                continue
+            inst = _instantiate(label)
+            if inst is None:
+                continue
+            registry.register(inst)
+            added.append(label)
+
+        if added:
+            logging.info('[LLM] auto-registered builtin evaluators from conf: %s'
+                         % ', '.join(added), extra={'id': 'LLM047'})
+        _bootstrap_done = True
+
+
+def _reset_bootstrap_for_test():
+    """테스트용 — bootstrap 재실행 가능하게."""
+    global _bootstrap_done
+    _bootstrap_done = False

whatap/llm/evaluators/sampler.py

@@ -0,0 +1,83 @@
+"""평가자 샘플링 — judge LLM 호출 비용 통제.
+
+``whatap.conf`` 의 ``llm_eval_sample_rate`` (float 0.0~1.0) 하나로 동작:
+
+- 1.0 (기본) — 모든 judge 평가자 항상 실행
+- 0.5       — judge 평가자 50% 만 실행
+- 0.0       — judge 평가자 전부 skip
+
+규칙 기반 평가자 (``USES_LLM_JUDGE=False`` — PIILeak / URLScan / 사용자 custom 등)
+는 비용 0 이라 항상 100% 실행 — rate 영향 받지 않음.
+
+샘플링은 txid 해시 기반 결정론적이라 같은 트랜잭션은 항상 같은 결정을 받는다.
+"""
+import threading
+
+from whatap import logging
+from whatap.conf.configure import Configure as conf
+
+
+class EvaluatorSampler(object):
+    """평가자 샘플링 결정 엔진.
+
+    호출 시 ``conf.llm_eval_sample_rate`` 를 매번 다시 읽어 런타임 변경 반영.
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._cached_raw = None
+        self._cached_rate = 1.0
+
+    def _get_rate(self):
+        """conf.llm_eval_sample_rate 를 float 으로 안전 변환. 변경 감지 + 캐시.
+
+        파싱 실패 / 범위 밖이면 1.0 (keep all) — 안전 default.
+        """
+        raw = getattr(conf, 'llm_eval_sample_rate', 1.0)
+        if raw == self._cached_raw:
+            return self._cached_rate
+        try:
+            v = float(raw)
+        except (TypeError, ValueError):
+            logging.warning('[LLM] invalid llm_eval_sample_rate: %r — fallback to 1.0' % raw,
+                            extra={'id': 'LLM042'})
+            v = 1.0
+        v = max(0.0, min(1.0, v))
+        with self._lock:
+            self._cached_raw = raw
+            self._cached_rate = v
+        return v
+
+    def should_run(self, evaluator, txid):
+        """샘플링 결정.
+
+        :param evaluator: BaseEvaluator 인스턴스. ``USES_LLM_JUDGE`` 플래그를 본다.
+        :param txid: 트랜잭션 ID. 같은 txid → 같은 결정 (결정론적 샘플링).
+        :return: True 면 평가 실행, False 면 skip.
+        """
+        # 규칙 기반 (judge 호출 없음 = 비용 0) → 항상 실행
+        if not getattr(evaluator, 'USES_LLM_JUDGE', False):
+            return True
+
+        rate = self._get_rate()
+        if rate >= 1.0:
+            return True
+        if rate <= 0.0:
+            return False
+        return _deterministic_unit(txid) < rate
+
+
+def _deterministic_unit(txid):
+    """txid 로부터 [0, 1) 결정론적 값을 만든다.
+
+    같은 txid → 같은 값. 다른 txid → 균등 분포.
+    """
+    if txid is None:
+        return 0.0
+    try:
+        seed = abs(int(txid))
+    except (TypeError, ValueError):
+        seed = abs(hash(txid))
+    # Knuth multiplicative hash
+    h = (seed * 2654435761) & 0xFFFFFFFF
+    return h / float(1 << 32)

whatap/llm/evaluators/scope.py

@@ -0,0 +1,334 @@
+"""스코프 기반 평가자 적용 — 데코레이터 + 컨텍스트 매니저.
+
+전역 ``register_evaluator()`` 는 모든 LLM 호출에 평가자를 적용한다.
+대부분의 경우 사용자는 특정 트랜잭션/함수에만 평가를 붙이고 싶어한다.
+이 모듈이 그 자연스러운 패턴을 제공한다.
+
+사용 예 (데코레이터):
+    from whatap.llm.evaluators import evaluate_with
+    from whatap.llm.evaluators.builtins import HallucinationEvaluator, make_openai_judge
+
+    judge = make_openai_judge(client=openai.OpenAI(), model='gpt-4o-mini')
+
+    @evaluate_with(HallucinationEvaluator(judge_fn=judge))
+    def chat(question: str) -> str:
+        return client.chat.completions.create(...).choices[0].message.content
+
+사용 예 (컨텍스트 매니저):
+    from whatap.llm.evaluators import evaluation_scope
+
+    def chat(question):
+        with evaluation_scope(HallucinationEvaluator(judge_fn=judge)):
+            return client.chat.completions.create(...).choices[0].message.content
+
+스코프 안에서 일어난 LLM 호출에만 해당 평가자가 적용된다. 전역 ``register_evaluator``
+로 등록된 평가자가 있다면 함께 실행되며 (merge), 같은 LABEL 인 경우 스코프 평가자가 우선.
+
+Storage:
+  1) trace context (있으면) — interceptor 의 hot path 에서 같은 ctx 로 빠르게 lookup
+  2) ContextVar (항상)      — asyncio.create_task / TaskGroup 으로 분기된 sub-task 도
+                              inherit. 같은 task chain 이면 ContextVar 가 같은 list 를
+                              가리켜 trace ctx 와 자동 sync.
+
+이전엔 fallback 이 ``threading.local()`` 이라 같은 스레드의 다른 asyncio task 들이 같은
+스코프를 공유 (cross-task contamination 위험) + ``asyncio.create_task`` 로 분기된 task
+는 trace ctx 가 다를 수 있어 못 보는 hole 이 있었음. ContextVar 로 둘 다 해결.
+"""
+import asyncio
+import contextvars
+import functools
+import inspect
+
+from whatap import logging
+
+
+# task 별로 격리되는 storage. asyncio.create_task / TaskGroup 으로 분기된 task 도
+# 시작 시점의 ContextVar snapshot 을 inherit 하므로 sub-task 안에서 LLM 호출 시 scope
+# 가 그대로 보임. None 이 default — append 시점에 list 생성.
+_scope_cv = contextvars.ContextVar('whatap_llm_scope_evaluators', default=None)
+
+
+def _ensure_cv_list():
+    cur = _scope_cv.get()
+    if cur is None:
+        cur = []
+        _scope_cv.set(cur)
+    return cur
+
+
+def _ensure_ctx_list(ctx):
+    if not hasattr(ctx, '_llm_scope_evaluators'):
+        ctx._llm_scope_evaluators = []
+    return ctx._llm_scope_evaluators
+
+
+def _get_active_storages():
+    """현재 활성 storage list 들을 반환 — (trace ctx + ContextVar) 양쪽 동시.
+
+    enter 시 양쪽 모두에 evaluator 추가, exit 시 양쪽 모두에서 제거. 그래야:
+      - LLM 호출 시점 trace ctx 기준 lookup 이 빠름 (hot path)
+      - asyncio.create_task / 다른 sub-task 에서도 ContextVar inherit 으로 보임
+    """
+    storages = []
+    try:
+        from whatap.trace.trace_context_manager import TraceContextManager
+        ctx = TraceContextManager.getLocalContext()
+        if ctx is not None:
+            storages.append(_ensure_ctx_list(ctx))
+    except Exception:
+        pass
+    storages.append(_ensure_cv_list())
+    return storages
+
+
+def get_scope_evaluators():
+    """LlmEvaluatorTask.enqueue 에서 호출. 현재 활성 스코프의 평가자 리스트.
+
+    trace ctx 와 ContextVar 양쪽을 합치고 같은 객체는 dedup (id 기반). 둘이 sync 되어
+    있으면 같은 entry 가 양쪽에 있을 수 있어 dedup 필요.
+    """
+    seen = set()
+    out = []
+    try:
+        from whatap.trace.trace_context_manager import TraceContextManager
+        ctx = TraceContextManager.getLocalContext()
+        if ctx is not None:
+            ctx_list = getattr(ctx, '_llm_scope_evaluators', None)
+            if ctx_list:
+                for e in ctx_list:
+                    if id(e) not in seen:
+                        seen.add(id(e))
+                        out.append(e)
+    except Exception:
+        pass
+    cv_list = _scope_cv.get()
+    if cv_list:
+        for e in cv_list:
+            if id(e) not in seen:
+                seen.add(id(e))
+                out.append(e)
+    return out
+
+
+class evaluation_scope(object):
+    """LLM 호출에 평가자를 스코프 단위로 적용하는 컨텍스트 매니저.
+
+    Example:
+        with evaluation_scope(HallucinationEvaluator(judge_fn=judge), RefusalEvaluator()):
+            response = client.chat.completions.create(...)
+
+    중첩 가능:
+        with evaluation_scope(EvalA()):
+            with evaluation_scope(EvalB()):
+                # 안쪽 호출에는 EvalA + EvalB 모두 적용
+
+    스코프 종료 시 해당 평가자들만 제거 (밖의 스코프는 그대로).
+    """
+
+    def __init__(self, *evaluators):
+        # BaseEvaluator 인스턴스만 필터 (LABEL 없으면 무의미)
+        from whatap.llm.evaluators.base import BaseEvaluator
+        self._evaluators = [
+            e for e in evaluators
+            if isinstance(e, BaseEvaluator) and getattr(e, 'LABEL', None)
+        ]
+        if len(self._evaluators) != len(evaluators):
+            logging.warning(
+                '[LLM] evaluation_scope: %d non-evaluator/no-LABEL items ignored'
+                % (len(evaluators) - len(self._evaluators)),
+                extra={'id': 'LLM045'},
+            )
+        self._storages = None
+        self._inserted_count = 0
+        self._inserted_ids = None
+
+    def __enter__(self):
+        if not self._evaluators:
+            return self
+        self._storages = _get_active_storages()
+        # 우리가 추가한 evaluator 들을 id 집합으로 기억 — exit 시점에 정확히 그 id 만 제거.
+        # 단순 ``del s[-N:]`` 는 외부 코드가 같은 storage 에 append 한 경우 잘못된
+        # 항목까지 잘라낼 위험. id() 매칭은 중첩 스코프 안전 + 외부 leak 에 robust.
+        self._inserted_ids = set(id(e) for e in self._evaluators)
+        for s in self._storages:
+            s.extend(self._evaluators)
+        self._inserted_count = len(self._evaluators)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if not self._storages or self._inserted_count == 0:
+            return False
+        # storage 끝에서부터 우리 id 매칭하는 항목만 제거. LIFO 원칙 + 외부 mutation 에 안전.
+        try:
+            for s in self._storages:
+                self._remove_inserted(s)
+        except Exception as e:
+            logging.warning('[LLM] evaluation_scope cleanup failed: %s' % e,
+                            extra={'id': 'LLM046'})
+        finally:
+            self._storages = None
+            self._inserted_count = 0
+            self._inserted_ids = None
+        return False  # 예외 propagate
+
+    def _remove_inserted(self, storage):
+        """우리가 enter 시 push 한 evaluator id 들을 storage 에서 정확히 제거.
+
+        역순 (LIFO) 으로 훑어 id() 일치 항목만 del. 외부 코드가 같은 storage 에
+        다른 evaluator 를 append 했더라도 영향 없음.
+        """
+        remaining = set(self._inserted_ids)
+        for i in range(len(storage) - 1, -1, -1):
+            if not remaining:
+                break
+            if id(storage[i]) in remaining:
+                remaining.discard(id(storage[i]))
+                del storage[i]
+
+
+def _is_streaming_response(obj):
+    """FastAPI/Starlette StreamingResponse (또는 호환 객체) 감지."""
+    # body_iterator 어트리뷰트로 식별 (Starlette/FastAPI 표준)
+    return hasattr(obj, 'body_iterator')
+
+
+def _wrap_async_iter_with_scope(orig_iter, scope):
+    """async iterator 를 감싸서 소진/예외 시 scope 정리."""
+    async def wrapped():
+        try:
+            async for chunk in orig_iter:
+                yield chunk
+        finally:
+            scope.__exit__(None, None, None)
+    return wrapped()
+
+
+def _wrap_sync_iter_with_scope(orig_iter, scope):
+    """sync iterator 도 같은 방식으로 감싸기 (sync StreamingResponse 케이스)."""
+    def wrapped():
+        try:
+            for chunk in orig_iter:
+                yield chunk
+        finally:
+            scope.__exit__(None, None, None)
+    return wrapped()
+
+
+def _wrap_result_keep_scope(result, scope):
+    """함수 result 의 type 별로 scope 유지 wrapping.
+
+    - StreamingResponse (body_iterator 보유) → body_iterator 를 감싸 scope 유지
+    - async generator object                  → 감싸 yield 끝까지 scope 유지
+    - sync generator object                   → 감싸 yield 끝까지 scope 유지
+    - 그 외 일반 객체                         → 즉시 scope 닫고 result 반환
+
+    return: 변경된 (또는 그대로의) result. scope 는 외부에서 더 이상 close 호출하면 안 됨.
+    """
+    if _is_streaming_response(result):
+        orig = result.body_iterator
+        if inspect.isasyncgen(orig) or hasattr(orig, '__aiter__'):
+            result.body_iterator = _wrap_async_iter_with_scope(orig, scope)
+        else:
+            result.body_iterator = _wrap_sync_iter_with_scope(orig, scope)
+        return result
+
+    if inspect.isasyncgen(result):
+        return _wrap_async_iter_with_scope(result, scope)
+
+    if inspect.isgenerator(result):
+        return _wrap_sync_iter_with_scope(result, scope)
+
+    # 일반 리턴 — 즉시 scope 정리
+    scope.__exit__(None, None, None)
+    return result
+
+
+def evaluate_with(*evaluators):
+    """함수에 평가자를 스코프 단위로 묶는 데코레이터. sync / async / generator /
+    async generator / FastAPI StreamingResponse 모두 지원.
+
+    Example:
+        @evaluate_with(HallucinationEvaluator(), RefusalEvaluator())
+        def chat(question):
+            return client.chat.completions.create(...).choices[0].message.content
+
+        @evaluate_with(ToxicityEvaluator())
+        async def achat(question):
+            return await aclient.chat.completions.create(...)
+
+    Streaming response (FastAPI/Starlette) 도 자동 처리:
+
+        @evaluate_with(CombinedJudgeEvaluator())
+        async def api_chat(request):
+            async def generate():
+                stream = await client.chat.completions.create(..., stream=True)
+                async for chunk in stream:
+                    yield ...
+            return StreamingResponse(generate(), ...)
+
+    이 경우 데코레이터는 함수가 StreamingResponse 를 리턴해도 scope 를 즉시 닫지 않고,
+    body_iterator 가 모두 소진되거나 예외가 날 때까지 유지한다. generate() 안의 LLM
+    호출에도 평가자가 적용됨.
+
+    함수가 직접 async generator / sync generator 를 리턴하는 경우, 그리고 sync 함수가
+    generator 객체를 return 하는 경우 (e.g. ``def fn(): return _make_gen()``) 도 모두
+    감싸진다.
+
+    asyncio.create_task / TaskGroup 으로 분기된 sub-task 도 ContextVar inherit 으로
+    scope 가 보임. 단 ``run_in_executor`` 등 다른 thread 로 dispatch 시 ContextVar 는
+    propagate 안 되므로 그쪽은 명시적으로 ``with evaluation_scope(...)`` 사용 권장.
+    """
+    def decorator(fn):
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args, **kwargs):
+                scope = evaluation_scope(*evaluators)
+                scope.__enter__()
+                try:
+                    result = await fn(*args, **kwargs)
+                except BaseException:
+                    scope.__exit__(None, None, None)
+                    raise
+                return _wrap_result_keep_scope(result, scope)
+            return async_wrapper
+
+        if inspect.isasyncgenfunction(fn):
+            @functools.wraps(fn)
+            def async_gen_wrapper(*args, **kwargs):
+                scope = evaluation_scope(*evaluators)
+                scope.__enter__()
+                try:
+                    gen = fn(*args, **kwargs)
+                except BaseException:
+                    scope.__exit__(None, None, None)
+                    raise
+                return _wrap_async_iter_with_scope(gen, scope)
+            return async_gen_wrapper
+
+        if inspect.isgeneratorfunction(fn):
+            @functools.wraps(fn)
+            def gen_wrapper(*args, **kwargs):
+                scope = evaluation_scope(*evaluators)
+                scope.__enter__()
+                try:
+                    gen = fn(*args, **kwargs)
+                except BaseException:
+                    scope.__exit__(None, None, None)
+                    raise
+                return _wrap_sync_iter_with_scope(gen, scope)
+            return gen_wrapper
+
+        # 일반 sync 함수 — 단, return 이 generator/asyncgen/StreamingResponse 일 수도
+        # 있으니 result 분기 적용.
+        @functools.wraps(fn)
+        def sync_wrapper(*args, **kwargs):
+            scope = evaluation_scope(*evaluators)
+            scope.__enter__()
+            try:
+                result = fn(*args, **kwargs)
+            except BaseException:
+                scope.__exit__(None, None, None)
+                raise
+            return _wrap_result_keep_scope(result, scope)
+        return sync_wrapper
+    return decorator

whatap/llm/features.py

@@ -0,0 +1,66 @@
+"""LLM feature / finish_reason 상수 — producer 측 typo 방지용.
+
+이 모듈의 역할은 producer 코드 (provider extractor / context) 에서 string literal
+을 직접 쓰는 대신 ``LlmFeature.VISION`` 같은 상수로 참조해 typo / IDE 자동완성 /
+검색을 돕는 것. **closed set 강제는 아님** — consumer (FeatureStat / FinishStat) 는
+producer 가 보내는 모든 raw 값을 그대로 누적한다.
+
+이렇게 한 이유:
+  - logsink (LlmStepStatus) 는 pack.features / pack.finish_reason 의 raw 값을
+    그대로 보존한다.
+  - metric (FeatureStat / FinishStat) 도 logsink 와 같은 데이터를 다뤄야 한다 —
+    metric 측에서 미리 정의한 set 에 없는 값을 silently drop 하면 두 layer 가
+    어긋난다.
+  - feature/reason 이름은 list-field (@id / features / features_count) 안의 entry
+    이지 dimension (tag) 이 아니므로 새 값이 들어와도 row cardinality 폭주는 없다.
+
+Producer 가 새 케이스를 잡고 싶으면:
+  1. (선택) ``LlmFeature`` 클래스에 상수 추가 — 코드 가독성/검색용
+  2. ``features.append(LlmFeature.NEW)`` 또는 raw 값 ``features.append('new_feat')``
+     둘 다 동일하게 metric 에 노출된다.
+"""
+
+
+class LlmFeature(object):
+    """``pack.features`` 에 들어가는 값을 producer 가 추가할 때 쓰는 상수.
+
+    이 목록은 현재 provider 코드가 발생시키는 알려진 케이스를 나열한 reference 일
+    뿐, FeatureStat 의 검증 set 이 아니다. 새 케이스가 생기면 producer 에서 raw
+    값을 그대로 보내도 된다.
+    """
+
+    VISION = 'vision'                       # 입력: 이미지/멀티모달
+    TOOL_USE = 'tool_use'                   # 출력: function/tool 호출
+    REASONING = 'reasoning'                 # 입력 reasoning_effort or 출력 thinking
+    STRUCTURED_OUTPUT = 'structured_output' # 입력 response_format=json_schema
+    WEBSEARCH = 'websearch'                 # 출력: 웹검색 도구 호출
+    COMPUTER_USE = 'computer_use'           # 출력: 컴퓨터 컨트롤 도구
+    DOCUMENT = 'document'                   # 입력: PDF/문서 첨부
+
+
+class LlmFinishReason(object):
+    """``pack.finish_reason`` 의 알려진 raw 값 reference.
+
+    Provider 가 raw response 객체에서 직접 읽어 pack 에 set 하므로 producer 에서
+    이 상수를 쓸 필요는 거의 없음. 외부 코드가 비교/검색할 때 참고용.
+    """
+
+    # OpenAI Chat / Completions
+    STOP = 'stop'
+    LENGTH = 'length'
+    TOOL_CALLS = 'tool_calls'
+    FUNCTION_CALL = 'function_call'
+    CONTENT_FILTER = 'content_filter'
+
+    # OpenAI Responses (response.status 가 pack.finish_reason 자리에 들어감)
+    COMPLETED = 'completed'
+    FAILED = 'failed'
+    INCOMPLETE = 'incomplete'
+    CANCELLED = 'cancelled'
+    IN_PROGRESS = 'in_progress'
+
+    # Anthropic Messages
+    END_TURN = 'end_turn'
+    MAX_TOKENS = 'max_tokens'
+    STOP_SEQUENCE = 'stop_sequence'
+    TOOL_USE = 'tool_use'

whatap/llm/log_sink_packs/__init__.py

@@ -0,0 +1,9 @@
+from whatap.llm.log_sink_packs.llm_log_sink_pack import LlmLogSinkPack
+from whatap.llm.log_sink_packs.llm_step_status import LlmStepStatus
+from whatap.llm.log_sink_packs.llm_step_eval_status import LlmStepEvalStatus
+from whatap.llm.log_sink_packs.llm_system_message import LlmSystemMessage
+from whatap.llm.log_sink_packs.llm_input_message import LlmInputMessage
+from whatap.llm.log_sink_packs.llm_output_message import LlmOutputMessage
+from whatap.llm.log_sink_packs.llm_tool_calls import LlmToolCalls
+from whatap.llm.log_sink_packs.llm_tool_results import LlmToolResults
+from whatap.llm.log_sink_packs.llm_tx_status import LlmTxStatus