whatap-python 2.1.0__py3-none-any.whl

whatap/llm/providers/anthropic/messages/messages_context.py

@@ -0,0 +1,76 @@
+"""Anthropic Messages API 요청에서 컨텍스트를 구성하는 모듈."""
+import json
+
+from whatap.llm.features import LlmFeature
+from whatap.llm.log_sink_packs.llm_step_status import LlmStepStatus
+from whatap.trace.trace_context_manager import TraceContextManager
+
+
+def _classify_input_features(kwargs):
+    """요청 kwargs에서 vision, document, reasoning 등 입력 피처를 분류한다."""
+    features = []
+    has_vision, has_document = False, False
+    for msg in kwargs.get("messages", []):
+        content = msg.get("content")
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict):
+                    bt = block.get("type", "")
+                    if bt == "image":
+                        has_vision = True
+                    elif bt == "document":
+                        has_document = True
+            if has_vision and has_document:
+                break
+    if has_vision:
+        features.append(LlmFeature.VISION)
+    if has_document:
+        features.append(LlmFeature.DOCUMENT)
+    thinking = kwargs.get("thinking")
+    if thinking and thinking.get("type") == "enabled":
+        features.append(LlmFeature.REASONING)
+    return features
+
+
+def _extract_input_text(messages, system=None):
+    """메시지 목록과 시스템 프롬프트에서 텍스트를 추출한다."""
+    if isinstance(system, list):
+        parts = []
+        for block in system:
+            if isinstance(block, dict):
+                parts.append(block.get("text", ""))
+            elif hasattr(block, 'text'):
+                parts.append(block.text)
+            else:
+                parts.append(str(block))
+        system_text = "\n".join(p for p in parts if p)
+    else:
+        system_text = system or ""
+    prompt_text = json.dumps(messages, ensure_ascii=False) if messages else ""
+    return system_text, prompt_text
+
+
+def build_context(kwargs):
+    """Messages kwargs로부터 LlmStepStatus 팩과 트레이스 컨텍스트를 구성한다."""
+    model = kwargs.get("model")
+    stream = kwargs.get("stream", False)
+    features = _classify_input_features(kwargs)
+
+    system_text, prompt_text = _extract_input_text(
+        kwargs.get("messages", []), system=kwargs.get("system"))
+
+    pack = LlmStepStatus()
+    pack.model = model
+    pack.prompt_text = prompt_text
+    pack.system_texts = [system_text] if system_text else []
+    pack.stream = stream
+    pack.features = ",".join(features)
+    if kwargs.get("temperature") is not None:
+        pack.temperature = kwargs["temperature"]
+
+    ctx = TraceContextManager.getLocalContext()
+    if ctx:
+        ctx._llm_httpc_pending = True
+        ctx._llm_model = model
+
+    return pack, ctx, features, stream

whatap/llm/providers/anthropic/messages/messages_extractor.py

@@ -0,0 +1,126 @@
+"""Anthropic Messages 응답에서 토큰 사용량 및 완성 텍스트를 추출하는 모듈."""
+from whatap import logging
+from whatap.llm.features import LlmFeature
+from whatap.llm.providers.stream_accumulator import StreamAccumulator
+
+
+def _extract_usage(response):
+    """응답 객체에서 캐시 토큰 포함 사용량 정보를 딕셔너리로 추출한다."""
+    usage = getattr(response, "usage", None)
+    inp = getattr(usage, "input_tokens", 0) or 0
+    out = getattr(usage, "output_tokens", 0) or 0
+    cc = getattr(usage, "cache_creation_input_tokens", 0) or 0
+    cr = getattr(usage, "cache_read_input_tokens", 0) or 0
+    return {
+        "input_tokens": inp, "output_tokens": out,
+        "total_tokens_count": inp + out + cc + cr,
+        "cache_creation_input_tokens": cc, "cache_read_input_tokens": cr,
+    }
+
+
+def _extract_response_text(response):
+    """응답 content 블록에서 텍스트와 thinking 내용을 분리 추출한다."""
+    try:
+        parts, thinking = [], []
+        for block in response.content:
+            if hasattr(block, 'type') and block.type == 'thinking':
+                thinking.append(getattr(block, 'thinking', ''))
+            elif hasattr(block, 'text'):
+                parts.append(block.text)
+        return "".join(parts), "".join(thinking)
+    except Exception as e:
+        logging.warning('[LLM] anthropic response text extraction failed: %s' % e, extra={'id': 'LLM030'})
+        return "", ""
+
+
+def _classify_response_features(response_content, features):
+    """응답 content에서 tool_use, computer_use 등 출력 피처를 분류한다."""
+    for block in response_content:
+        bt = getattr(block, 'type', '')
+        if bt == 'tool_use':
+            name = getattr(block, 'name', '')
+            tag = LlmFeature.COMPUTER_USE if 'computer' in name else LlmFeature.TOOL_USE
+            if tag not in features:
+                features.append(tag)
+
+
+def finalize(response, pack, features):
+    """비스트리밍 Messages 응답에서 완성 텍스트, 토큰, 피처 정보를 팩에 기록한다."""
+    _classify_response_features(response.content, features)
+    pack.features = ",".join(features)
+    text, reasoning = _extract_response_text(response)
+    pack.set_tokens(_extract_usage(response))
+    pack.completion_text = text
+    pack.finish_reason = getattr(response, 'stop_reason', None)
+    if reasoning:
+        pack.reasoning_text = reasoning
+
+
+class AnthropicStream(StreamAccumulator):
+    """Anthropic Messages 스트리밍 이벤트를 누적하는 어큐뮬레이터."""
+
+    def __init__(self, pack, active_key, features):
+        super().__init__(pack, active_key)
+        self.features = features
+        self.text = ""
+        self.reasoning = ""
+        self.block_type = None
+        self.block_name = None
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.cache_creation = 0
+        self.cache_read = 0
+
+    def on_chunk(self, event):
+        t = getattr(event, 'type', '')
+        if t == 'message_start':
+            usage = getattr(getattr(event, 'message', None), 'usage', None)
+            if usage:
+                self.input_tokens = getattr(usage, 'input_tokens', 0) or 0
+                self.cache_creation = getattr(usage, 'cache_creation_input_tokens', 0) or 0
+                self.cache_read = getattr(usage, 'cache_read_input_tokens', 0) or 0
+        elif t == 'content_block_start':
+            block = getattr(event, 'content_block', None)
+            self.block_type = getattr(block, 'type', None)
+            self.block_name = getattr(block, 'name', None)
+            if self.block_type == 'tool_use':
+                tag = (LlmFeature.COMPUTER_USE
+                       if self.block_name and 'computer' in self.block_name
+                       else LlmFeature.TOOL_USE)
+                if tag not in self.features:
+                    self.features.append(tag)
+        elif t == 'content_block_delta':
+            delta = getattr(event, 'delta', None)
+            if self.block_type == 'thinking':
+                self.reasoning += getattr(delta, 'thinking', '') or ''
+            elif self.block_type == 'text':
+                text = getattr(delta, 'text', '') or ''
+                if text:
+                    self.on_first_token()
+                    self.text += text
+        elif t == 'content_block_stop':
+            self.block_type = None
+            self.block_name = None
+        elif t == 'message_delta':
+            delta_obj = getattr(event, 'delta', None)
+            if delta_obj:
+                stop_reason = getattr(delta_obj, 'stop_reason', None)
+                if stop_reason:
+                    self.pack.finish_reason = stop_reason
+            usage = getattr(event, 'usage', None)
+            if usage:
+                self.output_tokens = getattr(usage, 'output_tokens', 0) or 0
+
+    def _apply(self):
+        pack = self.pack
+        pack.features = ",".join(self.features)
+        pack.set_tokens({
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "total_tokens_count": self.input_tokens + self.output_tokens + self.cache_creation + self.cache_read,
+            "cache_creation_input_tokens": self.cache_creation,
+            "cache_read_input_tokens": self.cache_read,
+        })
+        pack.completion_text = self.text
+        if self.reasoning:
+            pack.reasoning_text = self.reasoning

whatap/llm/providers/interceptor.py

@@ -0,0 +1,182 @@
+"""LLM 인터셉트 공통 라이프사이클 함수.
+
+API 호출 전후 처리 흐름:
+  before_call → fn() → after_call → finalize_non_streaming
+  에러 시: before_call → fn() → handle_error
+"""
+import time
+
+from whatap.counter.tasks.llm_log_sink_task import dispatch_llm_pack
+
+
+def capture_client(pack, ctx, args):
+    """인터셉트 시점에 호출된 LLM client 객체 + (async 면) event loop 를 캡처.
+
+    OpenAI/Anthropic SDK 모두 ``client.<resource>.<method>(...)`` 형태 메서드 호출이며,
+    인터셉트의 args[0] 은 그 resource 인스턴스. resource 의 ``_client`` 어트리뷰트로
+    상위 client (OpenAI/AsyncOpenAI/Anthropic/AsyncAnthropic) 에 접근 가능.
+
+    이걸 pack 에 stash 해두면 LLM judge 평가자가 사용자의 그 client 를 그대로 재사용 —
+    별도 sync client / httpx.Client 생성 없이 user 의 instance 를 그대로 호출.
+
+    async client 인 경우 ``asyncio.get_running_loop()`` 도 같이 캡처. 평가 워커 스레드는
+    sync 환경이라 그 loop 으로 ``run_coroutine_threadsafe`` dispatch 해야 user 의
+    AsyncClient (loop bind) 를 안전하게 재사용 가능.
+
+    실패해도 silently 무시 (인터셉트 자체는 절대 깨면 안 됨).
+    """
+    # Event loop 먼저 — sync 호출이면 RuntimeError 무시
+    try:
+        import asyncio
+        pack._llm_event_loop = asyncio.get_running_loop()
+        if ctx is not None:
+            ctx._llm_event_loop = pack._llm_event_loop
+    except RuntimeError:
+        pass
+    except Exception:
+        pass
+
+    if not args:
+        return
+    try:
+        resource = args[0]
+        llm_client = getattr(resource, '_client', None)
+        if llm_client is not None:
+            pack._llm_client = llm_client
+            if ctx is not None:
+                ctx._llm_client = llm_client
+    except Exception:
+        pass
+
+    # prompt_meta 스코프에서 (name, version) 가져와 pack 의 operation_type / prompt_version
+    # 으로 set. 데코레이터/scope 미적용 시 ('default', 'v1').
+    try:
+        from whatap.llm.prompt_meta import get_prompt_meta
+        name, version = get_prompt_meta()
+        pack.operation_type = name
+        pack.prompt_version = version
+    except Exception:
+        pass
+
+    # ★ judge LLM call (eval 워커 안에서 발생한 호출) 인 경우 — operation_type 을
+    # 'whatap_evaluation' 로 + parent step ids 를 user step 으로 override.
+    # capture_client 시점에 set 해야 (intercept_create 의 active_key 가 이 직후 계산되므로)
+    # 메트릭 (active_stat / perf_stat / token_usage_stat) 의 operation_type 라벨이
+    # 'whatap_evaluation' 로 정확하게 분리됨. dispatch 에서 override 하면 active_key 가 stale.
+    try:
+        from whatap.counter.tasks.llm_evaluator_task import (
+            _is_in_evaluator_worker, _get_eval_worker_state,
+        )
+        if _is_in_evaluator_worker():
+            state = _get_eval_worker_state() or {}
+            pack.operation_type = 'whatap_evaluation'
+            pack.prompt_version = 'v1'
+            if state.get('parent_txid'):
+                pack.txid = state['parent_txid']
+            if state.get('parent_step_id'):
+                pack.step_id = state['parent_step_id']
+            if state.get('parent_index') is not None:
+                pack.index = state['parent_index']
+    except Exception:
+        pass
+
+
+def _stat_task():
+    """LlmStatTask 싱글톤 인스턴스 반환. 미초기화 시 None."""
+    from whatap.counter.tasks.llm_stat_task import LlmStatTask
+    return LlmStatTask._instance
+
+
+def _active_stat():
+    """ActiveStat 인스턴스 반환. LLM 동시 호출 수 추적용."""
+    from whatap.counter.tasks.llm_stat_task import LlmStatTask
+    return LlmStatTask.get_stat('ActiveStat')
+
+
+def before_call(pack, active_key):
+    """API 호출 전: active 카운터 증가 + 시작 시간 기록 + 순차 인덱스 할당."""
+    pack._active_ended = False
+    stat = _active_stat()
+    if stat:
+        stat.on_start(*active_key)
+    pack._start_time = time.monotonic()
+    from whatap.trace.trace_context_manager import TraceContextManager
+    ctx = TraceContextManager.getLocalContext()
+    if ctx:
+        pack._trace_ctx = ctx
+        idx = getattr(ctx, '_llm_call_index', 0)
+        pack.index = idx
+        ctx._llm_call_index = idx + 1
+
+
+def _ensure_end(pack, active_key):
+    """on_end 멱등 호출 — 이미 호출되었으면 무시."""
+    if getattr(pack, '_active_ended', False):
+        return
+    pack._active_ended = True
+    stat = _active_stat()
+    if stat:
+        stat.on_end(*active_key, host=pack.provider or '')
+
+
+def handle_error(pack, err, active_key, api_error_cls):
+    """API 호출 실패 시: 에러 기록 (cause chain 포함) → 로그싱크 전송 → active 카운터 감소."""
+    try:
+        error_type = "api_error" if isinstance(err, api_error_cls) else "program_error"
+        # OpenAI SDK 의 APIConnectionError 등은 str(err)='Connection error.' 처럼 흐릿함.
+        # __cause__/__context__ 까지 풀어 진짜 원인 노출.
+        try:
+            chain = _format_exception_chain(err)
+        except Exception:
+            chain = '%s: %s' % (type(err).__name__, err)
+        pack.error = chain[:1500]
+        pack.error_type = error_type
+        _dispatch(pack)
+    finally:
+        _ensure_end(pack, active_key)
+
+
+def _format_exception_chain(e):
+    """예외 체인 (__cause__/__context__) 끝까지 펼쳐 한 줄로 직렬화."""
+    parts = []
+    seen = set()
+    cur = e
+    while cur is not None:
+        if id(cur) in seen:
+            break
+        seen.add(id(cur))
+        msg = str(cur).strip() or '(no message)'
+        parts.append('%s: %s' % (type(cur).__name__, msg))
+        cur = cur.__cause__ or cur.__context__
+        if len(parts) > 5:
+            parts.append('...')
+            break
+    return ' | caused by '.join(parts)
+
+
+def after_call(pack, ctx):
+    """API 호출 후: trace context에서 provider/url 추출 + active host 갱신."""
+    if ctx:
+        ctx._llm_httpc_pending = False
+        pack.set_context(ctx)
+    stat = _active_stat()
+    if stat:
+        stat.set_host(pack.model, pack.provider, pack.url)
+
+
+def finalize_non_streaming(pack, active_key):
+    """비스트리밍 응답 완료: latency 계산 → 로그싱크 전송 → active 카운터 감소."""
+    try:
+        pack.latency = round((time.monotonic() - pack._start_time) * 1000)
+        pack.success = True
+        _dispatch(pack)
+    finally:
+        _ensure_end(pack, active_key)
+
+
+def _dispatch(pack):
+    """로그싱크팩 전송 + 메트릭 stat 업데이트 통합 호출."""
+    dispatch_llm_pack(pack)
+    inst = _stat_task()
+    if inst:
+        inst.notify(pack)

whatap/llm/providers/openai/__init__.py

@@ -0,0 +1,133 @@
+from whatap import logging
+from whatap.conf.configure import Configure as conf
+from whatap.trace.trace_handler import trace_handler, async_trace_handler
+from whatap.llm.providers.openai.chat.chat import intercept_create, intercept_create_async
+from whatap.llm.providers.openai.responses.responses import intercept_responses_create, intercept_responses_create_async
+from whatap.llm.providers.openai.embeddings.embeddings import intercept_embeddings, intercept_embeddings_async
+from whatap.llm.providers.openai.completions.completions import intercept_completions, intercept_completions_async
+
+
+def instrument_openai(module):
+
+    if not conf.llm_enabled:
+        return
+
+    def create_wrapper(fn):
+        @trace_handler(fn)
+        def trace(*args, **kwargs):
+            return intercept_create(fn, *args, **kwargs)
+        return trace
+
+    def async_create_wrapper(fn):
+        @async_trace_handler(fn)
+        async def trace(*args, **kwargs):
+            return await intercept_create_async(fn, *args, **kwargs)
+        return trace
+
+    def embeddings_wrapper(fn):
+        @trace_handler(fn)
+        def trace(*args, **kwargs):
+            return intercept_embeddings(fn, *args, **kwargs)
+        return trace
+
+    def async_embeddings_wrapper(fn):
+        @async_trace_handler(fn)
+        async def trace(*args, **kwargs):
+            return await intercept_embeddings_async(fn, *args, **kwargs)
+        return trace
+
+    def completions_wrapper(fn):
+        @trace_handler(fn)
+        def trace(*args, **kwargs):
+            return intercept_completions(fn, *args, **kwargs)
+        return trace
+
+    def async_completions_wrapper(fn):
+        @async_trace_handler(fn)
+        async def trace(*args, **kwargs):
+            return await intercept_completions_async(fn, *args, **kwargs)
+        return trace
+
+    def responses_wrapper(fn):
+        @trace_handler(fn)
+        def trace(*args, **kwargs):
+            return intercept_responses_create(fn, *args, **kwargs)
+        return trace
+
+    def async_responses_wrapper(fn):
+        @async_trace_handler(fn)
+        async def trace(*args, **kwargs):
+            return await intercept_responses_create_async(fn, *args, **kwargs)
+        return trace
+
+    # Sync: openai.resources.chat.completions.Completions.create
+    if (hasattr(module, 'resources') and
+            hasattr(module.resources, 'chat') and
+            hasattr(module.resources.chat, 'completions') and
+            hasattr(module.resources.chat.completions, 'Completions') and
+            hasattr(module.resources.chat.completions.Completions, 'create')):
+        original_create = module.resources.chat.completions.Completions.create
+        module.resources.chat.completions.Completions.create = create_wrapper(original_create)
+
+    # Async: openai.resources.chat.completions.AsyncCompletions.create
+    if (hasattr(module, 'resources') and
+            hasattr(module.resources, 'chat') and
+            hasattr(module.resources.chat, 'completions') and
+            hasattr(module.resources.chat.completions, 'AsyncCompletions') and
+            hasattr(module.resources.chat.completions.AsyncCompletions, 'create')):
+        original_async_create = module.resources.chat.completions.AsyncCompletions.create
+        module.resources.chat.completions.AsyncCompletions.create = async_create_wrapper(original_async_create)
+
+    # Sync: openai.resources.completions.Completions.create
+    if (hasattr(module, 'resources') and
+            hasattr(module.resources, 'completions') and
+            hasattr(module.resources.completions, 'Completions') and
+            hasattr(module.resources.completions.Completions, 'create')):
+        original_completions = module.resources.completions.Completions.create
+        module.resources.completions.Completions.create = completions_wrapper(original_completions)
+
+    # Async: openai.resources.completions.AsyncCompletions.create
+    if (hasattr(module, 'resources') and
+            hasattr(module.resources, 'completions') and
+            hasattr(module.resources.completions, 'AsyncCompletions') and
+            hasattr(module.resources.completions.AsyncCompletions, 'create')):
+        original_async_completions = module.resources.completions.AsyncCompletions.create
+        module.resources.completions.AsyncCompletions.create = async_completions_wrapper(original_async_completions)
+
+    # Sync: openai.resources.embeddings.Embeddings.create
+    if (hasattr(module, 'resources') and
+            hasattr(module.resources, 'embeddings') and
+            hasattr(module.resources.embeddings, 'Embeddings') and
+            hasattr(module.resources.embeddings.Embeddings, 'create')):
+        original_embeddings = module.resources.embeddings.Embeddings.create
+        module.resources.embeddings.Embeddings.create = embeddings_wrapper(original_embeddings)
+
+    # Async: openai.resources.embeddings.AsyncEmbeddings.create
+    if (hasattr(module, 'resources') and
+            hasattr(module.resources, 'embeddings') and
+            hasattr(module.resources.embeddings, 'AsyncEmbeddings') and
+            hasattr(module.resources.embeddings.AsyncEmbeddings, 'create')):
+        original_async_embeddings = module.resources.embeddings.AsyncEmbeddings.create
+        module.resources.embeddings.AsyncEmbeddings.create = async_embeddings_wrapper(original_async_embeddings)
+
+    # Sync: openai.resources.responses.responses.Responses.create (Responses API)
+    try:
+        from openai.resources.responses.responses import Responses as ResponsesCls
+        if hasattr(ResponsesCls, 'create'):
+            original_responses_create = ResponsesCls.create
+            ResponsesCls.create = responses_wrapper(original_responses_create)
+    except ImportError:
+        pass
+    except AttributeError as e:
+        logging.warning('[LLM] Responses API patch failed: %s' % e, extra={'id': 'LLM020'})
+
+    # Async: openai.resources.responses.responses.AsyncResponses.create
+    try:
+        from openai.resources.responses.responses import AsyncResponses as AsyncResponsesCls
+        if hasattr(AsyncResponsesCls, 'create'):
+            original_async_responses_create = AsyncResponsesCls.create
+            AsyncResponsesCls.create = async_responses_wrapper(original_async_responses_create)
+    except ImportError:
+        pass
+    except AttributeError as e:
+        logging.warning('[LLM] Async Responses API patch failed: %s' % e, extra={'id': 'LLM021'})

whatap/llm/providers/openai/chat/chat.py

@@ -0,0 +1,82 @@
+"""OpenAI Chat Completions API 호출을 인터셉트하는 모듈."""
+from openai import OpenAIError
+
+from whatap.llm.providers.interceptor import (
+    before_call, handle_error, after_call, finalize_non_streaming, _ensure_end,
+    capture_client,
+)
+from whatap.llm.providers.stream_accumulator import sync_stream, async_stream
+from whatap.llm.providers.openai.chat.chat_context import build_context
+from whatap.llm.providers.openai.chat.chat_extractor import finalize, ChatStream
+
+
+def intercept_create(fn, *args, **kwargs):
+    """OpenAI Chat Completions 동기 호출을 인터셉트하여 모니터링 데이터를 수집한다."""
+    pack, ctx, features, stream = build_context(kwargs)
+    capture_client(pack, ctx, args)
+    active_key = (pack.model, pack.operation_type, getattr(pack, "prompt_version", "v1"))
+
+    if stream:
+        opts = dict(kwargs.get("stream_options") or {})
+        if not opts.get("include_usage"):
+            opts["include_usage"] = True
+            kwargs["stream_options"] = opts
+
+    before_call(pack, active_key)
+    _stream_returned = False
+    try:
+        try:
+            response = fn(*args, **kwargs)
+        except Exception as err:
+            handle_error(pack, err, active_key, OpenAIError)
+            raise
+        finally:
+            if ctx:
+                ctx._llm_httpc_pending = False
+
+        after_call(pack, ctx)
+        if stream:
+            _stream_returned = True
+            return sync_stream(response, ChatStream(pack, active_key))
+        finalize(response, pack, features)
+        finalize_non_streaming(pack, active_key)
+        return response
+    finally:
+        if not _stream_returned:
+            _ensure_end(pack, active_key)
+
+
+async def intercept_create_async(fn, *args, **kwargs):
+    """OpenAI Chat Completions 비동기 호출을 인터셉트하여 모니터링 데이터를 수집한다."""
+    pack, ctx, features, stream = build_context(kwargs)
+    capture_client(pack, ctx, args)
+    active_key = (pack.model, pack.operation_type, getattr(pack, "prompt_version", "v1"))
+
+    if stream:
+        opts = dict(kwargs.get("stream_options") or {})
+        if not opts.get("include_usage"):
+            opts["include_usage"] = True
+            kwargs["stream_options"] = opts
+
+    before_call(pack, active_key)
+    _stream_returned = False
+    try:
+        try:
+            response = await fn(*args, **kwargs)
+        except Exception as err:
+            handle_error(pack, err, active_key, OpenAIError)
+            raise
+        finally:
+            if ctx:
+                ctx._llm_httpc_pending = False
+
+        after_call(pack, ctx)
+        if stream:
+            _stream_returned = True
+            return async_stream(response, ChatStream(pack, active_key))
+        finalize(response, pack, features)
+        finalize_non_streaming(pack, active_key)
+        return response
+    finally:
+        if not _stream_returned:
+            _ensure_end(pack, active_key)

whatap/llm/providers/openai/chat/chat_context.py

@@ -0,0 +1,78 @@
+"""OpenAI Chat Completions 요청에서 컨텍스트를 구성하는 모듈."""
+import json
+
+from whatap import logging
+from whatap.llm.features import LlmFeature
+from whatap.llm.log_sink_packs.llm_step_status import LlmStepStatus
+from whatap.llm.providers.openai.content_parser import extract_content_text
+from whatap.trace.trace_context_manager import TraceContextManager
+
+
+def build_context(kwargs):
+    """Chat kwargs로부터 LlmStepStatus 팩과 트레이스 컨텍스트를 구성한다."""
+    messages = kwargs.get("messages", [])
+    model = kwargs.get("model")
+    stream = kwargs.get("stream", False)
+
+    system_parts, prompt_msgs, tool_results = [], [], []
+    features, has_vision = [], False
+
+    for msg in messages:
+        if not isinstance(msg, dict):
+            try:
+                msg = msg.model_dump()
+            except Exception:
+                msg = dict(msg)
+        role = msg.get("role", "user")
+        content = msg.get("content")
+        if role == "system":
+            system_parts.append(extract_content_text(content))
+        elif role == "tool":
+            text = extract_content_text(content)
+            tool_results.append({"tool_call_id": msg.get("tool_call_id", ""), "content": text})
+            sanitized = dict(msg)
+            if isinstance(content, list):
+                sanitized["content"] = text
+            prompt_msgs.append(sanitized)
+        else:
+            sanitized = dict(msg)
+            if isinstance(content, list):
+                if not has_vision:
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "image_url":
+                            has_vision = True
+                            break
+                sanitized["content"] = extract_content_text(content)
+            prompt_msgs.append(sanitized)
+
+    try:
+        prompt_text = json.dumps(prompt_msgs, ensure_ascii=False) if prompt_msgs else ""
+    except Exception as e:
+        logging.warning('[LLM] chat prompt serialization failed: %s' % e, extra={'id': 'LLM004'})
+        prompt_text = ""
+
+    if has_vision:
+        features.append(LlmFeature.VISION)
+    if kwargs.get("reasoning_effort"):
+        features.append(LlmFeature.REASONING)
+    rf = kwargs.get("response_format")
+    if isinstance(rf, dict) and rf.get("type") == "json_schema":
+        features.append(LlmFeature.STRUCTURED_OUTPUT)
+
+    pack = LlmStepStatus()
+    pack.model = model
+    pack.prompt_text = prompt_text
+    pack.system_texts = system_parts
+    pack.stream = stream
+    pack.features = ",".join(features)
+    if kwargs.get("temperature") is not None:
+        pack.temperature = kwargs["temperature"]
+    if tool_results:
+        pack.tool_results_text = json.dumps(tool_results, ensure_ascii=False)
+
+    ctx = TraceContextManager.getLocalContext()
+    if ctx:
+        ctx._llm_httpc_pending = True
+        ctx._llm_model = model
+
+    return pack, ctx, features, stream