clarity-api 1.0.0__py3-none-any.whl

clarity_api/__init__.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+"""Clarity API
+
+A Python library, MCP server, and A2A agent for exporting data from
+Microsoft Clarity.
+"""
+
+import importlib
+import inspect
+from typing import Any
+
+from clarity_api.version import __author__, __credits__, __version__
+
+__all__: list[str] = ["__version__", "__author__", "__credits__"]
+
+CORE_MODULES: list[str] = [
+    "clarity_api.clarity_models",
+    "clarity_api.api_client",
+]
+
+OPTIONAL_MODULES = {
+    "clarity_api.agent_server": "agent",
+    "clarity_api.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+# Eagerly import core modules (keeps API wrappers fast & light)
+for module_name in CORE_MODULES:
+    if module_name:
+        _module = importlib.import_module(module_name)
+        _expose_members(_module)
+
+# Dynamic/lazy loading of optional modules (agent_server, mcp_server)
+_loaded_optional_modules: dict[str, Any] = {}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    if name == "_MCP_AVAILABLE":
+        return _import_module_safely("clarity_api.mcp_server") is not None
+    if name == "_AGENT_AVAILABLE":
+        return _import_module_safely("clarity_api.agent_server") is not None
+
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            if module is not None:
+                _loaded_optional_modules[module_name] = module
+                _expose_members(module)
+
+        module = _loaded_optional_modules.get(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

clarity_api/__main__.py

@@ -0,0 +1,4 @@
+from clarity_api.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

clarity_api/agent_data/IDENTITY.md

@@ -0,0 +1,23 @@
+[default]
+name = "Clarity Analytics Manager"
+description = "AI agent for Microsoft Clarity analytics data export and insight interpretation."
+emoji = "📊"
+
+# System Prompt
+You are the **Clarity Analytics Manager**, a high-fidelity AI agent specialized in working with Microsoft Clarity dashboard data.
+
+## Role & Expertise
+- **Data Export**: You retrieve live insights from the Microsoft Clarity Data Export API over a configurable date range (the last 24, 48, or 72 hours).
+- **Dimensional Analysis**: You break down insights by up to three dimensions: Browser, Device, Country, OS, Source, Medium, Campaign, Channel, and URL.
+- **Interpretation**: You summarize traffic, session counts, bot activity, and pages-per-session metrics into clear, actionable insights.
+
+## Operational Instructions
+1. **Always list skills first**: Use `list_skills` to understand your available tool domains.
+2. **Use the insights tool**: Call the `clarity_insights` tool with `action="get_data_export"` and the desired `number_of_days` (1, 2, or 3) plus any dimensions.
+3. **Validate dimensions**: Only use supported dimension values (Browser, Device, Country, OS, Source, Medium, Campaign, Channel, URL).
+4. **Be Proactive**: When trends stand out (e.g., a spike in bot sessions), call them out.
+5. **Safety**: Never expose API tokens in responses.
+
+## Preferred Style
+- Professional, efficient, and data-driven.
+- Provide concise summaries of the metrics retrieved.

clarity_api/agent_server.py

@@ -0,0 +1,86 @@
+#!/usr/bin/python
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "1.0.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    """Start the Pydantic-AI A2A agent server (CONCEPT:CLA-005)."""
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "Clarity Api")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get(
+            "description",
+            "AI agent for Microsoft Clarity analytics data export.",
+        ),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    # Start server using the auto-discovery pattern (from mcp_config.json)
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

clarity_api/api/__init__.py

@@ -0,0 +1,14 @@
+#!/usr/bin/python
+"""Clarity API client package.
+
+Exposes the HTTP base client and the per-domain client mixins that compose the
+top-level :class:`clarity_api.api_client.Api` facade.
+"""
+
+from clarity_api.api.api_client_base import ClarityApiBase
+from clarity_api.api.api_client_insights import ClarityApiInsights
+
+__all__ = [
+    "ClarityApiBase",
+    "ClarityApiInsights",
+]

clarity_api/api/api_client_base.py

@@ -0,0 +1,125 @@
+#!/usr/bin/python
+"""HTTP/REST base client for the Microsoft Clarity Data Export API.
+
+Provides the shared ``requests.Session``, bearer-token authentication header,
+SSL-verify handling, base-URL normalization, and credential validation that all
+domain client mixins build on. Validation hits ``GET /projects`` during
+``__init__`` to fail fast on bad credentials — preserving the original
+``clarity_api.clarity_api.Api`` contract.
+"""
+
+import logging
+
+import requests
+import urllib3
+
+from clarity_api.exceptions import (
+    AuthError,
+    MissingParameterError,
+    ParameterError,
+    UnauthorizedError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ClarityApiBase:
+    """Base HTTP client for Microsoft Clarity.
+
+    CONCEPT:CLA-004 — REST Base Client. Owns the shared ``requests.Session``,
+    bearer-token header, SSL-verify handling, and fail-fast credential
+    validation against ``GET /projects``.
+
+    Args:
+        url: Base URL of the Clarity instance (e.g. ``https://www.clarity.ms``).
+        token: Bearer API token generated from the Clarity project settings.
+        verify: Whether to verify TLS certificates. Defaults to ``True``.
+        debug: Enable verbose logging when ``True``.
+
+    Raises:
+        MissingParameterError: If ``url`` or ``token`` is not provided.
+        UnauthorizedError: If the token is rejected (HTTP 403).
+        AuthError: If authentication fails (HTTP 401).
+        ParameterError: If the validation endpoint is not found (HTTP 404).
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        token: str | None = None,
+        verify: bool = True,
+        debug: bool = False,
+    ):
+        """Initialize the session and validate credentials (CONCEPT:CLA-004)."""
+        if debug:
+            logger.setLevel(logging.DEBUG)
+            logger.debug("Debug mode enabled")
+        else:
+            logger.setLevel(logging.ERROR)
+
+        if url is None:
+            raise MissingParameterError
+
+        self._session = requests.Session()
+        self.url = url.rstrip("/")
+        self.headers: dict | None = None
+        self.verify = verify
+        self.debug = debug
+
+        if self.verify is False:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+        if token:
+            self.headers = {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            }
+        else:
+            raise MissingParameterError
+
+        response = self._session.get(
+            url=f"{self.url}/projects",
+            headers=self.headers,
+            verify=self.verify,
+            timeout=10,
+        )
+
+        if response.status_code == 403:
+            logger.error(f"Unauthorized Error: {response.content!r}")
+            raise UnauthorizedError
+        elif response.status_code == 401:
+            logger.error(f"Authentication Error: {response.content!r}")
+            raise AuthError
+        elif response.status_code == 404:
+            logger.error(f"Parameter Error: {response.content!r}")
+            raise ParameterError
+
+    def api_request(
+        self,
+        method: str = "GET",
+        endpoint: str = "/",
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> requests.Response:
+        """Execute an arbitrary REST request against the Clarity instance.
+
+        CONCEPT:CLA-004 — REST Base Client.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, PATCH).
+            endpoint: Path appended to the base URL (e.g. ``/projects``).
+            params: Optional query parameters.
+            json: Optional JSON body payload.
+
+        Returns:
+            The raw ``requests.Response`` object.
+        """
+        url = f"{self.url}/{endpoint.lstrip('/')}"
+        return self._session.request(
+            method=method.upper(),
+            url=url,
+            params=params,
+            json=json,
+            headers=self.headers,
+            verify=self.verify,
+        )

clarity_api/api/api_client_insights.py

@@ -0,0 +1,59 @@
+#!/usr/bin/python
+"""Insights / Data Export domain client for the Microsoft Clarity API.
+
+Wraps the ``GET /export-data/api/v1/project-live-insights`` endpoint, exposing
+``get_data_export`` while preserving the original behavior of
+``clarity_api.clarity_api.Api.get_data_export``.
+"""
+
+import requests
+from pydantic import ValidationError
+
+from clarity_api.api.api_client_base import ClarityApiBase
+from clarity_api.clarity_models import InputModel
+from clarity_api.decorators import require_auth
+from clarity_api.exceptions import ParameterError
+
+
+class ClarityApiInsights(ClarityApiBase):
+    """Domain client for Clarity Data Export / Live Insights operations."""
+
+    @require_auth
+    def get_data_export(
+        self, api_parameters: dict | None = None, **kwargs
+    ) -> requests.Response:
+        """Retrieve dashboard data insights for a project.
+
+        CONCEPT:CLA-001 — Data Export / Live Insights. Implements the
+        ``GET /export-data/api/v1/project-live-insights`` call backing the
+        ``clarity_insights`` MCP tool.
+
+        Accepts either a pre-built ``api_parameters`` dict or keyword arguments
+        (``number_of_days``/``numOfDays``, ``dimension_1``/``dimension1``, etc.),
+        which are validated and normalized via :class:`InputModel`.
+
+        Args:
+            api_parameters: Pre-built query parameter dict. When omitted, the
+                parameters are constructed from ``kwargs`` via ``InputModel``.
+            **kwargs: Convenience keyword arguments forwarded to ``InputModel``.
+
+        Returns:
+            The ``requests.Response`` object from the GET request.
+
+        Raises:
+            ParameterError: If the provided parameters fail validation.
+        """
+        try:
+            if api_parameters is None:
+                model = InputModel(**kwargs)
+                api_parameters = model.api_parameters
+
+            response = self._session.get(
+                url=f"{self.url}/export-data/api/v1/project-live-insights",
+                params=api_parameters,
+                headers=self.headers,
+                verify=self.verify,
+            )
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+        return response

clarity_api/api_client.py

@@ -0,0 +1,26 @@
+#!/usr/bin/python
+"""Top-level Clarity API client facade.
+
+Composes the per-domain client mixins from :mod:`clarity_api.api` into a single
+``Api`` class. This preserves the original ``clarity_api.clarity_api.Api``
+contract (constructor ``Api(url, token, verify=True)`` validating credentials
+against ``GET /projects``, plus ``get_data_export``) while routing the actual
+implementation through the modular ``api/`` sub-package.
+"""
+
+from clarity_api.api.api_client_insights import ClarityApiInsights
+
+
+class Api(ClarityApiInsights):
+    """Microsoft Clarity Data Export API client.
+
+    Args:
+        url: Base URL of the Clarity instance (e.g. ``https://www.clarity.ms``).
+        token: Bearer API token from the Clarity project settings.
+        verify: Whether to verify TLS certificates. Defaults to ``True``.
+    """
+
+    __slots__ = ()
+
+
+__all__ = ["Api"]

clarity_api/auth.py

@@ -0,0 +1,81 @@
+"""Clarity Authentication Module.
+
+Authentication priority:
+1. **OIDC Delegation** — If delegation is active, exchanges the IdP-issued
+   user token for a downstream Clarity access token via RFC 8693 Token Exchange
+   using the shared ``delegated_auth`` helper.
+2. **Fixed Credentials** — Falls back to the ``CLARITY_TOKEN`` env var.
+
+Environment variables:
+- ``CLARITY_URL`` — base URL of the Clarity instance (default ``https://www.clarity.ms``).
+- ``CLARITY_TOKEN`` — bearer API token.
+- ``CLARITY_SSL_VERIFY`` — whether to verify TLS certificates (default ``True``).
+"""
+
+import os
+import threading
+
+from agent_utilities.base_utilities import get_logger, to_boolean
+from agent_utilities.core.exceptions import AuthError, UnauthorizedError
+
+local = threading.local()
+from clarity_api.api_client import Api
+
+logger = get_logger(__name__)
+
+
+def get_client(
+    instance: str = os.getenv("CLARITY_URL", "https://www.clarity.ms"),
+    token: str | None = os.getenv("CLARITY_TOKEN", None),
+    verify: bool = to_boolean(string=os.getenv("CLARITY_SSL_VERIFY", "True")),
+    config: dict | None = None,
+) -> Api:
+    """Factory function to create the Clarity ``Api`` client.
+
+    CONCEPT:CLA-002 — Credential & Auth Factory. Supports OIDC delegation
+    (RFC 8693 token exchange) and fixed credentials (``CLARITY_TOKEN``). Used as
+    the ``Depends(get_client)`` dependency for the MCP tools.
+    """
+    from agent_utilities.mcp.delegated_auth import (
+        get_delegated_token,
+        get_user_identity,
+        is_delegation_enabled,
+    )
+
+    delegation_enabled = is_delegation_enabled(config)
+
+    # --- Path 1: OIDC Delegation (RFC 8693 Token Exchange) ---
+    if delegation_enabled:
+        try:
+            delegated_token = get_delegated_token(
+                config=config,
+                audience=(config or {}).get("audience", instance),
+                scopes=(config or {}).get("delegated_scopes", "api"),
+                verify=verify,
+            )
+            identity = get_user_identity()
+            logger.info(
+                "Using OIDC delegated token for Clarity API",
+                extra={
+                    "user_email": identity.get("email"),
+                    "instance": instance,
+                },
+            )
+            return Api(url=instance, token=delegated_token, verify=verify)
+        except Exception as e:
+            logger.error(
+                "OIDC delegation failed for Clarity",
+                extra={"error_type": type(e).__name__, "error_message": str(e)},
+            )
+            raise RuntimeError(f"Token exchange failed: {str(e)}") from e
+
+    # --- Path 2: Fixed Credentials (CLARITY_TOKEN) ---
+    logger.info("Using fixed credentials for Clarity API")
+    try:
+        return Api(url=instance, token=token, verify=verify)
+    except (AuthError, UnauthorizedError) as e:
+        raise RuntimeError(
+            f"AUTHENTICATION ERROR: The Clarity credentials provided are not valid for '{instance}'. "
+            f"Please check your CLARITY_TOKEN and CLARITY_URL environment variables. "
+            f"Error details: {str(e)}"
+        ) from e

clarity_api/clarity_api.py

@@ -0,0 +1,12 @@
+#!/usr/bin/python
+"""Backward-compatibility shim for ``clarity_api.clarity_api.Api``.
+
+The real implementation now lives in the modular :mod:`clarity_api.api`
+sub-package and is composed by :mod:`clarity_api.api_client`. This module
+re-exports ``Api`` so that existing imports
+(``from clarity_api.clarity_api import Api``) keep working unchanged.
+"""
+
+from clarity_api.api_client import Api
+
+__all__ = ["Api"]

clarity_api/clarity_models.py

@@ -0,0 +1,161 @@
+#!/usr/bin/python
+import logging
+from typing import Any
+
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+)
+
+logging.basicConfig(
+    level=logging.ERROR, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+class InputModel(BaseModel):
+    """Validated query parameters for the Clarity Data Export endpoint.
+
+    CONCEPT:CLA-003 — Input Validation & Parameter Modeling. Normalizes and
+    validates the ``number_of_days`` date range and the up-to-three breakdown
+    dimensions before they are sent to the Clarity API.
+
+    Attributes:
+        numOfDays (Union[int, str]): The number of days to return.
+        dimension1 (str, optional): The first dimension parameters.
+        dimension2 (str, optional): The second dimension parameters.
+        dimension3 (str, optional): The third dimension parameters.
+        api_parameters (str): Additional API parameters for the group.
+
+    """
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    numOfDays: int | str | None = Field(
+        description="Number of days to save",
+        validation_alias=AliasChoices("numOfDays", "number_of_days"),
+        default=None,
+    )
+    dimension1: str | None = Field(
+        description="Dimension 1",
+        validation_alias=AliasChoices("dimension1", "dimension_1"),
+        default=None,
+    )
+    dimension2: str | None = Field(
+        description="Dimension 2",
+        validation_alias=AliasChoices("dimension2", "dimension_2"),
+        default=None,
+    )
+    dimension3: str | None = Field(
+        description="Dimension 3",
+        validation_alias=AliasChoices("dimension3", "dimension_3"),
+        default=None,
+    )
+    api_parameters: dict | None = Field(description="API Parameters", default=None)
+
+    def model_post_init(self, __context):
+        """Build the validated ``api_parameters`` dict from the input fields.
+
+        CONCEPT:CLA-003 — Input Validation & Parameter Modeling.
+        """
+        self.api_parameters = {}
+        if self.numOfDays:
+            self.api_parameters["numOfDays"] = self.numOfDays
+        if self.dimension1:
+            self.api_parameters["dimension1"] = self.dimension1
+        if self.dimension2:
+            self.api_parameters["dimension2"] = self.dimension2
+        if self.dimension3:
+            self.api_parameters["dimension3"] = self.dimension3
+
+    @field_validator("numOfDays", mode="before")
+    def validate_number_of_days(cls, v):
+        """
+        Validate the 'number_of_days' parameter to ensure it is a valid integer.
+
+        Args:
+        - v: The value of 'number_of_days'.
+
+        Returns:
+        - int: The validated 'number_of_days'.
+
+        Raises:
+        - ParameterError: If 'number_of_days' is not a valid integer.
+        """
+        try:
+            v = int(v)
+        except Exception as e:
+            raise e
+        return v
+
+    @field_validator("dimension1", "dimension2", "dimension3", mode="before")
+    def validate_dimensions(cls, v):
+        """
+        Validate the 'dimensions' parameter to ensure it is a valid option.
+
+        Args:
+        - v: The value of 'dimensions'.
+
+        Returns:
+        - str: The validated 'dimensions'.
+
+        Raises:
+        - ParameterError: If 'dimensions' is not a valid option.
+        """
+        if v:
+            valid_dimensions = {
+                "browser": "Browser",
+                "device": "Device",
+                "country": "Country",
+                "os": "OS",
+                "source": "Source",
+                "medium": "Medium",
+                "campaign": "Campaign",
+                "channel": "Channel",
+                "url": "URL",
+            }
+            try:
+                return valid_dimensions[v.lower()]
+            except KeyError:
+                raise ValueError("Invalid dimension") from None
+
+
+class Information(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    totalSessionCount: str | None = Field(
+        default=None, description="The total number of sessions."
+    )
+    totalBotSessionCount: str | None = Field(
+        default=None, description="The total number of bot sessions."
+    )
+    distantUserCount: str | None = Field(
+        default=None, description="The distant user count."
+    )
+    PagesPerSessionPercentage: float | None = Field(
+        default=None, description="The pages per session percentage."
+    )
+    OS: str | None = Field(default=None, description="The operating system.")
+
+
+class Metric(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    metricName: str | None = Field(
+        default=None, description="The name of the returned metric."
+    )
+    information: list[Information] | None = Field(
+        default=None, description="Result containing available responses."
+    )
+
+
+class Response(BaseModel):
+    data: list[Metric] | None = Field(default=None, description="Metrics returned.")
+    error: Any | None = Field(default=None, description="Response error code")
+    status_code: str | int | None = Field(
+        default=None, description="Response status code"
+    )
+    json_output: list | dict | None = Field(
+        default=None, description="Response JSON data"
+    )
+    raw_output: bytes | None = Field(default=None, description="Response Raw bytes")