From ff4e54c7b9ed10a7cf3684a87fd7c08cc25a2a87 Mon Sep 17 00:00:00 2001 From: Kevin Hermawan <84965338+kevinhermawan@users.noreply.github.com> Date: Tue, 2 Jan 2024 19:22:50 +0700 Subject: [PATCH] docs: improves the documentations --- .../Completion/OKCompletionOptions.swift | 59 ++++++++++++++ .../RequestData/OKChatRequestData.swift | 78 +++++++++---------- .../RequestData/OKCopyModelRequestData.swift | 7 +- .../OKDeleteModelRequestData.swift | 5 +- .../RequestData/OKGenerateRequestData.swift | 28 ++++--- .../RequestData/OKModelInfoRequestData.swift | 5 +- .../Completion/OKCompletionResponse.swift | 21 +++++ .../OllamaKit/Responses/OKChatResponse.swift | 43 ++++++++-- .../Responses/OKGenerateResponse.swift | 29 +++++-- .../Responses/OKModelInfoResponse.swift | 11 ++- .../OllamaKit/Responses/OKModelResponse.swift | 13 +++- .../JSONDecoder+Default.swift | 0 .../JSONEncoder+Default.swift | 0 13 files changed, 223 insertions(+), 76 deletions(-) create mode 100644 Sources/OllamaKit/RequestData/Completion/OKCompletionOptions.swift create mode 100644 Sources/OllamaKit/Responses/Completion/OKCompletionResponse.swift rename Sources/OllamaKit/{Extensions => Utils}/JSONDecoder+Default.swift (100%) rename Sources/OllamaKit/{Extensions => Utils}/JSONEncoder+Default.swift (100%) diff --git a/Sources/OllamaKit/RequestData/Completion/OKCompletionOptions.swift b/Sources/OllamaKit/RequestData/Completion/OKCompletionOptions.swift new file mode 100644 index 0000000..1f38b79 --- /dev/null +++ b/Sources/OllamaKit/RequestData/Completion/OKCompletionOptions.swift @@ -0,0 +1,59 @@ +// +// OKCompletionData.swift +// +// +// Created by Kevin Hermawan on 02/01/24. +// + +import Foundation + +/// A structure that encapsulates options for controlling the behavior of content generation in the Ollama API. +public struct OKCompletionOptions: Encodable { + /// Optional integer to enable Mirostat sampling for controlling perplexity. (0 = disabled, 1 = Mirostat, 2 = Mirostat 2.0) + public var mirostat: Int? + + /// Optional float influencing the adjustment speed of the Mirostat algorithm. (Lower = slower adjustment) + public var mirostatEta: Float? + + /// Optional float controlling the balance between coherence and diversity. (Lower = more focused text) + public var mirostatTau: Float? + + /// Optional integer setting the size of the context window for token generation. + public var numCtx: Int? + + /// Optional integer for the number of GQA groups in the transformer layer, specific to some models. + public var numGqa: Int? + + /// Optional integer indicating the number of layers to send to the GPU(s). + public var numGpu: Int? + + /// Optional integer for the number of threads used in computation, recommended to match physical CPU cores. + public var numThread: Int? + + /// Optional integer setting how far back the model checks to prevent repetition. + public var repeatLastN: Int? + + /// Optional float setting the penalty strength for repetitions. + public var repeatPenalty: Float? + + /// Optional float to control the model's creativity (higher = more creative). + public var temperature: Float? + + /// Optional integer for setting a random number seed for generation consistency. + public var seed: Int? + + /// Optional string defining stop sequences for the model to cease generation. + public var stop: String? + + /// Optional float for tail free sampling, reducing impact of less probable tokens. + public var tfsZ: Float? + + /// Optional integer for the maximum number of tokens to predict. + public var numPredict: Int? + + /// Optional integer to limit nonsense generation and control answer diversity. + public var topK: Int? + + /// Optional float working with top-k to balance text diversity and focus. + public var topP: Float? +} diff --git a/Sources/OllamaKit/RequestData/OKChatRequestData.swift b/Sources/OllamaKit/RequestData/OKChatRequestData.swift index c535cfd..9fb5f30 100644 --- a/Sources/OllamaKit/RequestData/OKChatRequestData.swift +++ b/Sources/OllamaKit/RequestData/OKChatRequestData.swift @@ -7,56 +7,52 @@ import Foundation -/// A structure representing the data required to generate responses from the Ollama API. -/// -/// It includes the model name, prompt, and other optional parameters that tailor the generation process, such as format and context. +/// A structure that encapsulates data for chat requests to the Ollama API. public struct OKChatRequestData: Encodable { private let stream: Bool + /// A string representing the model identifier to be used for the chat session. public let model: String - public let messages: [ChatMessage] - public var format: Format? - public var options: Options? - public var template: String? - public init(model: String, messages: [ChatMessage]) { + /// An array of ``Message`` instances representing the content to be sent to the Ollama API. + public let messages: [Message] + + /// Optional ``OKCompletionOptions`` providing additional configuration for the chat request. + public var options: OKCompletionOptions? + + public init(model: String, messages: [Message]) { self.stream = true self.model = model self.messages = messages } -} - -public struct ChatMessage: Encodable { - public var role: String - public var content: String - public let images: [String] - public init(role: String, content: String, images: [String] = []) { - self.role = role - self.content = content - self.images = images + /// A structure that represents a single message in the chat request. + public struct Message: Encodable { + /// A ``Role`` value indicating the sender of the message (system, assistant, user). + public let role: Role + + /// A string containing the message's content. + public let content: String + + /// An optional array of base64-encoded images. + public let images: [String] + + public init(role: Role, content: String, images: [String] = []) { + self.role = role + self.content = content + self.images = images + } + + /// An enumeration that represents the role of the message sender. + public enum Role: String, Encodable { + /// Indicates the message is from the system. + case system + + /// Indicates the message is from the assistant. + case assistant + + /// Indicates the message is from the user. + case user + } } } - -public enum Format: String, Encodable { - case json -} - -public struct Options: Encodable { - public var mirostat: Int? - public var mirostatEta: Double? - public var mirostatTau: Double? - public var numCtx: Int? - public var numGqa: Int? - public var numGpu: Int? - public var numThread: Int? - public var repeatLastN: Int? - public var repeatPenalty: Int? - public var temperature: Double? - public var seed: Int? - public var stop: String? - public var tfsZ: Double? - public var numPredict: Int? - public var topK: Int? - public var topP: Double? -} diff --git a/Sources/OllamaKit/RequestData/OKCopyModelRequestData.swift b/Sources/OllamaKit/RequestData/OKCopyModelRequestData.swift index 3b9ad6f..c2132ad 100644 --- a/Sources/OllamaKit/RequestData/OKCopyModelRequestData.swift +++ b/Sources/OllamaKit/RequestData/OKCopyModelRequestData.swift @@ -7,11 +7,12 @@ import Foundation -/// A structure representing the request data for copying a model via the Ollama API. -/// -/// This structure holds the information necessary to duplicate a model, including the source model's name and the desired destination name. +/// A structure that encapsulates the necessary data to request a model copy operation in the Ollama API. public struct OKCopyModelRequestData: Encodable { + /// A string representing the identifier of the source model to be copied. public let source: String + + /// A string indicating the identifier for the destination or the new copy of the model. public let destination: String public init(source: String, destination: String) { diff --git a/Sources/OllamaKit/RequestData/OKDeleteModelRequestData.swift b/Sources/OllamaKit/RequestData/OKDeleteModelRequestData.swift index 6864298..37f01d0 100644 --- a/Sources/OllamaKit/RequestData/OKDeleteModelRequestData.swift +++ b/Sources/OllamaKit/RequestData/OKDeleteModelRequestData.swift @@ -7,10 +7,9 @@ import Foundation -/// A structure representing the request data for deleting a model through the Ollama API. -/// -/// This structure encapsulates the name of the model to be deleted, providing a straightforward way to specify which model should be removed. +/// A structure that encapsulates the necessary data to request a model deletion in the Ollama API. public struct OKDeleteModelRequestData: Encodable { + /// A string representing the identifier of the model to be deleted. public let name: String public init(name: String) { diff --git a/Sources/OllamaKit/RequestData/OKGenerateRequestData.swift b/Sources/OllamaKit/RequestData/OKGenerateRequestData.swift index 8182c9e..6cab851 100644 --- a/Sources/OllamaKit/RequestData/OKGenerateRequestData.swift +++ b/Sources/OllamaKit/RequestData/OKGenerateRequestData.swift @@ -7,24 +7,32 @@ import Foundation -/// A structure representing the data required to generate responses from the Ollama API. -/// -/// It includes the model name, prompt, and other optional parameters that tailor the generation process, such as format and context. +/// A structure that encapsulates the data required for generating responses using the Ollama API. public struct OKGenerateRequestData: Encodable { private let stream: Bool - + + /// A string representing the identifier of the model. public let model: String + + /// A string containing the initial input or prompt. public let prompt: String - public var format: Format? + + /// /// An optional array of base64-encoded images. + public let images: [String] + + /// An optional string specifying the system message. public var system: String? - public var template: String? - public var options: Options? - public var context: [Int]? - public var raw: Bool? - public init(model: String, prompt: String) { + /// An optional array of doubles representing contextual information. + public var context: [Double]? + + /// Optional ``OKCompletionOptions`` providing additional configuration for the generation request. + public var options: OKCompletionOptions? + + public init(model: String, prompt: String, images: [String] = []) { self.stream = true self.model = model self.prompt = prompt + self.images = images } } diff --git a/Sources/OllamaKit/RequestData/OKModelInfoRequestData.swift b/Sources/OllamaKit/RequestData/OKModelInfoRequestData.swift index df35a15..90095ce 100644 --- a/Sources/OllamaKit/RequestData/OKModelInfoRequestData.swift +++ b/Sources/OllamaKit/RequestData/OKModelInfoRequestData.swift @@ -7,10 +7,9 @@ import Foundation -/// A structure representing the request data for fetching model information from the Ollama API. -/// -/// This structure is used to specify the name of the model for which detailed information is requested. +/// A structure that encapsulates the data necessary for requesting information about a specific model from the Ollama API. public struct OKModelInfoRequestData: Encodable { + /// A string representing the identifier of the model for which information is requested. public let name: String public init(name: String) { diff --git a/Sources/OllamaKit/Responses/Completion/OKCompletionResponse.swift b/Sources/OllamaKit/Responses/Completion/OKCompletionResponse.swift new file mode 100644 index 0000000..ba0267d --- /dev/null +++ b/Sources/OllamaKit/Responses/Completion/OKCompletionResponse.swift @@ -0,0 +1,21 @@ +// +// OKCompletionResponse.swift +// +// +// Created by Kevin Hermawan on 02/01/24. +// + +import Foundation + +protocol OKCompletionResponse: Decodable { + var model: String { get } + var createdAt: Date { get } + var done: Bool { get } + + var totalDuration: Int? { get } + var loadDuration: Int? { get } + var promptEvalCount: Int? { get } + var promptEvalDuration: Int? { get } + var evalCount: Int? { get } + var evalDuration: Int? { get } +} diff --git a/Sources/OllamaKit/Responses/OKChatResponse.swift b/Sources/OllamaKit/Responses/OKChatResponse.swift index a329e2c..cd0dab7 100644 --- a/Sources/OllamaKit/Responses/OKChatResponse.swift +++ b/Sources/OllamaKit/Responses/OKChatResponse.swift @@ -7,23 +7,56 @@ import Foundation -/// A structure representing the response from a chat request to the Ollama API. -/// -/// Contains details of the generation process, including the model used, response content, and various performance metrics. -public struct OKChatResponse: Decodable { +/// A structure that represents the response to a chat request from the Ollama API. +public struct OKChatResponse: OKCompletionResponse, Decodable { + /// A string representing the identifier of the model that processed the request. public let model: String + + /// A `Date` indicating when the response was created. public let createdAt: Date + + /// An optional `Message` instance representing the content of the response. public let message: Message? + + /// A boolean indicating whether the chat session is complete. public let done: Bool + + /// An optional integer representing the total duration of processing the request. public let totalDuration: Int? + + /// An optional integer indicating the duration of loading the model. public let loadDuration: Int? + + /// An optional integer specifying the number of evaluations performed on the prompt. public let promptEvalCount: Int? + + /// An optional integer indicating the duration of prompt evaluations. public let promptEvalDuration: Int? + + /// An optional integer representing the total number of evaluations performed. public let evalCount: Int? + + /// An optional integer indicating the duration of all evaluations. public let evalDuration: Int? + /// A structure that represents a single response message. public struct Message: Decodable { - public var role: String + /// A ``Role`` value indicating the sender of the message (system, assistant, user). + public var role: Role + + /// A string containing the message's content. public var content: String + + /// An enumeration that represents the role of the message sender. + public enum Role: String, Decodable { + /// Indicates the message is from the system. + case system + + /// Indicates the message is from the assistant. + case assistant + + /// Indicates the message is from the user. + case user + } } } diff --git a/Sources/OllamaKit/Responses/OKGenerateResponse.swift b/Sources/OllamaKit/Responses/OKGenerateResponse.swift index e7fd3fc..fe52331 100644 --- a/Sources/OllamaKit/Responses/OKGenerateResponse.swift +++ b/Sources/OllamaKit/Responses/OKGenerateResponse.swift @@ -7,19 +7,38 @@ import Foundation -/// A structure representing the response from a generate request to the Ollama API. -/// -/// Contains details of the generation process, including the model used, response content, and various performance metrics. -public struct OKGenerateResponse: Decodable { +/// A structure that represents the response to a content generation request from the Ollama API. +public struct OKGenerateResponse: OKCompletionResponse, Decodable { + /// A string representing the identifier of the model used for generation. public let model: String + + /// A `Date` indicating when the response was generated. public let createdAt: Date + + /// A string containing the generated content. public let response: String - public let done: Bool + + /// An optional array of integers representing contextual information used in the generation. public let context: [Int]? + + /// A boolean indicating whether the generation process is complete. + public let done: Bool + + /// An optional integer representing the total duration of processing the request. public let totalDuration: Int? + + /// An optional integer indicating the duration of loading the model. public let loadDuration: Int? + + /// An optional integer specifying the number of evaluations performed on the prompt. public let promptEvalCount: Int? + + /// An optional integer indicating the duration of prompt evaluations. public let promptEvalDuration: Int? + + /// An optional integer representing the total number of evaluations performed. public let evalCount: Int? + + /// An optional integer indicating the duration of all evaluations. public let evalDuration: Int? } diff --git a/Sources/OllamaKit/Responses/OKModelInfoResponse.swift b/Sources/OllamaKit/Responses/OKModelInfoResponse.swift index fd4fe19..947bfef 100644 --- a/Sources/OllamaKit/Responses/OKModelInfoResponse.swift +++ b/Sources/OllamaKit/Responses/OKModelInfoResponse.swift @@ -7,12 +7,17 @@ import Foundation -/// A structure encapsulating detailed information about a specific model from the Ollama API. -/// -/// Includes the model's license, template, modelfile, and operational parameters. +/// A structure that represents the response containing information about a specific model from the Ollama API. public struct OKModelInfoResponse: Decodable { + /// A string detailing the licensing information for the model. public let license: String + + /// A string representing the template used by the model. public let template: String + + /// A string containing the path or identifier of the model file. public let modelfile: String + + /// A string detailing the parameters or settings of the model. public let parameters: String } diff --git a/Sources/OllamaKit/Responses/OKModelResponse.swift b/Sources/OllamaKit/Responses/OKModelResponse.swift index 1ddc63d..2661bc1 100644 --- a/Sources/OllamaKit/Responses/OKModelResponse.swift +++ b/Sources/OllamaKit/Responses/OKModelResponse.swift @@ -7,16 +7,23 @@ import Foundation -/// A structure representing a list of models available through the Ollama API. -/// -/// Contains an array of `OKModelResponse.Model` structures, each detailing a specific model's name, digest, size, and last modification date. +/// A structure that represents the available models from the Ollama API. public struct OKModelResponse: Decodable { + /// An array of ``Model`` instances, each representing a specific model available in the Ollama API. public let models: [Model] + /// A structure that details individual models. public struct Model: Decodable { + /// A string representing the name of the model. public let name: String + + /// A string containing a digest or hash of the model, typically used for verification or identification. public let digest: String + + /// An integer indicating the size of the model, often in bytes. public let size: Int + + /// A `Date` representing the last modification date of the model. public let modifiedAt: Date } } diff --git a/Sources/OllamaKit/Extensions/JSONDecoder+Default.swift b/Sources/OllamaKit/Utils/JSONDecoder+Default.swift similarity index 100% rename from Sources/OllamaKit/Extensions/JSONDecoder+Default.swift rename to Sources/OllamaKit/Utils/JSONDecoder+Default.swift diff --git a/Sources/OllamaKit/Extensions/JSONEncoder+Default.swift b/Sources/OllamaKit/Utils/JSONEncoder+Default.swift similarity index 100% rename from Sources/OllamaKit/Extensions/JSONEncoder+Default.swift rename to Sources/OllamaKit/Utils/JSONEncoder+Default.swift