splunk-otel-util-genai 0.1.3__py3-none-any.whl

opentelemetry/util/genai/__init__.py

@@ -0,0 +1,17 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)

opentelemetry/util/genai/_fsspec_upload/__init__.py

@@ -0,0 +1,39 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from os import environ
+
+from opentelemetry.util.genai.environment_variables import (
+    OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH,
+)
+from opentelemetry.util.genai.upload_hook import UploadHook, _NoOpUploadHook
+
+
+def fsspec_upload_hook() -> UploadHook:
+    # If fsspec is not installed the hook will be a no-op.
+    try:
+        # pylint: disable=import-outside-toplevel
+        from opentelemetry.util.genai._fsspec_upload.fsspec_hook import (
+            FsspecUploadHook,
+        )
+    except ImportError:
+        return _NoOpUploadHook()
+
+    base_path = environ.get(OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH)
+    if not base_path:
+        return _NoOpUploadHook()
+
+    return FsspecUploadHook(base_path=base_path)

opentelemetry/util/genai/_fsspec_upload/fsspec_hook.py

@@ -0,0 +1,184 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import annotations
+
+import json
+import logging
+import posixpath
+import threading
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import asdict, dataclass
+from functools import partial
+from typing import Any, Callable, Literal, TextIO, cast
+from uuid import uuid4
+
+import fsspec
+
+from opentelemetry._logs import LogRecord
+from opentelemetry.trace import Span
+from opentelemetry.util.genai import types
+from opentelemetry.util.genai.upload_hook import UploadHook
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Completion:
+    inputs: list[types.InputMessage]
+    outputs: list[types.OutputMessage]
+    system_instruction: list[types.MessagePart]
+
+
+@dataclass
+class CompletionRefs:
+    inputs_ref: str
+    outputs_ref: str
+    system_instruction_ref: str
+
+
+JsonEncodeable = list[dict[str, Any]]
+
+# mapping of upload path to function computing upload data dict
+UploadData = dict[str, Callable[[], JsonEncodeable]]
+
+
+def fsspec_open(urlpath: str, mode: Literal["w"]) -> TextIO:
+    """typed wrapper around `fsspec.open`"""
+    return cast(TextIO, fsspec.open(urlpath, mode))  # pyright: ignore[reportUnknownMemberType]
+
+
+class FsspecUploadHook(UploadHook):
+    """An upload hook using ``fsspec`` to upload to external storage
+
+    This function can be used as the
+    :func:`~opentelemetry.util.genai.upload_hook.load_upload_hook` implementation by
+    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK` to ``fsspec``.
+    :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` must be configured to specify the
+    base path for uploads.
+
+    Both the ``fsspec`` and ``opentelemetry-sdk`` packages should be installed, or a no-op
+    implementation will be used instead. You can use ``opentelemetry-util-genai[fsspec]``
+    as a requirement to achieve this.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_path: str,
+        max_size: int = 20,
+    ) -> None:
+        self._base_path = base_path
+        self._max_size = max_size
+
+        # Use a ThreadPoolExecutor for its queueing and thread management. The semaphore
+        # limits the number of queued tasks. If the queue is full, data will be dropped.
+        self._executor = ThreadPoolExecutor(max_workers=max_size)
+        self._semaphore = threading.BoundedSemaphore(max_size)
+
+    def _submit_all(self, upload_data: UploadData) -> None:
+        def done(future: Future[None]) -> None:
+            self._semaphore.release()
+
+            try:
+                future.result()
+            except Exception:  # pylint: disable=broad-except
+                _logger.exception("fsspec uploader failed")
+
+        for path, json_encodeable in upload_data.items():
+            # could not acquire, drop data
+            if not self._semaphore.acquire(blocking=False):  # pylint: disable=consider-using-with
+                _logger.warning(
+                    "fsspec upload queue is full, dropping upload %s",
+                    path,
+                )
+                continue
+
+            try:
+                fut = self._executor.submit(
+                    self._do_upload, path, json_encodeable
+                )
+                fut.add_done_callback(done)
+            except RuntimeError:
+                _logger.info(
+                    "attempting to upload file after FsspecUploadHook.shutdown() was already called"
+                )
+                break
+
+    def _calculate_ref_path(self) -> CompletionRefs:
+        # TODO: experimental with using the trace_id and span_id, or fetching
+        # gen_ai.response.id from the active span.
+
+        uuid_str = str(uuid4())
+        return CompletionRefs(
+            inputs_ref=posixpath.join(
+                self._base_path, f"{uuid_str}_inputs.json"
+            ),
+            outputs_ref=posixpath.join(
+                self._base_path, f"{uuid_str}_outputs.json"
+            ),
+            system_instruction_ref=posixpath.join(
+                self._base_path, f"{uuid_str}_system_instruction.json"
+            ),
+        )
+
+    @staticmethod
+    def _do_upload(
+        path: str, json_encodeable: Callable[[], JsonEncodeable]
+    ) -> None:
+        with fsspec_open(path, "w") as file:
+            json.dump(json_encodeable(), file, separators=(",", ":"))
+
+    def upload(
+        self,
+        *,
+        inputs: list[types.InputMessage],
+        outputs: list[types.OutputMessage],
+        system_instruction: list[types.MessagePart],
+        span: Span | None = None,
+        log_record: LogRecord | None = None,
+        **kwargs: Any,
+    ) -> None:
+        completion = Completion(
+            inputs=inputs,
+            outputs=outputs,
+            system_instruction=system_instruction,
+        )
+        # generate the paths to upload to
+        ref_names = self._calculate_ref_path()
+
+        def to_dict(
+            dataclass_list: list[types.InputMessage]
+            | list[types.OutputMessage]
+            | list[types.MessagePart],
+        ) -> JsonEncodeable:
+            return [asdict(dc) for dc in dataclass_list]
+
+        self._submit_all(
+            {
+                # Use partial to defer as much as possible to the background threads
+                ref_names.inputs_ref: partial(to_dict, completion.inputs),
+                ref_names.outputs_ref: partial(to_dict, completion.outputs),
+                ref_names.system_instruction_ref: partial(
+                    to_dict, completion.system_instruction
+                ),
+            },
+        )
+
+        # TODO: stamp the refs on telemetry
+
+    def shutdown(self) -> None:
+        # TODO: support timeout
+        self._executor.shutdown()

opentelemetry/util/genai/attributes.py

@@ -0,0 +1,60 @@
+"""
+Centralized constants for GenAI telemetry attribute names.
+This module replaces inline string literals for span & event attributes.
+"""
+
+# Semantic attribute names for core GenAI spans/events
+GEN_AI_PROVIDER_NAME = "gen_ai.provider.name"
+GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages"
+GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages"
+GEN_AI_FRAMEWORK = "gen_ai.framework"
+GEN_AI_COMPLETION_PREFIX = "gen_ai.completion"
+
+# Additional semantic attribute constants
+GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+GEN_AI_RESPONSE_MODEL = "gen_ai.response.model"
+GEN_AI_RESPONSE_ID = "gen_ai.response.id"
+GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+GEN_AI_EVALUATION_NAME = "gen_ai.evaluation.name"
+GEN_AI_EVALUATION_SCORE_VALUE = "gen_ai.evaluation.score.value"
+GEN_AI_EVALUATION_SCORE_LABEL = "gen_ai.evaluation.score.label"
+GEN_AI_EVALUATION_EXPLANATION = "gen_ai.evaluation.explanation"
+GEN_AI_EVALUATION_ATTRIBUTES_PREFIX = "gen_ai.evaluation.attributes."
+
+# Agent attributes (from semantic conventions)
+GEN_AI_AGENT_NAME = "gen_ai.agent.name"
+GEN_AI_AGENT_ID = "gen_ai.agent.id"
+GEN_AI_AGENT_DESCRIPTION = "gen_ai.agent.description"
+GEN_AI_AGENT_TOOLS = "gen_ai.agent.tools"
+GEN_AI_AGENT_TYPE = "gen_ai.agent.type"
+GEN_AI_AGENT_SYSTEM_INSTRUCTIONS = "gen_ai.agent.system_instructions"
+GEN_AI_AGENT_INPUT_CONTEXT = "gen_ai.agent.input_context"
+GEN_AI_AGENT_OUTPUT_RESULT = "gen_ai.agent.output_result"
+
+# Workflow attributes (not in semantic conventions)
+GEN_AI_WORKFLOW_NAME = "gen_ai.workflow.name"
+GEN_AI_WORKFLOW_TYPE = "gen_ai.workflow.type"
+GEN_AI_WORKFLOW_DESCRIPTION = "gen_ai.workflow.description"
+GEN_AI_WORKFLOW_INITIAL_INPUT = "gen_ai.workflow.initial_input"
+GEN_AI_WORKFLOW_FINAL_OUTPUT = "gen_ai.workflow.final_output"
+
+# Step attributes (not in semantic conventions)
+GEN_AI_STEP_NAME = "gen_ai.step.name"
+GEN_AI_STEP_TYPE = "gen_ai.step.type"
+GEN_AI_STEP_OBJECTIVE = "gen_ai.step.objective"
+GEN_AI_STEP_SOURCE = "gen_ai.step.source"
+GEN_AI_STEP_ASSIGNED_AGENT = "gen_ai.step.assigned_agent"
+GEN_AI_STEP_STATUS = "gen_ai.step.status"
+GEN_AI_STEP_INPUT_DATA = "gen_ai.step.input_data"
+GEN_AI_STEP_OUTPUT_DATA = "gen_ai.step.output_data"
+
+# Embedding attributes
+GEN_AI_EMBEDDINGS_DIMENSION_COUNT = "gen_ai.embeddings.dimension.count"
+GEN_AI_EMBEDDINGS_INPUT_TEXTS = "gen_ai.embeddings.input.texts"
+GEN_AI_REQUEST_ENCODING_FORMATS = "gen_ai.request.encoding_formats"
+
+# Server attributes (from semantic conventions)
+SERVER_ADDRESS = "server.address"
+SERVER_PORT = "server.port"

opentelemetry/util/genai/callbacks.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from .types import GenAI
+
+
+class CompletionCallback(Protocol):
+    """Protocol implemented by handlers interested in completion events."""
+
+    def on_completion(self, invocation: GenAI) -> None:
+        """Handle completion of a GenAI invocation."""
+
+
+class NoOpCompletionCallback:
+    """Completion callback that performs no work."""
+
+    def on_completion(
+        self, invocation: GenAI
+    ) -> None:  # pragma: no cover - trivial
+        return None
+
+
+__all__ = ["CompletionCallback", "NoOpCompletionCallback"]

opentelemetry/util/genai/config.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Dict
+
+from .emitters.spec import CategoryOverride
+from .environment_variables import (
+    OTEL_GENAI_EVALUATION_EVENT_LEGACY,
+    OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT,
+    OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT_MODE,
+    OTEL_INSTRUMENTATION_GENAI_EMITTERS,
+    OTEL_INSTRUMENTATION_GENAI_EMITTERS_CONTENT_EVENTS,
+    OTEL_INSTRUMENTATION_GENAI_EMITTERS_EVALUATION,
+    OTEL_INSTRUMENTATION_GENAI_EMITTERS_METRICS,
+    OTEL_INSTRUMENTATION_GENAI_EMITTERS_SPAN,
+    OTEL_INSTRUMENTATION_GENAI_EVALUATION_SAMPLE_RATE,
+)
+from .types import ContentCapturingMode
+from .utils import get_content_capturing_mode
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Configuration for GenAI emitters derived from environment variables."""
+
+    enable_span: bool
+    enable_metrics: bool
+    enable_content_events: bool
+    extra_emitters: list[str]
+    only_traceloop_compat: bool
+    raw_tokens: list[str]
+    capture_messages_mode: ContentCapturingMode
+    capture_messages_override: bool
+    legacy_capture_request: bool
+    emit_legacy_evaluation_event: bool
+    category_overrides: Dict[str, CategoryOverride]
+    evaluation_sample_rate: float = 1.0
+
+
+def parse_env() -> Settings:
+    """Parse emitter-related environment variables into structured settings."""
+
+    raw_val = os.environ.get(OTEL_INSTRUMENTATION_GENAI_EMITTERS, "span")
+    tokens = [
+        token.strip().lower() for token in raw_val.split(",") if token.strip()
+    ]
+    if not tokens:
+        tokens = ["span"]
+
+    baseline_map = {
+        "span": (True, False, False),
+        "span_metric": (True, True, False),
+        "span_metric_event": (True, True, True),
+    }
+
+    baseline = next((token for token in tokens if token in baseline_map), None)
+    extra_emitters: list[str] = []
+    only_traceloop_compat = False
+
+    if baseline is None:
+        if tokens == ["traceloop_compat"]:
+            baseline = "span"
+            extra_emitters = ["traceloop_compat"]
+            only_traceloop_compat = True
+        else:
+            baseline = "span"
+            extra_emitters = [
+                token for token in tokens if token not in baseline_map
+            ]
+    else:
+        extra_emitters = [token for token in tokens if token != baseline]
+
+    enable_span, enable_metrics, enable_content_events = baseline_map.get(
+        baseline, (True, False, False)
+    )
+
+    capture_messages_override = any(
+        env is not None
+        for env in (
+            os.environ.get(OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT),
+            os.environ.get(
+                OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT_MODE
+            ),
+        )
+    )
+    capture_mode = get_content_capturing_mode()
+
+    # Legacy flag removed: always False now
+    legacy_capture_request = False
+
+    overrides: Dict[str, CategoryOverride] = {}
+    override_env_map = {
+        "span": os.environ.get(OTEL_INSTRUMENTATION_GENAI_EMITTERS_SPAN, ""),
+        "metrics": os.environ.get(
+            OTEL_INSTRUMENTATION_GENAI_EMITTERS_METRICS, ""
+        ),
+        "content_events": os.environ.get(
+            OTEL_INSTRUMENTATION_GENAI_EMITTERS_CONTENT_EVENTS, ""
+        ),
+        "evaluation": os.environ.get(
+            OTEL_INSTRUMENTATION_GENAI_EMITTERS_EVALUATION, ""
+        ),
+    }
+    for category, raw in override_env_map.items():
+        override = _parse_category_override(category, raw)
+        if override is not None:
+            overrides[category] = override
+
+    legacy_event_flag = os.environ.get(
+        OTEL_GENAI_EVALUATION_EVENT_LEGACY, ""
+    ).strip()
+    emit_legacy_event = legacy_event_flag.lower() in {"1", "true", "yes"}
+
+    evaluation_sample_rate = os.environ.get(
+        OTEL_INSTRUMENTATION_GENAI_EVALUATION_SAMPLE_RATE
+    )
+    if evaluation_sample_rate is None or evaluation_sample_rate.strip() == "":
+        evaluation_sample_rate = 1.0
+    try:
+        evaluation_sample_rate = float(evaluation_sample_rate)
+    except ValueError:
+        evaluation_sample_rate = 1.0
+    if evaluation_sample_rate < 0.0:
+        evaluation_sample_rate = 0.0
+    if evaluation_sample_rate > 1.0:
+        evaluation_sample_rate = 1.0
+
+    return Settings(
+        enable_span=enable_span,
+        enable_metrics=enable_metrics,
+        enable_content_events=enable_content_events,
+        extra_emitters=extra_emitters,
+        only_traceloop_compat=only_traceloop_compat,
+        raw_tokens=tokens,
+        capture_messages_mode=capture_mode,
+        capture_messages_override=capture_messages_override,
+        legacy_capture_request=legacy_capture_request,
+        emit_legacy_evaluation_event=emit_legacy_event,
+        category_overrides=overrides,
+        evaluation_sample_rate=evaluation_sample_rate,
+    )
+
+
+def _parse_category_override(
+    category: str, raw: str
+) -> CategoryOverride | None:  # pragma: no cover - thin parsing
+    if not raw:
+        return None
+    text = raw.strip()
+    if not text:
+        return None
+    directive = None
+    remainder = text
+    if ":" in text:
+        prefix, remainder = text.split(":", 1)
+        directive = prefix.strip().lower()
+    names = [name.strip() for name in remainder.split(",") if name.strip()]
+    mode_map = {
+        None: "append",
+        "append": "append",
+        "prepend": "prepend",
+        "replace": "replace-category",
+        "replace-category": "replace-category",
+        "replace-same-name": "replace-same-name",
+    }
+    mode = mode_map.get(directive)
+    if mode is None:
+        if directive:
+            _logger.warning(
+                "Unknown emitter override directive '%s' for category '%s'",
+                directive,
+                category,
+            )
+        mode = "append"
+    if mode != "replace-category" and not names:
+        return None
+    return CategoryOverride(mode=mode, emitter_names=tuple(names))
+
+
+__all__ = ["Settings", "parse_env"]

opentelemetry/util/genai/debug.py

@@ -0,0 +1,183 @@
+"""Opt-in debug logging utilities for GenAI telemetry types.
+
+The debug facility is disabled by default and activated when either
+`OTEL_GENAI_DEBUG` or `OTEL_INSTRUMENTATION_GENAI_DEBUG` environment variable
+is set to a truthy value (case-insensitive one of: 1, true, yes, on, debug).
+
+Usage pattern (internal):
+
+    from opentelemetry.util.genai.debug import genai_debug_log
+    genai_debug_log("handler.start_llm.begin", invocation)
+
+The helper auto-formats an object representation including span context IDs
+when available.
+
+This module intentionally avoids heavy imports and large content dumps.
+Message bodies are NOT logged; counts only.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from .span_context import (
+    extract_span_context,
+    span_context_hex_ids,
+    store_span_context,
+)
+
+try:  # Local import guarded for namespace package variations
+    from opentelemetry.util.genai.types import GenAI  # type: ignore
+except Exception:  # pragma: no cover - fallback for edge import errors
+    GenAI = object  # type: ignore
+
+_TRUTHY = {"1", "true", "yes", "on", "debug"}
+
+
+def _read_enabled_flag() -> bool:
+    for var in ("OTEL_GENAI_DEBUG", "OTEL_INSTRUMENTATION_GENAI_DEBUG"):
+        raw = os.environ.get(var)
+        if raw is None:
+            continue
+        if raw.strip().lower() in _TRUTHY:
+            return True
+    return False
+
+
+_ENABLED = _read_enabled_flag()
+
+_LOGGER = logging.getLogger("opentelemetry.util.genai.debug")
+if _ENABLED and not _LOGGER.handlers:  # configure minimal handler if none
+    handler = logging.StreamHandler()
+    fmt = logging.Formatter("%(message)s")  # raw message only (no ts/prefix)
+    handler.setFormatter(fmt)
+    _LOGGER.addHandler(handler)
+    _LOGGER.setLevel(logging.DEBUG)
+
+
+def is_enabled() -> bool:
+    """Return whether GenAI debug logging is enabled."""
+
+    return _ENABLED
+
+
+def _hex_trace(span_context: Any) -> str | None:
+    try:
+        if span_context and getattr(span_context, "is_valid", False):
+            return f"{span_context.trace_id:032x}"  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover
+        return None
+    return None
+
+
+def _hex_span(span_context: Any) -> str | None:
+    try:
+        if span_context and getattr(span_context, "is_valid", False):
+            return f"{span_context.span_id:016x}"  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover
+        return None
+    return None
+
+
+def summarize_genai(obj: Any) -> str:
+    """Return a short representation for a GenAI object.
+
+    Avoids printing message content; focuses on identity and context.
+    """
+
+    if obj is None:
+        return "<None>"
+    cls_name = obj.__class__.__name__
+    parts: list[str] = [cls_name]
+    # Common identifiers
+    run_id = getattr(obj, "run_id", None)
+    if run_id is not None:
+        parts.append(f"run_id={run_id}")
+    parent_run_id = getattr(obj, "parent_run_id", None)
+    if parent_run_id is not None:
+        parts.append(f"parent_run_id={parent_run_id}")
+    provider = getattr(obj, "provider", None)
+    if provider:
+        parts.append(f"provider={provider}")
+    model = getattr(obj, "request_model", None) or getattr(obj, "model", None)
+    if model:
+        parts.append(f"model={model}")
+    # Span context
+    span = getattr(obj, "span", None)
+    span_context = getattr(obj, "span_context", None)
+    if span_context is None and span is not None:
+        try:
+            span_context = extract_span_context(span)
+        except Exception:  # pragma: no cover
+            span_context = None
+        else:
+            store_span_context(obj, span_context)
+    trace_hex, span_hex = span_context_hex_ids(span_context)
+    if not trace_hex:
+        trace_val = getattr(obj, "trace_id", None)
+        if isinstance(trace_val, int) and trace_val:
+            trace_hex = f"{trace_val:032x}"
+    if not span_hex:
+        span_val = getattr(obj, "span_id", None)
+        if isinstance(span_val, int) and span_val:
+            span_hex = f"{span_val:016x}"
+    if trace_hex:
+        parts.append(f"trace_id={trace_hex}")
+    if span_hex:
+        parts.append(f"span_id={span_hex}")
+    # Token counts if present
+    for attr in ("input_tokens", "output_tokens"):
+        val = getattr(obj, attr, None)
+        if isinstance(val, (int, float)):
+            parts.append(f"{attr}={val}")
+    # Message counts when lists
+    inp_msgs = getattr(obj, "input_messages", None)
+    if isinstance(inp_msgs, list):
+        parts.append(f"input_messages={len(inp_msgs)}")
+    out_msgs = getattr(obj, "output_messages", None)
+    if isinstance(out_msgs, list):
+        parts.append(f"output_messages={len(out_msgs)}")
+    return "<" + " ".join(parts) + ">"
+
+
+def genai_debug_log(event: str, obj: Any = None, **info: Any) -> None:
+    """Conditionally emit a single structured debug log line.
+
+    Parameters
+    ----------
+    event : str
+        Event key/path (e.g., 'handler.start_llm.begin').
+    obj : GenAI | None
+        Related GenAI object for context representation.
+    **info : Any
+        Additional arbitrary key-value pairs (only simple scalar reprs recommended).
+    """
+
+    if not _ENABLED:
+        return
+    fields: list[str] = ["GENAIDEBUG", f"event={event}"]
+    if obj is not None:
+        fields.append(f"class={obj.__class__.__name__}")
+        # Include summary after key-value list for readability
+    for k, v in info.items():
+        if v is None:
+            continue
+        try:
+            if isinstance(v, (list, tuple, set)):
+                fields.append(f"{k}_count={len(v)}")
+            else:
+                fields.append(f"{k}={v}")
+        except Exception:  # pragma: no cover
+            continue
+    if obj is not None:
+        fields.append("repr=" + summarize_genai(obj))
+    _LOGGER.debug(" ".join(fields))
+
+
+__all__ = [
+    "is_enabled",
+    "genai_debug_log",
+    "summarize_genai",
+]