geminize 0.1.0

data/lib/geminize/models/memory.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Geminize
+  module Models
+    # Represents a message in the Gemini format
+    class Memory
+      # @return [String] The role of the sender (user, model, system)
+      attr_reader :role
+
+      # @return [Array<Hash>] The parts of the message (e.g., text content)
+      attr_reader :parts
+
+      # Initialize a new memory
+      # @param role [String] The role of the sender (user, model, system)
+      # @param parts [Array<Hash>] The parts of the message
+      def initialize(role = "", parts = nil)
+        @role = role
+        @parts = parts || [{text: ""}]
+        @parts.freeze
+      end
+
+      # Convert the memory to a hash suitable for API requests
+      # @return [Hash] The memory as a hash
+      def to_h
+        {
+          role: @role,
+          parts: @parts
+        }
+      end
+
+      # Convert the memory to a JSON string
+      # @param opts [Hash] JSON generate options
+      # @return [String] The memory as a JSON string
+      def to_json(*opts)
+        if opts.first && opts.first[:pretty]
+          JSON.pretty_generate(to_h)
+        else
+          to_h.to_json(*opts)
+        end
+      end
+
+      # Equality comparison
+      # @param other [Object] The object to compare with
+      # @return [Boolean] True if the objects are equal
+      def ==(other)
+        return false unless other.is_a?(Memory)
+        role == other.role && parts == other.parts
+      end
+
+      # Create a Memory object from a hash
+      # @param hash [Hash] The hash to create from
+      # @return [Memory] A new Memory object
+      def self.from_hash(hash)
+        # Handle both string and symbol keys
+        role = hash[:role] || hash["role"] || ""
+
+        # Handle parts
+        parts_data = hash[:parts] || hash["parts"]
+        parts = if parts_data
+          # Convert string keys to symbols
+          parts_data.map do |part|
+            if part.is_a?(Hash)
+              part_with_symbol_keys = {}
+              part.each { |k, v| part_with_symbol_keys[k.to_sym] = v }
+              part_with_symbol_keys
+            else
+              part
+            end
+          end
+        else
+          [{text: ""}]
+        end
+
+        new(role, parts)
+      end
+
+      # Create a Memory object from a JSON string
+      # @param json [String] The JSON string
+      # @return [Memory] A new Memory object
+      def self.from_json(json)
+        hash = JSON.parse(json)
+        from_hash(hash)
+      end
+    end
+  end
+end

data/lib/geminize/models/message.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Base class for messages in a conversation
+    class Message
+      # @return [String] The content of the message
+      attr_reader :content
+
+      # @return [Time] When the message was created
+      attr_reader :timestamp
+
+      # @return [String] The role of the message sender (user or model)
+      attr_reader :role
+
+      # Initialize a new message
+      # @param content [String] The content of the message
+      # @param role [String] The role of the message sender
+      # @param timestamp [Time, nil] When the message was created
+      def initialize(content, role, timestamp = nil)
+        @content = content
+        @role = role
+        @timestamp = timestamp || Time.now
+        validate!
+      end
+
+      # Convert the message to a hash suitable for the API
+      # @return [Hash] The message as a hash
+      def to_hash
+        {
+          role: @role,
+          parts: [
+            {
+              text: @content
+            }
+          ]
+        }
+      end
+
+      # Alias for to_hash for consistency with Ruby conventions
+      # @return [Hash] The message as a hash
+      def to_h
+        to_hash
+      end
+
+      # Check if this message is from the user
+      # @return [Boolean] True if the message is from the user
+      def user?
+        @role == "user"
+      end
+
+      # Check if this message is from the model
+      # @return [Boolean] True if the message is from the model
+      def model?
+        @role == "model"
+      end
+
+      # Serialize the message to a JSON string
+      # @return [String] The message as a JSON string
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # Create a message from a hash
+      # @param hash [Hash] The hash to create the message from
+      # @return [Message] A new message object
+      def self.from_hash(hash)
+        content = extract_content(hash)
+        role = hash["role"]
+        timestamp = hash["timestamp"] ? Time.parse(hash["timestamp"]) : Time.now
+
+        case role
+        when "user"
+          UserMessage.new(content, timestamp)
+        when "model"
+          ModelMessage.new(content, timestamp)
+        else
+          new(content, role, timestamp)
+        end
+      end
+
+      # Extract content from a message hash
+      # @param hash [Hash] The message hash
+      # @return [String] The extracted content
+      def self.extract_content(hash)
+        parts = hash["parts"]
+        return "" unless parts && !parts.empty?
+
+        parts.map { |part| part["text"] }.compact.join(" ")
+      end
+
+      private_class_method :extract_content
+
+      # Validate the message parameters
+      # @raise [Geminize::ValidationError] If any parameter is invalid
+      def validate!
+        validate_content!
+        validate_role!
+      end
+
+      # Validate the content parameter
+      # @raise [Geminize::ValidationError] If the content is invalid
+      def validate_content!
+        Validators.validate_not_empty!(@content, "Content")
+      end
+
+      # Validate the role parameter
+      # @raise [Geminize::ValidationError] If the role is invalid
+      def validate_role!
+        allowed_roles = ["user", "model", "system"]
+        unless allowed_roles.include?(@role)
+          raise Geminize::ValidationError.new(
+            "Role must be one of: #{allowed_roles.join(", ")}",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+    end
+
+    # Represents a message from the user
+    class UserMessage < Message
+      # Initialize a new user message
+      # @param content [String] The content of the message
+      # @param timestamp [Time, nil] When the message was created
+      def initialize(content, timestamp = nil)
+        super(content, "user", timestamp)
+      end
+    end
+
+    # Represents a message from the model
+    class ModelMessage < Message
+      # Initialize a new model message
+      # @param content [String] The content of the message
+      # @param timestamp [Time, nil] When the message was created
+      def initialize(content, timestamp = nil)
+        super(content, "model", timestamp)
+      end
+    end
+  end
+end

data/lib/geminize/models/model.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Represents an AI model from the Gemini API.
+    class Model
+      # @return [String] The unique identifier for the model
+      attr_reader :id
+
+      # @return [String] The display name of the model
+      attr_reader :name
+
+      # @return [String] The model version
+      attr_reader :version
+
+      # @return [String] The model description
+      attr_reader :description
+
+      # @return [Array<String>] List of supported capabilities (e.g., 'text', 'vision', 'embedding')
+      attr_reader :capabilities
+
+      # @return [Hash] Model limitations and constraints
+      attr_reader :limitations
+
+      # @return [Array<String>] Recommended use cases for this model
+      attr_reader :use_cases
+
+      # @return [Hash] Raw model data from the API
+      attr_reader :raw_data
+
+      # Create a new Model instance
+      # @param attributes [Hash] Model attributes
+      # @option attributes [String] :id The model ID
+      # @option attributes [String] :name The model name
+      # @option attributes [String] :version The model version
+      # @option attributes [String] :description The model description
+      # @option attributes [Array<String>] :capabilities List of capabilities
+      # @option attributes [Hash] :limitations Model limitations
+      # @option attributes [Array<String>] :use_cases Recommended use cases
+      # @option attributes [Hash] :raw_data Raw model data from API
+      def initialize(attributes = {})
+        @id = attributes[:id]
+        @name = attributes[:name]
+        @version = attributes[:version]
+        @description = attributes[:description]
+        @capabilities = attributes[:capabilities] || []
+        @limitations = attributes[:limitations] || {}
+        @use_cases = attributes[:use_cases] || []
+        @raw_data = attributes[:raw_data] || {}
+      end
+
+      # Check if model supports a specific capability
+      # @param capability [String] Capability to check for
+      # @return [Boolean] True if the model supports the capability
+      def supports?(capability)
+        capabilities.include?(capability.to_s.downcase)
+      end
+
+      # Convert model to a hash representation
+      # @return [Hash] Hash representation of the model
+      def to_h
+        {
+          id: id,
+          name: name,
+          version: version,
+          description: description,
+          capabilities: capabilities,
+          limitations: limitations,
+          use_cases: use_cases
+        }
+      end
+
+      # Convert model to JSON string
+      # @return [String] JSON representation of the model
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # Create a Model from API response data
+      # @param data [Hash] Raw API response data
+      # @return [Model] New Model instance
+      def self.from_api_data(data)
+        # Extract capabilities from model data
+        capabilities = extract_capabilities(data)
+
+        # Extract limitations from model data
+        limitations = extract_limitations(data)
+
+        # Extract use cases from model data
+        use_cases = extract_use_cases(data)
+
+        new(
+          id: data["name"]&.split("/")&.last,
+          name: data["displayName"],
+          version: extract_version(data),
+          description: data["description"],
+          capabilities: capabilities,
+          limitations: limitations,
+          use_cases: use_cases,
+          raw_data: data
+        )
+      end
+
+      private_class_method def self.extract_version(data)
+        # Extract version from model name or other fields
+        # Example: if name is "gemini-1.0-pro", extract "1.0"
+        if data["displayName"]
+          match = data["displayName"].match(/[-_](\d+\.\d+)[-_]/)
+          return match[1] if match
+
+          # Try another pattern (e.g., "Gemini 1.5 Pro")
+          match = data["displayName"].match(/\s(\d+\.\d+)\s/)
+          return match[1] if match
+        end
+        nil
+      end
+
+      private_class_method def self.extract_capabilities(data)
+        capabilities = []
+
+        # Example capability extraction, adjust based on actual API response format
+        capabilities << "text" if data.dig("supportedGenerationMethods")&.include?("generateText")
+        capabilities << "chat" if data.dig("supportedGenerationMethods")&.include?("generateMessage")
+        capabilities << "vision" if data.dig("supportedGenerationMethods")&.include?("generateContent") &&
+          data.dig("inputSetting", "supportMultiModal")
+        capabilities << "embedding" if data.dig("supportedGenerationMethods")&.include?("embedContent")
+
+        capabilities
+      end
+
+      private_class_method def self.extract_limitations(data)
+        limitations = {}
+
+        # Extract token limits
+        if data.dig("inputTokenLimit")
+          limitations[:input_token_limit] = data["inputTokenLimit"]
+        end
+
+        if data.dig("outputTokenLimit")
+          limitations[:output_token_limit] = data["outputTokenLimit"]
+        end
+
+        # Extract any other limitations from the API data
+        limitations
+      end
+
+      private_class_method def self.extract_use_cases(data)
+        # Extract use cases from the description or other fields
+        # This is a simple implementation - adjust based on actual API data
+        use_cases = []
+
+        if data["description"]
+          if data["description"].include?("chat")
+            use_cases << "conversational_ai"
+          end
+
+          if data["description"].include?("vision") || data["description"].include?("image")
+            use_cases << "image_understanding"
+          end
+
+          if data["description"].include?("embedding")
+            use_cases << "semantic_search"
+            use_cases << "clustering"
+          end
+        end
+
+        use_cases
+      end
+    end
+  end
+end

data/lib/geminize/models/model_list.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Geminize
+  module Models
+    # Represents a collection of AI models with filtering capabilities
+    class ModelList
+      include Enumerable
+      extend Forwardable
+
+      # @return [Array<Model>] The list of models
+      attr_reader :models
+
+      # Delegate array methods to the underlying models array
+      def_delegators :@models, :[], :size, :length, :empty?, :first, :last
+
+      # Create a new ModelList
+      # @param models [Array<Model>] Initial list of models
+      def initialize(models = [])
+        @models = models
+      end
+
+      # Implement Enumerable's required each method
+      # @yield [Model] Each model in the list
+      def each(&block)
+        @models.each(&block)
+      end
+
+      # Add a model to the list
+      # @param model [Model] The model to add
+      # @return [ModelList] The updated model list
+      def add(model)
+        @models << model
+        self
+      end
+
+      # Find a model by its ID
+      # @param id [String] The model ID to search for
+      # @return [Model, nil] The found model or nil
+      def find_by_id(id)
+        @models.find { |model| model.id == id }
+      end
+
+      # Find all models that support a specific capability
+      # @param capability [String] The capability to filter by
+      # @return [ModelList] A new ModelList containing only matching models
+      def filter_by_capability(capability)
+        filtered = @models.select { |model| model.supports?(capability) }
+        ModelList.new(filtered)
+      end
+
+      # Find all models that support vision capabilities
+      # @return [ModelList] A new ModelList containing only vision-capable models
+      def vision_models
+        filter_by_capability("vision")
+      end
+
+      # Find all models that support embedding capabilities
+      # @return [ModelList] A new ModelList containing only embedding-capable models
+      def embedding_models
+        filter_by_capability("embedding")
+      end
+
+      # Find all models that support text generation
+      # @return [ModelList] A new ModelList containing only text generation models
+      def text_models
+        filter_by_capability("text")
+      end
+
+      # Find all models that support chat/conversation
+      # @return [ModelList] A new ModelList containing only chat-capable models
+      def chat_models
+        filter_by_capability("chat")
+      end
+
+      # Filter models by version
+      # @param version [String] The version to filter by
+      # @return [ModelList] A new ModelList containing only matching models
+      def filter_by_version(version)
+        filtered = @models.select { |model| model.version == version }
+        ModelList.new(filtered)
+      end
+
+      # Filter models by name pattern
+      # @param pattern [String, Regexp] The pattern to match model names against
+      # @return [ModelList] A new ModelList containing only matching models
+      def filter_by_name(pattern)
+        pattern = Regexp.new(pattern.to_s, Regexp::IGNORECASE) if pattern.is_a?(String)
+        filtered = @models.select { |model| model.name&.match?(pattern) }
+        ModelList.new(filtered)
+      end
+
+      # Create a ModelList from API response data
+      # @param data [Hash] API response containing models
+      # @return [ModelList] New ModelList instance
+      def self.from_api_data(data)
+        models = []
+
+        # Process model data from API response
+        # The exact structure will depend on the Gemini API response format
+        if data.key?("models")
+          models = data["models"].map do |model_data|
+            Model.from_api_data(model_data)
+          end
+        end
+
+        new(models)
+      end
+
+      # Convert to array of hashes representation
+      # @return [Array<Hash>] Array of model hashes
+      def to_a
+        @models.map(&:to_h)
+      end
+
+      # Convert to JSON string
+      # @return [String] JSON representation
+      def to_json(*args)
+        to_a.to_json(*args)
+      end
+    end
+  end
+end

data/lib/geminize/models/stream_response.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Represents a streaming response chunk from the Gemini API
+    class StreamResponse
+      # @return [Hash] The raw API response data for this chunk
+      attr_reader :raw_chunk
+
+      # @return [String, nil] The text content in this chunk
+      attr_reader :text
+
+      # @return [String, nil] The finish reason if this is the last chunk
+      attr_reader :finish_reason
+
+      # @return [Hash, nil] Token usage metrics (only available in final chunk)
+      attr_reader :usage_metrics
+
+      # Initialize a new streaming response chunk
+      # @param chunk_data [Hash] The raw API response chunk
+      def initialize(chunk_data)
+        @raw_chunk = chunk_data
+        parse_chunk
+      end
+
+      # Check if this is the final chunk in the stream
+      # @return [Boolean] True if this is the final chunk
+      def final_chunk?
+        !@finish_reason.nil?
+      end
+
+      # Check if this chunk has usage metrics
+      # @return [Boolean] True if this chunk contains usage metrics
+      def has_usage_metrics?
+        !@usage_metrics.nil?
+      end
+
+      # Get the prompt token count if available
+      # @return [Integer, nil] Prompt token count or nil if not available
+      def prompt_tokens
+        return nil unless @usage_metrics
+        @usage_metrics["promptTokenCount"]
+      end
+
+      # Get the completion token count if available
+      # @return [Integer, nil] Completion token count or nil if not available
+      def completion_tokens
+        return nil unless @usage_metrics
+        @usage_metrics["candidatesTokenCount"]
+      end
+
+      # Get the total token count if available
+      # @return [Integer, nil] Total token count or nil if not available
+      def total_tokens
+        return nil unless @usage_metrics
+        (prompt_tokens || 0) + (completion_tokens || 0)
+      end
+
+      # Create a StreamResponse object from a raw API response chunk
+      # @param chunk_data [Hash] The raw API response chunk
+      # @return [StreamResponse] A new StreamResponse object
+      def self.from_hash(chunk_data)
+        new(chunk_data)
+      end
+
+      private
+
+      # Parse the chunk data and extract relevant information
+      def parse_chunk
+        @text = nil
+        @finish_reason = nil
+        @usage_metrics = nil
+
+        # First check if the response has the expected fields
+        if @raw_chunk.is_a?(Hash)
+          candidates = @raw_chunk["candidates"]
+          if candidates && !candidates.empty?
+            # Extract finish reason if available (last chunk)
+            if candidates.first["finishReason"]
+              @finish_reason = candidates.first["finishReason"]
+            end
+
+            # Extract text content if available
+            content = candidates.first["content"]
+            if content && content["parts"] && !content["parts"].empty?
+              parts_text = content["parts"].map { |part| part["text"] }.compact
+              @text = parts_text.join(" ") unless parts_text.empty?
+            end
+          end
+
+          # Extract usage metrics if available
+          if @raw_chunk["usageMetadata"]
+            @usage_metrics = @raw_chunk["usageMetadata"]
+          end
+        end
+      end
+    end
+  end
+end