semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/text/text_chunker.py

@@ -0,0 +1,307 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""A Text splitter.
+
+Split text in chunks, attempting to leave meaning intact.
+For plain text, split looking at new lines first, then periods, and so on.
+For markdown, split looking at punctuation first, and so on.
+"""
+
+import os
+import re
+from collections.abc import Callable
+
+NEWLINE = os.linesep
+
+TEXT_SPLIT_OPTIONS: list[list[str] | None] = [
+    ["\n", "\r"],
+    ["."],
+    ["?", "!"],
+    [";"],
+    [":"],
+    [","],
+    [")", "]", "}"],
+    [" "],
+    ["-"],
+    None,
+]
+
+MD_SPLIT_OPTIONS: list[list[str] | None] = [
+    ["."],
+    ["?", "!"],
+    [";"],
+    [":"],
+    [","],
+    [")", "]", "}"],
+    [" "],
+    ["-"],
+    ["\n", "\r"],
+    None,
+]
+
+
+def _token_counter(text: str) -> int:
+    """Count the number of tokens in a string.
+
+    TODO: chunking methods should be configurable to allow for different
+          tokenization strategies depending on the model to be called.
+          For now, we use an extremely rough estimate.
+    """
+    return len(text) // 4
+
+
+def split_plaintext_lines(text: str, max_token_per_line: int, token_counter: Callable = _token_counter) -> list[str]:
+    """Split plain text into lines.
+
+    it will split on new lines first, and then on punctuation.
+    """
+    return _split_text_lines(
+        text=text,
+        max_token_per_line=max_token_per_line,
+        trim=True,
+        token_counter=token_counter,
+    )
+
+
+def split_markdown_lines(text: str, max_token_per_line: int, token_counter: Callable = _token_counter) -> list[str]:
+    """Split markdown into lines.
+
+    It will split on punctuation first, and then on space and new lines.
+    """
+    return _split_markdown_lines(
+        text=text,
+        max_token_per_line=max_token_per_line,
+        trim=True,
+        token_counter=token_counter,
+    )
+
+
+def split_plaintext_paragraph(text: list[str], max_tokens: int, token_counter: Callable = _token_counter) -> list[str]:
+    """Split plain text into paragraphs."""
+    split_lines = []
+    for line in text:
+        split_lines.extend(
+            _split_text_lines(
+                text=line,
+                max_token_per_line=max_tokens,
+                trim=True,
+                token_counter=token_counter,
+            )
+        )
+
+    return _split_text_paragraph(text=split_lines, max_tokens=max_tokens, token_counter=token_counter)
+
+
+def split_markdown_paragraph(text: list[str], max_tokens: int, token_counter: Callable = _token_counter) -> list[str]:
+    """Split markdown into paragraphs."""
+    split_lines = []
+    for line in text:
+        split_lines.extend(
+            _split_markdown_lines(
+                text=line,
+                max_token_per_line=max_tokens,
+                trim=False,
+                token_counter=token_counter,
+            )
+        )
+
+    return _split_text_paragraph(text=split_lines, max_tokens=max_tokens, token_counter=token_counter)
+
+
+def _split_text_paragraph(text: list[str], max_tokens: int, token_counter: Callable = _token_counter) -> list[str]:
+    """Split text into paragraphs."""
+    if not text:
+        return []
+
+    paragraphs: list[str] = []
+    current_paragraph: list[str] = []
+
+    for line in text:
+        num_tokens_line = token_counter(line)
+        num_tokens_paragraph = token_counter("".join(current_paragraph))
+
+        if num_tokens_paragraph + num_tokens_line + 1 >= max_tokens and len(current_paragraph) > 0:
+            paragraphs.append("".join(current_paragraph).strip())
+            current_paragraph = []
+
+        current_paragraph.append(f"{line}{NEWLINE}")
+
+    if len(current_paragraph) > 0:
+        paragraphs.append("".join(current_paragraph).strip())
+        current_paragraph = []
+
+    # Distribute text more evenly in the last paragraphs
+    # when the last paragraph is too short.
+
+    if len(paragraphs) > 1:
+        last_para = paragraphs[-1]
+        sec_last_para = paragraphs[-2]
+
+        if token_counter(last_para) < max_tokens / 4:
+            last_para_tokens = last_para.split(" ")
+            sec_last_para_tokens = sec_last_para.split(" ")
+            last_para_token_count = len(last_para_tokens)
+            sec_last_para_token_count = len(sec_last_para_tokens)
+
+            if last_para_token_count + sec_last_para_token_count <= max_tokens:
+                sec_last_para = " ".join(sec_last_para_tokens) + NEWLINE
+                last_para = " ".join(last_para_tokens)
+                new_sec_last_para = sec_last_para + last_para
+                paragraphs[-2] = new_sec_last_para.strip()
+                paragraphs.pop()
+
+    return paragraphs
+
+
+def _split_markdown_lines(
+    text: str,
+    max_token_per_line: int,
+    trim: bool,
+    token_counter: Callable = _token_counter,
+) -> list[str]:
+    """Split markdown into lines."""
+    return _split_str_lines(
+        text=text,
+        max_tokens=max_token_per_line,
+        separators=MD_SPLIT_OPTIONS,
+        trim=trim,
+        token_counter=token_counter,
+    )
+
+
+def _split_text_lines(
+    text: str,
+    max_token_per_line: int,
+    trim: bool,
+    token_counter: Callable = _token_counter,
+) -> list[str]:
+    """Split text into lines."""
+    return _split_str_lines(
+        text=text,
+        max_tokens=max_token_per_line,
+        separators=TEXT_SPLIT_OPTIONS,
+        trim=trim,
+        token_counter=token_counter,
+    )
+
+
+def _split_str_lines(
+    text: str,
+    max_tokens: int,
+    separators: list[list[str] | None],
+    trim: bool,
+    token_counter: Callable = _token_counter,
+) -> list[str]:
+    """Split text into lines."""
+    if not text:
+        return []
+
+    text = text.replace("\r\n", "\n")
+    lines: list[str] = []
+    was_split = False
+    for split_option in separators:
+        if not lines:
+            lines, was_split = _split_str(
+                text=text,
+                max_tokens=max_tokens,
+                separators=split_option,
+                trim=trim,
+                token_counter=token_counter,
+            )
+        else:
+            lines, was_split = _split_list(
+                text=lines,
+                max_tokens=max_tokens,
+                separators=split_option,
+                trim=trim,
+                token_counter=token_counter,
+            )
+        if was_split:
+            break  # pragma: no cover
+
+    return lines
+
+
+def _split_str(
+    text: str,
+    max_tokens: int,
+    separators: list[str] | None,
+    trim: bool,
+    token_counter: Callable = _token_counter,
+) -> tuple[list[str], bool]:
+    """Split text into lines."""
+    input_was_split = False
+    if not text:
+        return [], input_was_split  # pragma: no cover
+
+    if trim:
+        text = text.strip()
+
+    text_as_is = [text]
+
+    if token_counter(text) <= max_tokens:
+        return text_as_is, input_was_split
+
+    half = len(text) // 2
+
+    cutpoint = -1
+
+    if not separators:
+        cutpoint = half
+    elif set(separators) & set(text) and len(text) > 2:
+        regex_separators = re.compile("|".join(re.escape(s) for s in separators))
+        min_dist = half
+        for match in re.finditer(regex_separators, text):
+            end = match.end()
+            dist = abs(half - end)
+            if dist < min_dist:
+                min_dist = dist
+                cutpoint = end
+            elif end > half:
+                # distance is increasing, so we can stop searching
+                break
+    else:
+        return text_as_is, input_was_split
+
+    if 0 < cutpoint < len(text):
+        lines = []
+        for text_part in [text[:cutpoint], text[cutpoint:]]:
+            split, has_split = _split_str(
+                text=text_part,
+                max_tokens=max_tokens,
+                separators=separators,
+                trim=trim,
+                token_counter=token_counter,
+            )
+            lines.extend(split)
+            input_was_split = input_was_split or has_split
+    else:
+        return text_as_is, input_was_split
+
+    return lines, input_was_split
+
+
+def _split_list(
+    text: list[str],
+    max_tokens: int,
+    separators: list[str] | None,
+    trim: bool,
+    token_counter: Callable = _token_counter,
+) -> tuple[list[str], bool]:
+    """Split list of string into lines."""
+    if not text:
+        return [], False  # pragma: no cover
+
+    lines = []
+    input_was_split = False
+    for line in text:
+        split_str, was_split = _split_str(
+            text=line,
+            max_tokens=max_tokens,
+            separators=separators,
+            trim=trim,
+            token_counter=token_counter,
+        )
+        lines.extend(split_str)
+        input_was_split = input_was_split or was_split
+
+    return lines, input_was_split

semantic_kernel-1.8.3/semantic_kernel/utils/chat.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING
+
+from semantic_kernel.contents.chat_history import ChatHistory
+
+if TYPE_CHECKING:
+    from semantic_kernel.contents.chat_message_content import ChatMessageContent
+
+
+def store_results(chat_history: ChatHistory, results: list["ChatMessageContent"]):
+    """Stores specific results in the context and chat prompt."""
+    for message in results:
+        chat_history.add_message(message=message)
+    return chat_history

semantic_kernel-1.8.3/semantic_kernel/utils/experimental_decorator.py

@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T", bound=type)
+
+
+def experimental_function(func: Callable) -> Callable:
+    """Decorator to mark a function as experimental."""
+    if callable(func):
+        if func.__doc__:
+            func.__doc__ += "\n\nNote: This function is experimental and may change in the future."
+        else:
+            func.__doc__ = "Note: This function is experimental and may change in the future."
+
+        setattr(func, "is_experimental", True)
+
+    return func
+
+
+def experimental_class(cls: T) -> T:
+    """Decorator to mark a class as experimental."""
+    if isinstance(cls, type):
+        if cls.__doc__:
+            cls.__doc__ += "\n\nNote: This class is experimental and may change in the future."
+        else:
+            cls.__doc__ = "Note: This class is experimental and may change in the future."
+
+        setattr(cls, "is_experimental", True)
+
+    return cls

semantic_kernel-1.8.3/semantic_kernel/utils/logging.py

@@ -0,0 +1,11 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+
+
+def setup_logging():
+    """Setup a detailed logging format."""
+    logging.basicConfig(
+        format="[%(asctime)s - %(name)s:%(lineno)d - %(levelname)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )

semantic_kernel-1.8.3/semantic_kernel/utils/naming.py

@@ -0,0 +1,19 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import random
+import string
+
+
+def generate_random_ascii_name(length: int = 16) -> str:
+    """Generate a series of random ASCII characters of the specified length.
+
+    As example, plugin/function names can contain upper/lowercase letters, and underscores
+
+    Args:
+        length (int): The length of the string to generate.
+
+    Returns:
+        A string of random ASCII characters of the specified length.
+    """
+    letters = string.ascii_letters
+    return "".join(random.choices(letters, k=length))  # nosec

semantic_kernel-1.8.3/semantic_kernel/utils/telemetry/model_diagnostics/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.utils.telemetry.model_diagnostics.decorators import trace_chat_completion, trace_text_completion
+
+__all__ = [
+    "trace_chat_completion",
+    "trace_text_completion",
+]

semantic_kernel-1.8.3/semantic_kernel/utils/telemetry/model_diagnostics/decorators.py

@@ -0,0 +1,232 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import functools
+import json
+from collections.abc import Callable
+from typing import Any
+
+from opentelemetry.trace import Span, StatusCode, get_tracer, use_span
+
+from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
+from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+from semantic_kernel.connectors.ai.text_completion_client_base import TextCompletionClientBase
+from semantic_kernel.contents.chat_history import ChatHistory
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.contents.text_content import TextContent
+from semantic_kernel.utils.experimental_decorator import experimental_function
+from semantic_kernel.utils.telemetry.model_diagnostics import gen_ai_attributes
+from semantic_kernel.utils.telemetry.model_diagnostics.model_diagnostics_settings import ModelDiagnosticSettings
+
+# Module to instrument GenAI models using OpenTelemetry and OpenTelemetry Semantic Conventions.
+# These are experimental features and may change in the future.
+
+# To enable these features, set one of the following environment variables to true:
+#    SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS
+#    SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE
+MODEL_DIAGNOSTICS_SETTINGS = ModelDiagnosticSettings.create()
+
+# Operation names
+CHAT_COMPLETION_OPERATION = "chat.completions"
+TEXT_COMPLETION_OPERATION = "text.completions"
+
+# Creates a tracer from the global tracer provider
+tracer = get_tracer(__name__)
+
+
+@experimental_function
+def are_model_diagnostics_enabled() -> bool:
+    """Check if model diagnostics are enabled.
+
+    Model diagnostics are enabled if either diagnostic is enabled or diagnostic with sensitive events is enabled.
+    """
+    return (
+        MODEL_DIAGNOSTICS_SETTINGS.enable_otel_diagnostics
+        or MODEL_DIAGNOSTICS_SETTINGS.enable_otel_diagnostics_sensitive
+    )
+
+
+@experimental_function
+def are_sensitive_events_enabled() -> bool:
+    """Check if sensitive events are enabled.
+
+    Sensitive events are enabled if the diagnostic with sensitive events is enabled.
+    """
+    return MODEL_DIAGNOSTICS_SETTINGS.enable_otel_diagnostics_sensitive
+
+
+@experimental_function
+def trace_chat_completion(model_provider: str) -> Callable:
+    """Decorator to trace chat completion activities.
+
+    Args:
+        model_provider (str): The model provider should describe a family of
+            GenAI models with specific model identified by ai_model_id. For example,
+            model_provider could be "openai" and ai_model_id could be "gpt-3.5-turbo".
+            Sometimes the model provider is unknown at runtime, in which case it can be
+            set to the most specific known provider. For example, while using local models
+            hosted by Ollama, the model provider could be set to "ollama".
+    """
+
+    def inner_trace_chat_completion(completion_func: Callable) -> Callable:
+        @functools.wraps(completion_func)
+        async def wrapper_decorator(*args: Any, **kwargs: Any) -> list[ChatMessageContent]:
+            if not are_model_diagnostics_enabled():
+                # If model diagnostics are not enabled, just return the completion
+                return await completion_func(*args, **kwargs)
+
+            completion_service: ChatCompletionClientBase = args[0]
+            chat_history: ChatHistory = kwargs["chat_history"]
+            settings: PromptExecutionSettings = kwargs["settings"]
+
+            with use_span(
+                _start_completion_activity(
+                    CHAT_COMPLETION_OPERATION,
+                    completion_service.ai_model_id,
+                    model_provider,
+                    chat_history,
+                    settings,
+                ),
+                end_on_exit=True,
+            ) as current_span:
+                try:
+                    completions: list[ChatMessageContent] = await completion_func(*args, **kwargs)
+                    _set_completion_response(current_span, completions)
+                    return completions
+                except Exception as exception:
+                    _set_completion_error(current_span, exception)
+                    raise
+
+        return wrapper_decorator
+
+    return inner_trace_chat_completion
+
+
+@experimental_function
+def trace_text_completion(model_provider: str) -> Callable:
+    """Decorator to trace text completion activities."""
+
+    def inner_trace_text_completion(completion_func: Callable) -> Callable:
+        @functools.wraps(completion_func)
+        async def wrapper_decorator(*args: Any, **kwargs: Any) -> list[TextContent]:
+            if not are_model_diagnostics_enabled():
+                # If model diagnostics are not enabled, just return the completion
+                return await completion_func(*args, **kwargs)
+
+            completion_service: TextCompletionClientBase = args[0]
+            prompt: str = kwargs["prompt"]
+            settings: PromptExecutionSettings = kwargs["settings"]
+
+            with use_span(
+                _start_completion_activity(
+                    TEXT_COMPLETION_OPERATION,
+                    completion_service.ai_model_id,
+                    model_provider,
+                    prompt,
+                    settings,
+                ),
+                end_on_exit=True,
+            ) as current_span:
+                try:
+                    completions: list[TextContent] = await completion_func(*args, **kwargs)
+                    _set_completion_response(current_span, completions)
+                    return completions
+                except Exception as exception:
+                    _set_completion_error(current_span, exception)
+                    raise
+
+        return wrapper_decorator
+
+    return inner_trace_text_completion
+
+
+def _start_completion_activity(
+    operation_name: str,
+    model_name: str,
+    model_provider: str,
+    prompt: str | ChatHistory,
+    execution_settings: PromptExecutionSettings | None,
+) -> Span:
+    """Start a text or chat completion activity for a given model."""
+    span = tracer.start_span(f"{operation_name} {model_name}")
+
+    # Set attributes on the span
+    span.set_attributes({
+        gen_ai_attributes.OPERATION: operation_name,
+        gen_ai_attributes.SYSTEM: model_provider,
+        gen_ai_attributes.MODEL: model_name,
+    })
+
+    # TODO(@glahaye): we'll need to have a way to get these attributes from model
+    # providers other than OpenAI (for example if the attributes are named differently)
+    if execution_settings:
+        attribute = execution_settings.extension_data.get("max_tokens")
+        if attribute:
+            span.set_attribute(gen_ai_attributes.MAX_TOKENS, attribute)
+
+        attribute = execution_settings.extension_data.get("temperature")
+        if attribute:
+            span.set_attribute(gen_ai_attributes.TEMPERATURE, attribute)
+
+        attribute = execution_settings.extension_data.get("top_p")
+        if attribute:
+            span.set_attribute(gen_ai_attributes.TOP_P, attribute)
+
+    if are_sensitive_events_enabled():
+        if isinstance(prompt, ChatHistory):
+            prompt = _messages_to_openai_format(prompt.messages)
+        span.add_event(gen_ai_attributes.PROMPT_EVENT, {gen_ai_attributes.PROMPT_EVENT_PROMPT: prompt})
+
+    return span
+
+
+def _set_completion_response(
+    current_span: Span,
+    completions: list[ChatMessageContent] | list[TextContent],
+) -> None:
+    """Set the a text or chat completion response for a given activity."""
+    first_completion = completions[0]
+
+    # Set the response ID
+    response_id = first_completion.metadata.get("id") or (first_completion.inner_content or {}).get("id")
+    if response_id:
+        current_span.set_attribute(gen_ai_attributes.RESPONSE_ID, response_id)
+
+    # Set the finish reason
+    finish_reasons = [
+        str(completion.finish_reason) for completion in completions if isinstance(completion, ChatMessageContent)
+    ]
+    if finish_reasons:
+        current_span.set_attribute(gen_ai_attributes.FINISH_REASON, ",".join(finish_reasons))
+
+    # Set usage attributes
+    usage = first_completion.metadata.get("usage", None)
+
+    prompt_tokens = getattr(usage, "prompt_tokens", None)
+    if prompt_tokens:
+        current_span.set_attribute(gen_ai_attributes.PROMPT_TOKENS, prompt_tokens)
+
+    completion_tokens = getattr(usage, "completion_tokens", None)
+    if completion_tokens:
+        current_span.set_attribute(gen_ai_attributes.COMPLETION_TOKENS, completion_tokens)
+
+    # Set the completion event
+    if are_sensitive_events_enabled():
+        completion_text: str = _messages_to_openai_format(completions)
+        current_span.add_event(
+            gen_ai_attributes.COMPLETION_EVENT, {gen_ai_attributes.COMPLETION_EVENT_COMPLETION: completion_text}
+        )
+
+
+def _set_completion_error(span: Span, error: Exception) -> None:
+    """Set an error for a text or chat completion ."""
+    span.set_attribute(gen_ai_attributes.ERROR_TYPE, str(type(error)))
+    span.set_status(StatusCode.ERROR, repr(error))
+
+
+def _messages_to_openai_format(messages: list[ChatMessageContent] | list[TextContent]) -> str:
+    """Convert a list of ChatMessageContent to a string in the OpenAI format.
+
+    OpenTelemetry recommends formatting the messages in the OpenAI format
+    regardless of the actual model being used.
+    """
+    return json.dumps([message.to_dict() for message in messages])

semantic_kernel-1.8.3/semantic_kernel/utils/telemetry/model_diagnostics/gen_ai_attributes.py

@@ -0,0 +1,29 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+# Constants for tracing activities with semantic conventions.
+# Ideally, we should use the attributes from the semcov package.
+# However, many of the attributes are not yet available in the package,
+# so we define them here for now.
+
+# Activity tags
+SYSTEM = "gen_ai.system"
+OPERATION = "gen_ai.operation.name"
+MODEL = "gen_ai.request.model"
+MAX_TOKENS = "gen_ai.request.max_tokens"  # nosec
+TEMPERATURE = "gen_ai.request.temperature"
+TOP_P = "gen_ai.request.top_p"
+RESPONSE_ID = "gen_ai.response.id"
+FINISH_REASON = "gen_ai.response.finish_reason"
+PROMPT_TOKENS = "gen_ai.response.prompt_tokens"  # nosec
+COMPLETION_TOKENS = "gen_ai.response.completion_tokens"  # nosec
+ADDRESS = "server.address"
+PORT = "server.port"
+ERROR_TYPE = "error.type"
+
+# Activity events
+PROMPT_EVENT = "gen_ai.content.prompt"
+COMPLETION_EVENT = "gen_ai.content.completion"
+
+# Activity event attributes
+PROMPT_EVENT_PROMPT = "gen_ai.prompt"
+COMPLETION_EVENT_COMPLETION = "gen_ai.completion"

semantic_kernel-1.8.3/semantic_kernel/utils/telemetry/model_diagnostics/model_diagnostics_settings.py

@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import ClassVar
+
+from semantic_kernel.kernel_pydantic import KernelBaseSettings
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+
+@experimental_class
+class ModelDiagnosticSettings(KernelBaseSettings):
+    """Settings for model diagnostics.
+
+    The settings are first loaded from environment variables with
+    the prefix 'AZURE_AI_INFERENCE_'.
+    If the environment variables are not found, the settings can
+    be loaded from a .env file with the encoding 'utf-8'.
+    If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the
+    settings are missing.
+
+    Required settings for prefix 'SEMANTICKERNEL_EXPERIMENTAL_GENAI_' are:
+    - enable_otel_diagnostics: bool - Enable OpenTelemetry diagnostics. Default is False.
+                (Env var SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS)
+    - enable_otel_diagnostics_sensitive: bool - Enable OpenTelemetry sensitive events. Default is False.
+                (Env var SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE)
+    """
+
+    env_prefix: ClassVar[str] = "SEMANTICKERNEL_EXPERIMENTAL_GENAI_"
+
+    enable_otel_diagnostics: bool = False
+    enable_otel_diagnostics_sensitive: bool = False