active_genie 0.27.1 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 752b254545d62f5e618ca56935dca6e89dce29e0353af995f96f276ac2852662
-  data.tar.gz: 7df0c3373970c5da1cf12cea004839a17e8489bf52b2e3d14dedcd61c04f91cc
+  metadata.gz: 9d304f581f4ebf42ba3fe4095d319c7d450b554b7af7c9a86ff4c34af1d6b771
+  data.tar.gz: 749952b6fcf70903b247987d739ab8d2a55e40fd70873ed65f9eedf64fde9abd
 SHA512:
-  metadata.gz: dd4d86d0bd8a8be3c44355d997883db01b424a070ab51b555e1f1b8a10c3c0fbc46f8afc4c5b8764b4462b9e1e5e711be38ad25a77a21e26b3ea55668fd61ccf
-  data.tar.gz: bb69781f7f05a339833e553ab7cb1dc805044cda7fb2615712c7fea3f5ce9f71dce82b38edd1b70aa6fca36d6ef6538c573b34058e80498a0a5a65bf6fd58821
+  metadata.gz: cb9fccff5748c42bdf51dbd4b57041bd6de75f69cafa10cf77246eb6e3e67c4204436187fb595afd70af610b841b103bfd79f5040019e58a779a6eae8b17802e
+  data.tar.gz: 1a958882621ce6a9f5d20b2383e8be76bee47e776d30a8f007f7d20516aefb01c936dd56f315cc3e1d1c0255d4eafc7ad9d80e477edf308b2acd5392489198db

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/active_genie.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/active_genie)
 [![Ruby](https://github.com/roriz/active_genie/actions/workflows/benchmark.yml/badge.svg)](https://github.com/roriz/active_genie/actions/workflows/benchmark.yml)
 
-ActiveGenie is a developer-first library for GenAI workflows, designed to help you compare, rank, and score LLM outputs with consistency and model-agnostic flexibility. Think of it as the Lodash for GenAI: built for real value, consistent results, and freedom from vendor lock-in. It solves the biggest pain in GenAI today: getting predictable, trustworthy answers across use cases, models, and providers.
+ActiveGenie is a developer-first library for GenAI workflows, designed to help you extract, compare, score, and rank with consistency and model-agnostic. Think of it as the Lodash for GenAI: built for real value, consistent results, and freedom from vendor lock-in. It solves the biggest pain in GenAI today: getting predictable, trustworthy answers across use cases, models, and providers.
 
 Behind the scenes, a custom benchmarking system keeps everything consistent across LLM vendors and versions, release after release.
 

data/VERSION

@@ -1 +1 @@
-0.27.1
+0.29.0

data/lib/active_genie/battle/fight.json

@@ -0,0 +1,61 @@
+{
+  "name": "fight_evaluation",
+  "description": "Evaluate a fight between player_a and player_b using predefined criteria and identify the winner.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "player_a_introduction": {
+        "type": "string",
+        "description": "player_a introduces their name and fighting style. Max of 100 words."
+      },
+      "player_b_introduction": {
+        "type": "string",
+        "description": "player_b introduces their name and fighting style. Max of 100 words."
+      },
+      "player_a_turn_1": {
+        "type": "string",
+        "description": "player_a makes their first turn. Max of 100 words."
+      },
+      "player_b_turn_1": {
+        "type": "string",
+        "description": "player_b makes their first turn. Max of 100 words."
+      },
+      "player_a_turn_2": {
+        "type": "string",
+        "description": "player_a makes their second turn. Max of 100 words."
+      },
+      "player_b_turn_2": {
+        "type": "string",
+        "description": "player_b makes their second turn. Max of 100 words."
+      },
+      "player_a_turn_3": {
+        "type": "string",
+        "description": "player_a makes their third turn. Max of 100 words."
+      },
+      "player_b_turn_3": {
+        "type": "string",
+        "description": "player_b makes their third turn. Max of 100 words."
+      },
+      "player_a_turn_4": {
+        "type": "string",
+        "description": "player_a makes their fourth turn. Max of 100 words."
+      },
+      "player_b_turn_4": {
+        "type": "string",
+        "description": "player_b makes their fourth turn. 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_introduction", "player_b_introduction", "player_a_turn_1", "player_b_turn_1",
+                 "player_a_turn_2", "player_b_turn_2", "player_a_turn_3", "player_b_turn_3", "player_a_turn_4",
+                 "player_b_turn_4", "impartial_judge_winner_reasoning", "impartial_judge_winner"]
+  }
+}

data/lib/active_genie/battle/fight.prompt.md

@@ -0,0 +1,44 @@
+Create a dynamic, back-and-forth verbal match between two fighters, given their names and preferred fighting styles. Criteria are vital as they provide a clear metric to compare the players. Follow these criteria strictly.
+In this match, fighters do not physically battle, instead, they engage in a spoken confrontation, each describing and boasting about their fighting style, how their techniques would outmaneuver, counter, or overwhelm the other's approach. Each moviment must be focused in how it will help the fighter to reach the criteria as fully as possible. Ensure that each verbal exchange details:
+- The technique or strategy the speaker would use.
+- How that move is superior to the opponent’s last stated tactic.
+- How the opponent might respond, and what reply the speaker would have.
+
+Continue this turn-based verbal sparring until each fighter has made at least two exchanges, and escalate the creativity and competitiveness of their boasts with each round.
+
+Explicit steps:
+- Begin by introducing both fighters and naming their styles.
+- Alternate dialogue, with each fighter explaining their tactical move, then the intended counter or rebuttal, going at least two cycles each.
+- Ensure reasoning (the logic or explanation behind each technique and counter) always precedes the conclusion or actual "move" or taunt.
+- Close with a final statement or taunt from each fighter, maintaining the competitive tone.
+- Make the dialogue lively and imaginative.
+- Make sure follow these criteria strictly.
+
+Output Format:
+- Structure as a script, with each turn labeled by the fighter’s name.
+- Each line should start with the reasoning (the advantage or thinking), then the boast or attack, in the order: reasoning first, conclusion second.
+- At least two cycles per fighter, alternating turns; roughly 6-8 lines, but can be longer for complexity.
+- No code blocks, use markdown for formatting.
+
+Example:
+
+Example Input:
+Fighter One: Master Crane, Style: Crane Kung Fu
+Fighter Two: Iron Ox, Style: Ox Bull Charge
+Criteria: Fair fight 1v1 using only techniques from their style.
+
+Example Output:
+Master Crane: My Crane Kung Fu relies on lightness and precision, striking where your heavy blows simply can't reach. Your Ox Bull Charge is powerful, but too direct, I'd dance aside and tap your pressure points before you even turn.
+Iron Ox: While speed is impressive, strength dominates in a real fight. My Ox Bull Charge would absorb your nimble attacks, and my sheer mass pins you before you could even flutter away!
+Master Crane: Adaptability ensures survival. As you lumber forward, I use your momentum to redirect you, your own strength becomes your undoing as you stumble into my calculated traps.
+Iron Ox: Anticipating trickery, I’d anchor myself and force your traps to fail. Your frailty means that, once caught, no escape, one bear hug from me, and there’s no dancing away.
+Master Crane: Patience and timing can unravel even the strongest grip. Just as you squeeze, a swift strike to your nerve centers will loosen your hold before you know it.
+Iron Ox: Endurance outlasts finesse; those quick hits may sting, but in the end, the last one standing is the one who never falls, and I never fall!
+
+(Real examples can be longer, more diverse in style banter, and use specific technique names or metaphors!)
+
+Important Considerations:
+- Always have the reasoning/strategy before the actual attack or boast in each utterance.
+- Maintain the turn order and competitive dialogue style.
+
+*Reminder: The main objective is to script an imaginative, turn-based verbal contest between two fighters, with detailed reasoning and taunts about their style advantages until reach the criteria, as instructed above.*

data/lib/active_genie/battle/fight.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../clients/unified_client'
+require_relative 'generalist'
+
+module ActiveGenie
+  module Battle
+    # The Fight class are battle specialized in a fight between two fighters, like martial arts, heroes, characters.
+    # The fight evaluation process simulate a fight using words, techniques, strategies, and reasoning.
+    #
+    # @example Fight usage with two fighters and criteria
+    #   Fight.call("Naruto", "Sasuke", "How can win without using jutsu?")
+    #
+    class Fight < Generalist
+      # @return [BattleResponse] The evaluation result containing the winner and reasoning
+      def call
+        messages = [
+          {  role: 'system', content: PROMPT },
+          {  role: 'user', content: "player_a: #{@player_a}" },
+          {  role: 'user', content: "player_b: #{@player_b}" },
+          {  role: 'user', content: "criteria: #{@criteria}" }
+        ]
+
+        response = ::ActiveGenie::Clients::UnifiedClient.function_calling(
+          messages,
+          FUNCTION,
+          config: @config
+        )
+
+        response_formatted(response)
+      end
+
+      PROMPT = File.read(File.join(__dir__, 'fight.prompt.md'))
+      FUNCTION = JSON.parse(File.read(File.join(__dir__, 'fight.json')), symbolize_names: true)
+    end
+  end
+end

data/lib/active_genie/battle/generalist.rb

@@ -15,6 +15,8 @@ module ActiveGenie
     #   Generalist.call("Player A content", "Player B content", "Evaluate keyword usage and pattern matching")
     #
     class Generalist
+      BattleResponse = Struct.new(:winner, :loser, :reasoning, :raw, keyword_init: true)
+
       def self.call(...)
         new(...).call
       end
@@ -23,7 +25,7 @@ module ActiveGenie
       # @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 [BattleResponse] The evaluation result containing the winner and reasoning
       #   @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
@@ -34,12 +36,13 @@ module ActiveGenie
         @config = ActiveGenie.configuration.merge(config)
       end
 
+      # @return [BattleResponse] The evaluation result containing the winner and reasoning
       def call
         messages = [
           {  role: 'system', content: PROMPT },
-          {  role: 'user', content: "criteria: #{@criteria}" },
           {  role: 'user', content: "player_a: #{@player_a}" },
-          {  role: 'user', content: "player_b: #{@player_b}" }
+          {  role: 'user', content: "player_b: #{@player_b}" },
+          {  role: 'user', content: "criteria: #{@criteria}" }
         ]
 
         response = ::ActiveGenie::Clients::UnifiedClient.function_calling(
@@ -48,15 +51,6 @@ module ActiveGenie
           config: @config
         )
 
-        @config.logger.call({
-                              code: :battle,
-                              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']
-                            })
-
         response_formatted(response)
       end
 
@@ -66,13 +60,26 @@ module ActiveGenie
       private
 
       def response_formatted(response)
-        winner = response['impartial_judge_winner']
-        loser = case winner
-                when 'player_a' then 'player_b'
-                when 'player_b' then 'player_a'
-                end
+        winner, loser = case response['impartial_judge_winner']
+                        when 'player_a' then [@player_a, @player_b]
+                        when 'player_b' then [@player_b, @player_a]
+                        end
+        reasoning = response['impartial_judge_winner_reasoning']
+
+        battle_response = BattleResponse.new(winner:, loser:, reasoning:, raw: response)
+        log_battle(battle_response)
 
-        { 'winner' => winner, 'loser' => loser, 'reasoning' => response['impartial_judge_winner_reasoning'] }
+        battle_response
+      end
+
+      def log_battle(battle_response)
+        @config.logger.call(
+          code: :battle,
+          player_a: @player_a[0..30],
+          player_b: @player_b[0..30],
+          criteria: @criteria[0..30],
+          **battle_response.to_h
+        )
       end
     end
   end

data/lib/active_genie/battle.rb

@@ -1,18 +1,31 @@
 # frozen_string_literal: true
 
 require_relative 'battle/generalist'
+require_relative 'battle/fight'
 
 module ActiveGenie
   # See the [Battle README](lib/active_genie/battle/README.md) for more information.
   module Battle
     module_function
 
+    def generalist(...)
+      Generalist.call(...)
+    end
+
     def call(...)
       Generalist.call(...)
     end
 
-    def generalist(...)
+    def battle(...)
       Generalist.call(...)
     end
+
+    def compare(...)
+      Generalist.call(...)
+    end
+
+    def fight(...)
+      Fight.call(...)
+    end
   end
 end

data/lib/active_genie/config/factory_config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveGenie
+  module Config
+    class FactoryConfig
+      attr_accessor :number_of_items
+
+      def initialize
+        @number_of_items = 5
+      end
+
+      def merge(config_params = {})
+        dup.tap do |config|
+          config.number_of_items = config_params[:number_of_items] if config_params.key?(:number_of_items)
+        end
+      end
+    end
+  end
+end

data/lib/active_genie/configuration.rb

@@ -7,6 +7,7 @@ require_relative 'config/scoring_config'
 require_relative 'config/data_extractor_config'
 require_relative 'config/battle_config'
 require_relative 'config/llm_config'
+require_relative 'config/factory_config'
 
 module ActiveGenie
   class Configuration
@@ -34,6 +35,10 @@ module ActiveGenie
       @battle ||= Config::BattleConfig.new
     end
 
+    def factory
+      @factory ||= Config::FactoryConfig.new
+    end
+
     def llm
       @llm ||= Config::LlmConfig.new
     end
@@ -42,7 +47,7 @@ module ActiveGenie
       @logger ||= ActiveGenie::Logger.new(log_config: log)
     end
 
-    SUB_CONFIGS = %w[log providers llm ranking scoring data_extractor battle].freeze
+    SUB_CONFIGS = %w[log providers llm ranking scoring data_extractor battle factory].freeze
 
     def merge(config_params = {})
       return config_params if config_params.is_a?(Configuration)
@@ -80,6 +85,6 @@ module ActiveGenie
       end
     end
 
-    attr_writer :log, :providers, :ranking, :scoring, :data_extractor, :battle, :llm, :logger
+    attr_writer(*SUB_CONFIGS, :logger)
   end
 end

data/lib/active_genie/factory/feud.json

@@ -0,0 +1,21 @@
+{
+  "name": "feud_items_generator",
+  "description": "Generate a list of items for a given theme.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "theme": {
+        "type": "string",
+        "description": "The theme for the feud."
+      },
+      "items": {
+        "type": "array",
+        "description": "The list of items for the feud.",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "required": ["theme", "items"]
+  }
+}

data/lib/active_genie/factory/feud.prompt.md

@@ -0,0 +1,20 @@
+Emulate the game "Family Feud": For a given theme, reason about the general public's most common answers impersonating a survey of average people's opinions and generate an ordered, survey-style answer list.
+
+- Before producing the answer list, internally consider: If a group of average people were surveyed on this theme, which answers would be mentioned most frequently?.
+
+# Output Format
+
+A numbered list in plain text
+
+# Example
+
+Example for the theme "Favorite Fast Foods":
+1. Pizza
+2. Hamburgers
+3. Hot Dogs
+4. French Fries
+
+# Notes
+
+- Always impersonate a "Family Feud" survey: order is critical most likely answers should come first.
+- Judge each item by their general public reputation and cultural impact.

data/lib/active_genie/factory/feud.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../clients/unified_client'
+
+module ActiveGenie
+  module Factory
+    # The Factory::Feud class provides a foundation for generating a list of items for a given theme
+    #
+    # @example Feud usage with two players and criteria
+    #   Feud.call("Industries that are most likely to be affected by climate change")
+    #
+    class Feud
+      def self.call(...)
+        new(...).call
+      end
+
+      # @param theme [String] The theme for the feud
+      # @param config [Hash] Additional configuration options that modify the battle evaluation behavior
+      # @return [Array of strings] List of items
+      def initialize(theme, config: {})
+        @theme = theme
+        @config = ActiveGenie.configuration.merge(config)
+      end
+
+      # @return [Array] The list of items
+      def call
+        messages = [
+          {  role: 'system', content: PROMPT },
+          {  role: 'system', content: "List #{number_of_items} top items." },
+          {  role: 'user', content: "theme: #{@theme}" }
+        ]
+
+        response = ::ActiveGenie::Clients::UnifiedClient.function_calling(
+          messages,
+          FUNCTION,
+          config: @config
+        )
+
+        log_feud(response)
+        response['items']
+      end
+
+      PROMPT = File.read(File.join(__dir__, 'feud.prompt.md'))
+      FUNCTION = JSON.parse(File.read(File.join(__dir__, 'feud.json')), symbolize_names: true)
+
+      private
+
+      def number_of_items
+        @config.factory.number_of_items
+      end
+
+      def log_feud(response)
+        @config.logger.call(
+          code: :feud,
+          theme: @theme[0..30],
+          items: response['items'].map { |item| item[0..30] }
+        )
+      end
+    end
+  end
+end

data/lib/active_genie/factory.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'factory/feud'
+
+module ActiveGenie
+  module Factory
+    module_function
+
+    def feud(...)
+      Feud.call(...)
+    end
+
+    def list(...)
+      Feud.call(...)
+    end
+
+    def call(...)
+      Feud.call(...)
+    end
+  end
+end

data/lib/active_genie/scoring/generalist.rb

@@ -106,7 +106,7 @@ module ActiveGenie
       end
 
       def reviewers
-        @reviewers ||= if @param_reviewers.count.positive?
+        @reviewers ||= if @param_reviewers.any?
                          @param_reviewers
                        else
                          result = RecommendedReviewers.call(@text, @criteria, config: @config)

data/lib/active_genie.rb

@@ -13,6 +13,7 @@ module ActiveGenie
   autoload :Battle, File.join(__dir__, 'active_genie/battle')
   autoload :Scoring, File.join(__dir__, 'active_genie/scoring')
   autoload :Ranking, File.join(__dir__, 'active_genie/ranking')
+  autoload :Factory, File.join(__dir__, 'active_genie/factory')
 
   VERSION = File.read(File.expand_path('../VERSION', __dir__)).strip
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_genie
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.29.0
 platform: ruby
 authors:
 - Radamés Roriz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-30 00:00:00.000000000 Z
+date: 2025-07-16 00:00:00.000000000 Z
 dependencies: []
 description: |
   ActiveGenie is a Ruby gem that helps developers build reliable, future-proof GenAI features without worrying about changing models, prompts, or providers. Like Lodash for GenAI, it offers simple, reusable modules for tasks like data extraction, scoring, and ranking, so you can focus on your app’s logic, not the shifting AI landscape.
@@ -24,7 +24,9 @@ files:
 - VERSION
 - lib/active_genie.rb
 - lib/active_genie/battle.rb
-- lib/active_genie/battle/README.md
+- lib/active_genie/battle/fight.json
+- lib/active_genie/battle/fight.prompt.md
+- lib/active_genie/battle/fight.rb
 - lib/active_genie/battle/generalist.json
 - lib/active_genie/battle/generalist.prompt.md
 - lib/active_genie/battle/generalist.rb
@@ -36,6 +38,7 @@ files:
 - lib/active_genie/clients/unified_client.rb
 - lib/active_genie/config/battle_config.rb
 - lib/active_genie/config/data_extractor_config.rb
+- lib/active_genie/config/factory_config.rb
 - lib/active_genie/config/llm_config.rb
 - lib/active_genie/config/log_config.rb
 - lib/active_genie/config/providers/anthropic_config.rb
@@ -55,6 +58,10 @@ files:
 - lib/active_genie/data_extractor/generalist.rb
 - lib/active_genie/errors/invalid_log_output_error.rb
 - lib/active_genie/errors/invalid_provider_error.rb
+- lib/active_genie/factory.rb
+- lib/active_genie/factory/feud.json
+- lib/active_genie/factory/feud.prompt.md
+- lib/active_genie/factory/feud.rb
 - lib/active_genie/logger.rb
 - lib/active_genie/ranking.rb
 - lib/active_genie/ranking/elo_round.rb

data/lib/active_genie/battle/README.md

@@ -1,39 +0,0 @@
-# Battle
-AI-powered battle evaluation system that determines winners between two players based on specified criteria.
-
-## Features
-- Content comparison - Evaluate submissions from two players against defined criteria
-- Objective analysis - AI-powered assessment of how well each player meets requirements
-- Detailed reasoning - Comprehensive explanation of why a winner was chosen
-- Draw avoidance - Suggestions on how to modify content to avoid draws
-- Flexible input - Support for both string content and structured data with content field
-
-## Basic Usage
-Evaluate a battle between two players with simple text content:
-
-```ruby
-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_a, player_b, criteria)
-# => {
-#      winner_player: "Implementation uses dependency injection for better testability",
-#      reasoning: "Player A's implementation demonstrates better maintainability through dependency injection,
-#                 which allows for easier testing and component replacement. While Player B has good test coverage,
-#                 the tight coupling makes the code harder to maintain and modify.",
-#      what_could_be_changed_to_avoid_draw: "Focus on specific architectural patterns and design principles"
-#    }
-```
-
-## Interface
-### .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_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