Principle:Microsoft Semantic kernel Python SDK Package Configuration

Overview

Configuration pattern for defining Python package metadata, dependencies, and build settings for the Semantic Kernel Python SDK. This principle describes how pyproject.toml serves as the single source of truth for package identity, version management, dependency specification, and development tooling configuration, following modern Python packaging standards.

Description

The Semantic Kernel Python SDK uses pyproject.toml as its central configuration file, adhering to PEP 517/518 and PEP 621 standards. This file consolidates all aspects of package configuration into a single, declarative document.

Package Identity and Metadata

The pyproject.toml file defines the package name, description, license, authors, classifiers, and Python version requirements. This metadata is used by package registries (such as PyPI) and by tooling that inspects installed packages.

[project]
name = "semantic-kernel"
description = "Semantic Kernel Python SDK"
license = {file = "LICENSE"}
requires-python = ">=3.10"
authors = [{ name = "Microsoft" }]
classifiers = [
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
]

Dynamic Versioning with Flit

The build system uses flit as the build backend, with the package version managed dynamically. Rather than hard-coding the version in pyproject.toml, flit reads it from the __version__ variable in the package's __init__.py file. This ensures a single source of truth for version numbers and avoids version drift between the source code and package metadata.

[build-system]
requires = ["flit_core>=3.9,<4.0"]
build-backend = "flit_core.api"

[project]
dynamic = ["version"]

Core vs Optional Dependencies

The configuration distinguishes between core dependencies (required for basic functionality) and optional dependency groups (required only for specific connectors or features). This modular approach allows users to install only what they need, keeping the base installation lightweight while supporting a wide ecosystem of AI service connectors.

[project]
dependencies = [
    "aiohttp>=3.8",
    "pydantic>=2.0",
    "numpy>=1.24",
]

[project.optional-dependencies]
openai = ["openai>=1.0"]
azure = ["azure-identity>=1.13", "azure-ai-inference>=1.0"]
hugging_face = ["transformers>=4.28", "sentence-transformers>=2.2"]
chromadb = ["chromadb>=0.4"]

Development Tooling Configuration

The pyproject.toml also centralizes configuration for development tools:

• pytest: Test runner configuration, including test discovery paths, markers, and default options.
• mypy: Static type checking settings, including strictness levels and per-module overrides.
• ruff: Linting and formatting rules, including selected rule sets and file exclusions.

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.mypy]
python_version = "3.10"
strict = true

[tool.ruff]
line-length = 120
target-version = "py310"

Usage

Use this configuration pattern in the following scenarios:

• Setting Up a Development Environment: Clone the repository and run pip install -e .[all] to install the SDK with all optional dependencies for development, or pip install -e .[openai] to install only the OpenAI connector dependencies.
• Contributing to the Project: Understand which dependencies are core versus optional, and add new dependencies to the appropriate section when implementing new connectors.
• Understanding the Dependency Landscape: Review the optional dependency groups to understand which AI providers and vector stores are supported and what libraries each connector requires.
• Building and Publishing: Use flit build or standard PEP 517 build tools to produce distributable packages that correctly reflect all metadata and dependencies.

Theoretical Basis

This configuration pattern is grounded in several Python Enhancement Proposals:

PEP 517/518: Build System Specification

PEP 518 introduced pyproject.toml as the file for declaring build system requirements, and PEP 517 defined a standard interface for build backends. Together, they decouple the build process from any specific tool (such as setuptools), allowing alternative backends like flit to be used. The [build-system] table specifies the backend and its dependencies, enabling reproducible builds across environments.

PEP 621: Project Metadata Standard

PEP 621 standardized the [project] table in pyproject.toml for declaring package metadata. This provides a tool-agnostic way to define package name, version, dependencies, and other metadata, replacing tool-specific configuration formats.

Optional Dependency Groups for Modular Connector Installation

The [project.optional-dependencies] mechanism allows packages to declare named groups of additional dependencies. This supports the Semantic Kernel's connector architecture, where each AI provider or vector store integration has its own set of required libraries. Users install only the connectors they need, reducing dependency conflicts and installation size. This pattern is formally specified in PEP 621 and supported by pip's extras syntax (e.g., pip install semantic-kernel[openai,chromadb]).

Related Pages

• Implementation:Microsoft_Semantic_kernel_Python_Pyproject_Configuration