Lambdua · Lambdua · May 11, 2024 · May 10, 2024 · May 10, 2024 · May 10, 2024
diff --git a/.github/release.yml b/.github/release.yml
@@ -0,0 +1,23 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+  categories:
+    - title: 🏕 Features
+      labels:
+        - enhancement
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+    - title: 👋 Deprecated
+      labels:
+        - deprecation
+    - title: 📄 documentation
+      labels:
+        - documentation
+    - title: 👒 Dependencies
+      labels:
+        - dependencies
+    - title: 'Other Changes'
+      labels:
+        - "*"
diff --git a/README-zh.md b/README-zh.md
diff --git a/README.md b/README.md
diff --git a/api/pom.xml b/api/pom.xml
@@ -33,6 +33,17 @@
             <artifactId>jtokkit</artifactId>
             <version>0.5.1</version>
         </dependency>
+        <dependency>
+            <groupId>com.kjetland</groupId>
+            <artifactId>mbknor-jackson-jsonschema_2.12</artifactId>
+            <version>1.0.39</version>
+            <exclusions>
+                <exclusion>
+                    <artifactId>jackson-databind</artifactId>
+                    <groupId>com.fasterxml.jackson.core</groupId>
+                </exclusion>
+            </exclusions>
+        </dependency>
     </dependencies>
 
 </project>
diff --git a/api/src/main/java/com/theokanning/openai/assistants/assistant/AssistantFunction.java b/api/src/main/java/com/theokanning/openai/assistants/assistant/AssistantFunction.java
diff --git a/api/src/main/java/com/theokanning/openai/assistants/assistant/FunctionTool.java b/api/src/main/java/com/theokanning/openai/assistants/assistant/FunctionTool.java
@@ -16,6 +16,9 @@ public class FunctionTool implements Tool {
 
     /**
      * Function definition, only used if type is "function"
+     * recommend to use {@link com.theokanning.openai.function.FunctionDefinition}  or custom class
+     *
+     * @since 0.20.5 {@link com.theokanning.openai.completion.chat.ChatFunction} {@link  com.theokanning.openai.completion.chat.ChatFunctionDynamic}will be deprecated
      */
     Object function;
 }
diff --git a/api/src/main/java/com/theokanning/openai/assistants/run/ToolCall.java b/api/src/main/java/com/theokanning/openai/assistants/run/ToolCall.java
@@ -20,6 +20,7 @@
 @NoArgsConstructor
 @AllArgsConstructor
 public class ToolCall {
+
     //may be need     @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
     Integer index;
 

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/ChatCompletionRequest.java b/api/src/main/java/com/theokanning/openai/completion/chat/ChatCompletionRequest.java
@@ -114,7 +114,9 @@ public class ChatCompletionRequest {
     String user;
 
     /**
-     * A list of the available functions.
+     * @deprecated Replaced by {@link #tools}
+     * recommend to use {@link com.theokanning.openai.function.FunctionDefinition}  or custom class
+     * @since 0.20.5 {@link com.theokanning.openai.completion.chat.ChatFunction} {@link  com.theokanning.openai.completion.chat.ChatFunctionDynamic}will be deprecated
      */
     @Deprecated
     List<?> functions;
@@ -146,8 +148,12 @@ public class ChatCompletionRequest {
     Integer topLogprobs;
 
 
+
     /**
-     * A list of tools the model may call. Currently, only functions are supported as a tool.
+     * Function definition, only used if type is "function"
+     * recommend to use {@link com.theokanning.openai.function.FunctionDefinition}  or custom class
+     *
+     * @since 0.20.5 {@link com.theokanning.openai.completion.chat.ChatFunction} {@link  com.theokanning.openai.completion.chat.ChatFunctionDynamic}will be deprecated
      */
     List<ChatTool> tools;
 

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunction.java b/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunction.java
@@ -8,8 +8,13 @@
 
 import java.util.function.Function;
 
+/**
+ * @deprecated This class is no longer used and will be removed in a future release.
+ * Please use {@link com.theokanning.openai.function.FunctionDefinition} instead.
+ */
 @Data
 @NoArgsConstructor
+@Deprecated
 public class ChatFunction {
 
     /**
@@ -29,6 +34,7 @@ public class ChatFunction {
     @JsonProperty("parameters")
     private Class<?> parametersClass;
 
+
     @JsonIgnore
     private Function<Object, Object> executor;
 

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunctionDynamic.java b/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunctionDynamic.java
@@ -4,7 +4,13 @@
 import lombok.NonNull;
 
 
+/**
+ * @deprecated function json schema(https://json-schema.org/understanding-json-schema/reference) 十分复杂,很多属性都是可选的,维护这个类会变得异常复杂,目前仅仅只是支持了很简单的属性,肯定无法满足更多灵活的function定义.<br>
+ * 现在推荐使用{@link  ChatFunction}来定义function
+ *
+ */
 @Data
+@Deprecated
 public class ChatFunctionDynamic {
 
     /**

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunctionParameters.java b/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunctionParameters.java
@@ -6,7 +6,12 @@
 import java.util.HashMap;
 import java.util.List;
 
+/**
+ * @deprecated function json schema(https://json-schema.org/understanding-json-schema/reference) 十分复杂,很多属性都是可选的,维护会变得异常复杂,目前仅仅只是支持了很简单的属性,肯定无法满足更多灵活的function定义.<br>
+ * 并且将这个类放在了错误的包下,应该放在service包下.<br>
+ */
 @Data
+@Deprecated
 public class ChatFunctionParameters {
 
     private final String type = "object";

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunctionProperty.java b/api/src/main/java/com/theokanning/openai/completion/chat/ChatFunctionProperty.java
@@ -18,6 +18,7 @@ public class ChatFunctionProperty {
     private String type;
     @JsonIgnore
     private Boolean required;
+
     private String description;
 
     private ChatFunctionParameters items;

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/ChatTool.java b/api/src/main/java/com/theokanning/openai/completion/chat/ChatTool.java
@@ -1,15 +1,17 @@
 package com.theokanning.openai.completion.chat;
 
+import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import lombok.NonNull;
 
 @Data
 @NoArgsConstructor
+@AllArgsConstructor
 public class ChatTool {
-
-    @NonNull
-    private Object function;
+    public ChatTool(@NonNull Object function) {
+        this.function = function;
+    }
 
     /**
      * The name of the tool being called, only function supported for now.
@@ -18,8 +20,14 @@ public class ChatTool {
     private String type = "function";
 
 
-    public ChatTool(@NonNull Object function) {
-        this.function = function;
-    }
+    /**
+     * recommend use {@link com.theokanning.openai.function.FunctionDefinition} .
+     * also you can customer your own function
+     */
+    @NonNull
+    private Object function;
+
+
+
 
 }
diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/FunctionMessage.java b/api/src/main/java/com/theokanning/openai/completion/chat/FunctionMessage.java
@@ -5,11 +5,13 @@
 import lombok.NoArgsConstructor;
 
 /**
+ * @deprecated see {@link ToolMessage}
  * @author LiangTao
  * @date 2024年04月10 10:37
  **/
 @Data
 @NoArgsConstructor
+@Deprecated
 public class FunctionMessage implements ChatMessage {
     private final String role = ChatMessageRole.FUNCTION.value();
 

diff --git a/api/src/main/java/com/theokanning/openai/completion/chat/StreamOption.java b/api/src/main/java/com/theokanning/openai/completion/chat/StreamOption.java
@@ -1,13 +1,17 @@
 package com.theokanning.openai.completion.chat;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
 import lombok.Data;
+import lombok.NoArgsConstructor;
 
 /**
  * @author LiangTao
  * @date 2024年05月07 22:46
  **/
 @Data
+@NoArgsConstructor
+@AllArgsConstructor
 public class StreamOption {
 
     public static final StreamOption INCLUDE = new StreamOption(true);
@@ -21,7 +25,4 @@ public class StreamOption {
     @JsonProperty("include_usage")
     Boolean includeUsage;
 
-    private StreamOption(Boolean includeUsage) {
-        this.includeUsage = includeUsage;
-    }
 }
diff --git a/api/src/main/java/com/theokanning/openai/function/FunctionDefinition.java b/api/src/main/java/com/theokanning/openai/function/FunctionDefinition.java
@@ -0,0 +1,112 @@
+package com.theokanning.openai.function;
+
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.kjetland.jackson.jsonSchema.JsonSchemaGenerator;
+import lombok.Getter;
+import lombok.NonNull;
+
+import java.util.function.Function;
+
+/**
+ * @author LiangTao
+ * @date 2024年05月10 11:15
+ **/
+@JsonSerialize(using = FunctionParametersSerializer.class)
+@Getter
+public class FunctionDefinition {
+
+    /**
+     * not allow to create instance by constructor
+     */
+    private FunctionDefinition() {
+
+    }
+
+    /**
+     * The name of the function being called.
+     */
+    @NonNull
+    protected String name;
+
+    /**
+     * A description of what the function does, used by the model to choose when and how to call the function.
+     */
+    private String description;
+
+    /**
+     * parameters definition by class schema ,will use {@link JsonSchemaGenerator} to generate json schema
+     */
+    private Class<?> parametersDefinitionClass;
+
+    /**
+     * The parameters the functions accepts.Choose between this parameter and {@link #parametersDefinitionClass}
+     **/
+    private Object parametersDefinition;
+
+    /**
+     * Function executor,if set {@link #parametersDefinitionClass},the executor type must {@link #parametersDefinitionClass}. <br>
+     * Else executor parameter type must {@link #parametersDefinition} JsonNode type
+     * 可以为null
+     */
+    private Function<Object, Object> executor;
+
+    public static <T> FunctionDefinition.Builder<T> builder() {
+        return new FunctionDefinition.Builder<>();
+    }
+
+    public static class Builder<T> {
+        private String name;
+        private String description;
+        private Class<T> parametersDefinitionClass;
+
+        private T parametersDefinition;
+
+        private Function<T, Object> executor;
+
+        public FunctionDefinition.Builder<T> name(String name) {
+            this.name = name;
+            return this;
+        }
+
+        public FunctionDefinition.Builder<T> description(String description) {
+            this.description = description;
+            return this;
+        }
+
+        public FunctionDefinition.Builder<T> parametersDefinition(T parametersDefinition) {
+            this.parametersDefinition = parametersDefinition;
+            return this;
+        }
+
+        public FunctionDefinition.Builder<T> parametersDefinitionByClass(Class<T> parametersDefinitionClass) {
+            this.parametersDefinitionClass = parametersDefinitionClass;
+            return this;
+        }
+
+        public FunctionDefinition.Builder<T> executor(Function<T, Object> executor) {
+            this.executor = executor;
+            return this;
+        }
+
+
+        @SuppressWarnings("unchecked")
+        public FunctionDefinition build() {
+            if (name == null) {
+                throw new IllegalArgumentException("name can't be null");
+            }
+            if (parametersDefinitionClass == null && parametersDefinition == null) {
+                throw new IllegalArgumentException("parametersDefinitionClass and parametersDefinition can't be null at the same time,please set one of them");
+            }
+            if (parametersDefinition != null && parametersDefinitionClass != null) {
+                throw new IllegalArgumentException("parametersDefinitionClass and parametersDefinition can't be set at the same time,please set one of them");
+            }
+            FunctionDefinition functionDefinition = new FunctionDefinition();
+            functionDefinition.name = name;
+            functionDefinition.description = description;
+            functionDefinition.parametersDefinitionClass = parametersDefinitionClass;
+            functionDefinition.parametersDefinition = parametersDefinition;
+            functionDefinition.executor = (Function<Object, Object>) executor;
+            return functionDefinition;
+        }
+    }
+}