feat: add AI agents warnings; allow for more types of metadata value (box/box-openapi#520) (#435)

Co-authored-by: box-sdk-build <[email protected]>

Author: box-sdk-build

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "42b7a5b", "specHash": "f737b7b", "version": "0.6.1" }
+{ "engineHash": "c2a365c", "specHash": "6a332e7", "version": "0.6.1" }

BoxSdkGen.xcodeproj/project.pbxproj

@@ -21,16 +21,7 @@ public class UpdateFileMetadataByIdRequestBody: Codable {
     /// characters and must be escaped in the key.
     public let path: String?
 
-    /// The value to be set or tested.
-    /// 
-    /// Required for `add`, `replace`, and `test` operations. For `add`,
-    /// if the value exists already the previous value will be overwritten
-    /// by the new value. For `replace`, the value must exist before
-    /// replacing.
-    /// 
-    /// For `test`, the existing value at the `path` location must match
-    /// the specified value.
-    public let value: String?
+    public let value: MetadataInstanceValue?
 
     /// The location in the metadata JSON object to move or copy a value
     /// from. Required for `move` or `copy` operations and must be in the
@@ -49,19 +40,11 @@ public class UpdateFileMetadataByIdRequestBody: Codable {
     ///     The path must always be prefixed with a `/` to represent the root
     ///     of the template. The characters `~` and `/` are reserved
     ///     characters and must be escaped in the key.
-    ///   - value: The value to be set or tested.
-    ///     
-    ///     Required for `add`, `replace`, and `test` operations. For `add`,
-    ///     if the value exists already the previous value will be overwritten
-    ///     by the new value. For `replace`, the value must exist before
-    ///     replacing.
-    ///     
-    ///     For `test`, the existing value at the `path` location must match
-    ///     the specified value.
+    ///   - value: 
     ///   - from: The location in the metadata JSON object to move or copy a value
     ///     from. Required for `move` or `copy` operations and must be in the
     ///     format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).
-    public init(op: UpdateFileMetadataByIdRequestBodyOpField? = nil, path: String? = nil, value: String? = nil, from: String? = nil) {
+    public init(op: UpdateFileMetadataByIdRequestBodyOpField? = nil, path: String? = nil, value: MetadataInstanceValue? = nil, from: String? = nil) {
         self.op = op
         self.path = path
         self.value = value
@@ -72,7 +55,7 @@ public class UpdateFileMetadataByIdRequestBody: Codable {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         op = try container.decodeIfPresent(UpdateFileMetadataByIdRequestBodyOpField.self, forKey: .op)
         path = try container.decodeIfPresent(String.self, forKey: .path)
-        value = try container.decodeIfPresent(String.self, forKey: .value)
+        value = try container.decodeIfPresent(MetadataInstanceValue.self, forKey: .value)
         from = try container.decodeIfPresent(String.self, forKey: .from)
     }
 

Sources/Managers/FileMetadata/UpdateFileMetadataByIdRequestBody.swift

@@ -21,16 +21,7 @@ public class UpdateFolderMetadataByIdRequestBody: Codable {
     /// characters and must be escaped in the key.
     public let path: String?
 
-    /// The value to be set or tested.
-    /// 
-    /// Required for `add`, `replace`, and `test` operations. For `add`,
-    /// if the value exists already the previous value will be overwritten
-    /// by the new value. For `replace`, the value must exist before
-    /// replacing.
-    /// 
-    /// For `test`, the existing value at the `path` location must match
-    /// the specified value.
-    public let value: String?
+    public let value: MetadataInstanceValue?
 
     /// The location in the metadata JSON object to move or copy a value
     /// from. Required for `move` or `copy` operations and must be in the
@@ -49,19 +40,11 @@ public class UpdateFolderMetadataByIdRequestBody: Codable {
     ///     The path must always be prefixed with a `/` to represent the root
     ///     of the template. The characters `~` and `/` are reserved
     ///     characters and must be escaped in the key.
-    ///   - value: The value to be set or tested.
-    ///     
-    ///     Required for `add`, `replace`, and `test` operations. For `add`,
-    ///     if the value exists already the previous value will be overwritten
-    ///     by the new value. For `replace`, the value must exist before
-    ///     replacing.
-    ///     
-    ///     For `test`, the existing value at the `path` location must match
-    ///     the specified value.
+    ///   - value: 
     ///   - from: The location in the metadata JSON object to move or copy a value
     ///     from. Required for `move` or `copy` operations and must be in the
     ///     format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).
-    public init(op: UpdateFolderMetadataByIdRequestBodyOpField? = nil, path: String? = nil, value: String? = nil, from: String? = nil) {
+    public init(op: UpdateFolderMetadataByIdRequestBodyOpField? = nil, path: String? = nil, value: MetadataInstanceValue? = nil, from: String? = nil) {
         self.op = op
         self.path = path
         self.value = value
@@ -72,7 +55,7 @@ public class UpdateFolderMetadataByIdRequestBody: Codable {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         op = try container.decodeIfPresent(UpdateFolderMetadataByIdRequestBodyOpField.self, forKey: .op)
         path = try container.decodeIfPresent(String.self, forKey: .path)
-        value = try container.decodeIfPresent(String.self, forKey: .value)
+        value = try container.decodeIfPresent(MetadataInstanceValue.self, forKey: .value)
         from = try container.decodeIfPresent(String.self, forKey: .from)
     }
 

Sources/Managers/FolderMetadata/UpdateFolderMetadataByIdRequestBody.swift

@@ -23,8 +23,9 @@ public class TransferManager {
     /// file-level are transferred during the operation, the collaborations are
     /// deleted when the original user is deleted.
     /// 
-    /// This call will be performed synchronously which might lead to a slow response
-    /// when the source user has a large number of items in all of its folders.
+    /// If the user has a large number of items across all folders, the call will
+    /// be run asynchronously. If the operation is not completed within 10 minutes,
+    /// the user will receive a 200 OK response, and the operation will continue running.
     /// 
     /// If the destination path has a metadata cascade policy attached to any of
     /// the parent folders, a metadata cascade operation will be kicked off

Sources/Managers/Transfer/TransferManager.swift

@@ -8,11 +8,11 @@ public class AiSingleAgentResponseFull: AiSingleAgentResponse {
         case extract
     }
 
-    public let ask: AiStudioAgentAsk?
+    public let ask: AiStudioAgentAskResponse?
 
-    public let textGen: AiStudioAgentTextGen?
+    public let textGen: AiStudioAgentTextGenResponse?
 
-    public let extract: AiStudioAgentExtract?
+    public let extract: AiStudioAgentExtractResponse?
 
     /// Initializer for a AiSingleAgentResponseFull.
     ///
@@ -31,7 +31,7 @@ public class AiSingleAgentResponseFull: AiSingleAgentResponse {
     ///   - ask: 
     ///   - textGen: 
     ///   - extract: 
-    public init(id: String, origin: String, name: String, accessState: String, type: AiSingleAgentResponseTypeField? = nil, createdBy: UserBase? = nil, createdAt: Date? = nil, modifiedBy: UserBase? = nil, modifiedAt: Date? = nil, iconReference: String? = nil, allowedEntities: [AiAgentAllowedEntity]? = nil, ask: AiStudioAgentAsk? = nil, textGen: AiStudioAgentTextGen? = nil, extract: AiStudioAgentExtract? = nil) {
+    public init(id: String, origin: String, name: String, accessState: String, type: AiSingleAgentResponseTypeField? = nil, createdBy: UserBase? = nil, createdAt: Date? = nil, modifiedBy: UserBase? = nil, modifiedAt: Date? = nil, iconReference: String? = nil, allowedEntities: [AiAgentAllowedEntity]? = nil, ask: AiStudioAgentAskResponse? = nil, textGen: AiStudioAgentTextGenResponse? = nil, extract: AiStudioAgentExtractResponse? = nil) {
         self.ask = ask
         self.textGen = textGen
         self.extract = extract
@@ -41,9 +41,9 @@ public class AiSingleAgentResponseFull: AiSingleAgentResponse {
 
     required public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
-        ask = try container.decodeIfPresent(AiStudioAgentAsk.self, forKey: .ask)
-        textGen = try container.decodeIfPresent(AiStudioAgentTextGen.self, forKey: .textGen)
-        extract = try container.decodeIfPresent(AiStudioAgentExtract.self, forKey: .extract)
+        ask = try container.decodeIfPresent(AiStudioAgentAskResponse.self, forKey: .ask)
+        textGen = try container.decodeIfPresent(AiStudioAgentTextGenResponse.self, forKey: .textGen)
+        extract = try container.decodeIfPresent(AiStudioAgentExtractResponse.self, forKey: .extract)
 
         try super.init(from: decoder)
     }

Sources/Schemas/AiSingleAgentResponseFull/AiSingleAgentResponseFull.swift

@@ -0,0 +1,82 @@
+import Foundation
+
+/// The AI Agent to be used for ask.
+public class AiStudioAgentAskResponse: Codable {
+    private enum CodingKeys: String, CodingKey {
+        case accessState = "access_state"
+        case description
+        case type
+        case customInstructions = "custom_instructions"
+        case longText = "long_text"
+        case basicText = "basic_text"
+        case longTextMulti = "long_text_multi"
+        case basicTextMulti = "basic_text_multi"
+    }
+
+    /// The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.
+    public let accessState: String
+
+    /// The description of the AI Agent.
+    public let description: String
+
+    /// The type of AI agent used to handle queries.
+    public let type: AiStudioAgentAskResponseTypeField
+
+    /// Custom instructions for the agent.
+    @CodableTriState public private(set) var customInstructions: String?
+
+    public let longText: AiStudioAgentLongTextToolResponse?
+
+    public let basicText: AiStudioAgentBasicTextToolResponse?
+
+    public let longTextMulti: AiStudioAgentLongTextToolResponse?
+
+    public let basicTextMulti: AiStudioAgentBasicTextToolResponse?
+
+    /// Initializer for a AiStudioAgentAskResponse.
+    ///
+    /// - Parameters:
+    ///   - accessState: The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.
+    ///   - description: The description of the AI Agent.
+    ///   - type: The type of AI agent used to handle queries.
+    ///   - customInstructions: Custom instructions for the agent.
+    ///   - longText: 
+    ///   - basicText: 
+    ///   - longTextMulti: 
+    ///   - basicTextMulti: 
+    public init(accessState: String, description: String, type: AiStudioAgentAskResponseTypeField = AiStudioAgentAskResponseTypeField.aiAgentAsk, customInstructions: TriStateField<String> = nil, longText: AiStudioAgentLongTextToolResponse? = nil, basicText: AiStudioAgentBasicTextToolResponse? = nil, longTextMulti: AiStudioAgentLongTextToolResponse? = nil, basicTextMulti: AiStudioAgentBasicTextToolResponse? = nil) {
+        self.accessState = accessState
+        self.description = description
+        self.type = type
+        self._customInstructions = CodableTriState(state: customInstructions)
+        self.longText = longText
+        self.basicText = basicText
+        self.longTextMulti = longTextMulti
+        self.basicTextMulti = basicTextMulti
+    }
+
+    required public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        accessState = try container.decode(String.self, forKey: .accessState)
+        description = try container.decode(String.self, forKey: .description)
+        type = try container.decode(AiStudioAgentAskResponseTypeField.self, forKey: .type)
+        customInstructions = try container.decodeIfPresent(String.self, forKey: .customInstructions)
+        longText = try container.decodeIfPresent(AiStudioAgentLongTextToolResponse.self, forKey: .longText)
+        basicText = try container.decodeIfPresent(AiStudioAgentBasicTextToolResponse.self, forKey: .basicText)
+        longTextMulti = try container.decodeIfPresent(AiStudioAgentLongTextToolResponse.self, forKey: .longTextMulti)
+        basicTextMulti = try container.decodeIfPresent(AiStudioAgentBasicTextToolResponse.self, forKey: .basicTextMulti)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(accessState, forKey: .accessState)
+        try container.encode(description, forKey: .description)
+        try container.encode(type, forKey: .type)
+        try container.encode(field: _customInstructions.state, forKey: .customInstructions)
+        try container.encodeIfPresent(longText, forKey: .longText)
+        try container.encodeIfPresent(basicText, forKey: .basicText)
+        try container.encodeIfPresent(longTextMulti, forKey: .longTextMulti)
+        try container.encodeIfPresent(basicTextMulti, forKey: .basicTextMulti)
+    }
+
+}

Sources/Schemas/AiStudioAgentAskResponse/AiStudioAgentAskResponse.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+public enum AiStudioAgentAskResponseTypeField: CodableStringEnum {
+    case aiAgentAsk
+    case customValue(String)
+
+    public init(rawValue value: String) {
+        switch value.lowercased() {
+        case "ai_agent_ask".lowercased():
+            self = .aiAgentAsk
+        default:
+            self = .customValue(value)
+        }
+    }
+
+    public var rawValue: String {
+        switch self {
+        case .aiAgentAsk:
+            return "ai_agent_ask"
+        case .customValue(let value):
+            return value
+        }
+    }
+
+}

Sources/Schemas/AiStudioAgentAskResponse/AiStudioAgentAskResponseTypeField.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+/// AI agent basic tool used to generate text.
+public class AiStudioAgentBasicGenToolResponse: AiStudioAgentBasicGenTool {
+    private enum CodingKeys: String, CodingKey {
+        case warnings
+    }
+
+    /// Warnings concerning tool
+    public let warnings: [String]?
+
+    /// Initializer for a AiStudioAgentBasicGenToolResponse.
+    ///
+    /// - Parameters:
+    ///   - model: The model used for the AI agent for basic text. For specific model values, see the [available models list](g://box-ai/supported-models).
+    ///   - numTokensForCompletion: The number of tokens for completion.
+    ///   - llmEndpointParams: The parameters for the LLM endpoint specific to OpenAI / Google models.
+    ///   - systemMessage: System messages aim at helping the LLM understand its role and what it is supposed to do.
+    ///     The input for `{current_date}` is optional, depending on the use.
+    ///   - promptTemplate: The prompt template contains contextual information of the request and the user prompt.
+    ///     
+    ///     When using the `prompt_template` parameter, you **must include** input for `{user_question}`.
+    ///     Inputs for `{current_date}` and `{content}` are optional, depending on the use.
+    ///   - embeddings: 
+    ///   - contentTemplate: How the content should be included in a request to the LLM.
+    ///     Input for `{content}` is optional, depending on the use.
+    ///   - isCustomInstructionsIncluded: True if system message contains custom instructions placeholder, false otherwise
+    ///   - warnings: Warnings concerning tool
+    public init(model: String? = nil, numTokensForCompletion: Int64? = nil, llmEndpointParams: AiLlmEndpointParamsAwsOrAiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi? = nil, systemMessage: String? = nil, promptTemplate: String? = nil, embeddings: AiAgentLongTextToolTextGenEmbeddingsField? = nil, contentTemplate: String? = nil, isCustomInstructionsIncluded: Bool? = nil, warnings: [String]? = nil) {
+        self.warnings = warnings
+
+        super.init(model: model, numTokensForCompletion: numTokensForCompletion, llmEndpointParams: llmEndpointParams, systemMessage: systemMessage, promptTemplate: promptTemplate, embeddings: embeddings, contentTemplate: contentTemplate, isCustomInstructionsIncluded: isCustomInstructionsIncluded)
+    }
+
+    required public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        warnings = try container.decodeIfPresent([String].self, forKey: .warnings)
+
+        try super.init(from: decoder)
+    }
+
+    public override func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encodeIfPresent(warnings, forKey: .warnings)
+        try super.encode(to: encoder)
+    }
+
+}

Sources/Schemas/AiStudioAgentBasicGenToolResponse/AiStudioAgentBasicGenToolResponse.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+/// AI agent processor used to handle basic text.
+public class AiStudioAgentBasicTextToolResponse: AiStudioAgentBasicTextTool {
+    private enum CodingKeys: String, CodingKey {
+        case warnings
+    }
+
+    /// Warnings concerning tool
+    public let warnings: [String]?
+
+    /// Initializer for a AiStudioAgentBasicTextToolResponse.
+    ///
+    /// - Parameters:
+    ///   - model: The model used for the AI agent for basic text. For specific model values, see the [available models list](g://box-ai/supported-models).
+    ///   - numTokensForCompletion: The number of tokens for completion.
+    ///   - llmEndpointParams: The parameters for the LLM endpoint specific to OpenAI / Google models.
+    ///   - systemMessage: System messages try to help the LLM "understand" its role and what it is supposed to do.
+    ///   - promptTemplate: The prompt template contains contextual information of the request and the user prompt.
+    ///     When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`.
+    ///     `{current_date}` is optional, depending on the use.
+    ///   - isCustomInstructionsIncluded: True if system message contains custom instructions placeholder, false otherwise
+    ///   - warnings: Warnings concerning tool
+    public init(model: String? = nil, numTokensForCompletion: Int64? = nil, llmEndpointParams: AiLlmEndpointParamsAwsOrAiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi? = nil, systemMessage: String? = nil, promptTemplate: String? = nil, isCustomInstructionsIncluded: Bool? = nil, warnings: [String]? = nil) {
+        self.warnings = warnings
+
+        super.init(model: model, numTokensForCompletion: numTokensForCompletion, llmEndpointParams: llmEndpointParams, systemMessage: systemMessage, promptTemplate: promptTemplate, isCustomInstructionsIncluded: isCustomInstructionsIncluded)
+    }
+
+    required public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        warnings = try container.decodeIfPresent([String].self, forKey: .warnings)
+
+        try super.init(from: decoder)
+    }
+
+    public override func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encodeIfPresent(warnings, forKey: .warnings)
+        try super.encode(to: encoder)
+    }
+
+}