mingx 0.1.0__py3-none-any.whl

mingx/__init__.py

@@ -0,0 +1,50 @@
+"""
+mingx: OpenTelemetry trace Python SDK with GenAI semantic conventions.
+
+- configure_tracer_provider / get_tracer: Tracer setup
+- traced: Method-level @traced decorator
+- OpenTelemetryCallbackHandler / get_langchain_callback: LangChain/LangGraph callbacks
+- span_input / span_output: 手动向 Span 添加输入或输出，支持自定义属性/Event（原生 OTEL 风格）
+- genai: GenAI span names and attributes (OTEL compliant)
+- 默认属性: mingx.workspace_id, mingx.span_type, mingx.user.id（支持 Baggage 传递）
+"""
+
+from mingx._trace import configure_tracer_provider, get_tracer, OTLPProtocol, AuthScheme
+from mingx.decorator import traced
+from mingx.adapters.langchain import (
+    OpenTelemetryCallbackHandler,
+    get_langchain_callback,
+)
+from mingx.genai.io import span_input, span_output
+from mingx._default_attributes import (
+    MINGX_WORKSPACE_ID,
+    MINGX_SPAN_TYPE,
+    MINGX_USER_ID,
+    SPAN_TYPE_AGENT,
+    SPAN_TYPE_CHAIN,
+    SPAN_TYPE_CUSTOM,
+    SPAN_TYPE_MODEL,
+    SPAN_TYPE_RETRIEVER,
+    SPAN_TYPE_TOOL,
+)
+
+__all__ = [
+    "configure_tracer_provider",
+    "get_tracer",
+    "OTLPProtocol",
+    "AuthScheme",
+    "traced",
+    "OpenTelemetryCallbackHandler",
+    "get_langchain_callback",
+    "span_input",
+    "span_output",
+    "MINGX_WORKSPACE_ID",
+    "MINGX_SPAN_TYPE",
+    "MINGX_USER_ID",
+    "SPAN_TYPE_AGENT",
+    "SPAN_TYPE_CHAIN",
+    "SPAN_TYPE_CUSTOM",
+    "SPAN_TYPE_MODEL",
+    "SPAN_TYPE_RETRIEVER",
+    "SPAN_TYPE_TOOL",
+]

mingx/_default_attributes.py

@@ -0,0 +1,76 @@
+"""
+默认 Span 属性及 Baggage 支持。
+
+通过 SpanProcessor 为每个 Span 添加 mingx.workspace_id、mingx.user.id（来自配置或 Baggage）；
+mingx.span_type 由调用方设置：@traced(span_type=...) 或适配器根据回调类型（model/tool/retriever/chain）自动设置。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from opentelemetry import context
+from opentelemetry.baggage import get_all as get_baggage_all
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+
+# 默认属性键名
+MINGX_WORKSPACE_ID = "mingx.workspace_id"
+MINGX_SPAN_TYPE = "mingx.span_type"
+MINGX_USER_ID = "mingx.user.id"
+
+# span_type 可选值（可扩展，由装饰器或适配器设置）
+SPAN_TYPE_MODEL = "model"
+SPAN_TYPE_RETRIEVER = "retriever"
+SPAN_TYPE_TOOL = "tool"
+SPAN_TYPE_CHAIN = "chain"
+SPAN_TYPE_AGENT = "agent"
+SPAN_TYPE_CUSTOM = "custom"  # 适配器方式下 span_type 为空时的默认值，表示自定义类型
+
+
+class DefaultAttributesSpanProcessor(SpanProcessor):
+    """
+    为每个 Span 添加默认属性：workspace_id、user_id 来自配置或 Baggage。
+    span_type 不由此处设置，由 @traced(span_type=...) 或适配器按调用类型设置。
+    """
+
+    def __init__(
+        self,
+        workspace_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        extra_attributes: Optional[Dict[str, Any]] = None,
+        use_baggage: bool = True,
+    ) -> None:
+        self._defaults: Dict[str, Any] = {}
+        if workspace_id is not None:
+            self._defaults[MINGX_WORKSPACE_ID] = workspace_id
+        if user_id is not None:
+            self._defaults[MINGX_USER_ID] = user_id
+        if extra_attributes:
+            self._defaults.update(extra_attributes)
+        self._use_baggage = use_baggage
+
+    def on_start(
+        self,
+        span: Span,
+        parent_context: Optional[context.Context] = None,
+    ) -> None:
+        attrs: Dict[str, Any] = dict(self._defaults)
+        if self._use_baggage and parent_context is not None:
+            baggage = get_baggage_all(parent_context)
+            if baggage:
+                for key in (MINGX_WORKSPACE_ID, MINGX_SPAN_TYPE, MINGX_USER_ID):
+                    val = baggage.get(key)
+                    if val is not None:
+                        attrs[key] = str(val) if not isinstance(val, str) else val
+        for k, v in attrs.items():
+            if v is not None:
+                span.set_attribute(k, v)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True

mingx/_trace.py

@@ -0,0 +1,147 @@
+"""
+Tracer and TracerProvider configuration for mingx.
+
+Uses the global TracerProvider when set; provides optional one-shot
+configure_tracer_provider for applications that do not configure OTel themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Literal, Optional
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+from opentelemetry.trace import Tracer
+
+from mingx._default_attributes import DefaultAttributesSpanProcessor
+
+OTLPProtocol = Literal["grpc", "http"]
+AuthScheme = Literal["bearer", "basic"]
+
+# Package version for get_tracer; keep in sync with pyproject.toml or use importlib.metadata
+__all__ = ["get_tracer", "configure_tracer_provider", "OTLPProtocol", "AuthScheme"]
+
+_PACKAGE_NAME = "mingx"
+_PACKAGE_VERSION = "0.1.0"
+
+
+def get_tracer(
+    name: str = _PACKAGE_NAME,
+    version: Optional[str] = None,
+) -> Tracer:
+    """
+    Return a Tracer from the global TracerProvider.
+
+    Uses opentelemetry.trace.get_tracer() so that whatever Provider is
+    set globally (by the app or by configure_tracer_provider) is used.
+    """
+    return trace.get_tracer(name or _PACKAGE_NAME, version or _PACKAGE_VERSION)
+
+
+def configure_tracer_provider(
+    service_name: str,
+    otlp_endpoint: Optional[str] = None,
+    exporter: Optional[SpanExporter] = None,
+    protocol: OTLPProtocol = "grpc",
+    api_key: Optional[str] = None,
+    auth_scheme: AuthScheme = "bearer",
+    workspace_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    extra_attributes: Optional[Dict[str, Any]] = None,
+    use_baggage: bool = True,
+) -> TracerProvider:
+    """
+    Create and set the global TracerProvider with BatchSpanProcessor and OTLP export.
+
+    Args:
+        service_name: Used as service.name in the resource.
+        otlp_endpoint: OTLP endpoint URL.
+            - For gRPC: e.g. http://localhost:4317 (default port 4317).
+            - For HTTP: e.g. http://localhost:4318 (default port 4318).
+            If None, uses env OTEL_EXPORTER_OTLP_ENDPOINT.
+        exporter: Optional pre-built SpanExporter. If provided, otlp_endpoint,
+            protocol and api_key are ignored.
+        protocol: "grpc" (OTLP over gRPC, protobuf) or "http" (OTLP over HTTP, protobuf).
+            Default "grpc".
+        api_key: Optional API key/token for collector auth; sent in Authorization header.
+            If value already starts with "Bearer " or "Basic ", used as-is; otherwise
+            prefixed according to auth_scheme.
+        auth_scheme: "bearer" (default) or "basic". Used only when api_key does not
+            already start with Bearer/Basic. Basic 常用于用户名:密码的 base64 编码。
+        workspace_id: Default mingx.workspace_id (工作空间) on every span.
+        user_id: Default mingx.user.id (用户 id) on every span.
+        extra_attributes: Optional dict of extra default attributes on every span.
+        use_baggage: If True (default), read mingx.workspace_id, mingx.span_type,
+            mingx.user.id from Baggage and overlay on span (Baggage overrides defaults).
+            span_type 不在初始化时设置，由 @traced(span_type=...) 或适配器按调用类型设置。
+
+    Returns:
+        The TracerProvider that is now set as global.
+    """
+    from opentelemetry.sdk.resources import Resource
+
+    resource = Resource.create({"service.name": service_name})
+    provider = TracerProvider(resource=resource)
+
+    # Default attributes (and optional Baggage); span_type 由装饰器/适配器设置
+    default_processor = DefaultAttributesSpanProcessor(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        extra_attributes=extra_attributes,
+        use_baggage=use_baggage,
+    )
+    provider.add_span_processor(default_processor)
+
+    if exporter is None:
+        exporter = _create_otlp_exporter(
+            protocol=protocol,
+            endpoint=otlp_endpoint,
+            api_key=api_key,
+            auth_scheme=auth_scheme,
+        )
+
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    return provider
+
+
+def _create_otlp_exporter(
+    protocol: OTLPProtocol = "grpc",
+    endpoint: Optional[str] = None,
+    api_key: Optional[str] = None,
+    auth_scheme: AuthScheme = "bearer",
+) -> SpanExporter:
+    """Create OTLP span exporter by protocol (grpc or http/protobuf)."""
+    headers = None
+    if api_key:
+        token = api_key.strip()
+        lower = token.lower()
+        if not (lower.startswith("bearer ") or lower.startswith("basic ")):
+            if auth_scheme == "basic":
+                token = f"Basic {token}"
+            else:
+                token = f"Bearer {token}"
+        headers = [("authorization", token)]
+
+    if protocol == "http":
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+            OTLPSpanExporter as OTLPSpanExporterHttp,
+        )
+        kwargs: Dict[str, Any] = {}
+        if endpoint:
+            kwargs["endpoint"] = endpoint
+        if headers:
+            kwargs["headers"] = dict(headers)
+        return OTLPSpanExporterHttp(**kwargs)
+    # gRPC (default)
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+        OTLPSpanExporter as OTLPSpanExporterGrpc,
+    )
+    kwargs = {}
+    if endpoint:
+        kwargs["endpoint"] = endpoint
+        kwargs["insecure"] = True
+    if headers:
+        kwargs["headers"] = headers
+    return OTLPSpanExporterGrpc(**kwargs)

mingx/adapters/__init__.py

@@ -0,0 +1,21 @@
+"""Framework adapters for LLM/Agent frameworks."""
+
+from mingx.adapters.base import (
+    BaseFrameworkTraceAdapter,
+    FrameworkTraceAdapter,
+    SUPPORTED_FRAMEWORKS,
+    PLANNED_FRAMEWORKS,
+)
+from mingx.adapters.langchain import (
+    OpenTelemetryCallbackHandler,
+    get_langchain_callback,
+)
+
+__all__ = [
+    "FrameworkTraceAdapter",
+    "BaseFrameworkTraceAdapter",
+    "SUPPORTED_FRAMEWORKS",
+    "PLANNED_FRAMEWORKS",
+    "OpenTelemetryCallbackHandler",
+    "get_langchain_callback",
+]

mingx/adapters/base.py

@@ -0,0 +1,77 @@
+"""
+Framework trace adapter abstraction.
+
+Adapters translate framework-specific events (e.g. LangChain on_llm_start,
+CrewAI task start) into GenAI semantic layer calls (span names, attributes).
+New frameworks (CrewAI, Google ADK) implement this protocol and register;
+no changes to core or other adapters.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class FrameworkTraceAdapter(Protocol):
+    """
+    Protocol for framework trace adapters.
+
+    Implementations start/end spans and set GenAI attributes via mingx.genai
+    (spans / attributes), not by writing gen_ai.* strings directly.
+    """
+
+    def start_span(self, name: str, attributes: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Start a span with the given name and attributes.
+
+        Returns a handle (e.g. context token or span) that is passed to end_span.
+        """
+        ...
+
+    def end_span(self, handle: Any, *, status: Optional[Any] = None) -> None:
+        """End the span identified by handle. Optionally set status (e.g. error)."""
+        ...
+
+    def set_attributes(self, handle: Any, attributes: Dict[str, Any]) -> None:
+        """Set additional attributes on the span (e.g. on_*_end data)."""
+        ...
+
+    def record_exception(self, handle: Any, exception: BaseException) -> None:
+        """Record an exception on the span and set error status."""
+        ...
+
+
+class BaseFrameworkTraceAdapter(ABC):
+    """
+    Abstract base for framework adapters.
+
+    Adapters that cannot use a simple Protocol (e.g. need to hold tracer or
+    run_id -> span mapping) can subclass this and implement the same contract.
+    """
+
+    @abstractmethod
+    def start_span(self, name: str, attributes: Optional[Dict[str, Any]] = None) -> Any:
+        """Start a span; return handle for end_span / set_attributes."""
+        ...
+
+    @abstractmethod
+    def end_span(self, handle: Any, *, status: Optional[Any] = None) -> None:
+        """End the span."""
+        ...
+
+    @abstractmethod
+    def set_attributes(self, handle: Any, attributes: Dict[str, Any]) -> None:
+        """Set attributes on the span."""
+        ...
+
+    @abstractmethod
+    def record_exception(self, handle: Any, exception: BaseException) -> None:
+        """Record exception on the span."""
+        ...
+
+
+# Optional: registry for "supported frameworks" for docs
+SUPPORTED_FRAMEWORKS = ["langchain"]
+PLANNED_FRAMEWORKS = ["crewai", "google_adk"]