Skip to content

Latest commit

 

History

History
106 lines (88 loc) · 5.07 KB

0002-java-folder-structure.md

File metadata and controls

106 lines (88 loc) · 5.07 KB
status date deciders consulted informed
accepted
2013-06-19
shawncal,johnoliver

Java Folder Structure

Context and Problem Statement

A port of the Semantic Kernel to Java is under development in the experimental-java branch. The folder structure being used has diverged from the .Net implementation. The purpose of this ADR is to document the folder structure that will be used by the Java port to make it clear to developers how to navigate between the .Net and Java implementations.

Decision Drivers

  • Goal is to learn for SDKs that already have excellent multiple language support e.g., Azure SDK
  • The Java SK should follow the general design guidelines and conventions of Java. It should feel natural to a Java developer.
  • Different language versions should be consistent with the .Net implementation. In cases of conflict, consistency with Java conventions is the highest priority.
  • The SK for Java and .Net should feel like a single product developed by a single team.
  • There should be feature parity between Java and .Net. Feature status must be tracked in the FEATURE_MATRIX

Considered Options

Below is a comparison of .Net and Java Folder structures

dotnet/src
           Connectors
           Extensions
           IntegrationTests
           InternalUtilities
           SemanticKernel.Abstractions
           SemanticKernel.MetaPackage
           SemanticKernel.UnitTests
           SemanticKernel
           Skills
Folder Description
Connectors Parent folder for various Connector implementations e.g., AI or Memory services
Extensions Parent folder for SK extensions e.g., planner implementations
IntegrationTests Integration tests
InternalUtilities Internal utilities i.e., shared code
SemanticKernel.Abstractions SK API definitions
SemanticKernel.MetaPackage SK common package collection
SemanticKernel.UnitTests Unit tests
SemanticKernel SK implementation
Skills Parent folder for various Skills implementations e.g., Core, MS Graph, GRPC, OpenAI, ...

Some observations:

  • The src folder is at the very start of the folder structure, which reduces flexibility
  • The use of the Skills term is due to change
java
     api-test
     samples
     semantickernel-api
     semantickernel-bom
     semantickernel-connectors-parent
     semantickernel-core-skills
     semantickernel-core
     semantickernel-extensions-parent
Folder Description
api-test Integration tests and API usage example
samples SK samples
semantickernel-api SK API definitions
semantickernel-bom SK Bill Of Materials
semantickernel-connectors-parent Parent folder for various Connector implementations
semantickernel-core-skills SK core skills (in .Net these are part of the core implementation)
semantickernel-core SK core implementation
semantickernel-extensions-parent Parent folder for SK extensions e.g., planner implementation

Some observations:

  • Using lowercase folder name with the - delimiter is idiomatic Java
  • The src folders are located as close as possible to the source files e.g., semantickernel-api/src/main/java, this is idiomatic Java
  • Unit tests are contained together with the implementation
  • The samples are located within the java folder and each sample runs standalone

Decision Outcome

Follow these guidelines:

  • The folder names will match those used (or planned for .Net) but in the idiomatic Java folder naming convention
  • Use bom instead of MetaPackage as the latter is .Net centric
  • Use api instead of Abstractions as the latter is .Net centric
  • Move semantickernel-core-skills to a new plugins folder and rename to plugins-core
  • Use the term plugins instead of skills and avoid introducing technical debt
Folder Description
connectors Containing: semantickernel-connectors-ai-openai, semantickernel-connectors-ai-huggingface, semantickernel-connectors-memory-qadrant, ...
extensions Containing: semantickernel-planning-action-planner, semantickernel-planning-sequential-planner
integration-tests Integration tests
semantickernel-api SK API definitions
semantickernel-bom SK common package collection
semantickernel-core SK core implementation
plugins Containing: semantickernel-plugins-core, semantickernel-plugins-document, semantickernel-plugins-msgraph, ...