Helicone Ruby Client

gem 'helicone-rb'

Helicone.configure do |config|
  config.default_model = "gpt-4o"             # default
  config.logger = Logger.new($stdout)         # default
end

client = Helicone::Client.new

# Single-turn conversation
response = client.ask("What is the capital of France?")
# => "The capital of France is Paris."

# With system prompt
response = client.ask(
  "Explain quantum computing",
  system_prompt: "You are a physics teacher. Explain concepts simply."
)

client = Helicone::Client.new

messages = [
  Helicone::Message.system("You are a helpful assistant."),
  Helicone::Message.user_text("My name is Alice."),
]

response = client.chat(messages: messages)
puts response.content
# => "Nice to meet you, Alice!"

# Continue the conversation
messages << response.to_message
messages << Helicone::Message.user_text("What's my name?")

response = client.chat(messages: messages)
puts response.content
# => "Your name is Alice."

client = Helicone::Client.new

# Single image
response = client.ask_with_image(
  "What's in this image?",
  "https://example.com/image.jpg"
)

# Multiple images
message = Helicone::Message.user_with_images(
  "Compare these two images",
  ["https://example.com/a.jpg", "https://example.com/b.jpg"],
  detail: "high"
)
response = client.chat(messages: [message])

client = Helicone::Client.new(
  session_id: conversation.id,
  session_name: "Support Chat ##{conversation.id}",
  account_id: user.account_id,
  account_name: user.account.name
)

class WeatherTool < Helicone::Tool
  description "Get current weather for a location"

  parameters(
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "City and state, e.g. 'San Francisco, CA'"
      },
      unit: {
        type: "string",
        enum: ["celsius", "fahrenheit"],
        description: "Temperature unit"
      }
    },
    required: ["location"]
  )

  def execute(location:, unit: "fahrenheit")
    # Your implementation here
    weather_api.get(location, unit: unit)
  end
end

class CreateOrderTool < Helicone::Tool
  description "Create a new order"

  parameters(
    type: "object",
    properties: {
      customer: {
        type: "object",
        properties: {
          name: { type: "string" },
          email: { type: "string", format: "email" }
        },
        required: ["name", "email"]
      },
      items: {
        type: "array",
        items: {
          type: "object",
          properties: {
            product_id: { type: "string" },
            quantity: { type: "integer", minimum: 1 }
          },
          required: ["product_id", "quantity"]
        }
      }
    },
    required: ["customer", "items"]
  )

  def execute(customer:, items:)
    Order.create!(customer: customer, items: items)
  end
end

agent = Helicone::Agent.new(
  tools: [WeatherTool, CalendarTool],
  system_prompt: "You are a helpful assistant with access to weather and calendar tools.",
  context: current_user  # Passed to tool#initialize
)

result = agent.run("What's the weather in Tokyo and do I have any meetings today?")

puts result.content          # Final response text
puts result.iterations       # Number of tool execution loops
puts result.tool_calls_made  # Total tool calls executed
puts result.success?         # Whether it completed successfully

agent = Helicone::Agent.new(tools: [WeatherTool])

result = agent.run("What's the weather in Paris?")
puts result.content

# Continue with follow-up
result = agent.continue("What about London?")
puts result.content

# Text messages
Helicone::Message.user_text("Hello")
Helicone::Message.assistant_text("Hi there!")
Helicone::Message.system("You are helpful")

# Images
Helicone::Message.user_image("https://example.com/img.jpg", text: "Describe this")
Helicone::Message.user_with_images("Compare", ["url1", "url2"])

# Tool results (internal use)
Helicone::Message.tool_result(tool_call_id: "call_123", content: { data: "result" })

response = client.chat(messages: messages)

response.content         # Text content
response.role           # "assistant"
response.finish_reason  # "stop", "length", "tool_calls"
response.tool_calls     # Array of tool calls if any
response.model          # Model used
response.usage          # Token usage stats
response.prompt_tokens
response.completion_tokens
response.total_tokens
response.success?       # Quick success check