Documentation improvements for published API reference

src/microsoft/opentelemetry/__init__.py

@@ -6,7 +6,8 @@
 
 """Microsoft OpenTelemetry Python.
 
-Provides a single entry-point — :func:`use_microsoft_opentelemetry` —
+Provides a single entry-point —
+:func:`microsoft.opentelemetry.use_microsoft_opentelemetry` —
 that initialises OpenTelemetry global providers (tracing, metrics, logging)
 and optionally configures Azure Monitor as an exporter.
 """

src/microsoft/opentelemetry/a365/constants.py

@@ -6,8 +6,9 @@
 
 """Constants for Agent365 observability.
 
-Superset of microsoft-agents-a365-observability-core constants plus
-package-specific environment variable constants.
+Span operation names, semantic-convention attribute keys, baggage keys, and
+environment-variable names used throughout the Agent365 observability
+integration.
 """
 
 # --- Span operation names ---

src/microsoft/opentelemetry/a365/core/__init__.py

@@ -1,7 +1,11 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-# Microsoft Agent 365 Python SDK for OpenTelemetry tracing.
+"""Core Agent365 observability primitives.
+
+Span scopes (such as invoke-agent, execute-tool, and apply-guardrail), data
+models, and exporters that make up the Agent365 OpenTelemetry tracing surface.
+"""
 
 from microsoft.opentelemetry.a365.core.agent_details import AgentDetails
 from microsoft.opentelemetry.a365.core.apply_guardrail_scope import ApplyGuardrailScope

src/microsoft/opentelemetry/a365/core/constants.py

@@ -1,7 +1,11 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-# Constants for SDK OpenTelemetry implementation.
+"""Constants for the Agent365 OpenTelemetry implementation.
+
+Span operation names and OpenTelemetry semantic-convention attribute keys
+shared across the Agent365 core scopes and exporters.
+"""
 
 # --- Span operation names ---
 INVOKE_AGENT_OPERATION_NAME = "invoke_agent"

src/microsoft/opentelemetry/a365/core/exporters/agent365_exporter.py

@@ -6,7 +6,8 @@
 
 """Agent365 span exporter.
 
-Vendored from microsoft-agents-a365-observability-core exporters/agent365_exporter.py.
+Exports OpenTelemetry spans to the Agent365 observability ingestion endpoint,
+handling authentication, batching, and payload size limits.
 """
 
 from __future__ import annotations

src/microsoft/opentelemetry/a365/core/exporters/agent365_exporter_options.py

@@ -4,9 +4,11 @@
 # license information.
 # --------------------------------------------------------------------------
 
-"""Configuration for Agent365 exporter.
+"""Configuration options for the Agent365 span exporter.
 
-Vendored from microsoft-agents-a365-observability-core exporters/agent365_exporter_options.py.
+Defines the tunable settings—such as the ingestion endpoint, authentication
+token resolvers, and payload size limits—used to construct an Agent365
+exporter.
 """
 
 from __future__ import annotations

src/microsoft/opentelemetry/a365/core/exporters/enriched_span.py

@@ -6,7 +6,9 @@
 
 """Enriched ReadableSpan wrapper for adding attributes to immutable spans.
 
-Vendored from microsoft-agents-a365-observability-core exporters/enriched_span.py.
+Wraps an already-ended :class:`~opentelemetry.sdk.trace.ReadableSpan` so that
+additional attributes can be layered on top without mutating the original
+span, which is immutable once ended.
 """
 
 from __future__ import annotations

src/microsoft/opentelemetry/a365/core/exporters/enriching_span_processor.py

@@ -6,7 +6,9 @@
 
 """Span enrichment support for the Agent365 exporter pipeline.
 
-Vendored from microsoft-agents-a365-observability-core exporters/enriching_span_processor.py.
+Provides a span processor that runs registered enrichers against each span
+before it is exported, allowing additional attributes to be attached without
+mutating the original span.
 """
 
 from __future__ import annotations

src/microsoft/opentelemetry/a365/core/exporters/span_processor.py

@@ -6,9 +6,6 @@
 
 """Span processor for propagating OpenTelemetry baggage entries onto spans.
 
-Vendored from microsoft-agents-a365-observability-core trace_processor/span_processor.py
-and trace_processor/util.py.
-
 For every new span:
   * Retrieve the current (or parent) context
   * Obtain all baggage entries

src/microsoft/opentelemetry/a365/core/exporters/utils.py

@@ -6,7 +6,8 @@
 
 """Utilities for the Agent365 exporter.
 
-Vendored from microsoft-agents-a365-observability-core exporters/utils.py.
+Shared helpers used by the Agent365 exporter pipeline, including payload
+serialization, size enforcement, and token-resolution helpers.
 """
 
 from __future__ import annotations

src/microsoft/opentelemetry/a365/core/guardrail_decision_type.py

@@ -7,8 +7,13 @@
 class GuardrailDecisionType:
     """Well-known guardrail decision type values."""
 
+    #: Allow the content to proceed unchanged.
     ALLOW = "allow"
+    #: Allow the content but record it for auditing.
     AUDIT = "audit"
+    #: Block the content.
     DENY = "deny"
+    #: Allow the content after modifying it.
     MODIFY = "modify"
+    #: Allow the content but surface a warning.
     WARN = "warn"

src/microsoft/opentelemetry/a365/core/guardrail_risk_severity.py

@@ -7,8 +7,13 @@
 class GuardrailRiskSeverity:
     """Well-known risk severity level values."""
 
+    #: No risk detected.
     NONE = "none"
+    #: Low-severity risk.
     LOW = "low"
+    #: Medium-severity risk.
     MEDIUM = "medium"
+    #: High-severity risk.
     HIGH = "high"
+    #: Critical-severity risk.
     CRITICAL = "critical"

src/microsoft/opentelemetry/a365/core/guardrail_target_type.py

@@ -10,12 +10,21 @@ class GuardrailTargetType:
     Users may also supply custom string values not listed here.
     """
 
+    #: A guardrail evaluated against model input.
     LLM_INPUT = "llm_input"
+    #: A guardrail evaluated against model output.
     LLM_OUTPUT = "llm_output"
+    #: A guardrail evaluated against a tool call.
     TOOL_CALL = "tool_call"
+    #: A guardrail evaluated against a tool definition.
     TOOL_DEFINITION = "tool_definition"
+    #: A guardrail evaluated when writing to a memory store.
     MEMORY_STORE = "memory_store"
+    #: A guardrail evaluated when reading from a memory store.
     MEMORY_RETRIEVE = "memory_retrieve"
+    #: A guardrail evaluated against a knowledge query.
     KNOWLEDGE_QUERY = "knowledge_query"
+    #: A guardrail evaluated against a knowledge result.
     KNOWLEDGE_RESULT = "knowledge_result"
+    #: A guardrail evaluated against a message.
     MESSAGE = "message"

src/microsoft/opentelemetry/a365/core/inference_operation_type.py

@@ -7,6 +7,9 @@
 class InferenceOperationType(Enum):
     """Supported inference operation types for generative AI."""
 
+    #: A chat-completion style request.
     CHAT = "Chat"
+    #: A text-completion style request.
     TEXT_COMPLETION = "TextCompletion"
+    #: A multimodal content-generation request.
     GENERATE_CONTENT = "GenerateContent"

src/microsoft/opentelemetry/a365/core/models/messages.py

@@ -5,8 +5,9 @@
 
 Defines the structured message format for input/output message tracing,
 following the OpenTelemetry gen-ai semantic conventions:
-  https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-input-messages.json
-  https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-output-messages.json
+
+* https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-input-messages.json
+* https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-output-messages.json
 """
 
 from __future__ import annotations
@@ -23,27 +24,39 @@
 class MessageRole(Enum):
     """Role of a message participant per OTEL gen-ai semantic conventions."""
 
+    #: System / developer instructions that set up the conversation.
     SYSTEM = "system"
+    #: Input authored by the end user.
     USER = "user"
+    #: Output produced by the model.
     ASSISTANT = "assistant"
+    #: Output of a tool returned back to the model.
     TOOL = "tool"
 
 
 class FinishReason(Enum):
     """Reason a model stopped generating per OTEL gen-ai semantic conventions."""
 
+    #: The model emitted a natural stop point or a provided stop sequence.
     STOP = "stop"
+    #: Generation stopped because the maximum token limit was reached.
     LENGTH = "length"
+    #: Generation stopped because content was filtered by a safety system.
     CONTENT_FILTER = "content_filter"
+    #: The model stopped to request a tool call.
     TOOL_CALL = "tool_call"
+    #: Generation stopped because an error occurred.
     ERROR = "error"
 
 
 class Modality(Enum):
     """Media modality for blob, file, and URI parts."""
 
+    #: Image content.
     IMAGE = "image"
+    #: Video content.
     VIDEO = "video"
+    #: Audio content.
     AUDIO = "audio"
 
 

src/microsoft/opentelemetry/a365/core/tool_type.py

@@ -9,6 +9,9 @@
 class ToolType(Enum):
     """Enumeration for different tool types for execute tool contexts."""
 
+    #: A callable function tool.
     FUNCTION = "function"
+    #: An extension or plugin tool.
     EXTENSION = "extension"
+    #: A datastore / knowledge-retrieval tool.
     DATASTORE = "datastore"

src/microsoft/opentelemetry/a365/core/utils.py

@@ -56,7 +56,7 @@ def get_traceparent(headers: dict[str, str]) -> str | None:
 
     Args:
         headers: Dictionary of HTTP headers, typically obtained from
-            :meth:`OpenTelemetryScope.inject_context_to_headers`.
+            :meth:`~microsoft.opentelemetry.a365.core.opentelemetry_scope.OpenTelemetryScope.inject_context_to_headers`.
 
     Returns:
         The traceparent string (e.g.

src/microsoft/opentelemetry/a365/hosting/middleware/output_logging_middleware.py

@@ -34,7 +34,10 @@
 
 logger = logging.getLogger(__name__)
 
-# TurnState key for the parent trace context (W3C traceparent string).
+#: TurnState key under which the parent trace context (a W3C ``traceparent``
+#: string) is stored so emitted
+#: :class:`~microsoft.opentelemetry.a365.core.spans_scopes.output_scope.OutputScope`
+#: spans can be linked to it.
 A365_PARENT_TRACEPARENT_KEY = "A365ParentTraceparent"
 
 
@@ -95,10 +98,13 @@ def _derive_channel(
 
 
 class OutputLoggingMiddleware:
-    """Middleware that creates :class:`OutputScope` spans for outgoing messages.
+    """Middleware that creates
+    :class:`~microsoft.opentelemetry.a365.core.spans_scopes.output_scope.OutputScope`
+    spans for outgoing messages.
 
-    Links to a parent span when :data:`A365_PARENT_TRACEPARENT_KEY` is set in
-    ``turn_state``.
+    Links to a parent span when
+    :data:`~microsoft.opentelemetry.a365.hosting.middleware.output_logging_middleware.A365_PARENT_TRACEPARENT_KEY`
+    is set in ``turn_state``.
 
     **Privacy note:** Outgoing message content is captured verbatim as span
     attributes and exported to the configured telemetry backend.

src/microsoft/opentelemetry/a365/hosting/scope_helpers/populate_invoke_agent_scope.py

@@ -22,11 +22,14 @@
 
 
 def populate(scope: InvokeAgentScope, turn_context: TurnContext) -> InvokeAgentScope:
-    """
-    Populate all supported InvokeAgentScope tags from the provided TurnContext.
-    :param scope: The InvokeAgentScope instance to populate.
-    :param turn_context: The TurnContext containing activity information.
-    :return: The updated InvokeAgentScope instance.
+    """Populate all supported InvokeAgentScope tags from the provided TurnContext.
+
+    Args:
+        scope: The InvokeAgentScope instance to populate.
+        turn_context: The TurnContext containing activity information.
+
+    Returns:
+        The updated InvokeAgentScope instance.
     """
     if not turn_context:
         raise ValueError("turn_context is required")

src/microsoft/opentelemetry/a365/langchain/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""LangChain support for Agent365 observability.
+
+Provides span enrichment that adapts LangChain telemetry to the Agent365
+export pipeline, converting OpenTelemetry gen-ai structured messages to the
+content shape expected by Agent365 and mapping conversation identifiers to
+session identifiers.
+"""

src/microsoft/opentelemetry/a365/runtime/__init__.py

@@ -1,6 +1,13 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
+"""Runtime helpers for Agent365 observability.
+
+Utilities for resolving the runtime environment, discovering Power Platform
+API endpoints, and modelling operation results used when configuring Agent365
+telemetry.
+"""
+
 from microsoft.opentelemetry.a365.runtime.environment_utils import get_observability_authentication_scope
 from microsoft.opentelemetry.a365.runtime.operation_error import OperationError
 from microsoft.opentelemetry.a365.runtime.operation_result import OperationResult