# coding: utf-8

"""
    Mixpeek API

    This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.

    The version of the OpenAPI document: 1.3.0
    Contact: info@mixpeek.com
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
"""  # noqa: E501

import warnings
from pydantic import validate_call, Field, StrictFloat, StrictStr, StrictInt
from typing import Any, Dict, List, Optional, Tuple, Union
from typing_extensions import Annotated

from pydantic import Field, StrictStr
from typing import Optional
from typing_extensions import Annotated
from mixpeek.models.available_steps_response import AvailableStepsResponse
from mixpeek.models.path_analysis_request import PathAnalysisRequest
from mixpeek.models.path_analysis_response import PathAnalysisResponse
from mixpeek.models.step_transition_request import StepTransitionRequest
from mixpeek.models.step_transition_response import StepTransitionResponse

from mixpeek.api_client import ApiClient, RequestSerialized
from mixpeek.api_response import ApiResponse
from mixpeek.rest import RESTResponseType


class TaxonomyAnalyticsApi:
    """NOTE: This class is auto generated by OpenAPI Generator
    Ref: https://openapi-generator.tech

    Do not edit the class manually.
    """

    def __init__(self, api_client=None) -> None:
        if api_client is None:
            api_client = ApiClient.get_default()
        self.api_client = api_client


    @validate_call
    def analyze_transition_paths_taxonomies_taxonomy_id_analytics(
        self,
        taxonomy_id: StrictStr,
        path_analysis_request: PathAnalysisRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> PathAnalysisResponse:
        """Analyze multi-step transition paths

        Discover the most common multi-step paths documents take between two taxonomy steps.  Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take.  ## Use Cases  **Email Thread Analysis:** - Question: What paths do emails take from \"inquiry\" to \"closed_won\"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won  **Content Editorial Paths:** - Question: Common paths from \"draft\" to \"published\"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review)  **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved  ## Requirements  - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields  ## Returns  **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed  **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_path_length\": 10,     \"min_support\": 5 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"total_sequences\": 1000,     \"completed_sequences\": 350,     \"completion_rate\": 0.35,     \"paths\": [         {             \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],             \"count\": 120,             \"percentage\": 34.3,             \"avg_duration_sec\": 604800.0         },         {             \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],             \"count\": 90,             \"percentage\": 25.7,             \"avg_duration_sec\": 432000.0         },         {             \"path\": [\"inquiry\", \"closed_won\"],             \"count\": 70,             \"percentage\": 20.0,             \"avg_duration_sec\": 172800.0         }     ] } ```  ## Path Interpretation  **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions  **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities  **Frequency Analysis:** - High-percentage paths are \"happy paths\" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param path_analysis_request: (required)
        :type path_analysis_request: PathAnalysisRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._analyze_transition_paths_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            path_analysis_request=path_analysis_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "PathAnalysisResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def analyze_transition_paths_taxonomies_taxonomy_id_analytics_with_http_info(
        self,
        taxonomy_id: StrictStr,
        path_analysis_request: PathAnalysisRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[PathAnalysisResponse]:
        """Analyze multi-step transition paths

        Discover the most common multi-step paths documents take between two taxonomy steps.  Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take.  ## Use Cases  **Email Thread Analysis:** - Question: What paths do emails take from \"inquiry\" to \"closed_won\"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won  **Content Editorial Paths:** - Question: Common paths from \"draft\" to \"published\"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review)  **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved  ## Requirements  - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields  ## Returns  **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed  **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_path_length\": 10,     \"min_support\": 5 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"total_sequences\": 1000,     \"completed_sequences\": 350,     \"completion_rate\": 0.35,     \"paths\": [         {             \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],             \"count\": 120,             \"percentage\": 34.3,             \"avg_duration_sec\": 604800.0         },         {             \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],             \"count\": 90,             \"percentage\": 25.7,             \"avg_duration_sec\": 432000.0         },         {             \"path\": [\"inquiry\", \"closed_won\"],             \"count\": 70,             \"percentage\": 20.0,             \"avg_duration_sec\": 172800.0         }     ] } ```  ## Path Interpretation  **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions  **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities  **Frequency Analysis:** - High-percentage paths are \"happy paths\" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param path_analysis_request: (required)
        :type path_analysis_request: PathAnalysisRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._analyze_transition_paths_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            path_analysis_request=path_analysis_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "PathAnalysisResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def analyze_transition_paths_taxonomies_taxonomy_id_analytics_without_preload_content(
        self,
        taxonomy_id: StrictStr,
        path_analysis_request: PathAnalysisRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Analyze multi-step transition paths

        Discover the most common multi-step paths documents take between two taxonomy steps.  Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take.  ## Use Cases  **Email Thread Analysis:** - Question: What paths do emails take from \"inquiry\" to \"closed_won\"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won  **Content Editorial Paths:** - Question: Common paths from \"draft\" to \"published\"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review)  **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved  ## Requirements  - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields  ## Returns  **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed  **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_path_length\": 10,     \"min_support\": 5 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"total_sequences\": 1000,     \"completed_sequences\": 350,     \"completion_rate\": 0.35,     \"paths\": [         {             \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],             \"count\": 120,             \"percentage\": 34.3,             \"avg_duration_sec\": 604800.0         },         {             \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],             \"count\": 90,             \"percentage\": 25.7,             \"avg_duration_sec\": 432000.0         },         {             \"path\": [\"inquiry\", \"closed_won\"],             \"count\": 70,             \"percentage\": 20.0,             \"avg_duration_sec\": 172800.0         }     ] } ```  ## Path Interpretation  **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions  **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities  **Frequency Analysis:** - High-percentage paths are \"happy paths\" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param path_analysis_request: (required)
        :type path_analysis_request: PathAnalysisRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._analyze_transition_paths_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            path_analysis_request=path_analysis_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "PathAnalysisResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _analyze_transition_paths_taxonomies_taxonomy_id_analytics_serialize(
        self,
        taxonomy_id,
        path_analysis_request,
        authorization,
        x_namespace,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if taxonomy_id is not None:
            _path_params['taxonomy_id'] = taxonomy_id
        # process the query parameters
        # process the header parameters
        if authorization is not None:
            _header_params['Authorization'] = authorization
        if x_namespace is not None:
            _header_params['X-Namespace'] = x_namespace
        # process the form parameters
        # process the body parameter
        if path_analysis_request is not None:
            _body_params = path_analysis_request


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )

        # set the HTTP header `Content-Type`
        if _content_type:
            _header_params['Content-Type'] = _content_type
        else:
            _default_content_type = (
                self.api_client.select_header_content_type(
                    [
                        'application/json'
                    ]
                )
            )
            if _default_content_type is not None:
                _header_params['Content-Type'] = _default_content_type

        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='POST',
            resource_path='/v1/taxonomies/{taxonomy_id}/analytics/paths',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def analyze_transition_paths_taxonomies_taxonomy_id_analytics_0(
        self,
        taxonomy_id: StrictStr,
        path_analysis_request: PathAnalysisRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> PathAnalysisResponse:
        """Analyze multi-step transition paths

        Discover the most common multi-step paths documents take between two taxonomy steps.  Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take.  ## Use Cases  **Email Thread Analysis:** - Question: What paths do emails take from \"inquiry\" to \"closed_won\"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won  **Content Editorial Paths:** - Question: Common paths from \"draft\" to \"published\"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review)  **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved  ## Requirements  - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields  ## Returns  **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed  **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_path_length\": 10,     \"min_support\": 5 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"total_sequences\": 1000,     \"completed_sequences\": 350,     \"completion_rate\": 0.35,     \"paths\": [         {             \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],             \"count\": 120,             \"percentage\": 34.3,             \"avg_duration_sec\": 604800.0         },         {             \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],             \"count\": 90,             \"percentage\": 25.7,             \"avg_duration_sec\": 432000.0         },         {             \"path\": [\"inquiry\", \"closed_won\"],             \"count\": 70,             \"percentage\": 20.0,             \"avg_duration_sec\": 172800.0         }     ] } ```  ## Path Interpretation  **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions  **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities  **Frequency Analysis:** - High-percentage paths are \"happy paths\" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param path_analysis_request: (required)
        :type path_analysis_request: PathAnalysisRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._analyze_transition_paths_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            path_analysis_request=path_analysis_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "PathAnalysisResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def analyze_transition_paths_taxonomies_taxonomy_id_analytics_0_with_http_info(
        self,
        taxonomy_id: StrictStr,
        path_analysis_request: PathAnalysisRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[PathAnalysisResponse]:
        """Analyze multi-step transition paths

        Discover the most common multi-step paths documents take between two taxonomy steps.  Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take.  ## Use Cases  **Email Thread Analysis:** - Question: What paths do emails take from \"inquiry\" to \"closed_won\"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won  **Content Editorial Paths:** - Question: Common paths from \"draft\" to \"published\"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review)  **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved  ## Requirements  - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields  ## Returns  **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed  **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_path_length\": 10,     \"min_support\": 5 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"total_sequences\": 1000,     \"completed_sequences\": 350,     \"completion_rate\": 0.35,     \"paths\": [         {             \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],             \"count\": 120,             \"percentage\": 34.3,             \"avg_duration_sec\": 604800.0         },         {             \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],             \"count\": 90,             \"percentage\": 25.7,             \"avg_duration_sec\": 432000.0         },         {             \"path\": [\"inquiry\", \"closed_won\"],             \"count\": 70,             \"percentage\": 20.0,             \"avg_duration_sec\": 172800.0         }     ] } ```  ## Path Interpretation  **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions  **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities  **Frequency Analysis:** - High-percentage paths are \"happy paths\" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param path_analysis_request: (required)
        :type path_analysis_request: PathAnalysisRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._analyze_transition_paths_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            path_analysis_request=path_analysis_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "PathAnalysisResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def analyze_transition_paths_taxonomies_taxonomy_id_analytics_0_without_preload_content(
        self,
        taxonomy_id: StrictStr,
        path_analysis_request: PathAnalysisRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Analyze multi-step transition paths

        Discover the most common multi-step paths documents take between two taxonomy steps.  Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take.  ## Use Cases  **Email Thread Analysis:** - Question: What paths do emails take from \"inquiry\" to \"closed_won\"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won  **Content Editorial Paths:** - Question: Common paths from \"draft\" to \"published\"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review)  **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved  ## Requirements  - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields  ## Returns  **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed  **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_path_length\": 10,     \"min_support\": 5 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"total_sequences\": 1000,     \"completed_sequences\": 350,     \"completion_rate\": 0.35,     \"paths\": [         {             \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],             \"count\": 120,             \"percentage\": 34.3,             \"avg_duration_sec\": 604800.0         },         {             \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],             \"count\": 90,             \"percentage\": 25.7,             \"avg_duration_sec\": 432000.0         },         {             \"path\": [\"inquiry\", \"closed_won\"],             \"count\": 70,             \"percentage\": 20.0,             \"avg_duration_sec\": 172800.0         }     ] } ```  ## Path Interpretation  **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions  **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities  **Frequency Analysis:** - High-percentage paths are \"happy paths\" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param path_analysis_request: (required)
        :type path_analysis_request: PathAnalysisRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._analyze_transition_paths_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            path_analysis_request=path_analysis_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "PathAnalysisResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _analyze_transition_paths_taxonomies_taxonomy_id_analytics_0_serialize(
        self,
        taxonomy_id,
        path_analysis_request,
        authorization,
        x_namespace,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if taxonomy_id is not None:
            _path_params['taxonomy_id'] = taxonomy_id
        # process the query parameters
        # process the header parameters
        if authorization is not None:
            _header_params['Authorization'] = authorization
        if x_namespace is not None:
            _header_params['X-Namespace'] = x_namespace
        # process the form parameters
        # process the body parameter
        if path_analysis_request is not None:
            _body_params = path_analysis_request


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )

        # set the HTTP header `Content-Type`
        if _content_type:
            _header_params['Content-Type'] = _content_type
        else:
            _default_content_type = (
                self.api_client.select_header_content_type(
                    [
                        'application/json'
                    ]
                )
            )
            if _default_content_type is not None:
                _header_params['Content-Type'] = _default_content_type

        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='POST',
            resource_path='/v1/taxonomies/{taxonomy_id}/analytics/paths',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def compute_step_transitions_taxonomies_taxonomy_id_analytics(
        self,
        taxonomy_id: StrictStr,
        step_transition_request: StepTransitionRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> StepTransitionResponse:
        """Compute step transition analytics

        Analyze how documents progress from one taxonomy step to another.  This endpoint computes conversion rates, duration statistics, and predictor lifts for documents transitioning between taxonomy labels.  ## Use Cases  **Email Thread Analysis:** - Question: How long from \"inquiry\" to \"closed_won\"? - Question: What % of inquiries result in sales? - Question: Which sender domains have highest conversion?  **Content Workflow Tracking:** - Question: Conversion rate from \"draft\" to \"published\"? - Question: How long does content stay in review? - Question: Which authors publish fastest?  **Safety Compliance Monitoring:** - Question: Time from violation detection to resolution? - Question: Success rate for remediation efforts?  ## Requirements  - Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`) - Collection must contain documents enriched with this taxonomy - Documents must have timestamp and sequence grouping fields configured  ## Returns  **Conversion Metrics:** - `count`: Total sequences starting at from_step - `converted`: Number reaching to_step - `conversion_rate`: Percentage that converted  **Duration Statistics (if converted > 0):** - `mean`, `median`: Average and middle duration - `p90`, `p95`: 90th and 95th percentile durations - `std_dev`, `min`, `max`: Distribution statistics  **Top Predictors:** - Covariates with highest impact on conversion - Lift values (>1.0 = increases conversion, <1.0 = decreases) - Statistical significance via minimum support threshold  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_window_days\": 90,     \"min_support\": 10 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"count\": 1000,     \"converted\": 350,     \"conversion_rate\": 0.35,     \"durations_sec\": {         \"mean\": 432000.0,         \"median\": 345600.0,         \"p50\": 345600.0,         \"p90\": 691200.0,         \"p95\": 864000.0     },     \"top_predictors\": [         {             \"field\": \"Sender Domain\",             \"value\": \"enterprise.com\",             \"count\": 150,             \"conversion_rate\": 0.75,             \"lift\": 2.14         }     ] } ```

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param step_transition_request: (required)
        :type step_transition_request: StepTransitionRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._compute_step_transitions_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            step_transition_request=step_transition_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "StepTransitionResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def compute_step_transitions_taxonomies_taxonomy_id_analytics_with_http_info(
        self,
        taxonomy_id: StrictStr,
        step_transition_request: StepTransitionRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[StepTransitionResponse]:
        """Compute step transition analytics

        Analyze how documents progress from one taxonomy step to another.  This endpoint computes conversion rates, duration statistics, and predictor lifts for documents transitioning between taxonomy labels.  ## Use Cases  **Email Thread Analysis:** - Question: How long from \"inquiry\" to \"closed_won\"? - Question: What % of inquiries result in sales? - Question: Which sender domains have highest conversion?  **Content Workflow Tracking:** - Question: Conversion rate from \"draft\" to \"published\"? - Question: How long does content stay in review? - Question: Which authors publish fastest?  **Safety Compliance Monitoring:** - Question: Time from violation detection to resolution? - Question: Success rate for remediation efforts?  ## Requirements  - Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`) - Collection must contain documents enriched with this taxonomy - Documents must have timestamp and sequence grouping fields configured  ## Returns  **Conversion Metrics:** - `count`: Total sequences starting at from_step - `converted`: Number reaching to_step - `conversion_rate`: Percentage that converted  **Duration Statistics (if converted > 0):** - `mean`, `median`: Average and middle duration - `p90`, `p95`: 90th and 95th percentile durations - `std_dev`, `min`, `max`: Distribution statistics  **Top Predictors:** - Covariates with highest impact on conversion - Lift values (>1.0 = increases conversion, <1.0 = decreases) - Statistical significance via minimum support threshold  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_window_days\": 90,     \"min_support\": 10 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"count\": 1000,     \"converted\": 350,     \"conversion_rate\": 0.35,     \"durations_sec\": {         \"mean\": 432000.0,         \"median\": 345600.0,         \"p50\": 345600.0,         \"p90\": 691200.0,         \"p95\": 864000.0     },     \"top_predictors\": [         {             \"field\": \"Sender Domain\",             \"value\": \"enterprise.com\",             \"count\": 150,             \"conversion_rate\": 0.75,             \"lift\": 2.14         }     ] } ```

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param step_transition_request: (required)
        :type step_transition_request: StepTransitionRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._compute_step_transitions_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            step_transition_request=step_transition_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "StepTransitionResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def compute_step_transitions_taxonomies_taxonomy_id_analytics_without_preload_content(
        self,
        taxonomy_id: StrictStr,
        step_transition_request: StepTransitionRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Compute step transition analytics

        Analyze how documents progress from one taxonomy step to another.  This endpoint computes conversion rates, duration statistics, and predictor lifts for documents transitioning between taxonomy labels.  ## Use Cases  **Email Thread Analysis:** - Question: How long from \"inquiry\" to \"closed_won\"? - Question: What % of inquiries result in sales? - Question: Which sender domains have highest conversion?  **Content Workflow Tracking:** - Question: Conversion rate from \"draft\" to \"published\"? - Question: How long does content stay in review? - Question: Which authors publish fastest?  **Safety Compliance Monitoring:** - Question: Time from violation detection to resolution? - Question: Success rate for remediation efforts?  ## Requirements  - Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`) - Collection must contain documents enriched with this taxonomy - Documents must have timestamp and sequence grouping fields configured  ## Returns  **Conversion Metrics:** - `count`: Total sequences starting at from_step - `converted`: Number reaching to_step - `conversion_rate`: Percentage that converted  **Duration Statistics (if converted > 0):** - `mean`, `median`: Average and middle duration - `p90`, `p95`: 90th and 95th percentile durations - `std_dev`, `min`, `max`: Distribution statistics  **Top Predictors:** - Covariates with highest impact on conversion - Lift values (>1.0 = increases conversion, <1.0 = decreases) - Statistical significance via minimum support threshold  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_window_days\": 90,     \"min_support\": 10 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"count\": 1000,     \"converted\": 350,     \"conversion_rate\": 0.35,     \"durations_sec\": {         \"mean\": 432000.0,         \"median\": 345600.0,         \"p50\": 345600.0,         \"p90\": 691200.0,         \"p95\": 864000.0     },     \"top_predictors\": [         {             \"field\": \"Sender Domain\",             \"value\": \"enterprise.com\",             \"count\": 150,             \"conversion_rate\": 0.75,             \"lift\": 2.14         }     ] } ```

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param step_transition_request: (required)
        :type step_transition_request: StepTransitionRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._compute_step_transitions_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            step_transition_request=step_transition_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "StepTransitionResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _compute_step_transitions_taxonomies_taxonomy_id_analytics_serialize(
        self,
        taxonomy_id,
        step_transition_request,
        authorization,
        x_namespace,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if taxonomy_id is not None:
            _path_params['taxonomy_id'] = taxonomy_id
        # process the query parameters
        # process the header parameters
        if authorization is not None:
            _header_params['Authorization'] = authorization
        if x_namespace is not None:
            _header_params['X-Namespace'] = x_namespace
        # process the form parameters
        # process the body parameter
        if step_transition_request is not None:
            _body_params = step_transition_request


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )

        # set the HTTP header `Content-Type`
        if _content_type:
            _header_params['Content-Type'] = _content_type
        else:
            _default_content_type = (
                self.api_client.select_header_content_type(
                    [
                        'application/json'
                    ]
                )
            )
            if _default_content_type is not None:
                _header_params['Content-Type'] = _default_content_type

        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='POST',
            resource_path='/v1/taxonomies/{taxonomy_id}/analytics/transitions',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def compute_step_transitions_taxonomies_taxonomy_id_analytics_0(
        self,
        taxonomy_id: StrictStr,
        step_transition_request: StepTransitionRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> StepTransitionResponse:
        """Compute step transition analytics

        Analyze how documents progress from one taxonomy step to another.  This endpoint computes conversion rates, duration statistics, and predictor lifts for documents transitioning between taxonomy labels.  ## Use Cases  **Email Thread Analysis:** - Question: How long from \"inquiry\" to \"closed_won\"? - Question: What % of inquiries result in sales? - Question: Which sender domains have highest conversion?  **Content Workflow Tracking:** - Question: Conversion rate from \"draft\" to \"published\"? - Question: How long does content stay in review? - Question: Which authors publish fastest?  **Safety Compliance Monitoring:** - Question: Time from violation detection to resolution? - Question: Success rate for remediation efforts?  ## Requirements  - Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`) - Collection must contain documents enriched with this taxonomy - Documents must have timestamp and sequence grouping fields configured  ## Returns  **Conversion Metrics:** - `count`: Total sequences starting at from_step - `converted`: Number reaching to_step - `conversion_rate`: Percentage that converted  **Duration Statistics (if converted > 0):** - `mean`, `median`: Average and middle duration - `p90`, `p95`: 90th and 95th percentile durations - `std_dev`, `min`, `max`: Distribution statistics  **Top Predictors:** - Covariates with highest impact on conversion - Lift values (>1.0 = increases conversion, <1.0 = decreases) - Statistical significance via minimum support threshold  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_window_days\": 90,     \"min_support\": 10 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"count\": 1000,     \"converted\": 350,     \"conversion_rate\": 0.35,     \"durations_sec\": {         \"mean\": 432000.0,         \"median\": 345600.0,         \"p50\": 345600.0,         \"p90\": 691200.0,         \"p95\": 864000.0     },     \"top_predictors\": [         {             \"field\": \"Sender Domain\",             \"value\": \"enterprise.com\",             \"count\": 150,             \"conversion_rate\": 0.75,             \"lift\": 2.14         }     ] } ```

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param step_transition_request: (required)
        :type step_transition_request: StepTransitionRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._compute_step_transitions_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            step_transition_request=step_transition_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "StepTransitionResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def compute_step_transitions_taxonomies_taxonomy_id_analytics_0_with_http_info(
        self,
        taxonomy_id: StrictStr,
        step_transition_request: StepTransitionRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[StepTransitionResponse]:
        """Compute step transition analytics

        Analyze how documents progress from one taxonomy step to another.  This endpoint computes conversion rates, duration statistics, and predictor lifts for documents transitioning between taxonomy labels.  ## Use Cases  **Email Thread Analysis:** - Question: How long from \"inquiry\" to \"closed_won\"? - Question: What % of inquiries result in sales? - Question: Which sender domains have highest conversion?  **Content Workflow Tracking:** - Question: Conversion rate from \"draft\" to \"published\"? - Question: How long does content stay in review? - Question: Which authors publish fastest?  **Safety Compliance Monitoring:** - Question: Time from violation detection to resolution? - Question: Success rate for remediation efforts?  ## Requirements  - Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`) - Collection must contain documents enriched with this taxonomy - Documents must have timestamp and sequence grouping fields configured  ## Returns  **Conversion Metrics:** - `count`: Total sequences starting at from_step - `converted`: Number reaching to_step - `conversion_rate`: Percentage that converted  **Duration Statistics (if converted > 0):** - `mean`, `median`: Average and middle duration - `p90`, `p95`: 90th and 95th percentile durations - `std_dev`, `min`, `max`: Distribution statistics  **Top Predictors:** - Covariates with highest impact on conversion - Lift values (>1.0 = increases conversion, <1.0 = decreases) - Statistical significance via minimum support threshold  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_window_days\": 90,     \"min_support\": 10 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"count\": 1000,     \"converted\": 350,     \"conversion_rate\": 0.35,     \"durations_sec\": {         \"mean\": 432000.0,         \"median\": 345600.0,         \"p50\": 345600.0,         \"p90\": 691200.0,         \"p95\": 864000.0     },     \"top_predictors\": [         {             \"field\": \"Sender Domain\",             \"value\": \"enterprise.com\",             \"count\": 150,             \"conversion_rate\": 0.75,             \"lift\": 2.14         }     ] } ```

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param step_transition_request: (required)
        :type step_transition_request: StepTransitionRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._compute_step_transitions_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            step_transition_request=step_transition_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "StepTransitionResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def compute_step_transitions_taxonomies_taxonomy_id_analytics_0_without_preload_content(
        self,
        taxonomy_id: StrictStr,
        step_transition_request: StepTransitionRequest,
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Compute step transition analytics

        Analyze how documents progress from one taxonomy step to another.  This endpoint computes conversion rates, duration statistics, and predictor lifts for documents transitioning between taxonomy labels.  ## Use Cases  **Email Thread Analysis:** - Question: How long from \"inquiry\" to \"closed_won\"? - Question: What % of inquiries result in sales? - Question: Which sender domains have highest conversion?  **Content Workflow Tracking:** - Question: Conversion rate from \"draft\" to \"published\"? - Question: How long does content stay in review? - Question: Which authors publish fastest?  **Safety Compliance Monitoring:** - Question: Time from violation detection to resolution? - Question: Success rate for remediation efforts?  ## Requirements  - Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`) - Collection must contain documents enriched with this taxonomy - Documents must have timestamp and sequence grouping fields configured  ## Returns  **Conversion Metrics:** - `count`: Total sequences starting at from_step - `converted`: Number reaching to_step - `conversion_rate`: Percentage that converted  **Duration Statistics (if converted > 0):** - `mean`, `median`: Average and middle duration - `p90`, `p95`: 90th and 95th percentile durations - `std_dev`, `min`, `max`: Distribution statistics  **Top Predictors:** - Covariates with highest impact on conversion - Lift values (>1.0 = increases conversion, <1.0 = decreases) - Statistical significance via minimum support threshold  ## Example Request  ```json {     \"collection_id\": \"col_emails\",     \"taxonomy_id\": \"tax_sales_stages\",     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"max_window_days\": 90,     \"min_support\": 10 } ```  ## Example Response  ```json {     \"from_step\": \"inquiry\",     \"to_step\": \"closed_won\",     \"count\": 1000,     \"converted\": 350,     \"conversion_rate\": 0.35,     \"durations_sec\": {         \"mean\": 432000.0,         \"median\": 345600.0,         \"p50\": 345600.0,         \"p90\": 691200.0,         \"p95\": 864000.0     },     \"top_predictors\": [         {             \"field\": \"Sender Domain\",             \"value\": \"enterprise.com\",             \"count\": 150,             \"conversion_rate\": 0.75,             \"lift\": 2.14         }     ] } ```

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param step_transition_request: (required)
        :type step_transition_request: StepTransitionRequest
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._compute_step_transitions_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            step_transition_request=step_transition_request,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "StepTransitionResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _compute_step_transitions_taxonomies_taxonomy_id_analytics_0_serialize(
        self,
        taxonomy_id,
        step_transition_request,
        authorization,
        x_namespace,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if taxonomy_id is not None:
            _path_params['taxonomy_id'] = taxonomy_id
        # process the query parameters
        # process the header parameters
        if authorization is not None:
            _header_params['Authorization'] = authorization
        if x_namespace is not None:
            _header_params['X-Namespace'] = x_namespace
        # process the form parameters
        # process the body parameter
        if step_transition_request is not None:
            _body_params = step_transition_request


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )

        # set the HTTP header `Content-Type`
        if _content_type:
            _header_params['Content-Type'] = _content_type
        else:
            _default_content_type = (
                self.api_client.select_header_content_type(
                    [
                        'application/json'
                    ]
                )
            )
            if _default_content_type is not None:
                _header_params['Content-Type'] = _default_content_type

        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='POST',
            resource_path='/v1/taxonomies/{taxonomy_id}/analytics/transitions',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def get_available_steps_taxonomies_taxonomy_id_analytics(
        self,
        taxonomy_id: StrictStr,
        collection_id: Annotated[StrictStr, Field(description="Collection ID to analyze")],
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> AvailableStepsResponse:
        """Get Available Steps

        Get all available steps for a taxonomy and collection.  This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.  **Use Cases:** - Discover available steps before querying analytics - Validate step names (avoid typos in from_step/to_step) - See which steps have the most events - Check data freshness (first_seen/last_seen timestamps)  **Example Usage:** ```python # 1. Get available steps GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails  # Response: {     \"taxonomy_id\": \"tax_sales\",     \"collection_id\": \"col_emails\",     \"total_events\": 5432,     \"total_sequences\": 1000,     \"steps\": [         {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},         {\"step_key\": \"followup\", \"event_count\": 450, ...},         {\"step_key\": \"closed_won\", \"event_count\": 350, ...}     ] }  # 2. Use discovered steps in transition query POST /v1/taxonomies/tax_sales/analytics/transitions {     \"collection_id\": \"col_emails\",     \"from_step\": \"inquiry\",      # From available steps     \"to_step\": \"closed_won\"      # From available steps } ```  Args:     request: FastAPI request object (contains tenant context)     taxonomy_id: Taxonomy ID to query     collection_id: Collection ID for filtering events  Returns:     AvailableStepsResponse with all steps sorted by event count (descending)  Raises:     NotFoundError: If taxonomy not found     ValidationError: If unable to query ClickHouse

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param collection_id: Collection ID to analyze (required)
        :type collection_id: str
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_available_steps_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            collection_id=collection_id,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "AvailableStepsResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def get_available_steps_taxonomies_taxonomy_id_analytics_with_http_info(
        self,
        taxonomy_id: StrictStr,
        collection_id: Annotated[StrictStr, Field(description="Collection ID to analyze")],
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[AvailableStepsResponse]:
        """Get Available Steps

        Get all available steps for a taxonomy and collection.  This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.  **Use Cases:** - Discover available steps before querying analytics - Validate step names (avoid typos in from_step/to_step) - See which steps have the most events - Check data freshness (first_seen/last_seen timestamps)  **Example Usage:** ```python # 1. Get available steps GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails  # Response: {     \"taxonomy_id\": \"tax_sales\",     \"collection_id\": \"col_emails\",     \"total_events\": 5432,     \"total_sequences\": 1000,     \"steps\": [         {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},         {\"step_key\": \"followup\", \"event_count\": 450, ...},         {\"step_key\": \"closed_won\", \"event_count\": 350, ...}     ] }  # 2. Use discovered steps in transition query POST /v1/taxonomies/tax_sales/analytics/transitions {     \"collection_id\": \"col_emails\",     \"from_step\": \"inquiry\",      # From available steps     \"to_step\": \"closed_won\"      # From available steps } ```  Args:     request: FastAPI request object (contains tenant context)     taxonomy_id: Taxonomy ID to query     collection_id: Collection ID for filtering events  Returns:     AvailableStepsResponse with all steps sorted by event count (descending)  Raises:     NotFoundError: If taxonomy not found     ValidationError: If unable to query ClickHouse

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param collection_id: Collection ID to analyze (required)
        :type collection_id: str
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_available_steps_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            collection_id=collection_id,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "AvailableStepsResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def get_available_steps_taxonomies_taxonomy_id_analytics_without_preload_content(
        self,
        taxonomy_id: StrictStr,
        collection_id: Annotated[StrictStr, Field(description="Collection ID to analyze")],
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Get Available Steps

        Get all available steps for a taxonomy and collection.  This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.  **Use Cases:** - Discover available steps before querying analytics - Validate step names (avoid typos in from_step/to_step) - See which steps have the most events - Check data freshness (first_seen/last_seen timestamps)  **Example Usage:** ```python # 1. Get available steps GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails  # Response: {     \"taxonomy_id\": \"tax_sales\",     \"collection_id\": \"col_emails\",     \"total_events\": 5432,     \"total_sequences\": 1000,     \"steps\": [         {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},         {\"step_key\": \"followup\", \"event_count\": 450, ...},         {\"step_key\": \"closed_won\", \"event_count\": 350, ...}     ] }  # 2. Use discovered steps in transition query POST /v1/taxonomies/tax_sales/analytics/transitions {     \"collection_id\": \"col_emails\",     \"from_step\": \"inquiry\",      # From available steps     \"to_step\": \"closed_won\"      # From available steps } ```  Args:     request: FastAPI request object (contains tenant context)     taxonomy_id: Taxonomy ID to query     collection_id: Collection ID for filtering events  Returns:     AvailableStepsResponse with all steps sorted by event count (descending)  Raises:     NotFoundError: If taxonomy not found     ValidationError: If unable to query ClickHouse

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param collection_id: Collection ID to analyze (required)
        :type collection_id: str
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_available_steps_taxonomies_taxonomy_id_analytics_serialize(
            taxonomy_id=taxonomy_id,
            collection_id=collection_id,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "AvailableStepsResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _get_available_steps_taxonomies_taxonomy_id_analytics_serialize(
        self,
        taxonomy_id,
        collection_id,
        authorization,
        x_namespace,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if taxonomy_id is not None:
            _path_params['taxonomy_id'] = taxonomy_id
        # process the query parameters
        if collection_id is not None:
            
            _query_params.append(('collection_id', collection_id))
            
        # process the header parameters
        if authorization is not None:
            _header_params['Authorization'] = authorization
        if x_namespace is not None:
            _header_params['X-Namespace'] = x_namespace
        # process the form parameters
        # process the body parameter


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )


        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='GET',
            resource_path='/v1/taxonomies/{taxonomy_id}/analytics/available-steps',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def get_available_steps_taxonomies_taxonomy_id_analytics_0(
        self,
        taxonomy_id: StrictStr,
        collection_id: Annotated[StrictStr, Field(description="Collection ID to analyze")],
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> AvailableStepsResponse:
        """Get Available Steps

        Get all available steps for a taxonomy and collection.  This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.  **Use Cases:** - Discover available steps before querying analytics - Validate step names (avoid typos in from_step/to_step) - See which steps have the most events - Check data freshness (first_seen/last_seen timestamps)  **Example Usage:** ```python # 1. Get available steps GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails  # Response: {     \"taxonomy_id\": \"tax_sales\",     \"collection_id\": \"col_emails\",     \"total_events\": 5432,     \"total_sequences\": 1000,     \"steps\": [         {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},         {\"step_key\": \"followup\", \"event_count\": 450, ...},         {\"step_key\": \"closed_won\", \"event_count\": 350, ...}     ] }  # 2. Use discovered steps in transition query POST /v1/taxonomies/tax_sales/analytics/transitions {     \"collection_id\": \"col_emails\",     \"from_step\": \"inquiry\",      # From available steps     \"to_step\": \"closed_won\"      # From available steps } ```  Args:     request: FastAPI request object (contains tenant context)     taxonomy_id: Taxonomy ID to query     collection_id: Collection ID for filtering events  Returns:     AvailableStepsResponse with all steps sorted by event count (descending)  Raises:     NotFoundError: If taxonomy not found     ValidationError: If unable to query ClickHouse

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param collection_id: Collection ID to analyze (required)
        :type collection_id: str
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_available_steps_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            collection_id=collection_id,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "AvailableStepsResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def get_available_steps_taxonomies_taxonomy_id_analytics_0_with_http_info(
        self,
        taxonomy_id: StrictStr,
        collection_id: Annotated[StrictStr, Field(description="Collection ID to analyze")],
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[AvailableStepsResponse]:
        """Get Available Steps

        Get all available steps for a taxonomy and collection.  This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.  **Use Cases:** - Discover available steps before querying analytics - Validate step names (avoid typos in from_step/to_step) - See which steps have the most events - Check data freshness (first_seen/last_seen timestamps)  **Example Usage:** ```python # 1. Get available steps GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails  # Response: {     \"taxonomy_id\": \"tax_sales\",     \"collection_id\": \"col_emails\",     \"total_events\": 5432,     \"total_sequences\": 1000,     \"steps\": [         {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},         {\"step_key\": \"followup\", \"event_count\": 450, ...},         {\"step_key\": \"closed_won\", \"event_count\": 350, ...}     ] }  # 2. Use discovered steps in transition query POST /v1/taxonomies/tax_sales/analytics/transitions {     \"collection_id\": \"col_emails\",     \"from_step\": \"inquiry\",      # From available steps     \"to_step\": \"closed_won\"      # From available steps } ```  Args:     request: FastAPI request object (contains tenant context)     taxonomy_id: Taxonomy ID to query     collection_id: Collection ID for filtering events  Returns:     AvailableStepsResponse with all steps sorted by event count (descending)  Raises:     NotFoundError: If taxonomy not found     ValidationError: If unable to query ClickHouse

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param collection_id: Collection ID to analyze (required)
        :type collection_id: str
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_available_steps_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            collection_id=collection_id,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "AvailableStepsResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def get_available_steps_taxonomies_taxonomy_id_analytics_0_without_preload_content(
        self,
        taxonomy_id: StrictStr,
        collection_id: Annotated[StrictStr, Field(description="Collection ID to analyze")],
        authorization: Annotated[Optional[StrictStr], Field(description="REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.")] = None,
        x_namespace: Annotated[Optional[StrictStr], Field(description="REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'")] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Get Available Steps

        Get all available steps for a taxonomy and collection.  This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.  **Use Cases:** - Discover available steps before querying analytics - Validate step names (avoid typos in from_step/to_step) - See which steps have the most events - Check data freshness (first_seen/last_seen timestamps)  **Example Usage:** ```python # 1. Get available steps GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails  # Response: {     \"taxonomy_id\": \"tax_sales\",     \"collection_id\": \"col_emails\",     \"total_events\": 5432,     \"total_sequences\": 1000,     \"steps\": [         {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},         {\"step_key\": \"followup\", \"event_count\": 450, ...},         {\"step_key\": \"closed_won\", \"event_count\": 350, ...}     ] }  # 2. Use discovered steps in transition query POST /v1/taxonomies/tax_sales/analytics/transitions {     \"collection_id\": \"col_emails\",     \"from_step\": \"inquiry\",      # From available steps     \"to_step\": \"closed_won\"      # From available steps } ```  Args:     request: FastAPI request object (contains tenant context)     taxonomy_id: Taxonomy ID to query     collection_id: Collection ID for filtering events  Returns:     AvailableStepsResponse with all steps sorted by event count (descending)  Raises:     NotFoundError: If taxonomy not found     ValidationError: If unable to query ClickHouse

        :param taxonomy_id: (required)
        :type taxonomy_id: str
        :param collection_id: Collection ID to analyze (required)
        :type collection_id: str
        :param authorization: REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
        :type authorization: str
        :param x_namespace: REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
        :type x_namespace: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_available_steps_taxonomies_taxonomy_id_analytics_0_serialize(
            taxonomy_id=taxonomy_id,
            collection_id=collection_id,
            authorization=authorization,
            x_namespace=x_namespace,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "AvailableStepsResponse",
            '400': "ErrorResponse",
            '401': "ErrorResponse",
            '403': "ErrorResponse",
            '404': "ErrorResponse",
            '500': "ErrorResponse",
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _get_available_steps_taxonomies_taxonomy_id_analytics_0_serialize(
        self,
        taxonomy_id,
        collection_id,
        authorization,
        x_namespace,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if taxonomy_id is not None:
            _path_params['taxonomy_id'] = taxonomy_id
        # process the query parameters
        if collection_id is not None:
            
            _query_params.append(('collection_id', collection_id))
            
        # process the header parameters
        if authorization is not None:
            _header_params['Authorization'] = authorization
        if x_namespace is not None:
            _header_params['X-Namespace'] = x_namespace
        # process the form parameters
        # process the body parameter


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )


        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='GET',
            resource_path='/v1/taxonomies/{taxonomy_id}/analytics/available-steps',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )


