arize-phoenix 3.0.2__py3-none-any.whl → 3.1.0__py3-none-any.whl

phoenix/session/session.py

@@ -477,6 +477,7 @@ def launch_app(
             f"port {port} is not occupied by another process) or file an issue "
             f"with us at https://github.com/Arize-ai/phoenix"
         )
+        _session = None
         return None
 
     print(f"🌍 To view the Phoenix app in your browser, visit {_session.url}")
@@ -489,7 +490,9 @@ def active_session() -> Optional[Session]:
     """
     Returns the active session if one exists, otherwise returns None
     """
-    return _session
+    if _session and _session.active:
+        return _session
+    return None
 
 
 def close_app() -> None:

phoenix/trace/dsl/filter.py

@@ -1,4 +1,5 @@
 import ast
+import inspect
 import sys
 from dataclasses import dataclass, field
 from difflib import SequenceMatcher
@@ -15,10 +16,10 @@ from typing import (
     cast,
 )
 
+from openinference.semconv import trace
 from typing_extensions import TypeGuard
 
 import phoenix.trace.v1 as pb
-from phoenix.trace import semantic_conventions
 from phoenix.trace.dsl.missing import MISSING
 from phoenix.trace.schemas import COMPUTED_PREFIX, ComputedAttributes, Span, SpanID
 
@@ -137,9 +138,11 @@ def _allowed_replacements() -> Iterator[Tuple[str, ast.expr]]:
         yield "span.context." + source_segment, ast_replacement
 
     for field_name in (
-        getattr(semantic_conventions, variable_name)
-        for variable_name in dir(semantic_conventions)
-        if variable_name.isupper()
+        getattr(klass, attr)
+        for name in dir(trace)
+        if name.endswith("Attributes") and inspect.isclass(klass := getattr(trace, name))
+        for attr in dir(klass)
+        if attr.isupper()
     ):
         source_segment = field_name
         ast_replacement = _ast_replacement(f"span.attributes.get('{field_name}')")
@@ -163,8 +166,14 @@ class _Translator(ast.NodeTransformer):
         # In Python 3.9+, we can use `ast.unparse(node)` (no need for `source`).
         self._source = source
 
+    def visit_Subscript(self, node: ast.Subscript) -> Any:
+        if _is_metadata(node) and (key := _get_subscript_key(node)):
+            return _ast_metadata_subscript(key)
+        source_segment: str = cast(str, ast.get_source_segment(self._source, node))
+        raise SyntaxError(f"invalid expression: {source_segment}")  # TODO: add details
+
     def visit_Attribute(self, node: ast.Attribute) -> Any:
-        if _is_eval(node.value) and (eval_name := _get_eval_name(node.value)):
+        if _is_eval(node.value) and (eval_name := _get_subscript_key(node.value)):
             # e.g. `evals["name"].score`
             return _ast_evaluation_result_value(eval_name, node.attr)
         source_segment: str = cast(str, ast.get_source_segment(self._source, node))
@@ -206,9 +215,11 @@ def _validate_expression(
         if i == 0:
             if isinstance(node, (ast.BoolOp, ast.Compare)):
                 continue
+        elif _is_metadata(node):
+            continue
         elif _is_eval(node):
             # e.g. `evals["name"]`
-            if not (eval_name := _get_eval_name(node)) or (
+            if not (eval_name := _get_subscript_key(node)) or (
                 valid_eval_names is not None and eval_name not in valid_eval_names
             ):
                 source_segment = cast(str, ast.get_source_segment(source, node))
@@ -293,6 +304,19 @@ def _ast_evaluation_result_value(name: str, attr: str) -> ast.expr:
     return ast.parse(source, mode="eval").body
 
 
+def _ast_metadata_subscript(key: str) -> ast.expr:
+    source = (
+        f"_MISSING if ("
+        f"    _MD := span.attributes.get('metadata')"
+        f") is None else ("
+        f"    _MISSING if not hasattr(_MD, 'get') or ("
+        f"        _VALUE := _MD.get('{key}')"
+        f"    ) is None else _VALUE"
+        f")"
+    )
+    return ast.parse(source, mode="eval").body
+
+
 def _is_eval(node: Any) -> TypeGuard[ast.Subscript]:
     # e.g. `evals["name"]`
     return (
@@ -302,7 +326,16 @@ def _is_eval(node: Any) -> TypeGuard[ast.Subscript]:
     )
 
 
-def _get_eval_name(node: ast.Subscript) -> Optional[str]:
+def _is_metadata(node: Any) -> TypeGuard[ast.Subscript]:
+    # e.g. `metadata["name"]`
+    return (
+        isinstance(node, ast.Subscript)
+        and isinstance(value := node.value, ast.Name)
+        and value.id == "metadata"
+    )
+
+
+def _get_subscript_key(node: ast.Subscript) -> Optional[str]:
     if sys.version_info < (3, 9):
         # Note that `ast.Index` is deprecated in Python 3.9+, but is necessary
         # for Python 3.8 as part of `ast.Subscript`.

phoenix/trace/dsl/helpers.py

@@ -1,15 +1,15 @@
 from typing import List, Optional, Protocol, Union, cast
 
 import pandas as pd
+from openinference.semconv.trace import DocumentAttributes, SpanAttributes
 
 from phoenix.trace.dsl import SpanQuery
-from phoenix.trace.semantic_conventions import (
-    DOCUMENT_CONTENT,
-    DOCUMENT_SCORE,
-    INPUT_VALUE,
-    OUTPUT_VALUE,
-    RETRIEVAL_DOCUMENTS,
-)
+
+DOCUMENT_CONTENT = DocumentAttributes.DOCUMENT_CONTENT
+DOCUMENT_SCORE = DocumentAttributes.DOCUMENT_SCORE
+INPUT_VALUE = SpanAttributes.INPUT_VALUE
+OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE
+RETRIEVAL_DOCUMENTS = SpanAttributes.RETRIEVAL_DOCUMENTS
 
 INPUT = {"input": INPUT_VALUE}
 OUTPUT = {"output": OUTPUT_VALUE}

phoenix/trace/dsl/query.py

@@ -19,13 +19,15 @@ from typing import (
 )
 
 import pandas as pd
+from openinference.semconv.trace import SpanAttributes
 
 from phoenix.trace.dsl import SpanFilter
 from phoenix.trace.dsl.filter import SupportsGetSpanEvaluation
 from phoenix.trace.schemas import ATTRIBUTE_PREFIX, CONTEXT_PREFIX, Span
-from phoenix.trace.semantic_conventions import RETRIEVAL_DOCUMENTS
 from phoenix.trace.span_json_encoder import span_to_json
 
+RETRIEVAL_DOCUMENTS = SpanAttributes.RETRIEVAL_DOCUMENTS
+
 _SPAN_ID = "context.span_id"
 _PRESCRIBED_POSITION_PREFIXES = {
     RETRIEVAL_DOCUMENTS: "document_",

phoenix/trace/errors.py

@@ -3,3 +3,7 @@ from phoenix.exceptions import PhoenixException
 
 class InvalidParquetMetadataError(PhoenixException):
     pass
+
+
+class IncompatibleLibraryVersionError(PhoenixException):
+    pass

phoenix/trace/fixtures.py

@@ -137,8 +137,6 @@ def _download_traces_fixture(
 def load_example_traces(use_case: str) -> TraceDataset:
     """
     Loads a trace dataframe by name.
-
-    NB: this functionality is under active construction.
     """
     fixture = _get_trace_fixture_by_name(use_case)
     return TraceDataset(json_lines_to_df(_download_traces_fixture(fixture)))

phoenix/trace/llama_index/__init__.py

@@ -1,4 +1,3 @@
 from .callback import OpenInferenceTraceCallbackHandler
-from .debug_callback import DebugCallbackHandler
 
-__all__ = ["OpenInferenceTraceCallbackHandler", "DebugCallbackHandler"]
+__all__ = ["OpenInferenceTraceCallbackHandler"]

phoenix/trace/llama_index/callback.py

@@ -1,25 +1,64 @@
 import logging
-from importlib.metadata import PackageNotFoundError
+from importlib.metadata import PackageNotFoundError, version
 from importlib.util import find_spec
-from typing import (
-    Any,
-)
-
-from openinference.instrumentation.llama_index._callback import (
-    OpenInferenceTraceCallbackHandler as _OpenInferenceTraceCallbackHandler,
-)
-from openinference.instrumentation.llama_index.version import (
-    __version__,
-)
+from typing import Any
+
 from opentelemetry import trace as trace_api
 from opentelemetry.sdk import trace as trace_sdk
 from opentelemetry.sdk.trace.export import SimpleSpanProcessor
 
+from phoenix.trace.errors import IncompatibleLibraryVersionError
 from phoenix.trace.exporter import _OpenInferenceExporter
 from phoenix.trace.tracer import _show_deprecation_warnings
 
 logger = logging.getLogger(__name__)
 
+LLAMA_INDEX_MODERN_VERSION = (0, 10, 0)
+INSTRUMENTATION_MODERN_VERSION = (1, 0, 0)
+
+
+def _check_instrumentation_compatibility() -> bool:
+    if find_spec("llama_index") is None:
+        raise PackageNotFoundError("Missing `llama-index`. Install with `pip install llama-index`.")
+    # split the version string into a tuple of integers
+    llama_index_version_str = version("llama-index")
+    llama_index_version = tuple(map(int, llama_index_version_str.split(".")[:3]))
+    instrumentation_version_str = version("openinference-instrumentation-llama-index")
+    instrumentation_version = tuple(map(int, instrumentation_version_str.split(".")[:3]))
+    # check if the llama_index version is compatible with the instrumentation version
+    if (
+        llama_index_version < LLAMA_INDEX_MODERN_VERSION
+        and instrumentation_version >= INSTRUMENTATION_MODERN_VERSION
+    ):
+        raise IncompatibleLibraryVersionError(
+            f"llama-index v{llama_index_version_str} is not compatible with "
+            f"openinference-instrumentation-llama-index v{instrumentation_version_str}."
+            "Please either migrate llama-index to at least 0.10.0 or downgrade "
+            "openinference-instrumentation-llama-index via "
+            "`pip install 'openinference-instrumentation-llama-index<1.0.0'`."
+        )
+    elif (
+        llama_index_version >= LLAMA_INDEX_MODERN_VERSION
+        and instrumentation_version < INSTRUMENTATION_MODERN_VERSION
+    ):
+        raise IncompatibleLibraryVersionError(
+            f"llama-index v{llama_index_version_str} is not compatible with "
+            f"openinference-instrumentation-llama-index v{instrumentation_version_str}."
+            "Please upgrade openinference-instrumentation-llama-index to at least 1.0.0"
+            "`pip install 'openinference-instrumentation-llama-index>=1.0.0'`."
+        )
+    # if the versions are compatible, return True
+    return True
+
+
+if _check_instrumentation_compatibility():
+    from openinference.instrumentation.llama_index._callback import (
+        OpenInferenceTraceCallbackHandler as _OpenInferenceTraceCallbackHandler,
+    )
+    from openinference.instrumentation.llama_index.version import (
+        __version__,
+    )
+
 
 class OpenInferenceTraceCallbackHandler(_OpenInferenceTraceCallbackHandler):
     """Callback handler for storing LLM application trace data in OpenInference format.
@@ -33,10 +72,6 @@ class OpenInferenceTraceCallbackHandler(_OpenInferenceTraceCallbackHandler):
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         _show_deprecation_warnings(self, *args, **kwargs)
-        if find_spec("llama_index") is None:
-            raise PackageNotFoundError(
-                "Missing `llama-index`. Install with `pip install llama-index`."
-            )
         tracer_provider = trace_sdk.TracerProvider()
         tracer_provider.add_span_processor(SimpleSpanProcessor(_OpenInferenceExporter()))
         super().__init__(trace_api.get_tracer(__name__, __version__, tracer_provider))

phoenix/trace/otel.py

@@ -1,3 +1,4 @@
+import inspect
 import json
 from binascii import hexlify, unhexlify
 from datetime import datetime, timezone
@@ -21,12 +22,23 @@ from typing import (
 
 import numpy as np
 import opentelemetry.proto.trace.v1.trace_pb2 as otlp
+from openinference.semconv import trace
+from openinference.semconv.trace import (
+    DocumentAttributes,
+    EmbeddingAttributes,
+    MessageAttributes,
+    SpanAttributes,
+    ToolCallAttributes,
+)
 from opentelemetry.proto.common.v1.common_pb2 import AnyValue, ArrayValue, KeyValue
 from opentelemetry.util.types import Attributes, AttributeValue
 from typing_extensions import TypeAlias, assert_never
 
-import phoenix.trace.semantic_conventions as sem_conv
 from phoenix.trace.schemas import (
+    EXCEPTION_ESCAPED,
+    EXCEPTION_MESSAGE,
+    EXCEPTION_STACKTRACE,
+    EXCEPTION_TYPE,
     MimeType,
     Span,
     SpanContext,
@@ -37,18 +49,38 @@ from phoenix.trace.schemas import (
     SpanStatusCode,
     TraceID,
 )
-from phoenix.trace.semantic_conventions import (
-    DOCUMENT_METADATA,
-    EXCEPTION_ESCAPED,
-    EXCEPTION_MESSAGE,
-    EXCEPTION_STACKTRACE,
-    EXCEPTION_TYPE,
-    INPUT_MIME_TYPE,
-    LLM_PROMPT_TEMPLATE_VARIABLES,
-    OPENINFERENCE_SPAN_KIND,
-    OUTPUT_MIME_TYPE,
-    TOOL_PARAMETERS,
-)
+
+DOCUMENT_CONTENT = DocumentAttributes.DOCUMENT_CONTENT
+DOCUMENT_ID = DocumentAttributes.DOCUMENT_ID
+DOCUMENT_METADATA = DocumentAttributes.DOCUMENT_METADATA
+EMBEDDING_EMBEDDINGS = SpanAttributes.EMBEDDING_EMBEDDINGS
+EMBEDDING_MODEL_NAME = SpanAttributes.EMBEDDING_MODEL_NAME
+EMBEDDING_TEXT = EmbeddingAttributes.EMBEDDING_TEXT
+EMBEDDING_VECTOR = EmbeddingAttributes.EMBEDDING_VECTOR
+INPUT_MIME_TYPE = SpanAttributes.INPUT_MIME_TYPE
+INPUT_VALUE = SpanAttributes.INPUT_VALUE
+LLM_INPUT_MESSAGES = SpanAttributes.LLM_INPUT_MESSAGES
+LLM_INVOCATION_PARAMETERS = SpanAttributes.LLM_INVOCATION_PARAMETERS
+LLM_MODEL_NAME = SpanAttributes.LLM_MODEL_NAME
+LLM_OUTPUT_MESSAGES = SpanAttributes.LLM_OUTPUT_MESSAGES
+LLM_PROMPTS = SpanAttributes.LLM_PROMPTS
+LLM_TOKEN_COUNT_COMPLETION = SpanAttributes.LLM_TOKEN_COUNT_COMPLETION
+LLM_TOKEN_COUNT_PROMPT = SpanAttributes.LLM_TOKEN_COUNT_PROMPT
+LLM_TOKEN_COUNT_TOTAL = SpanAttributes.LLM_TOKEN_COUNT_TOTAL
+MESSAGE_CONTENT = MessageAttributes.MESSAGE_CONTENT
+MESSAGE_FUNCTION_CALL_ARGUMENTS_JSON = MessageAttributes.MESSAGE_FUNCTION_CALL_ARGUMENTS_JSON
+MESSAGE_FUNCTION_CALL_NAME = MessageAttributes.MESSAGE_FUNCTION_CALL_NAME
+MESSAGE_ROLE = MessageAttributes.MESSAGE_ROLE
+MESSAGE_TOOL_CALLS = MessageAttributes.MESSAGE_TOOL_CALLS
+OPENINFERENCE_SPAN_KIND = SpanAttributes.OPENINFERENCE_SPAN_KIND
+OUTPUT_MIME_TYPE = SpanAttributes.OUTPUT_MIME_TYPE
+OUTPUT_VALUE = SpanAttributes.OUTPUT_VALUE
+RETRIEVAL_DOCUMENTS = SpanAttributes.RETRIEVAL_DOCUMENTS
+TOOL_CALL_FUNCTION_ARGUMENTS_JSON = ToolCallAttributes.TOOL_CALL_FUNCTION_ARGUMENTS_JSON
+TOOL_CALL_FUNCTION_NAME = ToolCallAttributes.TOOL_CALL_FUNCTION_NAME
+TOOL_PARAMETERS = SpanAttributes.TOOL_PARAMETERS
+LLM_PROMPT_TEMPLATE = SpanAttributes.LLM_PROMPT_TEMPLATE
+LLM_PROMPT_TEMPLATE_VARIABLES = SpanAttributes.LLM_PROMPT_TEMPLATE_VARIABLES
 
 
 def decode(otlp_span: otlp.Span) -> Span:
@@ -186,7 +218,13 @@ def _decode_status(otlp_status: otlp.Status) -> Tuple[SpanStatusCode, StatusMess
 
 
 _SEMANTIC_CONVENTIONS: List[str] = sorted(
-    (getattr(sem_conv, name) for name in dir(sem_conv) if name.isupper()),
+    (
+        getattr(klass, attr)
+        for name in dir(trace)
+        if name.endswith("Attributes") and inspect.isclass(klass := getattr(trace, name))
+        for attr in dir(klass)
+        if attr.isupper()
+    ),
     reverse=True,
 )  # sorted so the longer strings go first
 

phoenix/trace/schemas.py

@@ -4,12 +4,10 @@ from enum import Enum
 from typing import Any, Dict, List, Optional, Union
 from uuid import UUID
 
-from phoenix.trace.semantic_conventions import (
-    EXCEPTION_ESCAPED,
-    EXCEPTION_MESSAGE,
-    EXCEPTION_STACKTRACE,
-    EXCEPTION_TYPE,
-)
+EXCEPTION_TYPE = "exception.type"
+EXCEPTION_MESSAGE = "exception.message"
+EXCEPTION_ESCAPED = "exception.escaped"
+EXCEPTION_STACKTRACE = "exception.stacktrace"
 
 
 class SpanStatusCode(Enum):

phoenix/trace/span_json_decoder.py

@@ -2,7 +2,10 @@ import json
 from datetime import datetime
 from typing import Any, Dict, Optional
 
+from openinference.semconv.trace import SpanAttributes
+
 from phoenix.trace.schemas import (
+    EXCEPTION_MESSAGE,
     MimeType,
     Span,
     SpanContext,
@@ -14,11 +17,9 @@ from phoenix.trace.schemas import (
     SpanStatusCode,
     TraceID,
 )
-from phoenix.trace.semantic_conventions import (
-    EXCEPTION_MESSAGE,
-    INPUT_MIME_TYPE,
-    OUTPUT_MIME_TYPE,
-)
+
+INPUT_MIME_TYPE = SpanAttributes.INPUT_MIME_TYPE
+OUTPUT_MIME_TYPE = SpanAttributes.OUTPUT_MIME_TYPE
 
 
 def json_to_attributes(obj: Optional[Dict[str, Any]]) -> Dict[str, Any]:

phoenix/trace/span_json_encoder.py

@@ -5,12 +5,7 @@ from enum import Enum
 from typing import Any, List
 from uuid import UUID
 
-from .schemas import (
-    Span,
-    SpanContext,
-    SpanConversationAttributes,
-    SpanEvent,
-)
+from phoenix.trace.schemas import Span, SpanContext, SpanConversationAttributes, SpanEvent
 
 
 class SpanJSONEncoder(json.JSONEncoder):

phoenix/trace/trace_dataset.py

@@ -6,23 +6,26 @@ from uuid import UUID, uuid4
 from warnings import warn
 
 import pandas as pd
+from openinference.semconv.trace import (
+    DocumentAttributes,
+    RerankerAttributes,
+    SpanAttributes,
+)
 from pandas import DataFrame, read_parquet
 from pyarrow import Schema, Table, parquet
 
+from phoenix.config import DATASET_DIR, GENERATED_DATASET_NAME_PREFIX, TRACE_DATASET_DIR
 from phoenix.datetime_utils import normalize_timestamps
 from phoenix.trace.errors import InvalidParquetMetadataError
+from phoenix.trace.schemas import ATTRIBUTE_PREFIX, CONTEXT_PREFIX, Span
+from phoenix.trace.span_evaluations import Evaluations, SpanEvaluations
+from phoenix.trace.span_json_decoder import json_to_span
+from phoenix.trace.span_json_encoder import span_to_json
 
-from ..config import DATASET_DIR, GENERATED_DATASET_NAME_PREFIX, TRACE_DATASET_DIR
-from .schemas import ATTRIBUTE_PREFIX, CONTEXT_PREFIX, Span
-from .semantic_conventions import (
-    DOCUMENT_METADATA,
-    RERANKER_INPUT_DOCUMENTS,
-    RERANKER_OUTPUT_DOCUMENTS,
-    RETRIEVAL_DOCUMENTS,
-)
-from .span_evaluations import Evaluations, SpanEvaluations
-from .span_json_decoder import json_to_span
-from .span_json_encoder import span_to_json
+DOCUMENT_METADATA = DocumentAttributes.DOCUMENT_METADATA
+RERANKER_INPUT_DOCUMENTS = RerankerAttributes.RERANKER_INPUT_DOCUMENTS
+RERANKER_OUTPUT_DOCUMENTS = RerankerAttributes.RERANKER_OUTPUT_DOCUMENTS
+RETRIEVAL_DOCUMENTS = SpanAttributes.RETRIEVAL_DOCUMENTS
 
 # A set of columns that is required
 REQUIRED_COLUMNS = [
@@ -98,9 +101,12 @@ class TraceDataset:
     """
 
     name: str
+    """
+    A human readable name for the dataset.
+    """
     dataframe: pd.DataFrame
     evaluations: List[Evaluations] = []
-    _id: UUID = uuid4()
+    _id: UUID
     _data_file_name: str = "data.parquet"
 
     def __init__(
@@ -128,8 +134,10 @@ class TraceDataset:
             raise ValueError(
                 f"The dataframe is missing some required columns: {', '.join(missing_columns)}"
             )
+        self._id = uuid4()
         self.dataframe = normalize_dataframe(dataframe)
-        self.name = name or f"{GENERATED_DATASET_NAME_PREFIX}{str(uuid4())}"
+        # TODO: This is not used in any meaningful way. Should remove
+        self.name = name or f"{GENERATED_DATASET_NAME_PREFIX}{str(self._id)}"
         self.evaluations = list(evaluations)
 
     @classmethod
@@ -246,6 +254,8 @@ class TraceDataset:
             }
         )
         parquet.write_table(table, path)
+        print(f"💾 Trace dataset saved to under ID: {self._id}")
+        print(f"📂 Trace dataset path: {path}")
         return self._id
 
     @classmethod
@@ -285,7 +295,7 @@ class TraceDataset:
                 warn(f'Failed to load evaluations with id: "{eval_id}"')
         table = parquet.read_table(path)
         dataframe = table.to_pandas()
-        ds = cls(dataframe, dataset_name, evaluations)
+        ds = cls(dataframe=dataframe, name=dataset_name, evaluations=evaluations)
         ds._id = dataset_id
         return ds
 

phoenix/version.py

@@ -1 +1 @@
-__version__ = "3.0.2"
+__version__ = "3.1.0"

phoenix/trace/llama_index/debug_callback.py

@@ -1,50 +0,0 @@
-import logging
-from typing import Any, Dict, List, Optional
-
-from llama_index.callbacks.base_handler import BaseCallbackHandler
-from llama_index.callbacks.schema import CBEventType
-
-logger = logging.getLogger(__name__)
-logger.addHandler(logging.NullHandler())
-
-CBEventID = str
-
-
-class DebugCallbackHandler(BaseCallbackHandler):
-    def _print_event(self, payload: Dict[Any, Any]) -> None:
-        for k, v in payload.items():
-            print(f"**{k}: **\n{v}")
-            print("*" * 50)
-
-    def __init__(self) -> None:
-        super().__init__(event_starts_to_ignore=[], event_ends_to_ignore=[])
-
-    def on_event_start(
-        self,
-        event_type: CBEventType,
-        payload: Optional[Dict[str, Any]] = None,
-        event_id: CBEventID = "",
-        parent_id: CBEventID = "",
-        **kwargs: Any,
-    ) -> CBEventID:
-        return event_id
-
-    def on_event_end(
-        self,
-        event_type: CBEventType,
-        payload: Optional[Dict[str, Any]] = None,
-        event_id: CBEventID = "",
-        **kwargs: Any,
-    ) -> None:
-        if payload is not None:
-            self._print_event(payload)
-
-    def start_trace(self, trace_id: Optional[str] = None) -> None:
-        return
-
-    def end_trace(
-        self,
-        trace_id: Optional[str] = None,
-        trace_map: Optional[Dict[str, List[str]]] = None,
-    ) -> None:
-        return