active_genie 0.25.1 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c91ce12dad609d42839c1d71d172ae5ed6922357374097ec29de8bcbb0c7a3fd
-  data.tar.gz: 4de847656eff030d4bdf93bf8f492584c5ace9458af7f13b962941eabbe1e308
+  metadata.gz: 848de45258263935accfd02ce16d14eb96c6b5a73f42979fe0a74e5b9b746fb4
+  data.tar.gz: cb1f9eb843559a7040dc20b1442e120325d734b7610a75b57bfde91cba63dc4e
 SHA512:
-  metadata.gz: 0c9c8fbf3f4e940408d3a1051f280aec1da7d196ac61ba1fa02812b68376411a74198a44fb888fbd0c3cf385d39330c7c2265a3a73448c6b2a9179a1c29bdd48
-  data.tar.gz: 2d7001c0bb3b2ce274ecef96eaf10a0228d949f447d5df7cccca4f686c6f2b14273c71d376f5f7b8e39d9448a3ee27bd2f1358f4a7a69cdad2ac4fd34dfac574
+  metadata.gz: 12f38e95348fae6beab3cc7a74cfdefc132ef9e8308303f2df04a40703d6f86a9fe6f859c958dc8a1d9fca52d41ceb1f380324c5b34d5d13e0bde4a702362830
+  data.tar.gz: c512e6ae0fb0b47403f9c2fc3be5c55a458320877fe2aae93780af1fab4e95b2fa1553ff60a62ec30653933f77a5c8892e96227ee637e8ab03a30cf0c9ad177d

data/README.md

@@ -118,13 +118,13 @@ AI-powered battle evaluation system that determines winners between two players
 ```ruby
 require 'active_genie'
 
-player_1 = "Implementation uses dependency injection for better testability"
-player_2 = "Code has high test coverage but tightly coupled components"
+player_a = "Implementation uses dependency injection for better testability"
+player_b = "Code has high test coverage but tightly coupled components"
 criteria = "Evaluate code quality and maintainability"
 
 result = ActiveGenie::Battle.call(
-  player_1,
-  player_2,
+  player_a,
+  player_b,
   criteria,
   config: { provider: :google, model: 'gemini-2.0-flash-lite' } # optional
 )
@@ -238,7 +238,7 @@ ActiveGenie.configure do |config|
   config.llm.client = InternalCompanyApi
 end
 # or
-ActiveGenie::Battle.call('player_1', 'player_2', 'criteria', { client: InternalCompanyApi })
+ActiveGenie::Battle.call('player_a', 'player_b', 'criteria', { client: InternalCompanyApi })
 ```
 
 ## Observability

data/VERSION

@@ -1 +1 @@
-0.25.1
+0.26.0

data/lib/active_genie/battle/README.md

@@ -12,11 +12,11 @@ AI-powered battle evaluation system that determines winners between two players
 Evaluate a battle between two players with simple text content:
 
 ```ruby
-player_1 = "Implementation uses dependency injection for better testability"
-player_2 = "Code has high test coverage but tightly coupled components"
+player_a = "Implementation uses dependency injection for better testability"
+player_b = "Code has high test coverage but tightly coupled components"
 criteria = "Evaluate code quality and maintainability"
 
-result = ActiveGenie::Battle.call(player_1, player_2, criteria)
+result = ActiveGenie::Battle.call(player_a, player_b, criteria)
 # => {
 #      winner_player: "Implementation uses dependency injection for better testability",
 #      reasoning: "Player A's implementation demonstrates better maintainability through dependency injection,
@@ -27,13 +27,13 @@ result = ActiveGenie::Battle.call(player_1, player_2, criteria)
 ```
 
 ## Interface
-### .call(player_1, player_2, criteria, config: {})
-- `player_1` [String, Hash] - The content or submission from the first player
-- `player_2` [String, Hash] - The content or submission from the second player
+### .call(player_a, player_b, criteria, config: {})
+- `player_a` [String, Hash] - The content or submission from the first player
+- `player_b` [String, Hash] - The content or submission from the second player
 - `criteria` [String] - The evaluation criteria or rules to assess against
 - `config` [Hash] - Additional configuration config that modify the battle evaluation behavior
 
 Returns a Hash containing:
-- `winner_player` [String, Hash] - The winning player's content (either player_1 or player_2)
+- `winner_player` [String, Hash] - The winning player's content (either player_a or player_b)
 - `reasoning` [String] - Detailed explanation of why the winner was chosen
 - `what_could_be_changed_to_avoid_draw` [String] - A suggestion on how to avoid a draw

data/lib/active_genie/battle/generalist.json

@@ -0,0 +1,36 @@
+{
+  "name": "battle_evaluation",
+  "description": "Evaluate a battle between player_a and player_b using predefined criteria and identify the winner.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "player_a_sell_himself": {
+        "type": "string",
+        "description": "player_a presents their strengths and how they meet the criteria. Max of 100 words."
+      },
+      "player_b_sell_himself": {
+        "type": "string",
+        "description": "player_b presents their strengths and how they meet the criteria. Max of 100 words."
+      },
+      "player_a_arguments": {
+        "type": "string",
+        "description": "player_a arguments for why they should be the winner compared to player_b. Max of 100 words."
+      },
+      "player_b_counter": {
+        "type": "string",
+        "description": "player_b counter arguments for why they should be the winner compared to player_a. Max of 100 words."
+      },
+      "impartial_judge_winner_reasoning": {
+        "type": "string",
+        "description": "The detailed reasoning about why the impartial judge chose the winner. Max of 100 words."
+      },
+      "impartial_judge_winner": {
+        "type": "string",
+        "description": "Who is the winner based on the impartial judge reasoning?",
+        "enum": ["player_a", "player_b"]
+      }
+    },
+    "required": ["player_a_sell_himself", "player_b_sell_himself", "player_a_arguments", "player_b_counter",
+                 "impartial_judge_winner_reasoning", "impartial_judge_winner"]
+  }
+}

data/lib/active_genie/battle/generalist.md

@@ -0,0 +1,16 @@
+Based on two players, player_a and player_b, they will battle against each other based on criteria. Criteria are vital as they provide a clear metric to compare the players. Follow these criteria strictly.
+
+# Steps
+1. player_a presents their strengths and how they meet the criteria. Max of 100 words.
+2. player_b presents their strengths and how they meet the criteria. Max of 100 words.
+3. player_a argues why they should be the winner compared to player_b. Max of 100 words.
+4. player_b counter-argues why they should be the winner compared to player_a. Max of 100 words.
+5. The impartial judge chooses the winner.
+
+# Output Format
+- The impartial judge chooses this player as the winner.
+
+# Notes
+- Avoid resulting in a draw. Use reasoning or make fair assumptions if needed.
+- Critically assess each player's adherence to the criteria.
+- Clearly communicate the reasoning behind your decision.

data/lib/active_genie/battle/generalist.rb

@@ -19,17 +19,17 @@ module ActiveGenie
         new(...).call
       end
 
-      # @param player_1 [String] The content or submission from the first player
-      # @param player_2 [String] The content or submission from the second player
+      # @param player_a [String] The content or submission from the first player
+      # @param player_b [String] The content or submission from the second player
       # @param criteria [String] The evaluation criteria or rules to assess against
       # @param config [Hash] Additional configuration options that modify the battle evaluation behavior
       # @return [Hash] The evaluation result containing the winner and reasoning
-      #   @return [String] :winner The winner, either player_1 or player_2
+      #   @return [String] :winner The winner, either player_a or player_b
       #   @return [String] :reasoning Detailed explanation of why the winner was chosen
       #   @return [String] :what_could_be_changed_to_avoid_draw A suggestion on how to avoid a draw
-      def initialize(player_1, player_2, criteria, config: {})
-        @player_1 = player_1
-        @player_2 = player_2
+      def initialize(player_a, player_b, criteria, config: {})
+        @player_a = player_a
+        @player_b = player_b
         @criteria = criteria
         @config = ActiveGenie.configuration.merge(config)
       end
@@ -38,8 +38,8 @@ module ActiveGenie
         messages = [
           {  role: 'system', content: PROMPT },
           {  role: 'user', content: "criteria: #{@criteria}" },
-          {  role: 'user', content: "player_1: #{@player_1}" },
-          {  role: 'user', content: "player_2: #{@player_2}" }
+          {  role: 'user', content: "player_a: #{@player_a}" },
+          {  role: 'user', content: "player_b: #{@player_b}" }
         ]
 
         response = ::ActiveGenie::Clients::UnifiedClient.function_calling(
@@ -50,8 +50,8 @@ module ActiveGenie
 
         ActiveGenie::Logger.call({
                                    code: :battle,
-                                   player_1: @player_1[0..30],
-                                   player_2: @player_2[0..30],
+                                   player_a: @player_a[0..30],
+                                   player_b: @player_b[0..30],
                                    criteria: @criteria[0..30],
                                    winner: response['impartial_judge_winner'],
                                    reasoning: response['impartial_judge_winner_reasoning']
@@ -60,73 +60,20 @@ module ActiveGenie
         response_formatted(response)
       end
 
+      PROMPT = File.read(File.join(__dir__, 'generalist.md'))
+      FUNCTION = JSON.parse(File.read(File.join(__dir__, 'generalist.json')), symbolize_names: true)
+
       private
 
       def response_formatted(response)
         winner = response['impartial_judge_winner']
-        loser = case response['impartial_judge_winner']
-                when 'player_1' then 'player_2'
-                when 'player_2' then 'player_1'
+        loser = case winner
+                when 'player_a' then 'player_b'
+                when 'player_b' then 'player_a'
                 end
 
         { 'winner' => winner, 'loser' => loser, 'reasoning' => response['impartial_judge_winner_reasoning'] }
       end
-
-      PROMPT = <<~PROMPT
-        Based on two players, player_1 and player_2, they will battle against each other based on criteria. Criteria are vital as they provide a clear metric to compare the players. Follow these criteria strictly.
-
-        # Steps
-        1. player_1 presents their strengths and how they meet the criteria. Max of 100 words.
-        2. player_2 presents their strengths and how they meet the criteria. Max of 100 words.
-        3. player_1 argues why they should be the winner compared to player_2. Max of 100 words.
-        4. player_2 counter-argues why they should be the winner compared to player_1. Max of 100 words.
-        5. The impartial judge chooses the winner.
-
-        # Output Format
-        - The impartial judge chooses this player as the winner.
-
-        # Notes
-        - Avoid resulting in a draw. Use reasoning or make fair assumptions if needed.
-        - Critically assess each player's adherence to the criteria.
-        - Clearly communicate the reasoning behind your decision.
-      PROMPT
-
-      FUNCTION = {
-        name: 'battle_evaluation',
-        description: 'Evaluate a battle between player_1 and player_2 using predefined criteria and identify the winner.',
-        parameters: {
-          type: 'object',
-          properties: {
-            player_1_sell_himself: {
-              type: 'string',
-              description: 'player_1 presents their strengths and how they meet the criteria. Max of 100 words.'
-            },
-            player_2_sell_himself: {
-              type: 'string',
-              description: 'player_2 presents their strengths and how they meet the criteria. Max of 100 words.'
-            },
-            player_1_arguments: {
-              type: 'string',
-              description: 'player_1 arguments for why they should be the winner compared to player_2. Max of 100 words.'
-            },
-            player_2_counter: {
-              type: 'string',
-              description: 'player_2 counter arguments for why they should be the winner compared to player_1. Max of 100 words.'
-            },
-            impartial_judge_winner_reasoning: {
-              type: 'string',
-              description: 'The detailed reasoning about why the impartial judge chose the winner. Max of 100 words.'
-            },
-            impartial_judge_winner: {
-              type: 'string',
-              description: 'Who is the winner based on the impartial judge reasoning?',
-              enum: %w[player_1 player_2]
-            }
-          },
-          required: %w[player_1_sell_himself player_2_sell_himself player_1_arguments player_2_counter
-                       impartial_judge_winner_reasoning impartial_judge_winner]
-        }
-      }.freeze
     end
   end
 end

data/lib/active_genie/clients/providers/anthropic_client.rb

@@ -3,17 +3,12 @@
 require 'json'
 require 'net/http'
 require 'uri'
-require_relative './base_client'
+require_relative 'base_client'
 
 module ActiveGenie
   module Clients
     # Client for interacting with the Anthropic (Claude) API with json response
     class AnthropicClient < BaseClient
-      class AnthropicError < ClientError; end
-      class RateLimitError < AnthropicError; end
-
-      ANTHROPIC_ENDPOINT = '/v1/messages'
-
       # Requests structured JSON output from the Anthropic Claude model based on a schema.
       #
       # @param messages [Array<Hash>] A list of messages representing the conversation history.
@@ -22,56 +17,82 @@ module ActiveGenie
       # @param function [Hash] A JSON schema definition describing the desired output format.
       # @return [Hash, nil] The parsed JSON object matching the schema, or nil if parsing fails or content is empty.
       def function_calling(messages, function)
-        model = @config.llm.model || @config.providers.anthropic.tier_to_model(@config.llm.model_tier)
-
-        system_message = messages.find { |m| m[:role] == 'system' }&.dig(:content) || ''
-        user_messages = messages.select { |m| %w[user assistant].include?(m[:role]) }
-                                .map { |m| { role: m[:role], content: m[:content] } }
-
-        anthropic_function = function.dup
-        anthropic_function[:input_schema] = function[:parameters]
-        anthropic_function.delete(:parameters)
+        system_message, user_messages = split_messages(messages)
+        tool = function_to_tool(function)
 
         payload = {
           model:,
           system: system_message,
           messages: user_messages,
-          tools: [anthropic_function],
-          tool_choice: { name: anthropic_function[:name], type: 'tool' },
+          tools: [tool],
+          tool_choice: { name: tool[:name], type: 'tool' },
           max_tokens: @config.llm.max_tokens,
           temperature: @config.llm.temperature || 0
         }
 
-        headers = {
-          'x-api-key': @config.providers.anthropic.api_key,
-          'anthropic-version': @config.providers.anthropic.anthropic_version
-        }.compact
-
-        retry_with_backoff do
-          start_time = Time.now
-          url = "#{@config.providers.anthropic.api_url}#{ANTHROPIC_ENDPOINT}"
+        request(payload).dig('content', 0, 'input')
+      end
 
-          response = post(url, payload, headers: headers)
+      ANTHROPIC_ENDPOINT = '/v1/messages'
 
-          content = response.dig('content', 0, 'input')
+      private
 
-          ActiveGenie::Logger.call({
-                                     code: :llm_usage,
-                                     input_tokens: response.dig('usage', 'input_tokens'),
-                                     output_tokens: response.dig('usage', 'output_tokens'),
-                                     total_tokens: response.dig('usage',
-                                                                'input_tokens') + response.dig('usage',
-                                                                                               'output_tokens'),
-                                     model: payload[:model],
-                                     duration: Time.now - start_time,
-                                     usage: response['usage']
-                                   })
+      def split_messages(messages)
+        system_message = messages.find { |m| m[:role] == 'system' }&.dig(:content) || ''
+        user_messages = messages.select { |m| %w[user assistant].include?(m[:role]) }
+                                .map { |m| m.slice(:role, :content) }
 
-          ActiveGenie::Logger.call({ code: :function_calling, payload:, parsed_response: content })
+        [system_message, user_messages]
+      end
 
-          content
+      def function_to_tool(function)
+        function.dup.tap do |f|
+          f[:input_schema] = function[:parameters]
+          f.delete(:parameters)
         end
       end
+
+      def request(payload)
+        response = post(url, payload, headers:)
+
+        ActiveGenie::Logger.call(
+          {
+            code: :llm_usage,
+            input_tokens: response.dig('usage', 'input_tokens'),
+            output_tokens: response.dig('usage', 'output_tokens'),
+            total_tokens: response.dig('usage',
+                                       'input_tokens') + response.dig('usage',
+                                                                      'output_tokens'),
+            model: payload[:model],
+            usage: response['usage']
+          }
+        )
+        ActiveGenie::Logger.call(
+          {
+            code: :function_calling,
+            fine_tune: true,
+            payload:,
+            parsed_response: response.dig('content', 0, 'input')
+          }
+        )
+
+        response
+      end
+
+      def url
+        "#{@config.providers.anthropic.api_url}#{ANTHROPIC_ENDPOINT}"
+      end
+
+      def model
+        @config.llm.model || @config.providers.anthropic.tier_to_model(@config.llm.model_tier)
+      end
+
+      def headers
+        {
+          'x-api-key': @config.providers.anthropic.api_key,
+          'anthropic-version': @config.providers.anthropic.anthropic_version
+        }.compact
+      end
     end
   end
 end

data/lib/active_genie/clients/providers/base_client.rb

@@ -7,7 +7,7 @@ module ActiveGenie
 
       DEFAULT_HEADERS = {
         'Content-Type': 'application/json',
-        'Accept': 'application/json',
+        Accept: 'application/json',
         'User-Agent': "ActiveGenie/#{ActiveGenie::VERSION}"
       }.freeze
 
@@ -29,7 +29,8 @@ module ActiveGenie
       def get(endpoint, params: {}, headers: {})
         uri = build_uri(endpoint, params)
         request = Net::HTTP::Get.new(uri)
-        execute_request(uri, request, headers)
+        apply_headers(request, headers)
+        execute_request(uri, request)
       end
 
       # Make a POST request to the specified endpoint
@@ -42,7 +43,8 @@ module ActiveGenie
         uri = build_uri(endpoint, params)
         request = Net::HTTP::Post.new(uri)
         request.body = payload.to_json
-        execute_request(uri, request, headers)
+        apply_headers(request, headers)
+        execute_request(uri, request)
       end
 
       # Make a PUT request to the specified endpoint
@@ -55,7 +57,8 @@ module ActiveGenie
         uri = build_uri(endpoint)
         request = Net::HTTP::Put.new(uri)
         request.body = payload.to_json
-        execute_request(uri, request, headers)
+        apply_headers(request, headers)
+        execute_request(uri, request)
       end
 
       # Make a DELETE request to the specified endpoint
@@ -67,58 +70,40 @@ module ActiveGenie
       def delete(endpoint, headers: {}, params: {})
         uri = build_uri(endpoint, params)
         request = Net::HTTP::Delete.new(uri)
-        execute_request(uri, request, headers)
+        apply_headers(request, headers)
+        execute_request(uri, request)
       end
 
       protected
 
-      # Execute a request with retry logic and proper error handling
-      #
-      # @param uri [URI] The URI for the request
-      # @param request [Net::HTTP::Request] The request object
-      # @param headers [Hash] Additional headers to include
-      # @return [Hash, nil] The parsed JSON response or nil if empty
-      def execute_request(uri, request, headers)
+      def execute_request(uri, request)
         start_time = Time.now
 
-        # Apply headers
-        apply_headers(request, headers)
+        response = http_request(request, uri)
 
-        http = create_http_client(uri)
+        raise ClientError, "Unexpected response: #{response.code} - #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
-        response = http.request(request)
+        parsed_response = parse_response(response)
 
-        case response
-        when Net::HTTPSuccess
-          parsed_response = parse_response(response)
+        log_request_details(uri:, request:, response:, start_time:, parsed_response:)
 
-          log_request_details(
-            uri: uri,
-            method: request.method,
-            status: response.code,
-            duration: Time.now - start_time,
-            response: parsed_response
-          )
-
-          parsed_response
-        when Net::HTTPTooManyRequests, Net::HTTPClientError, Net::HTTPServerError
-          raise ClientError, "HTTP Error: #{response.code} - #{response.body}"
-        else
-          raise ClientError, "Unexpected response: #{response.code} - #{response.body}"
-        end
+        parsed_response
       end
 
       # Create and configure an HTTP client
       #
       # @param uri [URI] The URI for the request
       # @return [Net::HTTP] Configured HTTP client
-      def create_http_client(uri)
+      def http_request(request, uri)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = (uri.scheme == 'https')
         http.verify_mode = OpenSSL::SSL::VERIFY_PEER
         http.read_timeout = @config.llm.read_timeout || DEFAULT_TIMEOUT
         http.open_timeout = @config.llm.open_timeout || DEFAULT_OPEN_TIMEOUT
-        http
+
+        retry_with_backoff do
+          http.request(request)
+        end
       end
 
       # Apply headers to the request
@@ -165,51 +150,53 @@ module ActiveGenie
       # Log request details if logging is enabled
       #
       # @param details [Hash] Request and response details
-      def log_request_details(details)
+      def log_request_details(uri:, request:, response:, start_time:, parsed_response:)
         ActiveGenie::Logger.call(
           {
             code: :http_request,
-            uri: details[:uri].to_s,
-            method: details[:method],
-            status: details[:status],
-            duration: details[:duration],
-            response_size: details[:response].to_s.bytesize
+            uri: uri.to_s,
+            method: request.method,
+            status: response.code,
+            duration: Time.now - start_time,
+            response_size: parsed_response.to_s.bytesize
           }
         )
       end
 
-      # Retry a block with exponential backoff
-      #
-      # @yield The block to retry
-      # @return [Object] The result of the block
+      # FIXME: split the retry_with_backoff method into a separate class
+      # rubocop:disable Metrics/MethodLength
       def retry_with_backoff
-        max_retries = @config.llm.max_retries || DEFAULT_MAX_RETRIES
-        retry_delay = @config.llm.retry_delay || DEFAULT_RETRY_DELAY
-
         retries = 0
 
         begin
           yield
-        rescue Net::HTTPError => e
-          raise unless retries < max_retries
+        rescue Net::OpenTimeout, Net::ReadTimeout, ClientError => e
+          raise if retries > max_retries
 
           sleep_time = retry_delay * (2**retries)
           retries += 1
 
           ActiveGenie::Logger.call(
-            {
-              code: :retry_attempt,
-              attempt: retries,
-              max_retries: max_retries,
-              delay: sleep_time,
-              error: e.message
-            }
+            code: :retry_attempt,
+            attempt: retries,
+            max_retries: max_retries,
+            delay: sleep_time,
+            error: e.message
           )
 
           sleep(sleep_time)
           retry
         end
       end
+      # rubocop:enable Metrics/MethodLength
+
+      def max_retries
+        @config.llm.max_retries || DEFAULT_MAX_RETRIES
+      end
+
+      def retry_delay
+        @config.llm.retry_delay || DEFAULT_RETRY_DELAY
+      end
     end
   end
 end