100% documentation coverage.

Author: ioquatix

gems.rb

@@ -7,6 +7,8 @@
 
 gemspec
 
+gem "agent-context"
+
 group :maintenance, optional: true do
 	gem "bake-gem"
 	gem "bake-modernize"

lib/async/ollama.rb

@@ -7,3 +7,10 @@
 require_relative "ollama/client"
 
 require_relative "ollama/conversation"
+
+# @namespace
+module Async
+	# @namespace
+	module Ollama
+	end
+end

lib/async/ollama/chat.rb

@@ -8,57 +8,61 @@
 
 module Async
 	module Ollama
+		# Represents a chat response from the Ollama API, including message content, model, and timing information.
 		class Chat < Async::REST::Representation[ChatWrapper]
-			# The response message.
+			# @returns [Hash | nil] The message content, or nil if not present.
 			def message
 				self.value[:message]
 			end
 
+			# @returns [String | nil] The error message, or nil if not present.
 			def error
 				self.value[:error]
 			end
 
+			# @returns [Array(Hash) | nil] The tool calls, or nil if not present.
 			def tool_calls
 				if message = self.message
 					message[:tool_calls]
 				end
 			end
 
-			# The model used to generate the response.
+			# @returns [String] The model name used to generate this response.
 			def model
 				self.value[:model]
 			end
 
-			# @return [Integer] The time spent generating the response, in nanoseconds.
+			# @return [Integer | nil] The time spent generating the response, in nanoseconds.
 			def total_duration
 				self.value[:total_duration]
 			end
 
-			# @return [Integer] The time spent loading the model, in nanoseconds.
+			# @return [Integer | nil] The time spent loading the model, in nanoseconds.
 			def load_duration
 				self.value[:load_duration]
 			end
 
-			# @return [Integer] The number of tokens in the prompt (the token count).
+			# @return [Integer | nil] The number of tokens in the prompt (the token count).
 			def prompt_eval_count
 				self.value[:prompt_eval_count]
 			end
 
-			# @return [Integer] The time spent evaluating the prompt, in nanoseconds.
+			# @return [Integer | nil] The time spent evaluating the prompt, in nanoseconds.
 			def prompt_eval_duration
 				self.value[:prompt_eval_duration]
 			end
 
-			# @return [Integer] The number of tokens in the response.
+			# @return [Integer | nil] The number of tokens in the response.
 			def eval_count
 				self.value[:eval_count]
 			end
 
-			# @return [Integer] The time spent generating the response, in nanoseconds.
+			# @return [Integer | nil] The time spent generating the response, in nanoseconds.
 			def eval_duration
 				self.value[:eval_duration]
 			end
 
+			# @return [Integer] The sum of prompt and response token counts.
 			def token_count
 				count = 0
 

lib/async/ollama/client.rb

@@ -13,13 +13,15 @@ module Async
 	module Ollama
 		MODEL = ENV.fetch("ASYNC_OLLAMA_MODEL", "llama3.1:latest")
 
-		# Represents a connection to the Ollama service.
+		# Represents a connection to the Ollama service, providing methods to generate completions, chat, and list models.
 		class Client < Async::REST::Resource
 			# The default endpoint to connect to.
 			ENDPOINT = Async::HTTP::Endpoint.parse("http://localhost:11434")
 
-			# Generate a response from the given prompt.
+			# Generates a response from the given prompt using Ollama.
 			# @parameter prompt [String] The prompt to generate a response from.
+			# @parameter options [Hash] Additional options for the request.
+			# @returns [Generate] The generated response representation.
 			def generate(prompt, **options, &block)
 				options[:prompt] = prompt
 				options[:model] ||= MODEL
@@ -33,6 +35,10 @@ def generate(prompt, **options, &block)
 				end
 			end
 
+			# Sends a chat request with the given messages to Ollama.
+			# @parameter messages [Array(Hash)] The chat messages to send.
+			# @parameter options [Hash] Additional options for the request.
+			# @returns [Chat] The chat response representation.
 			def chat(messages, **options, &block)
 				options[:model] ||= MODEL
 				options[:messages] = messages
@@ -46,6 +52,8 @@ def chat(messages, **options, &block)
 				end
 			end
 
+			# Retrieves the list of available models from Ollama.
+			# @returns [Models] The models response representation.
 			def models
 				Models.get(self.with(path: "/api/tags"))
 			end

lib/async/ollama/conversation.rb

@@ -8,10 +8,17 @@
 
 module Async
 	module Ollama
+		# Represents a conversation with the Ollama API, managing messages, tool calls, and summarization.
 		class Conversation
+			# Raised when a chat error occurs during the conversation.
 			class ChatError < StandardError
 			end
 
+			# Initializes a new conversation.
+			# @parameter client [Client] The Ollama client instance.
+			# @parameter model [String] The model to use for the conversation.
+			# @parameter messages [Array(Hash)] The initial messages for the conversation.
+			# @parameter options [Hash] Additional options for the conversation.
 			def initialize(client, model: MODEL, messages: [], **options)
 				@client = client
 				@model = model
@@ -23,18 +30,25 @@ def initialize(client, model: MODEL, messages: [], **options)
 				@last_response = nil
 			end
 
+			# @attribute [Toolbox] The toolbox for this conversation.
 			attr :toolbox
 
+			# @attribute [Array(Hash)] The messages in the conversation.
 			attr :messages
 
+			# @returns [Integer] The number of messages in the conversation.
 			def size
 				@messages.size
 			end
 
+			# @returns [Integer] The token count of the last response, or 0 if none.
 			def token_count
 				@last_response&.token_count || 0
 			end
 
+			# Sends a prompt to the conversation and processes the response, including tool calls.
+			# @parameter prompt [String | Hash] The prompt to send (as a string or message hash).
+			# @returns [Chat] The final chat response.
 			def call(prompt, &block)
 				if prompt.is_a?(String)
 					@messages << {
@@ -68,6 +82,10 @@ def call(prompt, &block)
 
 			SUMMARIZE_MESSAGE = "Please summarize the conversation so far for your future reference. Do not introduce new information or questions. Refer to both user and assistant messages. Please keep the summary concise and relevant to the conversation and use it to continue the conversation."
 
+			# Summarizes the conversation and truncates messages to reduce context usage.
+			# @parameter retain [Integer] The number of messages to retain after summarization.
+			# @parameter role [String] The role to use for the summarization message.
+			# @returns [void]
 			def summarize!(retain = -1, role: "user")
 				current_size = @messages.size
 

lib/async/ollama/generate.rb

@@ -8,13 +8,14 @@
 
 module Async
 	module Ollama
+		# Represents a generated response from the Ollama API.
 		class Generate < Async::REST::Representation[Wrapper]
-			# The response to the prompt.
+			# @returns [String | nil] The generated response, or nil if not present.
 			def response
 				self.value[:response]
 			end
 
-			# The model used to generate the response.
+			# @returns [String] The model name used to generate the response.
 			def model
 				self.value[:model]
 			end

lib/async/ollama/models.rb

@@ -8,9 +8,11 @@
 
 module Async
 	module Ollama
+		# Represents the available models returned by the Ollama API.
 		class Models < Async::REST::Representation[Wrapper]
+			# @returns [Array(String)] The list of model names.
 			def names
-				self.value[:models].map{|model| model[:name]}
+				self.value[:models].map {|model| model[:name]}
 			end
 		end
 	end

lib/async/ollama/toolbox.rb

@@ -5,20 +5,32 @@
 
 module Async
 	module Ollama
+		# Represents a tool that can be registered and called by the Toolbox.
 		class Tool
+			# Initializes a new tool with the given name, schema, and block.
+			# @parameter name [String] The name of the tool.
+			# @parameter schema [Hash] The schema describing the tool's function.
+			# @parameter block [Proc] The implementation of the tool.
 			def initialize(name, schema, &block)
 				@name = name
 				@schema = schema
 				@block = block
 			end
 
+			# @attribute [String] The name of the tool.
 			attr :name
+			
+			# @attribute [Hash] The schema for the tool.
 			attr :schema
 
+			# Calls the tool with the given message.
+			# @parameter message [Hash] The message to process.
+			# @returns [Object] The result of the tool's block.
 			def call(message)
 				@block.call(message)
 			end
 
+			# @returns [Hash] The explanation of the tool's function for API usage.
 			def explain
 				{
 					type: "function",
@@ -27,17 +39,27 @@ def explain
 			end
 		end
 
+		# Manages a collection of tools and dispatches calls to them.
 		class Toolbox
+			# Initializes a new, empty toolbox.
 			def initialize
 				@tools = {}
 			end
 
+			# @attribute [Hash] The registered tools by name.
 			attr :tools
 
+			# Registers a new tool with the given name, schema, and block.
+			# @parameter name [String] The name of the tool.
+			# @parameter schema [Hash] The schema describing the tool's function.
+			# @parameter block [Proc] The implementation of the tool.
 			def register(name, schema, &block)
 				@tools[name] = Tool.new(name, schema, &block)
 			end
 
+			# Calls a registered tool with the given message.
+			# @parameter message [Hash] The message containing the function call.
+			# @returns [Hash] The tool's response message.
 			def call(message)
 				function = message[:function]
 				name = function[:name]
@@ -62,6 +84,7 @@ def call(message)
 				}
 			end
 
+			# @returns [Array(Hash)] The explanations for all registered tools.
 			def explain
 				@tools.values.map(&:explain)
 			end

lib/async/ollama/wrapper.rb

@@ -13,7 +13,9 @@
 
 module Async
 	module Ollama
+		# Parses streaming HTTP responses for Ollama, buffering and extracting JSON lines.
 		class StreamingParser < ::Protocol::HTTP::Body::Wrapper
+			# @parameter args [Array] Arguments for the parent initializer.
 			def initialize(...)
 				super
 
@@ -23,6 +25,8 @@ def initialize(...)
 				@value = {}
 			end
 
+			# Reads the next JSON object from the stream.
+			# @returns [Hash | nil] The next parsed object, or nil if the stream is empty.
 			def read
 				return if @buffer.nil?
 
@@ -49,21 +53,27 @@ def read
 				end
 			end
 
+			# Joins the stream, reading all objects and returning the final value.
+			# @returns [Hash] The final parsed value.
 			def join
 				self.each{}
 
 				return @value
 			end
 		end
 
+		# Parses streaming responses for the Ollama API, collecting the response string.
 		class StreamingResponseParser < StreamingParser
+			# Initializes the parser with an empty response string.
 			def initialize(...)
 				super
 
 				@response = String.new
 				@value[:response] = @response
 			end
 
+			# Iterates over each response line, yielding the response string.
+			# @returns [Enumerator] Yields each response string.
 			def each
 				super do |line|
 					response = line.delete(:response)
@@ -75,7 +85,9 @@ def each
 			end
 		end
 
+		# Parses streaming message responses for the Ollama API, collecting message content.
 		class StreamingMessageParser < StreamingParser
+			# Initializes the parser with an empty message content.
 			def initialize(...)
 				super
 
@@ -84,6 +96,8 @@ def initialize(...)
 				@value[:message] = @message
 			end
 
+			# Iterates over each message line, yielding the message content.
+			# @returns [Enumerator] Yields each message content string.
 			def each
 				super do |line|
 					message = line.delete(:message)
@@ -97,10 +111,14 @@ def each
 			end
 		end
 
+		# Wraps HTTP requests and responses for the Ollama API, handling content negotiation and parsing.
 		class Wrapper < Async::REST::Wrapper::Generic
 			APPLICATION_JSON = "application/json"
 			APPLICATION_JSON_STREAM = "application/x-ndjson"
 
+			# Prepares the HTTP request with appropriate headers and body.
+			# @parameter request [Protocol::HTTP::Request] The HTTP request object.
+			# @parameter payload [Protocol::HTTP::Response] The request payload.
 			def prepare_request(request, payload)
 				request.headers.add("accept", APPLICATION_JSON)
 				request.headers.add("accept", APPLICATION_JSON_STREAM)
@@ -114,6 +132,9 @@ def prepare_request(request, payload)
 				end
 			end
 
+			# Selects the appropriate parser for the HTTP response.
+			# @parameter response [Protocol::HTTP::Response] The HTTP response object.
+			# @returns [Class] The parser class to use.
 			def parser_for(response)
 				content_type = response.headers["content-type"]
 				media_type = content_type.split(";").first
@@ -127,7 +148,11 @@ def parser_for(response)
 			end
 		end
 
+		# Wraps chat-specific HTTP responses for the Ollama API, selecting the appropriate parser.
 		class ChatWrapper < Wrapper
+			# Selects the appropriate parser for the chat HTTP response.
+			# @parameter response [Protocol::HTTP::Response] The HTTP response object.
+			# @returns [Class] The parser class to use.
 			def parser_for(response)
 				content_type = response.headers["content-type"]
 				media_type = content_type.split(";").first