Class: Helicone::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/helicone/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(session_id: nil, session_name: nil, account_id: nil, account_name: nil) ⇒ Client

Initialize with optional session/account context for Helicone tracking

Parameters:

  • session_id (String, Integer) (defaults to: nil) —

    Conversation/session ID for Helicone grouping

  • session_name (String) (defaults to: nil) —

    Human-readable session name

  • account_id (String, Integer) (defaults to: nil) —

    Account ID for cost tracking per account

  • account_name (String) (defaults to: nil) —

    Human-readable account name



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/helicone/client.rb', line 13

def initialize(session_id: nil, session_name: nil, account_id: nil, account_name: nil)
  @client = OpenAI::Client.new(
    access_token: ENV["HELICONE_API_KEY"],
    uri_base: Helicone.configuration.base_url
  )

  # Add Helicone session headers if provided
  if session_id
    @client.add_headers(
      "Helicone-Session-Id" => session_id.to_s,
      "Helicone-Session-Name" => session_name || "Conversation ##{session_id}"
    )
  end

  # Add Helicone account/user headers if provided
  if 
    @client.add_headers(
      "Helicone-User-Id" => .to_s,
      "Helicone-Property-Account" =>  || .to_s
    )
  end
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



5
6
7
 
# File 'lib/helicone/client.rb', line 5

def client
  @client
end

Instance Method Details

#add_headers(headers) ⇒ void

This method returns an undefined value.

Add additional headers at any time

Parameters:

  • headers (Hash) —

    Headers to add to subsequent requests



103
104
105
 
# File 'lib/helicone/client.rb', line 103

def add_headers(headers)
  @client.add_headers(headers)
end

#ask(prompt, model: nil, system_prompt: nil, **options) ⇒ String

Convenience method for simple single-turn requests

Parameters:

  • prompt (String) —

    User prompt text

  • model (String) (defaults to: nil) —

    Model ID to use for completion

  • system_prompt (String) (defaults to: nil) —

    Optional system prompt

  • options (Hash) —

    Additional options passed to chat

Returns:

  • (String) —

    The text content of the response



72
73
74
75
76
77
78
79
 
# File 'lib/helicone/client.rb', line 72

def ask(prompt, model: nil, system_prompt: nil, **options)
  messages = []
  messages << Message.system(system_prompt) if system_prompt
  messages << Message.user_text(prompt)

  response = chat(messages: messages, model: model, **options)
  response.content
end

#ask_with_image(prompt, image_url, model: nil, system_prompt: nil, detail: "auto", **options) ⇒ String

Ask with an image

Parameters:

  • prompt (String) —

    User prompt text

  • image_url (String) —

    URL or base64 data URI of the image

  • model (String) (defaults to: nil) —

    Model ID to use for completion

  • system_prompt (String) (defaults to: nil) —

    Optional system prompt

  • detail (String) (defaults to: "auto") —

    Image detail level: "auto", "low", or "high"

  • options (Hash) —

    Additional options passed to chat

Returns:

  • (String) —

    The text content of the response



90
91
92
93
94
95
96
97
 
# File 'lib/helicone/client.rb', line 90

def ask_with_image(prompt, image_url, model: nil, system_prompt: nil, detail: "auto", **options)
  messages = []
  messages << Message.system(system_prompt) if system_prompt
  messages << Message.user_with_images(prompt, image_url, detail: detail)

  response = chat(messages: messages, model: model, **options)
  response.content
end

#chat(messages:, model: nil, tools: nil, tool_choice: nil, **options) ⇒ Helicone::Response

Send a chat completion request

Parameters:

  • messages (Array<Helicone::Message, Hash>) —

    Array of messages (Message objects or hashes)

  • model (String) (defaults to: nil) —

    Model ID to use for completion

  • tools (Array<Hash>) (defaults to: nil) —

    OpenAI tool definitions for function calling

  • tool_choice (String, Hash) (defaults to: nil) —

    Tool choice strategy ("auto", "none", or specific tool)

  • options (Hash) —

    Additional options passed to the API

Returns:



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/helicone/client.rb', line 44

def chat(messages:, model: nil, tools: nil, tool_choice: nil, **options)
  model ||= Helicone.configuration.default_model

  # Convert Message objects to hashes if needed
  message_hashes = messages.map { |m| m.respond_to?(:to_h) ? m.to_h : m }

  params = {
    model: model,
    messages: message_hashes,
    **options
  }

  # Add tools if provided
  params[:tools] = tools if tools && !tools.empty?
  params[:tool_choice] = tool_choice if tool_choice

  raw_response = @client.chat(parameters: params)

  Response.new(deep_symbolize_keys(raw_response))
end