active_genie 0.0.2 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '078409a35816dfb0870469dcf511a7b57bf216cd4665f0c50ef187e7be0c7707'
-  data.tar.gz: 108d56de78b375e23dfb0acc48db70175c6af0d457933cece70ff67f505c1203
+  metadata.gz: 834787b505134623a3f6c4995c9dec8a0ce89a1a014600c4d676d8801bf541cd
+  data.tar.gz: 16ae75ffa3926ecd87052d72ca3f5434be80327b712bb2dba54e55c46fa5ff8d
 SHA512:
-  metadata.gz: c5e7af633c6add150d098ebcd6589c564e570d1cad73a6937a0388b36ab418b4cf17ddda0dbed61d13ff6882c4a064e376caf3015d210ec70e884cba5951d71c
-  data.tar.gz: decbe01929b3412127fccbf5e0c08c8f96181348c35f2c8f13117385df7dbd42298783c69a11a1d990b320f8b01eb96d962a4a9546ee6df1d073cb42a13e1f84
+  metadata.gz: 1772fbfa59891e7a3673b50a54bd90914007917854e78fb5f0458db681bf89bd1ec118600d23ab98d6255e1b063b5d582d3b73dc738e66aeadc7f4f0bee75af8
+  data.tar.gz: bb6a0ea9ef737f7a2ed3ec558dcea5c67bcc2f90a155828e1e25a5a7a3ebd9d0fe6c5422dd9f3d9ff6fb667b63822e3bc86627cdb3e40a3c72c4ef50cee32c68

data/README.md

@@ -1,86 +1,154 @@
-# ActiveGenie
-Ruby gem for out of the box AI features. LLMs are just a raw tools that need to be polished and refined to be useful. This gem is a collection of tools that can be used to make LLMs more useful and easier to use.
-Think this gem is like ActiveStorage but for LLMs.
+# ActiveGenie 🧞‍♂️
+> Transform your Ruby application with powerful, production-ready GenAI features
 
 [![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/ruby.yml/badge.svg)](https://github.com/roriz/active_genie/actions/workflows/ruby.yml)
+
+ActiveGenie is a Ruby gem that provides a polished, production-ready interface for working with Generative AI (GenAI) models. Just like ActiveStorage simplifies file handling in Rails, ActiveGenie makes it effortless to integrate GenAI capabilities into your Ruby applications.
+
+## Features
+
+- 🎯 **Data Extraction**: Extract structured data from unstructured text with type validation
+- 📊 **Smart Scoring**: Multi-reviewer evaluation system with automatic expert selection
+- 💭 **Sentiment Analysis**: Advanced sentiment analysis with customizable rules
+- 🔒 **Safe & Secure**: Built-in validation and sanitization
+- 🛠️ **Configurable**: Supports multiple GenAI providers and models
 
 ## Installation
-Add this line to your application's Gemfile:
 
-1. Add the gem to your Gemfile
+1. Add to your Gemfile:
 ```ruby
 gem 'active_genie'
 ```
-2. install the gem
+
+2. Install the gem:
 ```shell
 bundle install
 ```
-3. call the initializer to create default configurations
+
+3. Generate the configuration:
 ```shell
+echo "ActiveGenie.load_tasks" >> Rakefile
 rails g active_genie:install
 ```
-4. Add the right credentials to the `config/active_genie.yml` file
+
+4. [Optional] Configure your credentials in `config/active_genie.yml`:
 ```yaml
 GPT-4o-mini:
   api_key: <%= ENV['OPENAI_API_KEY'] %>
   provider: "openai"
+
+claude-3-5-sonnet:
+  api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+  provider: "anthropic"
 ```
 
-## Quick Example
-```ruby
-require 'active_genie'
+> The first key will be used as default in all modules, in this example `GPT-4o-mini`
 
-puts ActiveGenie::DataExtractor.call(
-  "Hello, my name is Radamés Roriz",
-  { full_name: { type: 'string' } },
-  options: { model: 'gpt-4o-mini', api_key: 'your-api-key', provider: 'openai' } # Optional if has config/active_genie.yml
-) # => { full_name: "Radamés Roriz" }
-```
+## Quick Start
 
 ### Data Extractor
-Extract structured data from text using LLM-powered analysis, handling informal language and complex expressions.
+Extract structured data from text using AI-powered analysis, handling informal language and complex expressions.
 
 ```ruby
-require 'active_genie'
-
-text = "iPhone 14 Pro Max"
+text = "Nike Air Max 90 - Size 42 - $199.99"
 schema = {
-  brand: { type: 'string' },
-  model: { type: 'string' }
+  brand: { 
+    type: 'string',
+    enum: ["Nike", "Adidas", "Puma"]
+  },
+  price: { 
+    type: 'number',
+    minimum: 0
+  },
+  size: {
+    type: 'integer',
+    minimum: 35,
+    maximum: 46
+  }
 }
-result = ActiveGenie::DataExtractor.call(
-  text,
-  schema,
-  options: { model: 'GPT-4o-mini', api_key: 'your-api-key', provider: 'openai' } # Optional if 
-)
-# => { brand: "iPhone", model: "14 Pro Max" }
+
+result = ActiveGenie::DataExtractor.call(text, schema)
+# => { 
+#      brand: "Nike", 
+#      brand_explanation: "Brand name found at start of text",
+#      price: 199.99,
+#      price_explanation: "Price found in USD format at end",
+#      size: 42,
+#      size_explanation: "Size explicitly stated in the middle"
+#    }
 ```
 
-- More examples in the [Data Extractor README](lib/data_extractor/README.md)
-- Extract from ambiguous [from_informal](lib/data_extractor/README.md#extract-from-informal-text)
-- Interface details in the [Interface](lib/data_extractor/README.md#interface)
+Features:
+- Structured data extraction with type validation
+- Schema-based extraction with custom constraints
+- Informal text analysis (litotes, hedging)
+- Detailed explanations for extracted values
 
-### Summarizer (WIP)
-The summarizer is a tool that can be used to summarize a given text. It uses a set of rules to summarize the text out of the box. Uses the best practices of prompt engineering and engineering to make the summarization as accurate as possible.
+See the [Data Extractor README](lib/active_genie/data_extractor/README.md) for informal text processing, advanced schemas, and detailed interface documentation.
+
+### Scoring
+Text evaluation system that provides detailed scoring and feedback using multiple expert reviewers. Get balanced scoring through AI-powered expert reviewers that automatically adapt to your content.
+
+```ruby
+text = "The code implements a binary search algorithm with O(log n) complexity"
+criteria = "Evaluate technical accuracy and clarity"
+
+result = ActiveGenie::Scoring::Basic.call(text, criteria)
+# => {
+#      algorithm_expert_score: 95,
+#      algorithm_expert_reasoning: "Accurately describes binary search and its complexity",
+#      technical_writer_score: 90,
+#      technical_writer_reasoning: "Clear and concise explanation of the algorithm",
+#      final_score: 92.5
+#    }
+```
+
+Features:
+- Multi-reviewer evaluation with automatic expert selection
+- Detailed feedback with scoring reasoning
+- Customizable reviewer weights
+- Flexible evaluation criteria
+
+See the [Scoring README](lib/active_genie/scoring/README.md) for advanced usage, custom reviewers, and detailed interface documentation.
+
+### Battle
+AI-powered battle evaluation system that determines winners between two players based on specified criteria.
 
 ```ruby
 require 'active_genie'
 
-text = "Example text to be summarized. The fox jumps over the dog"
-summarized_text = ActiveGenie::Summarizer.call(text)
-puts summarized_text # => "The fox jumps over the dog"
+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::Basic.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"
+#    }
 ```
 
-### Scorer (WIP)
-The scorer is a tool that can be used to score a given text. It uses a set of rules to score the text out of the box. Uses the best practices of prompt engineering and engineering to make the scoring as accurate as possible.
+Features:
+- Multi-reviewer evaluation with automatic expert selection
+- Detailed feedback with scoring reasoning
+- Customizable reviewer weights
+- Flexible evaluation criteria
+
+See the [Battle README](lib/active_genie/battle/README.md) for advanced usage, custom reviewers, and detailed interface documentation.
+
+### Summarizer (WIP)
+The summarizer is a tool that can be used to summarize a given text. It uses a set of rules to summarize the text out of the box. Uses the best practices of prompt engineering and engineering to make the summarization as accurate as possible.
 
 ```ruby
 require 'active_genie'
 
-text = "Example text to be scored. The fox jumps over the dog"
-criterias = 'Grammar, Relevance'
-score = ActiveGenie::Scorer.call(text, criterias)
-puts score # => { 'Grammar' => 0.8, 'Relevance' => 1.0, total: 0.9 }
+text = "Example text to be summarized. The fox jumps over the dog"
+summarized_text = ActiveGenie::Summarizer.call(text)
+puts summarized_text # => "The fox jumps over the dog"
 ```
 
 ### Language detector (WIP)
@@ -128,9 +196,27 @@ ranked_items = ActiveGenie::EloRanking.call(items, criterias, rounds: 10)
 puts ranked_items # => [{ name: "Circle", score: 1500 }, { name: "Square", score: 800 }, { name: "Triangle", score: 800 }]
 ```
 
-## Good practices
-- LLMs can take a long time to respond, so avoid putting them in the main thread
-- Do not use the LLMs to extract sensitive or personal data
 
+## Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `provider` | LLM provider (openai, anthropic, etc) | `nil` |
+| `model` | Model to use | `nil` |
+| `api_key` | Provider API key | `nil` |
+| `timeout` | Request timeout in seconds | `5` |
+| `max_retries` | Maximum retry attempts | `3` |
+
+> **Note:** Each module can append its own set of configuration options, see the individual module documentation for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 ## License
-See the [LICENSE](LICENSE)
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.8

data/lib/active_genie/battle/README.md

@@ -0,0 +1,39 @@
+# 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::Basic.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
+### Basic.call(player_a, player_b, criteria, options: {})
+- `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
+- `options` [Hash] - Additional configuration options 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

data/lib/active_genie/battle/basic.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative '../clients/router'
+
+module ActiveGenie::Battle
+  # The Basic class provides a foundation for evaluating battles between two players
+  # using AI-powered evaluation. It determines a winner based on specified criteria,
+  # analyzing how well each player meets the requirements.
+  #
+  # The battle evaluation process compares two players' content against given criteria
+  # and returns detailed feedback including the winner and reasoning for the decision.
+  #
+  # @example Basic usage with two players and criteria
+  #   Basic.call("Player A content", "Player B content", "Evaluate keyword usage and pattern matching")
+  #
+  class Basic
+    def self.call(player_a, player_b, criteria, options: {})
+      new(player_a, player_b, criteria, options:).call
+    end
+
+    # @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 options [Hash] Additional configuration options that modify the battle evaluation behavior
+    # @return [Hash] The evaluation result containing the winner and reasoning
+    #   @return [String] :winner The @param 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_a, player_b, criteria, options: {})
+      @player_a = player_a
+      @player_b = player_b
+      @criteria = criteria
+      @options = options
+      @response = nil
+    end
+
+    def call
+      messages = [
+        {  role: 'system', content: PROMPT },
+        {  role: 'user', content: "criteria: #{@criteria}" },
+        {  role: 'user', content: "player_a: #{player_content(@player_a)}" },
+        {  role: 'user', content: "player_b: #{player_content(@player_b)}" },
+      ]
+
+      @response = ::ActiveGenie::Clients::Router.function_calling(messages, FUNCTION, options: @options)
+
+      response_formatted
+    end
+
+    private
+
+    def player_content(player)
+      return player.dig('content') if player.is_a?(Hash)
+
+      player
+    end
+
+    def response_formatted
+      if @response['winner'] == 'player_a'
+        @response['winner'] = @player_a
+        @response['loser'] = @player_b
+      elsif @response['winner'] == 'player_b'
+        @response['winner'] = @player_b
+        @response['loser'] = @player_a
+      else
+        @response['winner'] = nil
+        @response['loser'] = nil
+      end
+
+      @response
+    end
+
+    PROMPT = <<~PROMPT
+    Evaluate a battle between player_a and player_b using predefined criteria and identify the winner.
+
+    Consider rules, keywords, and patterns as the criteria for evaluation. Analyze the content from both players objectively, focusing on who meets the criteria most effectively. Explain your decision clearly, with specific reasoning on how the chosen player fulfilled the criteria better than the other. Avoid selecting a draw unless absolutely necessary.
+
+    # Steps
+    1. **Review Predefined Criteria**: Understand the specific rules, keywords, and patterns that serve as the basis for evaluation.
+    2. **Analyze Content**: Examine the contributions of both player_a and player_b. Look for how each player meets or fails to meet the criteria.
+    3. **Comparison**: Compare both players against each criterion to determine who aligns better with the standards set.
+    4. **Decision-Making**: Based on the analysis, determine the player who meets the most or all criteria effectively.
+    5. **Provide Justification**: Offer a clear and concise reason for your choice detailing how the winner outperformed the other.
+
+    # Examples
+    - **Example 1**:
+      - Input: Player A uses keyword X, follows rule Y, Player B uses keyword Z, breaks rule Y.
+      - Output: winner: player_a
+        - Justification: Player A successfully used keyword X and followed rule Y, whereas Player B broke rule Y.
+
+    - **Example 2**:
+      - Input: Player A matches pattern P, Player B matches pattern P, uses keyword Q.
+      - Output: winner: player_b
+        - Justification: Both matched pattern P, but Player B also used keyword Q, meeting more criteria.
+
+    # Notes
+    - Avoid drawing if a clear winner can be discerned.
+    - 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_a and player_b using predefined criteria and identify the winner.',
+      schema: {
+        type: "object",
+        properties: {
+          winner: {
+            type: 'string',
+            description: 'The player who won the battle based on the criteria.',
+            enum: ['player_a', 'player_b', 'draw']
+          },
+          reasoning_of_winner: {
+            type: 'string',
+            description: 'The detailed reasoning about why the winner won based on the criteria.',
+          },
+          what_could_be_changed_to_avoid_draw: {
+            type: 'string',
+            description: 'Suggestions on how to avoid a draw based on the criteria. Be as objective and short as possible. Can be empty.',
+          }
+        }
+      }
+    }
+  end
+end

data/lib/active_genie/battle.rb

@@ -0,0 +1,13 @@
+
+require_relative 'battle/basic'
+
+module ActiveGenie
+  # Battle module
+  module Battle
+    module_function
+
+    def basic(...)
+      Basic.call(...)
+    end
+  end
+end

data/lib/{requester → active_genie/clients}/openai.rb

@@ -1,10 +1,10 @@
 require 'json'
 require 'net/http'
 
-module ActiveGenie
+module ActiveGenie::Clients
   class Openai
     class << self
-      def function_calling(messages, function, options)
+      def function_calling(messages, function, options: {})
         app_config = ActiveGenie.config_by_model(options[:model])
 
         model = options[:model] || app_config[:model]
@@ -28,7 +28,9 @@ module ActiveGenie
 
         response = request(payload, headers)
 
-        JSON.parse(response.dig('choices', 0, 'message', 'content'))
+        parsed_response = JSON.parse(response.dig('choices', 0, 'message', 'content'))
+        
+        parsed_response.dig('properties') || parsed_response
       rescue JSON::ParserError
         nil
       end
@@ -48,7 +50,6 @@ module ActiveGenie
 
     end
     
-      
     API_URL = 'https://api.openai.com/v1/chat/completions'.freeze
     DEFAULT_HEADERS = {
       'Content-Type': 'application/json',

data/lib/{requester/requester.rb → active_genie/clients/router.rb}

@@ -1,23 +1,23 @@
 require_relative './openai'
 
-module ActiveGenie
-  class Requester    
+module ActiveGenie::Clients
+  class Router
     class << self
-      def function_calling(messages, function, options = {})
+      def function_calling(messages, function, options: {})
         app_config = ActiveGenie.config_by_model(options[:model])
-        
+
         provider = options[:provider] || app_config[:provider]
-        provider_sdk = PROVIDER_TO_SDK[provider&.to_sym&.downcase]
-        raise "Provider #{provider} not supported" unless provider_sdk
+        client = PROVIDER_TO_CLIENT[provider&.downcase&.strip&.to_sym]
+        raise "Provider \"#{provider}\" not supported" unless client
 
-        response = provider_sdk.function_calling(messages, function, options)
+        response = client.function_calling(messages, function, options:)
 
         clear_invalid_values(response)
       end
 
       private
 
-      PROVIDER_TO_SDK = {
+      PROVIDER_TO_CLIENT = {
         openai: Openai,
       }
 

data/lib/active_genie/configuration.rb

@@ -5,7 +5,7 @@ module ActiveGenie
     attr_accessor :path_to_config
 
     def initialize
-      @path_to_config = File.join(__dir__, 'config', 'gen_ai.yml')
+      @path_to_config = File.join('config', 'active_genie.yml')
     end
 
     def values
@@ -23,7 +23,8 @@ module ActiveGenie
     def load_values
       return {} unless File.exist?(@path_to_config)
 
-      YAML.load_file(@path_to_config) || {}
+      yaml_content = ERB.new(File.read(@path_to_config)).result
+      YAML.safe_load(yaml_content, aliases: true) || {}
     rescue Psych::SyntaxError => e
       warn "ActiveGenie.warning: Config file '#{@path_to_config}' is not a valid YAML file (#{e.message}), using default configuration"
       {}

data/lib/active_genie/data_extractor/README.md

@@ -0,0 +1,132 @@
+# Data Extractor
+Extract structured data from text using AI-powered analysis, handling informal language and complex expressions.
+
+## ✨ Features
+- Structured data extraction - Extract typed data from unstructured text using predefined schemas
+- Informal text analysis - Identifies and handles informal language patterns, including litotes
+- Explanation tracking - Provides reasoning for each extracted data point
+
+## Basic Usage
+
+Extract structured data from text using predefined schemas:
+
+```ruby
+text = "John Doe is 25 years old"
+schema = {
+  name: { type: 'string', description: 'Full name of the person' },
+  age: { type: 'integer', description: 'Age in years' }
+}
+result = ActiveGenie::DataExtractor.call(text, schema)
+# => { 
+#      name: "John Doe", 
+#      name_explanation: "Found directly in text",
+#      age: 25, 
+#      age_explanation: "Explicitly stated as 25 years old" 
+#    }
+
+product = "Nike Air Max 90 - Size 42 - $199.99"
+schema = {
+  brand: { 
+    type: 'string',
+    enum: ["Nike", "Adidas", "Puma"]
+  },
+  price: { 
+    type: 'number',
+    minimum: 0
+  },
+  currency: { 
+    type: 'string',
+    enum: ["USD", "EUR"]
+  },
+  size: {
+    type: 'integer',
+    minimum: 35,
+    maximum: 46
+  }
+}
+
+result = ActiveGenie::DataExtractor.call(product, schema)
+# => { 
+#      brand: "Nike", 
+#      brand_explanation: "Brand name found at start of text",
+#      price: 199.99,
+#      price_explanation: "Price found in USD format at end",
+#      size: 42,
+#      size_explanation: "Size explicitly stated in the middle",
+#      currency: "USD",
+#      currency_explanation: "Derived from $ symbol"
+#    }
+```
+
+## Informal Text Processing
+
+The `from_informal` method extends the basic extraction by analyzing rhetorical devices and informal language patterns like:
+
+- Litotes ("not bad", "isn't terrible")
+- Affirmative expressions ("sure", "no problem")
+- Negative expressions ("nah", "not really")
+- Hedging ("maybe", "I guess")
+
+### Example
+
+```ruby
+text = "The weather isn't bad today"
+schema = { 
+  mood: { type: 'string', description: 'The mood of the message' } 
+}
+
+result = ActiveGenie::DataExtractor.from_informal(text, schema)
+# => { 
+#      mood: "positive",
+#      mood_explanation: "Speaker views weather favorably",
+#      message_litote: true,
+#      litote_rephrased: "The weather is good today"
+#    }
+```
+
+### Usage Notes
+- Best suited for processing conversational user inputs
+- Automatically detects and interprets litotes
+- Provides rephrased positive statements for litotes
+- May require more processing time due to rhetorical analysis
+- Accuracy depends on context clarity
+
+⚠️ Performance Impact: This method performs additional rhetorical analysis, which can increase processing time.
+
+## Interface
+
+### `.call(text, data_to_extract, options = {})`
+Extracts structured data from text based on a predefined schema.
+
+#### Parameters
+| Name | Type | Description | Required | Example |
+| --- | --- | --- | --- | --- |
+| `text` | `String` | The text to analyze and extract data from | Yes | "John Doe is 25 years old" |
+| `data_to_extract` | `Hash` | Schema defining the data structure to extract | Yes | `{ name: { type: 'string' } }` |
+| `options` | `Hash` | Additional extraction configuration | No | `{ model: "gpt-4" }` |
+
+#### Options
+| Name | Type | Description |
+| --- | --- | --- |
+| `model` | `String` | The model to use for the extraction |
+| `api_key` | `String` | The API key to use for the extraction |
+
+#### Returns
+`Hash` containing:
+- Extracted values matching the schema structure
+- Explanation field for each extracted value
+- Additional analysis fields when using `from_informal`
+
+### `.from_informal(text, data_to_extract, options = {})`
+Extends basic extraction with rhetorical analysis, particularly for litotes.
+
+#### Additional Return Fields
+| Name | Type | Description |
+| --- | --- | --- |
+| `message_litote` | `Boolean` | Whether the text contains a litote |
+| `litote_rephrased` | `String` | Positive rephrasing of any detected litote |
+
+⚠️ Performance Considerations
+- Both methods may require multiple AI model calls
+- Informal processing requires additional rhetorical analysis
+- Consider background processing for production use