Core Kernel and Functions

class Kernel:
    """
    The main entry point for Semantic Kernel operations.
    
    Manages AI services, plugins, functions, and execution flow.
    """
    
    def __init__(
        self,
        plugins: KernelPlugin | dict[str, KernelPlugin] | list[KernelPlugin] | None = None,
        services: AI_SERVICE_CLIENT_TYPE | list[AI_SERVICE_CLIENT_TYPE] | dict[str, AI_SERVICE_CLIENT_TYPE] | None = None,
        ai_service_selector: AIServiceSelector | None = None,
        **kwargs
    ):
        """
        Initialize a new Kernel instance.
        
        Parameters:
        - plugins: Plugins to add to the kernel
        - services: AI services to register with the kernel  
        - ai_service_selector: Service selector for choosing AI services
        - **kwargs: Additional configuration options
        """
    
    async def invoke(
        self,
        plugin_name: str | None = None,
        function_name: str | None = None,
        arguments: KernelArguments | None = None,
        **kwargs
    ) -> FunctionResult:
        """
        Invoke a kernel function.
        
        Parameters:
        - plugin_name: Name of the plugin containing the function
        - function_name: Name of the function to invoke
        - arguments: Arguments to pass to the function
        - **kwargs: Additional arguments
        
        Returns:
        FunctionResult containing the execution result
        """
    
    async def invoke_prompt(
        self,
        prompt: str,
        arguments: KernelArguments | None = None,
        template_format: str = "semantic-kernel",
        **kwargs
    ) -> FunctionResult:
        """
        Invoke a prompt-based function.
        
        Parameters:
        - prompt: The prompt string to execute
        - arguments: Arguments for prompt variables
        - template_format: Template format (semantic-kernel, handlebars, jinja2)
        - **kwargs: Additional execution settings
        
        Returns:
        FunctionResult containing the AI response
        """
    
    async def invoke_stream(
        self,
        plugin_name: str | None = None,
        function_name: str | None = None,
        arguments: KernelArguments | None = None,    
        **kwargs
    ):
        """
        Invoke a function with streaming response.
        
        Parameters:
        - plugin_name: Name of the plugin containing the function
        - function_name: Name of the function to invoke
        - arguments: Arguments to pass to the function
        - **kwargs: Additional arguments
        
        Yields:
        Streaming content as it becomes available
        """
    
    def add_service(
        self,
        service: AI_SERVICE_CLIENT_TYPE,
        overwrite: bool = False
    ) -> Kernel:
        """
        Add an AI service to the kernel.
        
        Parameters:
        - service: The AI service instance to add
        - overwrite: Whether to overwrite existing service with same ID
        
        Returns:
        Self for method chaining
        """
    
    def add_plugin(
        self,
        plugin: KernelPlugin | dict | object,
        plugin_name: str | None = None
    ) -> KernelPlugin:
        """
        Add a plugin to the kernel.
        
        Parameters:
        - plugin: Plugin instance, dict of functions, or object with kernel_function methods
        - plugin_name: Name for the plugin (auto-generated if not provided)
        
        Returns:
        The added KernelPlugin instance
        """
    
    def get_plugin(self, plugin_name: str) -> KernelPlugin:
        """
        Get a plugin by name.
        
        Parameters:
        - plugin_name: Name of the plugin to retrieve
        
        Returns:
        The requested KernelPlugin instance
        """
    
    def get_function(self, plugin_name: str, function_name: str) -> KernelFunction:
        """
        Get a function from a plugin.
        
        Parameters:
        - plugin_name: Name of the plugin containing the function
        - function_name: Name of the function to retrieve
        
        Returns:
        The requested KernelFunction instance
        """

@kernel_function
def kernel_function(
    description: str | None = None,
    name: str | None = None
) -> Callable:
    """
    Decorator to convert a Python method into a KernelFunction.
    
    Parameters:
    - description: Description of what the function does
    - name: Name for the function (defaults to method name)
    
    Returns:
    Decorated function that can be used by the kernel
    """

class KernelFunction:
    """
    Represents an executable function in the kernel.
    """
    
    def __init__(
        self,
        function: Callable,
        metadata: KernelFunctionMetadata,
        plugin_name: str | None = None
    ):
        """
        Initialize a KernelFunction.
        
        Parameters:
        - function: The callable Python function
        - metadata: Function metadata including parameters and description
        - plugin_name: Name of the plugin this function belongs to
        """
    
    async def invoke(
        self,
        kernel: Kernel,
        arguments: KernelArguments | None = None
    ) -> FunctionResult:
        """
        Invoke the function with given arguments.
        
        Parameters:
        - kernel: The kernel instance for execution context
        - arguments: Arguments to pass to the function
        
        Returns:
        FunctionResult containing the execution result
        """
    
    @property
    def name(self) -> str:
        """Get the function name."""
    
    @property
    def plugin_name(self) -> str:
        """Get the plugin name this function belongs to."""
    
    @property
    def description(self) -> str:
        """Get the function description."""
    
    @property
    def parameters(self) -> list[KernelParameterMetadata]:
        """Get the function parameter metadata."""

class KernelFunctionFromMethod(KernelFunction):
    """
    A KernelFunction created from a Python method.
    """
    
    def __init__(
        self,
        method: Callable,
        plugin_name: str | None = None,
        function_name: str | None = None,
        description: str | None = None
    ):
        """
        Create a KernelFunction from a Python method.
        
        Parameters:
        - method: The Python method to wrap
        - plugin_name: Name of the plugin this function belongs to
        - function_name: Name for the function (defaults to method name)
        - description: Description of the function
        """

class KernelFunctionFromPrompt(KernelFunction):
    """
    A KernelFunction created from a prompt template.
    """
    
    def __init__(
        self,
        function_name: str,
        plugin_name: str,
        description: str,
        prompt: str,
        template_format: str = "semantic-kernel",
        prompt_execution_settings: PromptExecutionSettings | None = None
    ):
        """
        Create a KernelFunction from a prompt template.
        
        Parameters:
        - function_name: Name of the function
        - plugin_name: Name of the plugin this function belongs to
        - description: Description of the function
        - prompt: The prompt template string
        - template_format: Template format (semantic-kernel, handlebars, jinja2)
        - prompt_execution_settings: Execution settings for the AI service
        """

class KernelPlugin:
    """
    A collection of related kernel functions.
    """
    
    def __init__(
        self,
        name: str,
        description: str | None = None,
        functions: dict[str, KernelFunction] | None = None
    ):
        """
        Initialize a KernelPlugin.
        
        Parameters:
        - name: Name of the plugin
        - description: Description of the plugin's purpose
        - functions: Dictionary of functions in this plugin
        """
    
    def add_function(self, function: KernelFunction) -> None:
        """
        Add a function to this plugin.
        
        Parameters:
        - function: The KernelFunction to add
        """
    
    def get_function(self, function_name: str) -> KernelFunction:
        """
        Get a function by name.
        
        Parameters:
        - function_name: Name of the function to retrieve
        
        Returns:
        The requested KernelFunction
        """
    
    @property
    def name(self) -> str:
        """Get the plugin name."""
    
    @property
    def description(self) -> str:
        """Get the plugin description."""
    
    @property
    def functions(self) -> dict[str, KernelFunction]:
        """Get all functions in this plugin."""

class KernelArguments:
    """
    Arguments container for kernel function invocations.
    """
    
    def __init__(self, **kwargs):
        """
        Initialize KernelArguments with keyword arguments.
        
        Parameters:
        - **kwargs: Named arguments for function invocation
        """
    
    def __getitem__(self, key: str):
        """Get argument value by key."""
    
    def __setitem__(self, key: str, value):
        """Set argument value by key."""
    
    def get(self, key: str, default=None):
        """
        Get argument value with optional default.
        
        Parameters:
        - key: Argument name
        - default: Default value if key not found
        
        Returns:
        Argument value or default
        """

class FunctionResult:
    """
    Container for function execution results.
    """
    
    def __init__(
        self,
        function: KernelFunction,
        value: Any = None,
        metadata: dict | None = None
    ):
        """
        Initialize a FunctionResult.
        
        Parameters:
        - function: The function that was executed
        - value: The result value from function execution
        - metadata: Additional metadata about the execution
        """
    
    @property
    def value(self) -> Any:
        """Get the result value."""
    
    @property
    def metadata(self) -> dict:
        """Get the result metadata."""
    
    def __str__(self) -> str:
        """String representation of the result."""

class KernelFunctionMetadata:
    """
    Metadata describing a kernel function's signature and capabilities.
    """
    
    def __init__(
        self,
        name: str,
        plugin_name: str,
        description: str | None = None,
        parameters: list[KernelParameterMetadata] | None = None,
        return_parameter: KernelParameterMetadata | None = None
    ):
        """
        Initialize function metadata.
        
        Parameters:
        - name: Function name
        - plugin_name: Plugin name containing this function
        - description: Function description
        - parameters: List of parameter metadata
        - return_parameter: Return type metadata
        """
    
    @property
    def name(self) -> str:
        """Get the function name."""
    
    @property
    def plugin_name(self) -> str:
        """Get the plugin name."""
    
    @property
    def description(self) -> str:
        """Get the function description."""
    
    @property
    def parameters(self) -> list[KernelParameterMetadata]:
        """Get the parameter metadata list."""

class KernelParameterMetadata:
    """
    Metadata describing a function parameter.
    """
    
    def __init__(
        self,
        name: str,
        description: str,
        default_value: str | None = None,
        type_: str = "str",
        is_required: bool = True
    ):
        """
        Initialize parameter metadata.
        
        Parameters:
        - name: Parameter name
        - description: Parameter description
        - default_value: Default value if parameter is optional
        - type_: Parameter type as string
        - is_required: Whether parameter is required
        """
    
    @property
    def name(self) -> str:
        """Get the parameter name."""
    
    @property
    def description(self) -> str:
        """Get the parameter description."""
    
    @property
    def default_value(self) -> str | None:
        """Get the default value."""
    
    @property
    def type_(self) -> str:
        """Get the parameter type."""
    
    @property
    def is_required(self) -> bool:
        """Check if parameter is required."""

from semantic_kernel import Kernel
from semantic_kernel.functions import kernel_function

class WeatherPlugin:
    @kernel_function(
        description="Get current weather for a location",
        name="get_weather"
    )
    def get_current_weather(self, location: str, units: str = "fahrenheit") -> str:
        """Get weather information for a location."""
        # Implementation would call actual weather API
        return f"The weather in {location} is 72°{units[0].upper()}"

# Use the plugin
kernel = Kernel()
weather_plugin = WeatherPlugin()
kernel.add_plugin(weather_plugin, plugin_name="weather")

# Invoke the function
result = await kernel.invoke("weather", "get_weather", location="Seattle")
print(result.value)  # "The weather in Seattle is 72°F"

from semantic_kernel.functions import KernelFunctionFromPrompt

# Create a prompt-based function
summarize_function = KernelFunctionFromPrompt(
    function_name="summarize",
    plugin_name="text",
    description="Summarize text content",
    prompt="Summarize the following text in 2-3 sentences: {{$input}}"
)

# Add to kernel and use
kernel.add_plugin({"summarize": summarize_function}, plugin_name="text")
result = await kernel.invoke("text", "summarize", input="Long text to summarize...")