async-ollama 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b063f95dd3bfc375203e52136932e15e7fdb060c5e8c2c88714285679d4ed535
-  data.tar.gz: a431d19a4817acf9d77ab225f22dfe523d0e04826f4ad87e615bd7c6d22d20f9
+  metadata.gz: 6ccd3b807e6fb1863176fe45a44a41176cc122d72c9650ef0e96eb748151c2a9
+  data.tar.gz: 28a590bb9f9a62e12419a6c5e6c1c6b1661cee0a0b1068a795c3ebcfb9422282
 SHA512:
-  metadata.gz: ac83698f0c120ede1b595509da72e83ab81faffe50bed02e3aebf01e5b66579699d2329fbdaff0e0f087813677fc6f338029bccda9d62d0ed6726c26586e9973
-  data.tar.gz: 148408b29f5aafd3ce3d71c5ecd3f2eadbd496736893049e01701e52e214188912725a3ba13245b261d5c02e159725a29998493e7739aed6f8e0e0a08db0ad4b
+  metadata.gz: 68119787b00471de152fb5d99a3d94c6a86c20216925cb36cb8ed9c88bb694861d0b293dee7594ad411b65894a03ecf2e18c775708db9465c4341008fee3615e
+  data.tar.gz: 1dca4d6db7fd5cc6136f6a65ef5b61777ed6c720d9d7ec445d7d7443c1a4d6769c552939a02cc4fa306de93038c0cfff6ef7b328061130716c5280cfbb836fef

data/lib/async/ollama/chat.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/rest/representation"
+require_relative "wrapper"
+
+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]
+			# @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
+			
+			# @returns [String] The model name used to generate this response.
+			def model
+				self.value[:model]
+			end
+			
+			# @return [Integer | nil] The time spent generating the response, in nanoseconds.
+			def total_duration
+				self.value[:total_duration]
+			end
+			
+			# @return [Integer | nil] The time spent loading the model, in nanoseconds.
+			def load_duration
+				self.value[:load_duration]
+			end
+			
+			# @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 | nil] The time spent evaluating the prompt, in nanoseconds.
+			def prompt_eval_duration
+				self.value[:prompt_eval_duration]
+			end
+			
+			# @return [Integer | nil] The number of tokens in the response.
+			def eval_count
+				self.value[:eval_count]
+			end
+			
+			# @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
+				
+				if prompt_eval_count = self.prompt_eval_count
+					count += prompt_eval_count
+				end
+				
+				if eval_count = self.eval_count
+					count += eval_count
+				end
+				
+				return count
+			end
+		end
+	end
+end

data/lib/async/ollama/client.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require "async/rest/resource"
 
 require_relative "generate"
+require_relative "chat"
 require_relative "models"
 
 module Async
 	module Ollama
-		# Represents a connection to the Ollama service.
+		MODEL = ENV.fetch("ASYNC_OLLAMA_MODEL", "llama3.1:latest")
+		
+		# 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] ||= "llama3"
+				options[:model] ||= MODEL
 				
 				Generate.post(self.with(path: "/api/generate"), options) do |resource, response|
 					if block_given?
@@ -30,6 +35,25 @@ module Async
 				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
+				
+				Chat.post(self.with(path: "/api/chat"), options) do |resource, response|
+					if block_given?
+						yield response
+					end
+					
+					Chat.new(resource, value: response.read, metadata: response.headers)
+				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

data/lib/async/ollama/conversation.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+require_relative "client"
+require_relative "toolbox"
+
+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
+				@messages = messages
+				@options = options
+				
+				@toolbox = Toolbox.new
+				
+				@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 << {
+						role: "user",
+						content: prompt
+					}
+				else
+					@messages << prompt
+				end
+				
+				while true
+					@last_response = @client.chat(@messages, model: @model, tools: @toolbox.explain, options: @options, &block)
+					
+					if error = @last_response.error
+						raise ChatError, error
+					end
+					
+					@messages << @last_response.message
+					
+					tool_calls = @last_response.tool_calls
+					
+					if tool_calls.nil? || tool_calls.empty?
+						return @last_response
+					end
+					
+					tool_calls.each do |tool_call|
+						@messages << @toolbox.call(tool_call)
+					end
+				end
+			end
+			
+			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
+				
+				# In principle, this could generate several messages:
+				message = {
+					role: role,
+					content: SUMMARIZE_MESSAGE,
+				}
+				
+				self.call(message)
+				
+				# The number of messages generated by the summarization:
+				delta = @messages.size - current_size
+				
+				# After much experimentation, I found that leaving the SUMMARIZE_MESSAGE in the message stream caused extreme confusion, so we set retain to -1 to remove it by default.
+				retain += delta
+				if retain < @messages.size
+					truncated = @messages.size - retain
+					
+					# We need to truncate the messages:
+					@messages = @messages.last(retain)
+					
+					@messages.unshift({
+						role: "system",
+						content: "#{truncated} previous messages that have been removed and summarized to reduce context usage. Continue the conversation naturally as if the previous messages were still present.",
+					})
+				end
+			end
+		end
+	end
+end

data/lib/async/ollama/generate.rb

@@ -1,35 +1,24 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require "async/rest/representation"
 require_relative "wrapper"
 
 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 conversation context. Used to maintain state between prompts.
-			def context
-				self.value[:context]
-			end
-			
-			# The model used to generate the response.
+			# @returns [String] The model name used to generate the response.
 			def model
 				self.value[:model]
 			end
-			
-			# Generate a new response from the given prompt.
-			# @parameter prompt [String] The prompt to generate a response from.
-			# @yields {|response| ...} Optional streaming response.
-			def generate(prompt, &block)
-				self.class.post(self.resource, prompt: prompt, context: self.context, model: self.model, &block)
-			end
 		end
 	end
 end

data/lib/async/ollama/models.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require "async/rest/representation"
 require_relative "wrapper"
 
 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

data/lib/async/ollama/toolbox.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+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",
+					function: @schema,
+				}
+			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]
+				
+				if tool = @tools[name]
+					arguments = function[:arguments]
+					result = tool.call(arguments)
+					
+					return {
+						role: "tool",
+						tool_name: name,
+						content: result.to_json,
+					}
+				else
+					raise ArgumentError.new("Unknown tool: #{name}")
+				end
+			rescue => error
+				return {
+					role: "tool",
+					tool_name: name,
+					error: error.inspect,
+				}
+			end
+			
+			# @returns [Array(Hash)] The explanations for all registered tools.
+			def explain
+				@tools.values.map(&:explain)
+			end
+		end
+	end
+end

data/lib/async/ollama/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Ollama
-		VERSION = "0.4.0"
+		VERSION = "0.5.0"
 	end
 end

data/lib/async/ollama/wrapper.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require "async/rest/wrapper/generic"
 require "async/rest/wrapper/json"
@@ -13,10 +13,112 @@ require "json"
 
 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
+				
+				@buffer = String.new.b
+				@offset = 0
+				
+				@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?
+				
+				while true
+					if index = @buffer.index("\n", @offset)
+						line = @buffer.byteslice(@offset, index - @offset)
+						@buffer = @buffer.byteslice(index + 1, @buffer.bytesize - index - 1)
+						@offset = 0
+						
+						return ::JSON.parse(line, symbolize_names: true)
+					end
+					
+					if chunk = super
+						@buffer << chunk
+					else
+						return nil if @buffer.empty?
+						
+						line = @buffer
+						@buffer = nil
+						@offset = 0
+						
+						return ::JSON.parse(line, symbolize_names: true)
+					end
+				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)
+					@response << response
+					@value.merge!(line)
+					
+					yield response
+				end
+			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
+				
+				@content = String.new
+				@message = {content: @content, role: "assistant"}
+				@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)
+					content = message.delete(:content)
+					@content << content
+					@message.merge!(message)
+					@value.merge!(line)
+					
+					yield content
+				end
+			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)
@@ -30,60 +132,27 @@ module Async
 				end
 			end
 			
-			class StreamingResponseParser < ::Protocol::HTTP::Body::Wrapper
-				def initialize(...)
-					super
-					
-					@buffer = String.new.b
-					@offset = 0
-					
-					@response = String.new
-					@value = {response: @response}
-				end
-				
-				def read
-					return if @buffer.nil?
-					
-					while true
-						if index = @buffer.index("\n", @offset)
-							line = @buffer.byteslice(@offset, index - @offset)
-							@buffer = @buffer.byteslice(index + 1, @buffer.bytesize - index - 1)
-							@offset = 0
-							
-							return ::JSON.parse(line, symbolize_names: true)
-						end
-						
-						if chunk = super
-							@buffer << chunk
-						else
-							return nil if @buffer.empty?
-							
-							line = @buffer
-							@buffer = nil
-							@offset = 0
-							
-							return ::JSON.parse(line, symbolize_names: true)
-						end
-					end
-				end
-				
-				def each
-					super do |line|
-						token = line.delete(:response)
-						@response << token
-						@value.merge!(line)
-						
-						yield token
-					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
 				
-				def join
-					self.each{}
-					
-					return @value
+				case media_type
+				when APPLICATION_JSON
+					return Async::REST::Wrapper::JSON::Parser
+				when APPLICATION_JSON_STREAM
+					return StreamingResponseParser
 				end
 			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
@@ -92,7 +161,7 @@ module Async
 				when APPLICATION_JSON
 					return Async::REST::Wrapper::JSON::Parser
 				when APPLICATION_JSON_STREAM
-					return StreamingResponseParser
+					return StreamingMessageParser
 				end
 			end
 		end

data/lib/async/ollama.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "ollama/version"
 require_relative "ollama/client"
+
+require_relative "ollama/conversation"
+
+# @namespace
+module Async
+	# @namespace
+	module Ollama
+	end
+end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2024, by Samuel Williams.  
+Copyright, 2024-2025, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -10,6 +10,15 @@ Please see the [project documentation](https://socketry.github.io/async-ollama/)
 
   - [Getting Started](https://socketry.github.io/async-ollama/guides/getting-started/index) - This guide explains how to get started with the `async-ollama` gem.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-ollama/releases/index) for all releases.
+
+### v0.5.0
+
+  - Add `Async::Ollama::Conversation` for interactive real-time conversations. Includes support for summarization of chat history for large conversations.
+  - Add `Async::Ollama::Toolbox` for managing tool based interactions with models.
+
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## v0.5.0
+
+  - Add `Async::Ollama::Conversation` for interactive real-time conversations. Includes support for summarization of chat history for large conversations.
+  - Add `Async::Ollama::Toolbox` for managing tool based interactions with models.

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: async-ollama
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-11-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -57,37 +56,38 @@ dependencies:
   name: async-rest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.17'
-description:
-email:
+        version: '0'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/async/ollama.rb
+- lib/async/ollama/chat.rb
 - lib/async/ollama/client.rb
+- lib/async/ollama/conversation.rb
 - lib/async/ollama/generate.rb
 - lib/async/ollama/models.rb
+- lib/async/ollama/toolbox.rb
 - lib/async/ollama/version.rb
 - lib/async/ollama/wrapper.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/async-ollama
 licenses:
 - MIT
 metadata:
   documentation_uri: https://socketry.github.io/async-ollama/
   source_code_uri: https://github.com/socketry/async-ollama.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -95,15 +95,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A asynchronous interface to the ollama chat service
 test_files: []