mingx 0.1.0__py3-none-any.whl

mingx/decorator.py

@@ -0,0 +1,185 @@
+"""
+Method-level automatic tracing via @traced decorator.
+
+Supports sync and async; uses mingx._trace.get_tracer() for consistency
+with global TracerProvider. 默认记录函数入参（输入）与返回值（输出）到当前 Span。
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+from opentelemetry.trace import Status, StatusCode
+
+from mingx._default_attributes import MINGX_SPAN_TYPE
+from mingx._trace import get_tracer
+from mingx.genai.io import record_span_input, record_span_output
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def traced(
+    func: Optional[F] = None,
+    *,
+    name: Optional[str] = None,
+    span_type: Optional[str] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    record_io: bool = True,
+    record_io_as: str = "events",
+    max_content_length: Optional[int] = None,
+) -> Any:
+    """
+    Decorator that creates an OpenTelemetry span for each call.
+
+    Usage:
+        @traced
+        def my_func(): ...
+
+        @traced(name="custom_span", span_type="model", attributes={"key": "value"})
+        def other(): ...
+
+    span_type: 设置 mingx.span_type，如 "model", "retriever", "tool", "chain", "agent" 等（可扩展）。
+    record_io: 是否记录函数入参（输入）与返回值（输出），默认 True，与适配器行为一致。
+    record_io_as: "events"（默认）| "attributes" | "none"。
+    max_content_length: 可选，单条 content 截断长度。
+    Supports sync and async; on exception sets span status to ERROR and
+    record_exception, then re-raises.
+    """
+    attrs = dict(attributes or {})
+    if span_type is not None:
+        attrs[MINGX_SPAN_TYPE] = span_type
+
+    def decorator(f: F) -> F:
+        span_name = name or _default_span_name(f)
+
+        if inspect.iscoroutinefunction(f):
+            return _wrap_async(f, span_name, attrs, record_io, record_io_as, max_content_length)  # type: ignore[return-value]
+        return _wrap_sync(f, span_name, attrs, record_io, record_io_as, max_content_length)  # type: ignore[return-value]
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+def _default_span_name(func: Callable[..., Any]) -> str:
+    """Default span name: module.funcname or funcname."""
+    module = getattr(func, "__module__", "") or ""
+    qualname = getattr(func, "__qualname__", func.__name__)
+    if module:
+        return f"{module}.{qualname}"
+    return qualname
+
+
+def _args_to_input(args: tuple, kwargs: Dict[str, Any]) -> Dict[str, Any]:
+    """将 *args, **kwargs 转为可序列化的 input 结构（与适配器“入参作为输入”一致）。"""
+    return {"args": list(args), "kwargs": dict(kwargs)}
+
+
+def _wrap_sync(
+    func: F,
+    span_name: str,
+    attrs: Dict[str, Any],
+    record_io: bool,
+    record_io_as: str,
+    max_content_length: Optional[int],
+) -> F:
+    @functools.wraps(func)
+    def _inner(*args: Any, **kwargs: Any) -> Any:
+        tracer = get_tracer()
+        with tracer.start_as_current_span(span_name, attributes=attrs) as span:
+            if record_io and record_io_as != "none":
+                try:
+                    record_span_input(
+                        span,
+                        _args_to_input(args, kwargs),
+                        record_as=record_io_as,
+                        max_length=max_content_length,
+                    )
+                except Exception:
+                    pass
+            try:
+                result = func(*args, **kwargs)
+                if record_io and record_io_as != "none":
+                    try:
+                        record_span_output(
+                            span,
+                            result,
+                            record_as=record_io_as,
+                            max_length=max_content_length,
+                        )
+                    except Exception:
+                        pass
+                span.set_status(Status(StatusCode.OK))
+                return result
+            except Exception as e:
+                if record_io and record_io_as != "none":
+                    try:
+                        record_span_output(
+                            span,
+                            {"error": str(e), "error_type": type(e).__name__},
+                            record_as=record_io_as,
+                            max_length=max_content_length,
+                        )
+                    except Exception:
+                        pass
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+                span.record_exception(e)
+                raise
+
+    return _inner  # type: ignore[return-value]
+
+
+def _wrap_async(
+    func: F,
+    span_name: str,
+    attrs: Dict[str, Any],
+    record_io: bool,
+    record_io_as: str,
+    max_content_length: Optional[int],
+) -> F:
+    @functools.wraps(func)
+    async def _inner(*args: Any, **kwargs: Any) -> Any:
+        tracer = get_tracer()
+        with tracer.start_as_current_span(span_name, attributes=attrs) as span:
+            if record_io and record_io_as != "none":
+                try:
+                    record_span_input(
+                        span,
+                        _args_to_input(args, kwargs),
+                        record_as=record_io_as,
+                        max_length=max_content_length,
+                    )
+                except Exception:
+                    pass
+            try:
+                result = await func(*args, **kwargs)
+                if record_io and record_io_as != "none":
+                    try:
+                        record_span_output(
+                            span,
+                            result,
+                            record_as=record_io_as,
+                            max_length=max_content_length,
+                        )
+                    except Exception:
+                        pass
+                span.set_status(Status(StatusCode.OK))
+                return result
+            except Exception as e:
+                if record_io and record_io_as != "none":
+                    try:
+                        record_span_output(
+                            span,
+                            {"error": str(e), "error_type": type(e).__name__},
+                            record_as=record_io_as,
+                            max_length=max_content_length,
+                        )
+                    except Exception:
+                        pass
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+                span.record_exception(e)
+                raise
+
+    return _inner  # type: ignore[return-value]

mingx/genai/__init__.py

@@ -0,0 +1,99 @@
+"""
+GenAI semantic layer: OTEL GenAI span names and attributes.
+
+See: https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+"""
+
+from mingx.genai import attributes
+from mingx.genai.attributes import (
+    GEN_AI_OPERATION_NAME,
+    GEN_AI_PROVIDER_NAME,
+    GEN_AI_REQUEST_MODEL,
+    GEN_AI_TOOL_NAME,
+    GEN_AI_USAGE_INPUT_TOKENS,
+    GEN_AI_USAGE_OUTPUT_TOKENS,
+    OPERATION_CHAT,
+    OPERATION_EMBEDDINGS,
+    OPERATION_EXECUTE_TOOL,
+    execute_tool_attributes,
+    inference_attributes,
+    embeddings_attributes,
+    inference_span_name,
+    execute_tool_span_name,
+    embeddings_span_name,
+)
+from mingx.genai.span_attributes import (
+    ChainSpanAttributes,
+    InferenceInputOutput,
+    InferenceResponseAttributes,
+    InferenceSpanAttributes,
+    RetrieverSpanAttributes,
+    TokenUsage,
+    ToolSpanAttributes,
+)
+from mingx.genai.spans import (
+    inference_span,
+    embeddings_span,
+    execute_tool_span,
+    build_inference_span_args,
+    build_execute_tool_span_args,
+    build_embeddings_span_args,
+)
+from mingx.genai.io import (
+    GEN_AI_EVENT_INPUT,
+    GEN_AI_EVENT_OUTPUT,
+    GEN_AI_EVENT_SYSTEM_INSTRUCTIONS,
+    build_input_messages_from_prompts,
+    build_output_messages_from_llm_result,
+    record_llm_input_output,
+    record_span_input,
+    record_span_output,
+    record_span_input_output,
+    span_input,
+    span_output,
+    record_current_span_input_output,
+)
+
+__all__ = [
+    "ChainSpanAttributes",
+    "InferenceInputOutput",
+    "InferenceResponseAttributes",
+    "InferenceSpanAttributes",
+    "RetrieverSpanAttributes",
+    "TokenUsage",
+    "ToolSpanAttributes",
+    "attributes",
+    "GEN_AI_OPERATION_NAME",
+    "GEN_AI_PROVIDER_NAME",
+    "GEN_AI_REQUEST_MODEL",
+    "GEN_AI_TOOL_NAME",
+    "GEN_AI_USAGE_INPUT_TOKENS",
+    "GEN_AI_USAGE_OUTPUT_TOKENS",
+    "OPERATION_CHAT",
+    "OPERATION_EMBEDDINGS",
+    "OPERATION_EXECUTE_TOOL",
+    "inference_attributes",
+    "embeddings_attributes",
+    "execute_tool_attributes",
+    "inference_span_name",
+    "execute_tool_span_name",
+    "embeddings_span_name",
+    "inference_span",
+    "embeddings_span",
+    "execute_tool_span",
+    "build_inference_span_args",
+    "build_execute_tool_span_args",
+    "build_embeddings_span_args",
+    "GEN_AI_EVENT_INPUT",
+    "GEN_AI_EVENT_OUTPUT",
+    "GEN_AI_EVENT_SYSTEM_INSTRUCTIONS",
+    "build_input_messages_from_prompts",
+    "build_output_messages_from_llm_result",
+    "record_llm_input_output",
+    "record_span_input",
+    "record_span_output",
+    "record_span_input_output",
+    "span_input",
+    "span_output",
+    "record_current_span_input_output",
+]

mingx/genai/attributes.py

@@ -0,0 +1,176 @@
+"""
+OpenTelemetry GenAI semantic convention attribute names and builders.
+
+Follows: https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+Respects OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental for experimental attributes.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+# --- Attribute key constants (gen_ai.* and related) ---
+
+GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+GEN_AI_PROVIDER_NAME = "gen_ai.provider.name"
+GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+GEN_AI_REQUEST_TEMPERATURE = "gen_ai.request.temperature"
+GEN_AI_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens"
+GEN_AI_REQUEST_TOP_P = "gen_ai.request.top_p"
+GEN_AI_REQUEST_TOP_K = "gen_ai.request.top_k"
+GEN_AI_REQUEST_FREQUENCY_PENALTY = "gen_ai.request.frequency_penalty"
+GEN_AI_REQUEST_PRESENCE_PENALTY = "gen_ai.request.presence_penalty"
+GEN_AI_REQUEST_STOP_SEQUENCES = "gen_ai.request.stop_sequences"
+GEN_AI_RESPONSE_ID = "gen_ai.response.id"
+GEN_AI_RESPONSE_MODEL = "gen_ai.response.model"
+GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons"
+GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+GEN_AI_TOOL_NAME = "gen_ai.tool.name"
+GEN_AI_TOOL_DESCRIPTION = "gen_ai.tool.description"
+GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id"
+GEN_AI_TOOL_TYPE = "gen_ai.tool.type"
+ERROR_TYPE = "error.type"
+
+# 输入/输出（Opt-In，建议通过 Span Event 记录，见 genai.io）
+GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages"
+GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages"
+GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+
+# Well-known values for gen_ai.operation.name
+OPERATION_CHAT = "chat"
+OPERATION_EMBEDDINGS = "embeddings"
+OPERATION_EXECUTE_TOOL = "execute_tool"
+OPERATION_GENERATE_CONTENT = "generate_content"
+OPERATION_TEXT_COMPLETION = "text_completion"
+OPERATION_INVOKE_AGENT = "invoke_agent"
+OPERATION_CREATE_AGENT = "create_agent"
+
+# Well-known provider names (subset)
+PROVIDER_OPENAI = "openai"
+PROVIDER_ANTHROPIC = "anthropic"
+PROVIDER_GCP_VERTEX_AI = "gcp.vertex_ai"
+PROVIDER_GCP_GEN_AI = "gcp.gen_ai"
+PROVIDER_AZURE_OPENAI = "azure.ai.openai"
+PROVIDER_AWS_BEDROCK = "aws.bedrock"
+
+# Span name templates per spec
+# Inference: {gen_ai.operation.name} {gen_ai.request.model}
+# Execute tool: execute_tool {gen_ai.tool.name}
+# Embeddings: embeddings {gen_ai.request.model}
+
+
+def _use_experimental() -> bool:
+    opt_in = os.environ.get("OTEL_SEMCONV_STABILITY_OPT_IN", "")
+    return "gen_ai_latest_experimental" in opt_in.replace(" ", "").split(",")
+
+
+def inference_attributes(
+    operation_name: str,
+    provider_name: str,
+    *,
+    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,
+    response_id: Optional[str] = None,
+    response_model: Optional[str] = None,
+    finish_reasons: Optional[List[str]] = None,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Build attribute dict for an inference (chat/completion) span."""
+    attrs: Dict[str, Any] = {
+        GEN_AI_OPERATION_NAME: operation_name,
+        GEN_AI_PROVIDER_NAME: provider_name,
+    }
+    if model is not None:
+        attrs[GEN_AI_REQUEST_MODEL] = model
+    if temperature is not None:
+        attrs[GEN_AI_REQUEST_TEMPERATURE] = temperature
+    if max_tokens is not None:
+        attrs[GEN_AI_REQUEST_MAX_TOKENS] = max_tokens
+    if top_p is not None:
+        attrs[GEN_AI_REQUEST_TOP_P] = top_p
+    if top_k is not None:
+        attrs[GEN_AI_REQUEST_TOP_K] = top_k
+    if frequency_penalty is not None:
+        attrs[GEN_AI_REQUEST_FREQUENCY_PENALTY] = frequency_penalty
+    if presence_penalty is not None:
+        attrs[GEN_AI_REQUEST_PRESENCE_PENALTY] = presence_penalty
+    if stop_sequences is not None:
+        attrs[GEN_AI_REQUEST_STOP_SEQUENCES] = stop_sequences
+    if response_id is not None:
+        attrs[GEN_AI_RESPONSE_ID] = response_id
+    if response_model is not None:
+        attrs[GEN_AI_RESPONSE_MODEL] = response_model
+    if finish_reasons is not None:
+        attrs[GEN_AI_RESPONSE_FINISH_REASONS] = finish_reasons
+    if input_tokens is not None:
+        attrs[GEN_AI_USAGE_INPUT_TOKENS] = input_tokens
+    if output_tokens is not None:
+        attrs[GEN_AI_USAGE_OUTPUT_TOKENS] = output_tokens
+    return attrs
+
+
+def embeddings_attributes(
+    provider_name: str,
+    *,
+    model: Optional[str] = None,
+    input_tokens: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Build attribute dict for an embeddings span."""
+    attrs: Dict[str, Any] = {
+        GEN_AI_OPERATION_NAME: OPERATION_EMBEDDINGS,
+        GEN_AI_PROVIDER_NAME: provider_name,
+    }
+    if model is not None:
+        attrs[GEN_AI_REQUEST_MODEL] = model
+    if input_tokens is not None:
+        attrs[GEN_AI_USAGE_INPUT_TOKENS] = input_tokens
+    return attrs
+
+
+def execute_tool_attributes(
+    tool_name: str,
+    *,
+    tool_description: Optional[str] = None,
+    tool_call_id: Optional[str] = None,
+    tool_type: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build attribute dict for an execute_tool span."""
+    attrs: Dict[str, Any] = {
+        GEN_AI_OPERATION_NAME: OPERATION_EXECUTE_TOOL,
+        GEN_AI_TOOL_NAME: tool_name,
+    }
+    if tool_description is not None:
+        attrs[GEN_AI_TOOL_DESCRIPTION] = tool_description
+    if tool_call_id is not None:
+        attrs[GEN_AI_TOOL_CALL_ID] = tool_call_id
+    if tool_type is not None:
+        attrs[GEN_AI_TOOL_TYPE] = tool_type
+    return attrs
+
+
+def inference_span_name(operation_name: str, model: Optional[str] = None) -> str:
+    """Span name for inference: {gen_ai.operation.name} {gen_ai.request.model}."""
+    if model:
+        return f"{operation_name} {model}"
+    return operation_name
+
+
+def execute_tool_span_name(tool_name: str) -> str:
+    """Span name for execute_tool: execute_tool {gen_ai.tool.name}."""
+    return f"{OPERATION_EXECUTE_TOOL} {tool_name}"
+
+
+def embeddings_span_name(model: Optional[str] = None) -> str:
+    """Span name for embeddings span."""
+    if model:
+        return f"{OPERATION_EMBEDDINGS} {model}"
+    return OPERATION_EMBEDDINGS