Class: Ollama::Client

Inherits:
Object
  • Object
show all
Includes:
Command, Configuration, Handlers, Tins::Annotate
Defined in:
lib/ollama/client.rb,
lib/ollama/client.rb

Overview

A class that serves as the main entry point for interacting with the Ollama API.

The Client class provides methods to communicate with an Ollama server, handling various API endpoints such as chat, generate, create, and model management commands. It manages configuration settings like base URL, timeouts, and output streams, and supports different response handlers for processing API results.

Examples:

Initializing a client with a base URL

client = Ollama::Client.new(base_url: 'http://localhost:11434')

Configuring a client using a configuration object

config = Ollama::Client::Config[base_url: 'http://localhost:11434']
client = Ollama::Client.configure_with(config)

Defined Under Namespace

Modules: Command, Configuration Classes: Doc

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_url: nil, output: $stdout, connect_timeout: nil, read_timeout: nil, write_timeout: nil, debug: nil, user_agent: nil) ⇒ Client

The initialize method sets up a new client instance with the specified configuration parameters.

This method is responsible for initializing a new Ollama::Client instance by processing various configuration options including the base URL, output stream, timeouts, and debug settings. It handles default values for the base URL by falling back to an environment variable, validates that the base URL is a valid HTTP or HTTPS URI, and extracts SSL verification settings from query parameters. The method also sets up instance variables for all configuration options, making them available for use in subsequent client operations.

Parameters:

  • base_url (String, nil) (defaults to: nil) —

    the base URL of the Ollama API endpoint, defaults to nil

  • output (IO) (defaults to: $stdout) —

    the output stream to be used for handling responses, defaults to $stdout

  • connect_timeout (Integer, nil) (defaults to: nil) —

    the connection timeout value in seconds, defaults to nil

  • read_timeout (Integer, nil) (defaults to: nil) —

    the read timeout value in seconds, defaults to nil

  • write_timeout (Integer, nil) (defaults to: nil) —

    the write timeout value in seconds, defaults to nil

  • debug (Boolean, nil) (defaults to: nil) —

    the debug flag indicating whether debug output is enabled, defaults to nil

  • user_agent (String, nil) (defaults to: nil) —

    the user agent string to be used for API requests, defaults to nil



44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/ollama/client.rb', line 44

def initialize(base_url: nil, output: $stdout, connect_timeout: nil, read_timeout: nil, write_timeout: nil, debug: nil, user_agent: nil)
  base_url.nil? and base_url = ENV.fetch('OLLAMA_URL') do
    raise ArgumentError,
      'missing :base_url parameter or OLLAMA_URL environment variable'
  end
  base_url.is_a? URI or base_url = URI.parse(base_url)
  base_url.is_a?(URI::HTTP) || base_url.is_a?(URI::HTTPS) or
    raise ArgumentError, "require #{base_url.inspect} to be http/https-URI"
  @ssl_verify_peer = base_url.query.to_s.split(?&).inject({}) { |h, l|
    h.merge Hash[*l.split(?=)]
  }['ssl_verify_peer'] != 'false'
  @base_url, @output, @connect_timeout, @read_timeout, @write_timeout, @debug, @user_agent =
    base_url, output, connect_timeout, read_timeout, write_timeout, debug, user_agent
end

Instance Attribute Details

#base_url ⇒ URI (readonly)

The base_url attribute reader returns the base URL used for making requests to the Ollama API.

Returns:

  • (URI) —

    the base URL configured for API requests



69
70
71
 
# File 'lib/ollama/client.rb', line 69

def base_url
  @base_url
end

#output ⇒ Object

The output attribute accessor allows reading and setting the output stream used for handling responses and messages.



64
65
66
 
# File 'lib/ollama/client.rb', line 64

def output
  @output
end

Class Method Details

.user_agent ⇒ String (private)

The user_agent method generates a formatted user agent string for API requests.

This method creates a user agent identifier that combines the class name with the library version, which is used to identify the client making requests to the Ollama API.

Returns:

  • (String) —

    a formatted user agent string in the format “Ollama::Client/1.2.3”



228
229
230
 
# File 'lib/ollama/client.rb', line 228

def self.user_agent
  '%s/%s' % [ self, Ollama::VERSION ]
end

Instance Method Details

#commands ⇒ Array<String>

The commands method retrieves and sorts the documented commands available in the client.

This method extracts all command annotations from the class, sorts them by their names, and returns an array containing only the command names in alphabetical order.

Returns:

  • (Array<String>) —

    an array of command names sorted alphabetically



126
127
128
 
# File 'lib/ollama/client.rb', line 126

def commands
  doc_annotations.sort_by(&:first).transpose.last
end

#excon(url) ⇒ Excon (private)

The excon method creates and returns a new Excon client instance configured with the receiver’s timeout and debugging settings.

This method constructs an Excon client object using the provided URL and configures it with connection, read, and write timeouts, SSL verification settings, and debug mode based on the instance variables of the receiver. It compacts the parameters hash to remove any nil values before passing them to Excon.new.

Parameters:

  • url (String) —

    the URL to be used for the Excon client

Returns:

  • (Excon) —

    a new Excon client instance configured with the specified parameters



244
245
246
247
248
249
250
251
252
253
 
# File 'lib/ollama/client.rb', line 244

def excon(url)
  params = {
    connect_timeout: @connect_timeout,
    read_timeout:    @read_timeout,
    write_timeout:   @write_timeout,
    ssl_verify_peer: @ssl_verify_peer,
    debug:           @debug,
  }.compact
  Excon.new(url, params)
end

#headers ⇒ Hash (private)

The headers method constructs and returns a hash of HTTP headers.

This method generates a set of standard HTTP headers required for making requests to the Ollama API, including the User-Agent and Content-Type. It uses the instance’s configured user agent or falls back to the class-level user agent if none is set.

Returns:

  • (Hash) —

    a hash containing the HTTP headers with keys ‘User-Agent’ and ‘Content-Type’



214
215
216
217
218
219
 
# File 'lib/ollama/client.rb', line 214

def headers
  {
    'User-Agent'   => @user_agent || self.class.user_agent,
    'Content-Type' => 'application/json; charset=utf-8',
  }
end

#help ⇒ Object

The help method displays a list of available commands to the output stream.

This method retrieves the sorted list of documented commands from the client and outputs them as a comma-separated string to the configured output stream. It is typically used to provide users with information about which commands are available for execution through the client interface.



137
138
139
 
# File 'lib/ollama/client.rb', line 137

def help
  @output.puts "Commands: %s" % commands.join(?,)
end

#inspect ⇒ String Also known as: to_s

The inspect method returns a string representation of the client instance.

This method provides a human-readable description of the client object, including its class name and the base URL it is configured to use.

Returns:

  • (String) —

    a string representation in the format “#<Ollama::Client@http://localhost:11434>”



198
199
200
 
# File 'lib/ollama/client.rb', line 198

def inspect
  "#<#{self.class}@#{@base_url}>"
end

#parse_json(string) ⇒ Ollama::Response? (private)

The parse_json method attempts to parse a JSON string into a structured object.

This method takes a string containing JSON data and converts it into a Ruby object using the JSON.parse method. It specifies Ollama::Response as the object class to ensure that the parsed data is wrapped in the appropriate response structure.

Parameters:

  • string (String) —

    the JSON string to be parsed

Returns:



266
267
268
269
270
271
 
# File 'lib/ollama/client.rb', line 266

def parse_json(string)
  JSON.parse(string, object_class: Ollama::Response)
rescue JSON::ParserError => e
  warn "Caught #{e.class}: #{e}"
  return
end

#request(method:, path:, handler:, body: nil, stream: nil) ⇒ Ollama::Client

The request method sends an HTTP request to the Ollama API and processes responses through a handler.

This method constructs an HTTP request to the specified API endpoint, handling both streaming and non-streaming responses. It manages different HTTP status codes, including success (200), not found (404), and other error cases. The method also includes comprehensive error handling for network-related issues such as socket errors and timeouts.

Parameters:

  • method (Symbol) —

    the HTTP method to use for the request (:get, :post, :delete)

  • path (String) —

    the API endpoint path to request

  • handler (Ollama::Handler) —

    the handler object responsible for processing API responses

  • body (String, nil) (defaults to: nil) —

    the request body content, if applicable

  • stream (TrueClass, FalseClass, nil) (defaults to: nil) —

    whether to enable streaming for the operation

Returns:

  • (Ollama::Client) —

    returns the client instance itself after initiating the request



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/ollama/client.rb', line 157

def request(method:, path:, handler:, body: nil, stream: nil)
  url = @base_url + path
  responses = Enumerator.new do |yielder|
    if stream
      response_block = -> chunk, remaining_bytes, total_bytes do
        response_line = parse_json(chunk)
        response_line and yielder.yield response_line
      end
      response = excon(url).send(method, headers:, body:, response_block:)
    else
      response = excon(url).send(method, headers:, body:)
    end

    case response.status
    when 200
      response.body.each_line do |l|
        response_line = parse_json(l)
        response_line and yielder.yield response_line
      end
    when 404
      raise Ollama::Errors::NotFoundError, "#{response.status} #{response.body.inspect}"
    else
      raise Ollama::Errors::Error, "#{response.status} #{response.body.inspect}"
    end
  end
  responses.each { |response| handler.call(response) }
  self
rescue Excon::Errors::SocketError => e
  raise Ollama::Errors::SocketError, "Caught #{e.class} #{e.message.inspect} for #{url.to_s.inspect}"
rescue Excon::Errors::Timeout => e
  raise Ollama::Errors::TimeoutError, "Caught #{e.class} #{e.message.inspect} for #{url.to_s.inspect}"
rescue Excon::Error => e
  raise Ollama::Errors::Error, "Caught #{e.class} #{e.message.inspect} for #{url.to_s.inspect}"
end

#ssl_verify_peer? ⇒ TrueClass, FalseClass

The ssl_verify_peer? method checks whether SSL peer verification is enabled.

This method returns a boolean value indicating if the client should verify the SSL certificate of the Ollama server during communication. It converts the internal SSL verification flag to a boolean value for easy checking.

Returns:

  • (TrueClass, FalseClass) —

    true if SSL peer verification is enabled, false otherwise



79
80
81
 
# File 'lib/ollama/client.rb', line 79

def ssl_verify_peer?
  !!@ssl_verify_peer
end