ContextQMD
Back to Semantic Kernel

These are optional elements. Feel free to remove any of them

docs/decisions/0010-dotnet-project-structure.md

latest14.1 KB
Original Source

DotNet Project Structure for 1.0 Release

Context and Problem Statement

  • Provide a cohesive, well-defined set of assemblies that developers can easily combine based on their needs.
    • Semantic Kernel core should only contain functionality related to AI orchestration
      • Remove prompt template engine and semantic functions
    • Semantic Kernel abstractions should only interfaces, abstract classes and minimal classes to support these
  • Remove Skills naming from NuGet packages and replace with Plugins
    • Clearly distinguish between plugin implementations (Skills.MsGraph) and plugin integration (Skills.OpenAPI)
  • Have consistent naming for assemblies and their root namespaces

Decision Drivers

Considered Options

  • Option #1: New planning, functions and plugins project areas
  • Option #2: Folder naming matches assembly name

In all cases the following changes will be made:

  • Move non core Connectors to a separate repository
  • Merge prompt template engine and semantic functions into a single package

Decision Outcome

Chosen option: Option #2: Folder naming matches assembly name, because:

  1. It provides a way for developers to easily discover where code for a particular assembly is located
  2. It is consistent with other e.g., azure-sdk-for-net

Main categories for the projects will be:

  1. Connectors: A connector project allows the Semantic Kernel to connect to AI and Memory services. Some of the existing connector projects may move to other repositories.
  2. Planners: A planner project provides one or more planner implementations which take an ask and convert it into an executable plan to achieve that ask. This category will include the current action, sequential and stepwise planners (these could be merged into a single project). Additional planning implementations e.g., planners that generate Powershell or Python code can be added as separate projects.
  3. Functions: A function project that enables the Semantic Kernel to access the functions it will orchestrate. This category will include:
    1. Semantic functions i.e., prompts executed against an LLM
    2. GRPC remote procedures i.e., procedures executed remotely using the GRPC framework
    3. Open API endpoints i.e., REST endpoints that have Open API definitions executed remotely using the HTTP protocol
  4. Plugins: A plugin project contains the implementation(s) of a Semantic Kernel plugin. A Semantic Kernel plugin is contains a concrete implementation of a function e.g., a plugin may include code for basic text operations.

Option #1: New planning, functions and plugins project areas

text
SK-dotnet
├── samples/
└── src/
    ├── connectors/
    │   ├── Connectors.AI.OpenAI*
    │   ├── Connectors.AI.HuggingFace
    │   ├── Connectors.Memory.AzureCognitiveSearch
    │   ├── Connectors.Memory.Qdrant
    │   ├── ...
    │   └── Connectors.UnitTests
    ├── planners/
    │   ├── Planners.Action*
    │   ├── Planners.Sequential*
    │   └── Planners.Stepwise*
    ├── functions/
    │   ├── Functions.Native*
    │   ├── Functions.Semantic*
    │   ├── Functions.Planning*
    │   ├── Functions.Grpc
    │   ├── Functions.OpenAPI
    │   └── Functions.UnitTests
    ├── plugins/
    │   ├── Plugins.Core*
    │   ├── Plugins.Document
    │   ├── Plugins.MsGraph
    │   ├── Plugins.WebSearch
    │   └── Plugins.UnitTests
    ├── InternalUtilities/
    ├── IntegrationTests
    ├── SemanticKernel*
    ├── SemanticKernel.Abstractions*
    ├── SemanticKernel.MetaPackage
    └── SemanticKernel.UnitTests

Changes

ProjectDescription
Functions.NativeExtract native functions from Semantic Kernel core and abstractions.
Functions.SemanticExtract semantic functions from Semantic Kernel core and abstractions. Include the prompt template engine.
Functions.PlanningExtract planning from Semantic Kernel core and abstractions.
Functions.GrpcOld Skills.Grpc project
Functions.OpenAPIOld Skills.OpenAPI project
Plugins.CoreOld Skills.Core project
Plugins.DocumentOld Skills.Document project
Plugins.MsGraphOld Skills.MsGraph project
Plugins.WebSearchOld Skills.WebSearch project

Semantic Kernel Skills and Functions

This diagram how functions and plugins would be integrated with the Semantic Kernel core.

Option #2: Folder naming matches assembly name

text
SK-dotnet
├── samples/
└── libraries/
    ├── SK-dotnet.sln
    │
    ├── Microsoft.SemanticKernel.Connectors.AI.OpenAI*
    │   ├── src
    │   └── tests
    │ (Not shown but all projects will have src and tests subfolders)
    ├── Microsoft.SemanticKernel.Connectors.AI.HuggingFace
    ├── Microsoft.SemanticKernel.Connectors.Memory.AzureCognitiveSearch
    ├── Microsoft.SemanticKernel.Connectors.Memory.Qdrant
    │
    ├── Microsoft.SemanticKernel.Planners*
    │
    ├── Microsoft.SemanticKernel.Reliability.Basic*
    ├── Microsoft.SemanticKernel.Reliability.Polly
    │
    ├── Microsoft.SemanticKernel.TemplateEngines.Basic*
    │
    ├── Microsoft.SemanticKernel.Functions.Semantic*
    ├── Microsoft.SemanticKernel.Functions.Grpc
    ├── Microsoft.SemanticKernel.Functions.OpenAPI
    │
    ├── Microsoft.SemanticKernel.Plugins.Core*
    ├── Microsoft.SemanticKernel.Plugins.Document
    ├── Microsoft.SemanticKernel.Plugins.MsGraph
    ├── Microsoft.SemanticKernel.Plugins.Web
    │
    ├── InternalUtilities
    │
    ├── IntegrationTests
    │
    ├── Microsoft.SemanticKernel.Core*
    ├── Microsoft.SemanticKernel.Abstractions*
    └── Microsoft.SemanticKernel.MetaPackage

Notes:

  • There will only be a single solution file (initially).
  • Projects will be grouped in the solution i.e., connectors, planners, plugins, functions, extensions, ...
  • Each project folder contains a src and tests folder.
  • There will be a gradual process to move existing unit tests to the correct location as some projects will need to be broken up.

More Information

Current Project Structure

text
SK-dotnet
├── samples/
└── src/
    ├── connectors/
    │   ├── Connectors.AI.OpenAI*
    │   ├── Connectors...
    │   └── Connectors.UnitTests
    ├── extensions/
    │   ├── Planner.ActionPlanner*
    │   ├── Planner.SequentialPlanner*
    │   ├── Planner.StepwisePlanner
    │   ├── TemplateEngine.PromptTemplateEngine*
    │   └── Extensions.UnitTests
    ├── InternalUtilities/
    ├── skills/
    │   ├── Skills.Core
    │   ├── Skills.Document
    │   ├── Skills.Grpc
    │   ├── Skills.MsGraph
    │   ├── Skills.OpenAPI
    │   ├── Skills.Web
    │   └── Skills.UnitTests
    ├── IntegrationTests
    ├── SemanticKernel*
    ├── SemanticKernel.Abstractions*
    ├── SemanticKernel.MetaPackage
    └── SemanticKernel.UnitTests

\* - Means the project is part of the Semantic Kernel meta package

Project Descriptions

ProjectDescription
Connectors.AI.OpenAIAzure OpenAI and OpenAI service connectors
Connectors...Collection of other AI service connectors, some of which will move to another repository
Connectors.UnitTestsConnector unit tests
Planner.ActionPlannerSemantic Kernel implementation of an action planner
Planner.SequentialPlannerSemantic Kernel implementation of a sequential planner
Planner.StepwisePlannerSemantic Kernel implementation of a stepwise planner
TemplateEngine.BasicPrompt template engine basic implementations which are used by Semantic Functions only
Extensions.UnitTestsExtensions unit tests
InternalUtilitiesInternal utilities which are reused by multiple NuGet packages (all internal)
Skills.CoreCore set of native functions which are provided to support Semantic Functions
Skills.DocumentNative functions for interacting with Microsoft documents
Skills.GrpcSemantic Kernel integration for GRPC based endpoints
Skills.MsGraphNative functions for interacting with Microsoft Graph endpoints
Skills.OpenAPISemantic Kernel integration for OpenAI endpoints and reference Azure Key Vault implementation
Skills.WebNative functions for interacting with Web endpoints e.g., Bing, Google, File download
Skills.UnitTestsSkills unit tests
IntegrationTestsSemantic Kernel integration tests
SemanticKernelSemantic Kernel core implementation
SemanticKernel.AbstractionsSemantic Kernel abstractions i.e., interface, abstract classes, supporting classes, ...
SemanticKernel.MetaPackageSemantic Kernel meta package i.e., a NuGet package that references other required Semantic Kernel NuGet packages
SemanticKernel.UnitTestsSemantic Kernel unit tests

Naming Patterns

Below are some different examples of Assembly and root namespace naming that are used in the projects.

xml
    <AssemblyName>Microsoft.SemanticKernel.Abstractions</AssemblyName>
    <RootNamespace>Microsoft.SemanticKernel</RootNamespace>

    <AssemblyName>Microsoft.SemanticKernel.Core</AssemblyName>
    <RootNamespace>Microsoft.SemanticKernel</RootNamespace>

    <AssemblyName>Microsoft.SemanticKernel.Planning.ActionPlanner</AssemblyName>
    <RootNamespace>Microsoft.SemanticKernel.Planning.Action</RootNamespace>

    <AssemblyName>Microsoft.SemanticKernel.Skills.Core</AssemblyName>
    <RootNamespace>$(AssemblyName)</RootNamespace>

Current Folder Structure

text
dotnet/
├── samples/
│   ├── ApplicationInsightsExample/
│   ├── KernelSyntaxExamples/
│   └── NCalcSkills/
└── src/
    ├── Connectors/
    │   ├── Connectors.AI.OpenAI*
    │   ├── Connectors...
    │   └── Connectors.UnitTests
    ├── Extensions/
    │   ├── Planner.ActionPlanner
    │   ├── Planner.SequentialPlanner
    │   ├── Planner.StepwisePlanner
    │   ├── TemplateEngine.PromptTemplateEngine
    │   └── Extensions.UnitTests
    ├── InternalUtilities/
    ├── Skills/
    │   ├── Skills.Core
    │   ├── Skills.Document
    │   ├── Skills.Grpc
    │   ├── Skills.MsGraph
    │   ├── Skills.OpenAPI
    │   ├── Skills.Web
    │   └── Skills.UnitTests
    ├── IntegrationTests/
    ├── SemanticKernel/
    ├── SemanticKerne.Abstractions/
    ├── SemanticKernel.MetaPackage/
    └── SemanticKernel.UnitTests/

Semantic Kernel Skills and Functions

This diagram show current skills are integrated with the Semantic Kernel core.

Note:

  • This is not a true class hierarchy diagram. It show some class relationships and dependencies.
  • Namespaces are abbreviated to remove Microsoft.SemanticKernel prefix. Namespaces use _ rather than ..