Class: ActiveAgent::Providers::OpenAI::Chat::Request

Inherits:
SimpleDelegator
  • Object
show all
Defined in:
lib/active_agent/providers/open_ai/chat/request.rb

Overview

Wraps OpenAI gem’s CompletionCreateParams with normalization

Delegates to OpenAI::Models::Chat::CompletionCreateParams while providing parameter normalization and shorthand format support via the Transforms module.

All OpenAI Chat API fields are available via delegation: model, messages, temperature, max_tokens, max_completion_tokens, top_p, frequency_penalty, presence_penalty, tools, tool_choice, response_format, stream_options, audio, prediction, metadata, modalities, service_tier, store, parallel_tool_calls, reasoning_effort, verbosity, stop, seed, logit_bias, logprobs, top_logprobs, prompt_cache_key, safety_identifier, user, web_search_options, function_call, functions

Examples:

Basic usage

request = Request.new(
  model: "gpt-4o",
  messages: [{role: "user", content: "Hello"}]
)

String message normalization

Request.new(model: "gpt-4o", messages: "Hello")
# Normalized to: [{role: "user", content: "Hello"}]

Instructions support

Request.new(
  model: "gpt-4o",
  messages: [{role: "user", content: "Hi"}],
  instructions: ["You are helpful", "Be concise"]
)
# instructions converted to developer messages and prepended

Constant Summary collapse

DEFAULTS =

Default parameter values applied during initialization

{
  frequency_penalty: 0,
  logprobs: false,
  modalities: [ "text" ],
  n: 1,
  parallel_tool_calls: true,
  presence_penalty: 0,
  service_tier: "auto",
  store: false,
  stream: false,
  temperature: 1,
  top_p: 1
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**params) ⇒ Request

Creates a new chat completion request

Parameters:

  • params (Hash) —

    request parameters

Options Hash (**params):

  • :model (String) —

    required model identifier

  • :messages (Array, String, Hash) —

    required conversation messages

  • :instructions (Array<String>, String) —

    system/developer prompts

  • :response_format (Hash, String, Symbol)
  • :temperature (Float) — default: 1 —

    sampling temperature 0-2

  • :max_tokens (Integer) —

    maximum tokens to generate

  • :tools (Array) —

    available tool definitions

Raises:

  • (ArgumentError) —

    when parameters are invalid



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 71

def initialize(**params)
  # Step 1: Extract stream flag
  @stream = params[:stream]

  # Step 2: Apply defaults
  params = apply_defaults(params)

  # Step 3: Normalize all parameters (instructions, messages, response_format)
  params = Chat::Transforms.normalize_params(params)

  # Step 4: Create gem model - this validates all parameters!
  gem_model = ::OpenAI::Models::Chat::CompletionCreateParams.new(**params)

  # Step 5: Delegate all method calls to gem model
  super(gem_model)
rescue ArgumentError => e
  # Re-raise with more context
  raise ArgumentError, "Invalid OpenAI Chat request parameters: #{e.message}"
end

Instance Attribute Details

#stream ⇒ Boolean? (readonly)

Returns:

  • (Boolean, nil) 


58
59
60
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 58

def stream
  @stream
end

Instance Method Details

#instructions=(*values) ⇒ void

This method returns an undefined value.

Sets instructions as developer messages

Prepends developer messages to the messages array for common format compatibility.

Parameters:

  • values (Array<String>, String) 


138
139
140
141
142
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 138

def instructions=(*values)
  instructions_messages = Chat::Transforms.normalize_instructions(values.flatten)
  current_messages = messages || []
  self.messages = instructions_messages + current_messages
end

#message ⇒ Array<Hash>?

Alias for messages (common format compatibility)

Returns:

  • (Array<Hash>, nil) 


122
123
124
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 122

def message
  messages
end

#message=(value) ⇒ void

This method returns an undefined value.

Parameters:

  • value (Array, String, Hash) 


128
129
130
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 128

def message=(value)
  self.messages = value
end

#messages ⇒ Array<Hash>?

Returns:

  • (Array<Hash>, nil) 


106
107
108
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 106

def messages
  __getobj__.instance_variable_get(:@data)[:messages]
end

#messages=(value) ⇒ void

This method returns an undefined value.

Sets messages with normalization

Parameters:

  • value (Array, String, Hash) 


114
115
116
117
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 114

def messages=(value)
  normalized_value = Chat::Transforms.normalize_messages(value)
  __getobj__.instance_variable_get(:@data)[:messages] = normalized_value
end

#serialize ⇒ Hash

Serializes request for API call

Uses gem’s JSON serialization, removes default values for minimal request body, and simplifies messages where possible.

Returns:

  • (Hash) —

    cleaned request hash



97
98
99
100
101
102
103
 
# File 'lib/active_agent/providers/open_ai/chat/request.rb', line 97

def serialize
  # Use gem's JSON serialization (handles all nested objects)
  hash = Chat::Transforms.gem_to_hash(__getobj__)

  # Cleanup and simplify for API request
  Chat::Transforms.cleanup_serialized_request(hash, DEFAULTS, __getobj__)
end