llm-shell 0.9.2 → 0.10.0

data/lib/llm/shell/internal/llm.rb/lib/llm/providers/zai.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The ZAI class implements a provider for [zAI](https://docs.z.ai/guides/overview/quick-start).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.zai(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm, stream: $stdout)
+  #   bot.chat("Greetings Robot", role: :user).flush
+  class ZAI < OpenAI
+    ##
+    # @param [String] host A regional host or the default ("api.z.ai")
+    # @param key (see LLM::Provider#initialize)
+    def initialize(host: "api.z.ai", **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @return [LLM::XAI::Images]
+    def images
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def audio
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def moderations
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def responses
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def vector_stores
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # #see https://docs.z.ai/guides/llm/glm-4.5#glm-4-5-flash glm-4.5-flash
+    # @return [String]
+    def default_model
+      "glm-4.5-flash"
+    end
+
+    private
+
+    def completions_path
+      "/api/paas/v4/chat/completions"
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/response.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Response LLM::Response} encapsulates a response
+  # from an LLM provider. It is returned by all methods
+  # that make requests to a provider, and sometimes extended
+  # with provider-specific functionality.
+  class Response
+    require "json"
+
+    ##
+    # Returns the HTTP response
+    # @return [Net::HTTPResponse]
+    attr_reader :res
+
+    ##
+    # @param [Net::HTTPResponse] res
+    #  HTTP response
+    # @return [LLM::Response]
+    #  Returns an instance of LLM::Response
+    def initialize(res)
+      @res = res
+    end
+
+    ##
+    # Returns the response body
+    # @return [Hash, String]
+    def body
+      @body ||= case @res["content-type"]
+      when %r|\Aapplication/json\s*| then LLM::Object.from_hash(JSON.parse(@res.body))
+      else @res.body
+      end
+    end
+
+    ##
+    # Returns an inspection of the response object
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} @body=#{body.inspect} @res=#{@res.inspect}>"
+    end
+
+    ##
+    # Returns true if the response is successful
+    # @return [Boolean]
+    def ok?
+      Net::HTTPSuccess === @res
+    end
+
+    ##
+    # Returns true if the response is from the Files API
+    # @return [Boolean]
+    def file?
+      false
+    end
+
+    private
+
+    def method_missing(m, *args, **kwargs, &b)
+      body.respond_to?(m) ? body[m.to_s] : super
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      body.respond_to?(m) || super
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/array.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Array LLM::Schema::Array} class represents an
+  # array value in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
+  # can act as constraints.
+  class Array < Leaf
+    def initialize(items)
+      @items = items
+    end
+
+    def to_h
+      super.merge!({type: "array", items:})
+    end
+
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    private
+
+    attr_reader :items
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/boolean.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Boolean LLM::Schema::Boolean} class represents a
+  # boolean value in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class Boolean < Leaf
+    def to_h
+      super.merge!({type: "boolean"})
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/integer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Integer LLM::Schema::Integer} class represents a
+  # whole number value in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
+  # can act as constraints.
+  class Integer < Leaf
+    ##
+    # Constrain the number to a minimum value
+    # @param [Integer] i The minimum value
+    # @return [LLM::Schema::Number] Returns self
+    def min(i)
+      tap { @minimum = i }
+    end
+
+    ##
+    # Constrain the number to a maximum value
+    # @param [Integer] i The maximum value
+    # @return [LLM::Schema::Number] Returns self
+    def max(i)
+      tap { @maximum = i }
+    end
+
+    ##
+    # Constrain the number to a multiple of a given value
+    # @param [Integer] i The multiple
+    # @return [LLM::Schema::Number] Returns self
+    def multiple_of(i)
+      tap { @multiple_of = i }
+    end
+
+    def to_h
+      super.merge!({
+        type: "integer",
+        minimum: @minimum,
+        maximum: @maximum,
+        multipleOf: @multiple_of
+      }).compact
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/leaf.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Leaf LLM::Schema::Leaf} class is the
+  # superclass of all values that can appear in a JSON schema.
+  # See the instance methods of {LLM::Schema LLM::Schema} for
+  # an example of how to create instances of {LLM::Schema::Leaf LLM::Schema::Leaf}
+  # through its subclasses.
+  class Leaf
+    def initialize
+      @description = nil
+      @default = nil
+      @enum = nil
+      @required = nil
+      @const = nil
+    end
+
+    ##
+    # Set the description of a leaf
+    # @param [String] str The description
+    # @return [LLM::Schema::Leaf]
+    def description(str)
+      tap { @description = str }
+    end
+
+    ##
+    # Set the default value of a leaf
+    # @param [Object] value The default value
+    # @return [LLM::Schema::Leaf]
+    def default(value)
+      tap { @default = value }
+    end
+
+    ##
+    # Set the allowed values of a leaf
+    # @see https://tour.json-schema.org/content/02-Primitive-Types/07-Enumerated-Values-II Enumerated Values
+    # @param [Array] values The allowed values
+    # @return [LLM::Schema::Leaf]
+    def enum(*values)
+      tap { @enum = values }
+    end
+
+    ##
+    # Set the value of a leaf to be a constant value
+    # @see https://tour.json-schema.org/content/02-Primitive-Types/08-Defining-Constant-Values Constant Values
+    # @param [Object] value The constant value
+    # @return [LLM::Schema::Leaf]
+    def const(value)
+      tap { @const = value }
+    end
+
+    ##
+    # Denote a leaf as required
+    # @return [LLM::Schema::Leaf]
+    def required
+      tap { @required = true }
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      {description: @description, default: @default, enum: @enum}.compact
+    end
+
+    ##
+    # @return [String]
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    ##
+    # @return [Boolean]
+    def required?
+      @required
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/null.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Null LLM::Schema::Null} class represents a
+  # null value in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf}.
+  class Null < Leaf
+    def to_h
+      super.merge!({type: "null"})
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/number.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Number LLM::Schema::Number} class represents a
+  # a number (either whole or decimal) value in a JSON schema. It is a
+  # subclass of {LLM::Schema::Leaf LLM::Schema::Leaf} and provides
+  # methods that can act as constraints.
+  class Number < Leaf
+    ##
+    # Constrain the number to a minimum value
+    # @param [Integer, Float] i The minimum value
+    # @return [LLM::Schema::Number] Returns self
+    def min(i)
+      tap { @minimum = i }
+    end
+
+    ##
+    # Constrain the number to a maximum value
+    # @param [Integer, Float] i The maximum value
+    # @return [LLM::Schema::Number] Returns self
+    def max(i)
+      tap { @maximum = i }
+    end
+
+    ##
+    # Constrain the number to a multiple of a given value
+    # @param [Integer, Float] i The multiple
+    # @return [LLM::Schema::Number] Returns self
+    def multiple_of(i)
+      tap { @multiple_of = i }
+    end
+
+    def to_h
+      super.merge!({
+        type: "number",
+        minimum: @minimum,
+        maximum: @maximum,
+        multipleOf: @multiple_of
+      }).compact
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/object.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Object LLM::Schema::Object} class represents an
+  # object value in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
+  # can act as constraints.
+  class Object < Leaf
+    attr_reader :properties
+
+    def initialize(properties)
+      @properties = properties
+    end
+
+    def to_h
+      super.merge!({type: "object", properties:, required:})
+    end
+
+    ##
+    # @raise [TypeError]
+    #  When given an object other than Object
+    # @return [LLM::Schema::Object]
+    #  Returns self
+    def merge!(other)
+      raise TypeError unless self.class === self
+      @properties.merge!(other.properties)
+      self
+    end
+
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    private
+
+    def required
+      @properties.filter_map {  _2.required? ? _1 : nil }
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/string.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::String LLM::Schema::String} class represents a
+  # string value in a JSON schema. It is a subclass of
+  # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
+  # can act as constraints.
+  class String < Leaf
+    ##
+    # Constrain the string to a minimum length
+    # @param [Integer] i The minimum length
+    # @return [LLM::Schema::String] Returns self
+    def min(i)
+      tap { @minimum = i }
+    end
+
+    ##
+    # Constrain the string to a maximum length
+    # @param [Integer] i The maximum length
+    # @return [LLM::Schema::String] Returns self
+    def max(i)
+      tap { @maximum = i }
+    end
+
+    def to_h
+      super.merge!({
+        type: "string",
+        minLength: @minimum,
+        maxLength: @maximum
+      }).compact
+    end
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module JSON
+end unless defined?(JSON)
+
+class LLM::Schema
+  VERSION = "0.1.0"
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/schema.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Schema LLM::Schema} class represents a JSON schema,
+# and provides methods that let you describe and produce a schema
+# that can be used in various contexts that include the validation
+# and generation of JSON data.
+#
+# @see https://json-schema.org/ JSON Schema Specification
+# @see https://tour.json-schema.org/ JSON Schema Tour
+#
+# @example
+#  schema = LLM::Schema.new
+#  schema.object({
+#    name: schema.string.enum("John", "Jane").required,
+#    age: schema.integer.required,
+#    hobbies: schema.array(schema.string, schema.null).required,
+#    address: schema.object({street: schema.string}).required,
+#  })
+class LLM::Schema
+  require_relative "schema/version"
+  require_relative "schema/leaf"
+  require_relative "schema/object"
+  require_relative "schema/array"
+  require_relative "schema/string"
+  require_relative "schema/number"
+  require_relative "schema/integer"
+  require_relative "schema/boolean"
+  require_relative "schema/null"
+
+  ##
+  # Returns an object
+  # @param [Hash] properties A hash of properties
+  # @return [LLM::Schema::Object]
+  def object(properties)
+    Object.new(properties)
+  end
+
+  ##
+  # Returns an array
+  # @param [Array] items An array of items
+  # @return [LLM::Schema::Array]
+  def array(*items)
+    Array.new(*items)
+  end
+
+  ##
+  # Returns a string
+  # @return [LLM::Schema::String]
+  def string
+    String.new
+  end
+
+  ##
+  # Returns a number
+  # @return [LLM::Schema::Number] a number
+  def number
+    Number.new
+  end
+
+  ##
+  # Returns an integer
+  # @return [LLM::Schema::Integer]
+  def integer
+    Integer.new
+  end
+
+  ##
+  # Returns a boolean
+  # @return [LLM::Schema::Boolean]
+  def boolean
+    Boolean.new
+  end
+
+  ##
+  # Returns null
+  # @return [LLM::Schema::Null]
+  def null
+    Null.new
+  end
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/server_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::ServerTool LLM::ServerTool} class represents a platform-native tool
+# that can be activated by an LLM provider. Unlike {LLM::Function LLM::Function},
+# these tools are pre-defined by the provider and their capabilities
+# are already known to the underlying LLM.
+#
+# @example
+#   #!/usr/bin/env ruby
+#   llm = LLM.gemini ENV["KEY"]
+#   bot = LLM::Bot.new(llm, tools: [LLM::ServerTool.new(:google_search)])
+#   bot.chat("Summarize today's news", role: :user)
+#   print bot.messages.find(&:assistant?).content, "\n"
+class LLM::ServerTool < Struct.new(:name, :options, :provider)
+  ##
+  # @return [String]
+  def to_json(...)
+    to_h.to_json(...)
+  end
+
+  ##
+  # @return [Hash]
+  def to_h
+    case provider.class.to_s
+    when "LLM::Anthropic" then options.merge("name" => name.to_s)
+    when "LLM::Gemini" then {name => options}
+    else options.merge("type" => name.to_s)
+    end
+  end
+  alias_method :to_hash, :to_h
+end

data/lib/llm/shell/internal/llm.rb/lib/llm/tool/param.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Param LLM::Tool::Param} module extends the
+  # {LLM::Tool LLM::Tool} class with a "param" method that can
+  # define a parameter for simple types. For complex types, use
+  # {LLM::Tool.params LLM::Tool.params} instead.
+  #
+  # @example
+  #   class Greeter < LLM::Tool
+  #     name "greeter"
+  #     description "Greets the user"
+  #     param :name, String, "The user's name", required: true
+  #
+  #     def call(name:)
+  #       puts "Hello, #{name}!"
+  #     end
+  #   end
+  module Param
+    ##
+    # @param name [Symbol]
+    #   The name of a parameter
+    # @param type [Class, Symbol]
+    #   The parameter type (eg String)
+    # @param description [String]
+    #   The description of a property
+    # @param options [Hash]
+    #   A hash of options for the parameter
+    # @option options [Boolean] :required
+    #   Whether or not the parameter is required
+    # @option options [Object] :default
+    #   The default value for a given property
+    # @option options [Array<String>] :enum
+    #   One or more possible values for a param
+    def param(name, type, description, options = {})
+      lock do
+        function.params do |schema|
+          leaf = schema.public_send(Utils.resolve(type))
+          leaf = Utils.setup(leaf, description, options)
+          schema.object(name => leaf)
+        end
+      end
+    end
+
+    ##
+    # @api private
+    module Utils
+      extend self
+
+      def resolve(type)
+        if type == String
+          :string
+        elsif type == Integer
+          :integer
+        elsif type == Float
+          :number
+        else
+          type
+        end
+      end
+
+      def setup(leaf, description, options)
+        required = options.fetch(:required, false)
+        default = options.fetch(:default, nil)
+        enum = options.fetch(:enum, nil)
+        leaf.required if required
+        leaf.description(description) if description
+        leaf.default(default) if default
+        leaf.enum(enum) if enum
+        leaf
+      end
+    end
+  end
+end