mingx 0.1.0__py3-none-any.whl

mingx/genai/io.py

@@ -0,0 +1,439 @@
+"""
+GenAI 输入/输出记录：优先使用 Span Event，符合 OTEL GenAI 规范。
+
+与 Traceloop 等 SDK 一致：模型的输入/输出优先通过 Event 记录，避免大 payload
+撑大 Span、便于后端对 Event 单独采样或脱敏。也可选记录为 Span 属性。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Literal, Optional
+
+from mingx.genai.attributes import (
+    GEN_AI_INPUT_MESSAGES,
+    GEN_AI_OUTPUT_MESSAGES,
+    GEN_AI_SYSTEM_INSTRUCTIONS,
+)
+
+RecordInputOutputAs = Literal["events", "attributes", "none"]
+
+# Event 名称（与 OTEL GenAI 语义一致，便于后端识别）
+GEN_AI_EVENT_INPUT = "gen_ai.input"
+GEN_AI_EVENT_OUTPUT = "gen_ai.output"
+GEN_AI_EVENT_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+
+
+def _coerce_attribute_value(value: Any) -> Any:
+    """OTEL 属性值：str / int / float / bool / Sequence 或转 str；None 转为空串。"""
+    if value is None:
+        return ""
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [_coerce_attribute_value(x) for x in value]
+    if isinstance(value, dict):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+def record_llm_input_output(
+    span: Any,
+    input_messages: List[Dict[str, Any]],
+    output_messages: List[Dict[str, Any]],
+    *,
+    record_as: RecordInputOutputAs = "events",
+    system_instructions: Optional[List[Dict[str, Any]]] = None,
+    max_length: Optional[int] = None,
+) -> None:
+    """
+    在 Span 上记录 LLM 输入/输出，优先使用 Event（推荐）。
+
+    与 OpenTelemetry GenAI 语义一致：gen_ai.input.messages、gen_ai.output.messages。
+    使用 Event 时：Span 本体保持精简，后端可对 Event 单独采样、脱敏或存储。
+
+    Args:
+        span: OpenTelemetry Span（需支持 add_event / set_attribute）。
+        input_messages: 输入消息列表，每项建议 { "role": "user"|"assistant"|"system", "content": "..." }。
+        output_messages: 输出消息列表，结构同上。
+        record_as: "events"（默认，推荐）| "attributes" | "none"。
+        system_instructions: 可选，系统指令（单独一条 Event 或属性）。
+        max_length: 可选，对单条 content 截断长度（字符），避免过大。
+    """
+    if record_as == "none":
+        return
+    if not span.is_recording():
+        return
+
+    def _truncate(obj: Any) -> Any:
+        if max_length is None:
+            return obj
+        if isinstance(obj, dict):
+            if "content" in obj and isinstance(obj["content"], str) and len(obj["content"]) > max_length:
+                return {**obj, "content": obj["content"][:max_length] + "..."}
+            return {k: _truncate(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [_truncate(x) for x in obj]
+        return obj
+
+    input_messages = _truncate(input_messages)
+    output_messages = _truncate(output_messages)
+    payload_input = json.dumps(input_messages, ensure_ascii=False)
+    payload_output = json.dumps(output_messages, ensure_ascii=False)
+
+    if record_as == "events":
+        span.add_event(GEN_AI_EVENT_INPUT, attributes={GEN_AI_INPUT_MESSAGES: payload_input})
+        span.add_event(GEN_AI_EVENT_OUTPUT, attributes={GEN_AI_OUTPUT_MESSAGES: payload_output})
+        if system_instructions is not None:
+            payload_sys = json.dumps(system_instructions, ensure_ascii=False)
+            span.add_event(GEN_AI_EVENT_SYSTEM_INSTRUCTIONS, attributes={GEN_AI_SYSTEM_INSTRUCTIONS: payload_sys})
+    elif record_as == "attributes":
+        span.set_attribute(GEN_AI_INPUT_MESSAGES, payload_input)
+        span.set_attribute(GEN_AI_OUTPUT_MESSAGES, payload_output)
+        if system_instructions is not None:
+            span.set_attribute(GEN_AI_SYSTEM_INSTRUCTIONS, json.dumps(system_instructions, ensure_ascii=False))
+
+
+def _is_langchain_message(obj: Any) -> bool:
+    """Duck-typing: LangChain BaseMessage 有 type 与 content。"""
+    return (
+        obj is not None
+        and hasattr(obj, "type")
+        and hasattr(obj, "content")
+        and isinstance(getattr(obj, "type", None), str)
+    )
+
+
+def _message_type_to_role(msg_type: str) -> str:
+    """LangChain message type -> GenAI role."""
+    t = (msg_type or "").strip().lower()
+    if t == "system":
+        return "system"
+    if t == "human":
+        return "user"
+    if t == "ai":
+        return "assistant"
+    return msg_type or "user"
+
+
+def _message_content_to_serializable(content: Any, truncate_fn: Any) -> Any:
+    """将 Message.content（str 或 content blocks 列表）转为可 JSON 的格式。"""
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return truncate_fn(content)
+    if isinstance(content, (list, tuple)):
+        out: List[Any] = []
+        for block in content:
+            if isinstance(block, dict):
+                out.append(block)
+            elif hasattr(block, "model_dump"):
+                out.append(block.model_dump())
+            elif isinstance(block, str):
+                out.append({"type": "text", "text": truncate_fn(block)})
+            else:
+                out.append({"type": "unknown", "value": str(block)})
+        return out
+    return str(content)
+
+
+def _langchain_messages_to_messages_json(
+    messages: List[Any],
+    truncate_fn: Any,
+) -> List[Dict[str, Any]]:
+    """将 LangChain Message 列表转为 [{"role": "...", "content": ...}, ...] 的 JSON 友好结构。"""
+    result: List[Dict[str, Any]] = []
+    for m in messages:
+        if not _is_langchain_message(m):
+            return []  # 非全为 message 时交给默认序列化
+        msg_type = getattr(m, "type", "user")
+        content = getattr(m, "content", None)
+        role = _message_type_to_role(msg_type)
+        result.append({
+            "role": role,
+            "content": _message_content_to_serializable(content, truncate_fn),
+        })
+    return result
+
+
+def _serialize_span_io(
+    data: Any,
+    max_length: Optional[int],
+) -> str:
+    def _truncate_str(s: str) -> str:
+        if max_length is not None and len(s) > max_length:
+            return s[:max_length] + "..."
+        return s
+
+    def _to_serializable(obj: Any) -> Any:
+        if obj is None:
+            return None
+        if isinstance(obj, str):
+            return _truncate_str(obj)
+        if isinstance(obj, dict):
+            return {k: _to_serializable(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            seq = list(obj)
+            if seq and _is_langchain_message(seq[0]) and all(_is_langchain_message(x) for x in seq):
+                return _langchain_messages_to_messages_json(seq, _truncate_str)
+            return [_to_serializable(x) for x in obj]
+        if hasattr(obj, "page_content") and hasattr(obj, "metadata"):
+            return {"page_content": _truncate_str(getattr(obj, "page_content", "") or ""), "metadata": getattr(obj, "metadata", {}) or {}}
+        # 如 PromptValue 等带 .messages 的对象，统一转为 [{"role","content"}] 的 JSON
+        if hasattr(obj, "messages"):
+            msgs = getattr(obj, "messages", None)
+            if isinstance(msgs, (list, tuple)) and msgs and all(_is_langchain_message(m) for m in msgs):
+                return _langchain_messages_to_messages_json(list(msgs), _truncate_str)
+        if _is_langchain_message(obj):
+            role = _message_type_to_role(getattr(obj, "type", "user"))
+            content = _message_content_to_serializable(getattr(obj, "content", None), _truncate_str)
+            return [{"role": role, "content": content}]
+        try:
+            json.dumps(obj)
+            return obj
+        except (TypeError, ValueError):
+            return str(obj)
+
+    return json.dumps(_to_serializable(data), ensure_ascii=False)
+
+
+def record_span_input(
+    span: Any,
+    input_data: Any,
+    *,
+    record_as: RecordInputOutputAs = "events",
+    max_length: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    event_attributes: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    在 Span 上仅记录输入。可与 record_span_output 分开调用，按需只添加输入或只添加输出。
+    attributes: 自定义 Span 属性（会写入当前 Span）。
+    event_attributes: 自定义 Event 属性（record_as=events 时合并到 gen_ai.input 的 attributes）。
+    """
+    if record_as == "none" and not (attributes or event_attributes):
+        return
+    if not span.is_recording():
+        return
+    if attributes:
+        for k, v in attributes.items():
+            span.set_attribute(k, _coerce_attribute_value(v))
+    if record_as != "none":
+        payload = _serialize_span_io(input_data, max_length)
+        ev_attrs = {GEN_AI_INPUT_MESSAGES: payload}
+        if event_attributes:
+            for k, v in event_attributes.items():
+                ev_attrs[k] = _coerce_attribute_value(v)
+        if record_as == "events":
+            span.add_event(GEN_AI_EVENT_INPUT, attributes=ev_attrs)
+        elif record_as == "attributes":
+            span.set_attribute(GEN_AI_INPUT_MESSAGES, payload)
+            for k, v in (event_attributes or {}).items():
+                span.set_attribute(k, _coerce_attribute_value(v))
+
+
+def record_span_output(
+    span: Any,
+    output_data: Any,
+    *,
+    record_as: RecordInputOutputAs = "events",
+    max_length: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    event_attributes: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    在 Span 上仅记录输出。可与 record_span_input 分开调用，按需只添加输入或只添加输出。
+    attributes: 自定义 Span 属性（会写入当前 Span）。
+    event_attributes: 自定义 Event 属性（record_as=events 时合并到 gen_ai.output 的 attributes）。
+    """
+    if record_as == "none" and not (attributes or event_attributes):
+        return
+    if not span.is_recording():
+        return
+    if attributes:
+        for k, v in attributes.items():
+            span.set_attribute(k, _coerce_attribute_value(v))
+    if record_as != "none":
+        payload = _serialize_span_io(output_data, max_length)
+        ev_attrs = {GEN_AI_OUTPUT_MESSAGES: payload}
+        if event_attributes:
+            for k, v in event_attributes.items():
+                ev_attrs[k] = _coerce_attribute_value(v)
+        if record_as == "events":
+            span.add_event(GEN_AI_EVENT_OUTPUT, attributes=ev_attrs)
+        elif record_as == "attributes":
+            span.set_attribute(GEN_AI_OUTPUT_MESSAGES, payload)
+            for k, v in (event_attributes or {}).items():
+                span.set_attribute(k, _coerce_attribute_value(v))
+
+
+def record_span_input_output(
+    span: Any,
+    input_data: Any,
+    output_data: Any,
+    *,
+    record_as: RecordInputOutputAs = "events",
+    max_length: Optional[int] = None,
+) -> None:
+    """
+    在 Span 上记录任意类型的输入/输出（chain、tool、retriever 等），优先使用 Event。
+
+    与 record_llm_input_output 一致：同一套 Event 名与属性键，payload 为 JSON 序列化后的
+    input_data / output_data（dict、list、str 等可序列化结构）。
+
+    Args:
+        span: OpenTelemetry Span。
+        input_data: 可 JSON 序列化的输入（如 chain 的 inputs、tool 的 input_str、retriever 的 query）。
+        output_data: 可 JSON 序列化的输出（如 chain 的 outputs、tool 的 output、retriever 的 documents）。
+        record_as: "events"（默认）| "attributes" | "none"。
+        max_length: 可选，对字符串类 content 截断长度。
+    """
+    if record_as == "none":
+        return
+    if not span.is_recording():
+        return
+    payload_input = _serialize_span_io(input_data, max_length)
+    payload_output = _serialize_span_io(output_data, max_length)
+    if record_as == "events":
+        span.add_event(GEN_AI_EVENT_INPUT, attributes={GEN_AI_INPUT_MESSAGES: payload_input})
+        span.add_event(GEN_AI_EVENT_OUTPUT, attributes={GEN_AI_OUTPUT_MESSAGES: payload_output})
+    elif record_as == "attributes":
+        span.set_attribute(GEN_AI_INPUT_MESSAGES, payload_input)
+        span.set_attribute(GEN_AI_OUTPUT_MESSAGES, payload_output)
+
+
+def span_input(
+    input_data: Any,
+    *,
+    span: Optional[Any] = None,
+    record_as: RecordInputOutputAs = "events",
+    max_length: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    event_attributes: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    向 Span 添加输入（入参）。可与 span_output 分开调用，按需只添加输入或只添加输出。
+
+    用法（原生 OTEL 风格）：
+        with get_tracer().start_as_current_span("call_model") as span:
+            span_input({"prompt": "..."})
+            result = call_model()
+            span_output(result)
+
+    若未传 span，则对当前 Span 生效；无活跃 Span 或未 recording 时静默忽略。
+    attributes: 自定义 Span 属性。event_attributes: 自定义 Event 属性（合并到 gen_ai.input）。
+    """
+    from opentelemetry import trace
+    s = span if span is not None else trace.get_current_span()
+    record_span_input(
+        s,
+        input_data,
+        record_as=record_as,
+        max_length=max_length,
+        attributes=attributes,
+        event_attributes=event_attributes,
+    )
+
+
+def span_output(
+    output_data: Any,
+    *,
+    span: Optional[Any] = None,
+    record_as: RecordInputOutputAs = "events",
+    max_length: Optional[int] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    event_attributes: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    向 Span 添加输出（返回值）。可与 span_input 分开调用，按需只添加输入或只添加输出。
+
+    用法（原生 OTEL 风格）：
+        with get_tracer().start_as_current_span("call_model") as span:
+            span_input({"prompt": "..."})
+            result = call_model()
+            span_output(result)
+
+    若未传 span，则对当前 Span 生效；无活跃 Span 或未 recording 时静默忽略。
+    attributes: 自定义 Span 属性。event_attributes: 自定义 Event 属性（合并到 gen_ai.output）。
+    """
+    from opentelemetry import trace
+    s = span if span is not None else trace.get_current_span()
+    record_span_output(
+        s,
+        output_data,
+        record_as=record_as,
+        max_length=max_length,
+        attributes=attributes,
+        event_attributes=event_attributes,
+    )
+
+
+def record_current_span_input_output(
+    input_data: Any,
+    output_data: Any,
+    *,
+    record_as: RecordInputOutputAs = "events",
+    max_length: Optional[int] = None,
+) -> None:
+    """
+    手动向当前 Span 上报输入/输出（入参作为输入，返回值作为输出，无返回值传 None 或空即可）。
+
+    适用于：在 @traced 装饰的函数内、或已有 Span 的上下文中，手动补充或覆盖输入/输出。
+    若当前无活跃 Span 或 Span 未在 recording 则静默忽略。
+
+    Args:
+        input_data: 可序列化的输入（如函数入参、dict、list、str）。
+        output_data: 可序列化的输出（如函数返回值）；无返回值可传 None 或 {}。
+        record_as: "events"（默认）| "attributes" | "none"。
+        max_length: 可选，单条字符串截断长度。
+    """
+    from opentelemetry import trace
+    span = trace.get_current_span()
+    if not span.is_recording():
+        return
+    record_span_input_output(
+        span,
+        input_data,
+        output_data,
+        record_as=record_as,
+        max_length=max_length,
+    )
+
+
+def build_input_messages_from_prompts(prompts: List[str]) -> List[Dict[str, Any]]:
+    """将 LangChain 的 prompts（str 列表）转为 GenAI 规范的 input messages 结构。"""
+    return [{"role": "user", "content": p} for p in (prompts or [])]
+
+
+def build_input_messages_from_langchain_messages(
+    messages: List[Any],
+    max_length: Optional[int] = None,
+) -> List[Dict[str, Any]]:
+    """
+    将 LangChain BaseMessage 列表转为 GenAI 规范的 input messages 结构 [{"role", "content"}, ...]。
+    Adapter 在 on_chat_model_start 收到 messages 后，在 on_llm_end 用此函数生成 input_messages。
+    """
+    if not messages:
+        return []
+    if not all(_is_langchain_message(m) for m in messages):
+        return []
+    truncate_fn = (lambda s: s[:max_length] + "..." if max_length is not None and len(s) > max_length else s) if max_length else (lambda s: s)
+    return _langchain_messages_to_messages_json(messages, truncate_fn)
+
+
+def build_output_messages_from_llm_result(response: Any) -> List[Dict[str, Any]]:
+    """从 LangChain LLMResult 提取 output messages 结构。"""
+    out: List[Dict[str, Any]] = []
+    try:
+        for gen_list in (response.generations or []):
+            for gen in gen_list or []:
+                if hasattr(gen, "message") and gen.message:
+                    msg = gen.message
+                    content = getattr(msg, "content", None) or ""
+                    if isinstance(content, str):
+                        out.append({"role": "assistant", "content": content})
+                    else:
+                        out.append({"role": "assistant", "content": str(content)})
+    except Exception:
+        pass
+    return out

mingx/genai/span_attributes.py

@@ -0,0 +1,172 @@
+"""
+各类型 Span 上送属性的数据模型。
+
+将 LLM/Chain/Tool/Retriever 等不同语义的 Span 属性拆成独立模型，
+通过 to_attributes() 统一输出为 OpenTelemetry 所需的 Dict[str, Any]，保证设计清晰、易扩展。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from mingx._default_attributes import (
+    MINGX_SPAN_TYPE,
+    SPAN_TYPE_CHAIN,
+    SPAN_TYPE_MODEL,
+    SPAN_TYPE_RETRIEVER,
+    SPAN_TYPE_TOOL,
+)
+
+from . import attributes as genai_attrs
+
+# 适配器层常用键（如 LangChain run_id）
+LC_RUN_ID = "lc.run_id"
+
+
+@dataclass(frozen=True)
+class InferenceSpanAttributes:
+    """推理/LLM Span 上送属性（gen_ai.request.* 等）。"""
+
+    operation_name: str
+    provider_name: str
+    run_id: str
+    span_type: str = SPAN_TYPE_MODEL
+    model: Optional[str] = None
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    top_p: Optional[float] = None
+    top_k: Optional[int] = None
+    frequency_penalty: Optional[float] = None
+    presence_penalty: Optional[float] = None
+    stop_sequences: Optional[List[str]] = None
+
+    def to_attributes(self) -> Dict[str, Any]:
+        d = genai_attrs.inference_attributes(
+            self.operation_name,
+            self.provider_name,
+            model=self.model,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens,
+            top_p=self.top_p,
+            top_k=self.top_k,
+            frequency_penalty=self.frequency_penalty,
+            presence_penalty=self.presence_penalty,
+            stop_sequences=self.stop_sequences,
+        )
+        d[LC_RUN_ID] = self.run_id
+        d[MINGX_SPAN_TYPE] = self.span_type
+        return d
+
+
+@dataclass(frozen=True)
+class ChainSpanAttributes:
+    """Chain Span 上送属性。"""
+
+    run_id: str
+    operation_name: str = genai_attrs.OPERATION_INVOKE_AGENT
+    span_type: str = SPAN_TYPE_CHAIN
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    def to_attributes(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            LC_RUN_ID: self.run_id,
+            genai_attrs.GEN_AI_OPERATION_NAME: self.operation_name,
+            MINGX_SPAN_TYPE: self.span_type,
+        }
+        d.update(self.extra)
+        return d
+
+
+@dataclass(frozen=True)
+class ToolSpanAttributes:
+    """Execute Tool Span 上送属性。"""
+
+    tool_name: str
+    run_id: str
+    span_type: str = SPAN_TYPE_TOOL
+    tool_description: Optional[str] = None
+    tool_call_id: Optional[str] = None
+    tool_type: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    def to_attributes(self) -> Dict[str, Any]:
+        d = genai_attrs.execute_tool_attributes(
+            self.tool_name,
+            tool_description=self.tool_description,
+            tool_call_id=self.tool_call_id,
+            tool_type=self.tool_type,
+        )
+        d[LC_RUN_ID] = self.run_id
+        d[MINGX_SPAN_TYPE] = self.span_type
+        d.update(self.extra)
+        return d
+
+
+@dataclass(frozen=True)
+class RetrieverSpanAttributes:
+    """Retriever Span 上送属性。"""
+
+    run_id: str
+    operation_name: str = "retriever"
+    span_type: str = SPAN_TYPE_RETRIEVER
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    def to_attributes(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            LC_RUN_ID: self.run_id,
+            genai_attrs.GEN_AI_OPERATION_NAME: self.operation_name,
+            MINGX_SPAN_TYPE: self.span_type,
+        }
+        d.update(self.extra)
+        return d
+
+
+# ---------------------------------------------------------------------------
+# 大模型调用结束时的上送数据：Token 使用、响应元数据、输入/输出消息
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    """Token 使用情况（gen_ai.usage.*），用于推理/Embeddings 等 Span 结束时的属性。"""
+
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+
+    def apply_to_span(self, span: Any) -> None:
+        """将 usage 写入当前 Span 的 gen_ai.usage.* 属性。"""
+        if not getattr(span, "is_recording", lambda: False)():
+            return
+        if self.input_tokens is not None:
+            span.set_attribute(genai_attrs.GEN_AI_USAGE_INPUT_TOKENS, self.input_tokens)
+        if self.output_tokens is not None:
+            span.set_attribute(genai_attrs.GEN_AI_USAGE_OUTPUT_TOKENS, self.output_tokens)
+
+
+@dataclass(frozen=True)
+class InferenceResponseAttributes:
+    """大模型调用响应元数据（gen_ai.response.*），在 Span 结束时上送。"""
+
+    response_model: Optional[str] = None
+    finish_reasons: Optional[List[str]] = None
+    response_id: Optional[str] = None
+
+    def apply_to_span(self, span: Any) -> None:
+        """将响应元数据写入当前 Span 的 gen_ai.response.* 属性。"""
+        if not getattr(span, "is_recording", lambda: False)():
+            return
+        if self.response_model is not None:
+            span.set_attribute(genai_attrs.GEN_AI_RESPONSE_MODEL, self.response_model)
+        if self.finish_reasons is not None:
+            span.set_attribute(genai_attrs.GEN_AI_RESPONSE_FINISH_REASONS, self.finish_reasons)
+        if self.response_id is not None:
+            span.set_attribute(genai_attrs.GEN_AI_RESPONSE_ID, self.response_id)
+
+
+@dataclass(frozen=True)
+class InferenceInputOutput:
+    """大模型调用的输入/输出消息体，用于 Span 的 Event 或属性记录（由 io.record_llm_input_output 写入）。"""
+
+    input_messages: List[Dict[str, Any]] = field(default_factory=list)
+    output_messages: List[Dict[str, Any]] = field(default_factory=list)