microsoft-agents-a365-runtime 0.2.1.dev2__py3-none-any.whl

microsoft_agents_a365/runtime/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from .environment_utils import get_observability_authentication_scope
+from .operation_error import OperationError
+from .operation_result import OperationResult
+from .power_platform_api_discovery import ClusterCategory, PowerPlatformApiDiscovery
+from .utility import Utility
+
+__all__ = [
+    "get_observability_authentication_scope",
+    "PowerPlatformApiDiscovery",
+    "ClusterCategory",
+    "Utility",
+    "OperationError",
+    "OperationResult",
+]
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

microsoft_agents_a365/runtime/environment_utils.py

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Utility logic for environment-related operations.
+"""
+
+import os
+
+# Authentication scopes for different environments
+PROD_OBSERVABILITY_SCOPE = "https://api.powerplatform.com/.default"
+
+# Cluster categories for different environments
+PROD_OBSERVABILITY_CLUSTER_CATEGORY = "prod"
+
+# Default environment names
+PRODUCTION_ENVIRONMENT_NAME = "production"
+DEVELOPMENT_ENVIRONMENT_NAME = "Development"
+
+
+def get_observability_authentication_scope() -> list[str]:
+    """
+    Returns the scope for authenticating to the observability service based on the current environment.
+
+    The scope can be overridden via the A365_OBSERVABILITY_SCOPE_OVERRIDE environment variable
+    to enable testing against pre-production environments.
+
+    Returns:
+        list[str]: The authentication scope for the current environment.
+    """
+    override_scope = os.getenv("A365_OBSERVABILITY_SCOPE_OVERRIDE", "").strip()
+    return [override_scope] if override_scope else [PROD_OBSERVABILITY_SCOPE]
+
+
+def is_development_environment() -> bool:
+    """
+    Returns True if the current environment is a development environment.
+
+    Returns:
+        bool: True if the current environment is development, False otherwise.
+    """
+    environment = _get_current_environment()
+    return environment.lower() == DEVELOPMENT_ENVIRONMENT_NAME.lower()
+
+
+def _get_current_environment() -> str:
+    """
+    Gets the current environment name.
+
+    Returns:
+        str: The current environment name.
+    """
+    # Check environment variables in order of precedence
+
+    # Check Python-specific environment variables
+    environment = os.getenv("PYTHON_ENVIRONMENT")
+    if environment:
+        return environment
+
+    # Default to Production
+    return PRODUCTION_ENVIRONMENT_NAME

microsoft_agents_a365/runtime/operation_error.py

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Encapsulates an error from an operation.
+"""
+
+
+class OperationError:
+    """
+    Represents an error that occurred during an operation.
+
+    This class wraps an exception and provides a consistent interface for
+    accessing error information.
+    """
+
+    def __init__(self, exception: Exception):
+        """
+        Initialize a new instance of the OperationError class.
+
+        Args:
+            exception: The exception associated with the error.
+
+        Raises:
+            ValueError: If exception is None.
+        """
+        if exception is None:
+            raise ValueError("exception cannot be None")
+        self._exception = exception
+
+    @property
+    def exception(self) -> Exception:
+        """
+        Get the exception associated with the error.
+
+        Returns:
+            Exception: The exception associated with the error.
+        """
+        return self._exception
+
+    @property
+    def message(self) -> str:
+        """
+        Get the message associated with the error.
+
+        Returns:
+            str: The error message from the exception.
+        """
+        return str(self._exception)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the error.
+
+        Returns:
+            str: A string representation of the error.
+        """
+        return str(self._exception)

microsoft_agents_a365/runtime/operation_result.py

@@ -0,0 +1,98 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Represents the result of an operation.
+"""
+
+from typing import List, Optional
+
+from .operation_error import OperationError
+
+
+class OperationResult:
+    """
+    Represents the result of an operation.
+
+    This class encapsulates the success or failure state of an operation along
+    with any associated errors.
+    """
+
+    _success_instance: Optional["OperationResult"] = None
+
+    def __init__(self, succeeded: bool, errors: Optional[List[OperationError]] = None):
+        """
+        Initialize a new instance of the OperationResult class.
+
+        Args:
+            succeeded: Flag indicating whether the operation succeeded.
+            errors: Optional list of errors that occurred during the operation.
+        """
+        self._succeeded = succeeded
+        self._errors = errors if errors is not None else []
+
+    @property
+    def succeeded(self) -> bool:
+        """
+        Get a flag indicating whether the operation succeeded.
+
+        Returns:
+            bool: True if the operation succeeded, otherwise False.
+        """
+        return self._succeeded
+
+    @property
+    def errors(self) -> List[OperationError]:
+        """
+        Get the list of errors that occurred during the operation.
+
+        Note:
+            This property returns a defensive copy of the internal error list
+            to prevent external modifications, which is especially important for
+            protecting the singleton instance returned by success().
+
+        Returns:
+            List[OperationError]: A copy of the list of operation errors.
+        """
+        return list(self._errors)
+
+    @staticmethod
+    def success() -> "OperationResult":
+        """
+        Return an OperationResult indicating a successful operation.
+
+        Returns:
+            OperationResult: An OperationResult indicating a successful operation.
+        """
+        return OperationResult._success_instance
+
+    @staticmethod
+    def failed(*errors: OperationError) -> "OperationResult":
+        """
+        Create an OperationResult indicating a failed operation.
+
+        Args:
+            *errors: Variable number of OperationError instances.
+
+        Returns:
+            OperationResult: An OperationResult indicating a failed operation.
+        """
+        error_list = list(errors) if errors else []
+        return OperationResult(succeeded=False, errors=error_list)
+
+    def __str__(self) -> str:
+        """
+        Convert the value of the current OperationResult object to its string representation.
+
+        Returns:
+            str: A string representation of the current OperationResult object.
+        """
+        if self._succeeded:
+            return "Succeeded"
+        else:
+            error_messages = ", ".join(str(error.message) for error in self._errors)
+            return f"Failed: {error_messages}" if error_messages else "Failed"
+
+
+# Module-level eager initialization (thread-safe by Python's import lock)
+OperationResult._success_instance = OperationResult(succeeded=True)

microsoft_agents_a365/runtime/power_platform_api_discovery.py

@@ -0,0 +1,90 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+import re
+from typing import Literal
+
+ClusterCategory = Literal[
+    "local",
+    "dev",
+    "test",
+    "preprod",
+    "firstrelease",
+    "prod",
+    "gov",
+    "high",
+    "dod",
+    "mooncake",
+    "ex",
+    "rx",
+]
+
+
+class PowerPlatformApiDiscovery:
+    """Discovery helper for Power Platform API endpoints."""
+
+    def __init__(self, cluster_category: ClusterCategory) -> None:
+        self.cluster_category = cluster_category
+
+    def get_token_audience(self) -> str:
+        return f"https://{self._get_environment_api_host_name_suffix()}"
+
+    def get_token_endpoint_host(self) -> str:
+        return self._get_environment_api_host_name_suffix()
+
+    def get_tenant_endpoint(self, tenant_id: str) -> str:
+        return self._generate_power_platform_api_domain(tenant_id)
+
+    def get_tenant_island_cluster_endpoint(self, tenant_id: str) -> str:
+        return self._generate_power_platform_api_domain(tenant_id, "il-")
+
+    def _generate_power_platform_api_domain(
+        self, host_name_identifier: str, host_name_prefix: str = ""
+    ) -> str:
+        # Validate allowed characters: alphanumeric and dash
+        if not re.match(r"^[a-zA-Z0-9-]+$", host_name_identifier):
+            raise ValueError(
+                f"Cannot generate Power Platform API endpoint because the tenant identifier contains invalid host name characters, only alphanumeric and dash characters are expected: {host_name_identifier}"
+            )
+
+        host_name_infix = "tenant"
+        hex_name_suffix_length = self._get_hex_api_suffix_length()
+        hex_name = host_name_identifier.lower().replace("-", "")
+
+        if hex_name_suffix_length >= len(hex_name):
+            raise ValueError(
+                f"Cannot generate Power Platform API endpoint because the normalized tenant identifier must be at least {hex_name_suffix_length + 1} "
+                f"characters in length: {hex_name}"
+            )
+
+        hex_name_suffix = hex_name[-hex_name_suffix_length:]
+        hex_name_prefix = hex_name[: len(hex_name) - hex_name_suffix_length]
+        host_name_suffix = self._get_environment_api_host_name_suffix()
+
+        return f"{host_name_prefix}{hex_name_prefix}.{hex_name_suffix}.{host_name_infix}.{host_name_suffix}"
+
+    def _get_hex_api_suffix_length(self) -> int:
+        if self.cluster_category in ("firstrelease", "prod"):
+            return 2
+        return 1
+
+    def _get_environment_api_host_name_suffix(self) -> str:
+        cluster_to_suffix = {
+            "local": "api.powerplatform.localhost",
+            "dev": "api.powerplatform.com",  # defaulting to prod
+            "test": "api.powerplatform.com",  # defaulting to prod
+            "preprod": "api.powerplatform.com",  # defaulting to prod
+            "firstrelease": "api.powerplatform.com",
+            "prod": "api.powerplatform.com",
+            "gov": "api.gov.powerplatform.microsoft.us",
+            "high": "api.high.powerplatform.microsoft.us",
+            "dod": "api.appsplatform.us",
+            "mooncake": "api.powerplatform.partner.microsoftonline.cn",
+            "ex": "api.powerplatform.eaglex.ic.gov",
+            "rx": "api.powerplatform.microsoft.scloud",
+        }
+        cc = self.cluster_category
+        try:
+            return cluster_to_suffix[cc]
+        except KeyError as exc:
+            raise ValueError(f"Invalid ClusterCategory value: {self.cluster_category}") from exc

microsoft_agents_a365/runtime/utility.py

@@ -0,0 +1,111 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Utility functions for Microsoft Agent 365 runtime operations.
+
+This module provides utility functions for token handling, agent identity resolution,
+and other common runtime operations.
+"""
+
+from __future__ import annotations
+
+import platform
+import uuid
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Optional
+
+import jwt
+
+
+class Utility:
+    """
+    Utility class providing common runtime operations for Agent 365.
+
+    This class contains static methods for token processing, agent identity resolution,
+    and other utility functions used across the Agent 365 runtime.
+    """
+
+    _cached_version = None
+
+    @staticmethod
+    def get_app_id_from_token(token: Optional[str]) -> str:
+        """
+        Decodes the current token and retrieves the App ID (appid or azp claim).
+
+        Args:
+            token: JWT token to decode. Can be None or empty.
+
+        Returns:
+            str: The App ID from the token's claims, or empty GUID if token is invalid.
+                 Returns "00000000-0000-0000-0000-000000000000" if no valid App ID is found.
+        """
+        if not token or not token.strip():
+            return str(uuid.UUID(int=0))
+
+        try:
+            # Decode the JWT token without verification (we only need the claims)
+            # Note: verify=False is used because we only need to extract claims,
+            # not verify the token's authenticity
+            decoded_payload = jwt.decode(token, options={"verify_signature": False})
+
+            # Look for appid or azp claims (appid takes precedence)
+            app_id = decoded_payload.get("appid") or decoded_payload.get("azp")
+            return app_id if app_id else ""
+
+        except (jwt.DecodeError, jwt.InvalidTokenError):
+            # Token is malformed or invalid
+            return ""
+
+    @staticmethod
+    def resolve_agent_identity(context: Any, auth_token: Optional[str]) -> str:
+        """
+        Resolves the agent identity from the turn context or auth token.
+
+        Args:
+            context: Turn context of the conversation turn. Expected to have an Activity
+                    with methods like is_agentic_request() and get_agentic_instance_id().
+            auth_token: Authentication token if available.
+
+        Returns:
+            str: The agent identity (App ID). Returns the agentic instance ID if the
+                 request is agentic, otherwise returns the App ID from the auth token.
+        """
+        try:
+            # App ID is required to pass to MCP server URL
+            # Try to get agentic instance ID if this is an agentic request
+            if context and context.activity and context.activity.is_agentic_request():
+                agentic_id = context.activity.get_agentic_instance_id()
+                return agentic_id if agentic_id else ""
+
+        except (AttributeError, TypeError, Exception):
+            # Context/activity doesn't have the expected methods or properties
+            # or any other error occurred while accessing context/activity
+            pass
+
+        # Fallback to extracting App ID from the auth token
+        return Utility.get_app_id_from_token(auth_token)
+
+    @staticmethod
+    def get_user_agent_header(orchestrator: Optional[str] = None) -> str:
+        """
+        Generates a User-Agent header string for SDK requests.
+
+        Args:
+            orchestrator: Optional orchestrator name to include in the User-Agent header.
+                         Defaults to empty string if not provided.
+
+        Returns:
+            str: A formatted User-Agent header string containing SDK version, OS type,
+                 Python version, and optional orchestrator information.
+        """
+        if Utility._cached_version is None:
+            try:
+                Utility._cached_version = version("microsoft-agents-a365-runtime")
+            except PackageNotFoundError:
+                Utility._cached_version = "unknown"
+
+        orchestrator_part = f"; {orchestrator}" if orchestrator else ""
+        os_type = platform.system()
+        python_version = platform.python_version()
+        return f"Agent365SDK/{Utility._cached_version} ({os_type}; Python {python_version}{orchestrator_part})"

microsoft_agents_a365/runtime/version_utils.py

@@ -0,0 +1,34 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Version utilities for Microsoft Agent 365 SDK packages.
+
+This module is deprecated. Versioning is now handled automatically by
+setuptools-git-versioning. See versioning/TARGET-VERSION and
+HOW_TO_SET_A_VERSION.md for details.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def build_version():
+    """
+    DEPRECATED: This function is no longer used.
+
+    Version is now automatically calculated by setuptools-git-versioning
+    based on Git history and tags. See HOW_TO_SET_A_VERSION.md for details.
+
+    Returns:
+        str: Version from AGENT365_PYTHON_SDK_PACKAGE_VERSION environment variable or "0.0.0"
+    """
+    import warnings
+
+    warnings.warn(
+        "build_version() is deprecated. Version is now managed by setuptools-git-versioning.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return os.environ.get("AGENT365_PYTHON_SDK_PACKAGE_VERSION", "0.0.0")

microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-a365-runtime
+Version: 0.2.1.dev2
+Summary: Telemetry, tracing, and monitoring components for AI agents
+Author-email: Microsoft <support@microsoft.com>
+License: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agent365-python
+Project-URL: Repository, https://github.com/microsoft/Agent365-python
+Project-URL: Issues, https://github.com/microsoft/Agent365-python/issues
+Project-URL: Documentation, https://github.com/microsoft/Agent365-python/tree/main/libraries/microsoft-agents-a365-runtime
+Keywords: observability,telemetry,tracing,opentelemetry,monitoring,ai,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+
+# microsoft-agents-a365-runtime
+
+[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-runtime?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-runtime)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-runtime?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-runtime)
+
+Core runtime utilities and environment management for AI agent applications. This package provides essential Power Platform API discovery, environment configuration, and authentication scope resolution.
+
+## Installation
+
+```bash
+pip install microsoft-agents-a365-runtime
+```
+
+## Usage
+
+For usage examples and detailed documentation, see the [Microsoft Agent 365 Developer documentation](https://learn.microsoft.com/microsoft-agent-365/developer/?tabs=python) on Microsoft Learn.
+
+## Support
+
+For issues, questions, or feedback:
+
+- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section
+- See the [main documentation](../../README.md) for more information
+ 
+## Trademarks
+ 
+*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.*
+
+## License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under the MIT License - see the [LICENSE](../../LICENSE.md) file for details.

microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/RECORD

@@ -0,0 +1,11 @@
+microsoft_agents_a365/runtime/__init__.py,sha256=_Q6AfhdNV-YhvkJKqTG-TlImI2B5bEbtTC_Mv82-ob4,591
+microsoft_agents_a365/runtime/environment_utils.py,sha256=B5A3CfGJJeuVgIW3Si7oSPYLQNkzc54nNqw3QnLgaC0,1824
+microsoft_agents_a365/runtime/operation_error.py,sha256=OqG6IIQR5lfvZrtyqpTa9Gc4B_eo2qxfoJ1Cj96WiUs,1418
+microsoft_agents_a365/runtime/operation_result.py,sha256=HIJLAzoAfPTINzjnThzXHDAizRaZ4xXX4D7TuOPjmdk,3066
+microsoft_agents_a365/runtime/power_platform_api_discovery.py,sha256=B6Ar2-P9pHrv-Pe_vFl0j9gRqAWyipbTfxkLEc9aA0k,3460
+microsoft_agents_a365/runtime/utility.py,sha256=5YEN1EGmHvRBb9gc9GeD58xAxUzGiZNON_zWkXh9Oms,4282
+microsoft_agents_a365/runtime/version_utils.py,sha256=nkgYIaPXD9OyT_lJ8K3sqpEze_VMJzekMmjsiYNghB8,965
+microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/METADATA,sha256=CUvTC5htAC9pCUy4IktF7y0LIIlHt6RPXy1vis9zxuw,3205
+microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/RECORD,,

microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_a365_runtime-0.2.1.dev2.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents_a365