helicone-rb 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2be72b17bc38b9d451b2888a29407c7af83212d26c580ec22de03cdb9a97c0fb
+  data.tar.gz: 17682bc18311ebc1c2be4e3607db90b3e9d7c2fc90bfeedae38e8bef67e79321
+SHA512:
+  metadata.gz: 5641f51284e72fdcc5a74f68b38fb9afe0cd11607dda855e6193ec555c6c8aae5d2507b4ce0a7e39161ec5a6fd2e22d0a0d19200e895641167a93cffd50914ef
+  data.tar.gz: 5ea90b79077f3ffc5b19c98ae8ab998790bd8580bb63ecf70fc7f3ee74d9e447f61a4d518007bcc2c17a988adcda0df26cfa0f6e1ae110838b2037f8dab3ff80

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Genevere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,263 @@
+# Helicone Ruby Client
+
+A Ruby client for the [Helicone AI Gateway](https://helicone.ai), wrapping the OpenAI API with built-in session tracking, cost attribution, and an agentic framework for building AI applications with tool/function calling.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'helicone-rb'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install helicone-rb
+```
+
+## Configuration
+
+Configure the gem with your API key and optional settings:
+
+```ruby
+Helicone.configure do |config|
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.uri_base = "https://oai.helicone.ai/v1"  # default
+  config.default_model = "gpt-4"                   # default
+  config.logger = Logger.new($stdout)              # default
+end
+```
+
+## Basic Usage
+
+### Simple Chat
+
+```ruby
+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: "You are a physics teacher. Explain concepts simply."
+)
+```
+
+### Multi-turn Conversations
+
+```ruby
+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."
+```
+
+### Vision (Images)
+
+```ruby
+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])
+```
+
+## Session and Account Tracking
+
+Track conversations and costs in the Helicone dashboard:
+
+```ruby
+client = Helicone::Client.new(
+  session_id: conversation.id,
+  session_name: "Support Chat ##{conversation.id}",
+  account_id: user.account_id,
+  account_name: user.account.name
+)
+```
+
+## Agentic Framework
+
+Build AI agents that can use tools to accomplish tasks.
+
+### Defining Tools
+
+Tools use JSON Schema for parameter definitions. The schema is passed through to the underlying [ruby-openai](https://github.com/alexrudall/ruby-openai) gem, so any schema format that OpenAI's function calling API accepts will work:
+
+```ruby
+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
+```
+
+Complex nested schemas are supported:
+
+```ruby
+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
+```
+
+### Running an Agent
+
+```ruby
+agent = Helicone::Agent.new(
+  tools: [WeatherTool, CalendarTool],
+  system: "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
+```
+
+### Continuing Conversations
+
+```ruby
+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
+```
+
+## Message Types
+
+```ruby
+# 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 Object
+
+```ruby
+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
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/genevere-inc/helicone-rb.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/helicone.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/helicone/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "helicone-rb"
+  spec.version = Helicone::VERSION
+  spec.authors = ["Genevere"]
+  spec.email = ["hello@genevere.com"]
+
+  spec.summary = "Ruby client for Helicone AI Gateway with agentic tool support"
+  spec.description = "A Ruby client that wraps the OpenAI API through the Helicone AI Gateway, " \
+                     "providing session tracking, cost attribution, and an agentic framework " \
+                     "for building AI applications with tool/function calling."
+  spec.homepage = "https://github.com/genevere-inc/helicone-rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/genevere-inc/helicone-rb"
+  spec.metadata["changelog_uri"] = "https://github.com/genevere-inc/helicone-rb/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ruby-openai", "~> 7.0"
+
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+end

data/lib/helicone/agent.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Helicone
+  class Agent
+    MAX_ITERATIONS = 10
+
+    attr_reader :client, :tools, :messages, :context
+
+    # Create an agent with tools and optional context
+    #
+    # @param client [Helicone::Client] Optional client (creates new one if not provided)
+    # @param tools [Array<Class>] Array of Tool subclasses
+    # @param context [Object] Context object passed to tool#initialize
+    # @param system [String] System prompt
+    # @param messages [Array<Helicone::Message>] Initial messages (for continuing conversations)
+    def initialize(client: nil, tools: [], context: nil, system: nil, messages: [])
+      @client = client || Client.new
+      @tools = tools
+      @context = context
+      @messages = messages.dup
+
+      # Add system message at the start if provided and not already present
+      if system && @messages.none? { |m| m.respond_to?(:role) && m.role == "system" }
+        @messages.unshift(Message.system(system))
+      end
+    end
+
+    # Run the agent with a prompt, executing tools until done
+    #
+    # @param prompt [String] User prompt to start with
+    # @param max_iterations [Integer] Maximum tool execution loops
+    # @return [AgentResult]
+    def run(prompt, max_iterations: MAX_ITERATIONS)
+      @messages << Message.user_text(prompt)
+
+      iterations = 0
+      while iterations < max_iterations
+        response = call_llm
+
+        tool_calls = response.tool_calls
+        if tool_calls && !tool_calls.empty?
+          # Add assistant message with tool calls to conversation
+          @messages << Message.assistant_with_tool_calls(response.message)
+
+          # Execute each tool and add results
+          response.tool_calls.each do |tc|
+            tool_call = ToolCall.from_response([tc]).first
+            result = execute_tool(tool_call)
+            @messages << Message.tool_result(
+              tool_call_id: tool_call.id,
+              content: result
+            )
+          end
+
+          iterations += 1
+        else
+          # No tool calls - we're done
+          return AgentResult.new(
+            content: response.content,
+            messages: @messages,
+            iterations: iterations,
+            response: response
+          )
+        end
+      end
+
+      # Max iterations reached - make one final call without tools to get a response
+      final_response = @client.chat(messages: @messages)
+
+      AgentResult.new(
+        content: final_response.content,
+        messages: @messages,
+        iterations: iterations,
+        response: final_response,
+        max_iterations_reached: true
+      )
+    end
+
+    # Continue the conversation with a new prompt
+    #
+    # @param prompt [String] User prompt to continue with
+    # @param max_iterations [Integer] Maximum tool execution loops
+    # @return [AgentResult]
+    def continue(prompt, max_iterations: MAX_ITERATIONS)
+      run(prompt, max_iterations: max_iterations)
+    end
+
+    private
+
+    def logger
+      Helicone.configuration.logger
+    end
+
+    def call_llm
+      @client.chat(
+        messages: @messages,
+        tools: tools_for_api,
+        tool_choice: "auto"
+      )
+    end
+
+    def tools_for_api
+      return nil if @tools.empty?
+      @tools.map(&:to_openai_tool)
+    end
+
+    def execute_tool(tool_call)
+      tool_class = find_tool_class(tool_call.name)
+
+      unless tool_class
+        logger.warn("[Helicone::Agent] Unknown tool: #{tool_call.name}")
+        return { error: "Unknown tool: #{tool_call.name}" }
+      end
+
+      logger.info("[Helicone::Agent] Executing tool: #{tool_call.name} with #{tool_call.arguments}")
+
+      tool_instance = tool_class.new(@context)
+      result = tool_instance.execute(**tool_call.arguments)
+
+      result_preview = result.inspect
+      result_preview = result_preview[0, 197] + "..." if result_preview.length > 200
+      logger.info("[Helicone::Agent] Tool result: #{result_preview}")
+      result
+    rescue => e
+      logger.error("[Helicone::Agent] Tool execution error: #{e.message}")
+      logger.error(e.backtrace.first(5).join("\n"))
+      { error: e.message }
+    end
+
+    def find_tool_class(name)
+      @tools.find { |t| t.function_name == name }
+    end
+  end
+end

data/lib/helicone/agent_result.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Helicone
+  class AgentResult
+    attr_reader :content, :messages, :iterations, :response
+
+    # Initialize an agent result
+    #
+    # @param content [String] Final text response from the agent
+    # @param messages [Array<Helicone::Message>] Full conversation history
+    # @param iterations [Integer] Number of tool execution loops
+    # @param response [Helicone::Response] The final API response
+    # @param max_iterations_reached [Boolean] Whether the agent hit the iteration limit
+    def initialize(content:, messages:, iterations:, response: nil, max_iterations_reached: false)
+      @content = content
+      @messages = messages
+      @iterations = iterations
+      @response = response
+      @max_iterations_reached = max_iterations_reached
+    end
+
+    # Check if the agent hit the iteration limit
+    #
+    # @return [Boolean]
+    def max_iterations_reached?
+      @max_iterations_reached
+    end
+
+    # Check if the agent completed successfully
+    #
+    # @return [Boolean]
+    def success?
+      !@max_iterations_reached && !@content.nil? && !@content.empty?
+    end
+
+    # Count of tool calls executed during the run
+    #
+    # @return [Integer]
+    def tool_calls_made
+      @messages.count { |m| m.respond_to?(:role) && m.role == "tool" }
+    end
+
+    # Get all tool result messages from the conversation
+    #
+    # @return [Array<Helicone::Message>] Messages with role "tool"
+    def tool_results
+      @messages.select { |m| m.respond_to?(:role) && m.role == "tool" }
+    end
+  end
+end

data/lib/helicone/client.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Helicone
+  class Client
+    attr_reader :client
+
+    # Initialize with optional session/account context for Helicone tracking
+    #
+    # @param api_key [String] OpenAI API key (defaults to Helicone.configuration.api_key)
+    # @param session_id [String, Integer] Conversation/session ID for Helicone grouping
+    # @param session_name [String] Human-readable session name
+    # @param account_id [String, Integer] Account ID for cost tracking per account
+    # @param account_name [String] Human-readable account name
+    def initialize(api_key: nil, session_id: nil, session_name: nil, account_id: nil, account_name: nil)
+      config = Helicone.configuration
+
+      @client = OpenAI::Client.new(
+        access_token: api_key || config.api_key,
+        uri_base: config.uri_base
+      )
+
+      # 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 account_id
+        @client.add_headers(
+          "Helicone-User-Id" => account_id.to_s,
+          "Helicone-Property-Account" => account_name || account_id.to_s
+        )
+      end
+    end
+
+    # Send a chat completion request
+    #
+    # @param messages [Array<Helicone::Message, Hash>] Array of messages (Message objects or hashes)
+    # @param model [String] Model ID to use for completion
+    # @param tools [Array<Hash>] OpenAI tool definitions for function calling
+    # @param tool_choice [String, Hash] Tool choice strategy ("auto", "none", or specific tool)
+    # @param options [Hash] Additional options passed to the API
+    # @return [Helicone::Response] Wrapped API response
+    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
+
+    # Convenience method for simple single-turn requests
+    #
+    # @param prompt [String] User prompt text
+    # @param model [String] Model ID to use for completion
+    # @param system [String] Optional system prompt
+    # @param options [Hash] Additional options passed to chat
+    # @return [String] The text content of the response
+    def ask(prompt, model: nil, system: nil, **options)
+      messages = []
+      messages << Message.system(system) if system
+      messages << Message.user_text(prompt)
+
+      response = chat(messages: messages, model: model, **options)
+      response.content
+    end
+
+    # Ask with an image
+    #
+    # @param prompt [String] User prompt text
+    # @param image_url [String] URL or base64 data URI of the image
+    # @param model [String] Model ID to use for completion
+    # @param system [String] Optional system prompt
+    # @param detail [String] Image detail level: "auto", "low", or "high"
+    # @param options [Hash] Additional options passed to chat
+    # @return [String] The text content of the response
+    def ask_with_image(prompt, image_url, model: nil, system: nil, detail: "auto", **options)
+      messages = []
+      messages << Message.system(system) if system
+      messages << Message.user_with_images(prompt, image_url, detail: detail)
+
+      response = chat(messages: messages, model: model, **options)
+      response.content
+    end
+
+    # Add additional headers at any time
+    #
+    # @param headers [Hash] Headers to add to subsequent requests
+    # @return [void]
+    def add_headers(headers)
+      @client.add_headers(headers)
+    end
+
+    private
+
+    # Recursively symbolize keys in a hash
+    #
+    # @param obj [Object] Object to process
+    # @return [Object] Object with symbolized keys
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = deep_symbolize_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_symbolize_keys(item) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/helicone/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Helicone
+  class Configuration
+    attr_accessor :api_key, :uri_base, :logger, :default_model
+
+    # Initialize configuration with defaults
+    #
+    # @return [Configuration]
+    def initialize
+      @uri_base = "https://oai.helicone.ai/v1"
+      @default_model = "gpt-4"
+      @logger = Logger.new($stdout, level: Logger::INFO)
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    # Get the current configuration
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem
+    #
+    # @yield [Configuration] configuration object
+    # @return [void]
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults
+    #
+    # @return [Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/helicone/message.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Helicone
+  class Message
+    attr_reader :role, :content, :tool_call_id
+
+    # Initialize a message
+    #
+    # @param role [String, Symbol] Message role ("user", "assistant", "system", "tool")
+    # @param content [String, Array<Hash>] Message content (text or structured content)
+    # @param tool_call_id [String] Tool call ID (required for tool result messages)
+    def initialize(role:, content:, tool_call_id: nil)
+      @role = role.to_s
+      @content = content
+      @tool_call_id = tool_call_id
+    end
+
+    # Build a user message with text
+    #
+    # @param text [String] The text content
+    # @return [Helicone::Message]
+    def self.user_text(text)
+      new(role: "user", content: text)
+    end
+
+    # Build an assistant message with text
+    #
+    # @param text [String] The text content
+    # @return [Helicone::Message]
+    def self.assistant_text(text)
+      new(role: "assistant", content: text)
+    end
+
+    # Build a system message
+    #
+    # @param text [String] The system prompt text
+    # @return [Helicone::Message]
+    def self.system(text)
+      new(role: "system", content: text)
+    end
+
+    # Build a user message with text and images
+    #
+    # @param text [String] The text content
+    # @param images [Array<String>, String] Image URL(s) or base64 data URI(s)
+    # @param detail [String] Image detail level: "auto", "low", or "high"
+    # @return [Helicone::Message]
+    def self.user_with_images(text, images, detail: "auto")
+      content = []
+      content << { type: "text", text: text }
+
+      Array(images).each do |image|
+        content << {
+          type: "image_url",
+          image_url: {
+            url: image,
+            detail: detail
+          }
+        }
+      end
+
+      new(role: "user", content: content)
+    end
+
+    # Build a user message with a single image
+    #
+    # @param image_url [String] URL or base64 data URI of the image
+    # @param text [String] Optional text content to include
+    # @param detail [String] Image detail level: "auto", "low", or "high"
+    # @return [Helicone::Message]
+    def self.user_image(image_url, text: nil, detail: "auto")
+      content = []
+      content << { type: "text", text: text } if text
+      content << {
+        type: "image_url",
+        image_url: {
+          url: image_url,
+          detail: detail
+        }
+      }
+
+      new(role: "user", content: content)
+    end
+
+    # Build a tool result message
+    #
+    # @param tool_call_id [String] The ID of the tool call being responded to
+    # @param content [String, Hash] The tool result (will be JSON-encoded if not a string)
+    # @return [Helicone::Message]
+    def self.tool_result(tool_call_id:, content:)
+      content_str = content.is_a?(String) ? content : content.to_json
+      new(role: "tool", content: content_str, tool_call_id: tool_call_id)
+    end
+
+    # Build an assistant message that contains tool_calls (from API response)
+    # This stores the raw message so it can be returned as-is for the API
+    # Note: We transform null content to empty string as the API rejects null
+    #
+    # @param raw_message [Hash] The raw message hash from the API response
+    # @return [Helicone::Message]
+    def self.assistant_with_tool_calls(raw_message)
+      msg = new(role: "assistant", content: nil)
+      # Deep duplicate the message to avoid mutating the original
+      sanitized_message = deep_dup(raw_message)
+      if sanitized_message[:content].nil?
+        sanitized_message[:content] = ""
+      end
+      msg.instance_variable_set(:@raw_message, sanitized_message)
+      msg
+    end
+
+    # Convert to hash for API request
+    #
+    # @return [Hash] Message formatted for the API
+    def to_h
+      # If this is a raw message (assistant with tool_calls), return it as-is
+      if @raw_message
+        @raw_message
+      else
+        hash = { role: role, content: content }
+        hash[:tool_call_id] = tool_call_id if tool_call_id
+        hash
+      end
+    end
+
+    # Check if this message has tool calls
+    #
+    # @return [Boolean]
+    def tool_calls?
+      tool_calls = @raw_message&.dig(:tool_calls)
+      !tool_calls.nil? && !tool_calls.empty?
+    end
+
+    alias_method :to_hash, :to_h
+
+    # Deep duplicate a hash/array structure
+    #
+    # @param obj [Object] Object to duplicate
+    # @return [Object] Deep copy of the object
+    def self.deep_dup(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+      when Array
+        obj.map { |v| deep_dup(v) }
+      else
+        obj.respond_to?(:dup) ? obj.dup : obj
+      end
+    end
+  end
+end

data/lib/helicone/response.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Helicone
+  class Response
+    attr_reader :raw
+
+    # Initialize a response wrapper
+    #
+    # @param raw [Hash] The raw API response (symbolized keys)
+    def initialize(raw)
+      @raw = raw
+    end
+
+    # The assistant's text response content
+    #
+    # @return [String, nil]
+    def content
+      message&.dig(:content)
+    end
+
+    # The full message object from the first choice
+    #
+    # @return [Hash, nil]
+    def message
+      raw.dig(:choices, 0, :message)
+    end
+
+    # The role of the response (usually "assistant")
+    #
+    # @return [String, nil]
+    def role
+      message&.dig(:role)
+    end
+
+    # All choices returned (for n > 1)
+    #
+    # @return [Array<Hash>]
+    def choices
+      raw[:choices] || []
+    end
+
+    # The finish reason: "stop", "length", "tool_calls", etc.
+    #
+    # @return [String, nil]
+    def finish_reason
+      raw.dig(:choices, 0, :finish_reason)
+    end
+
+    # Usage statistics
+    #
+    # @return [Hash, nil]
+    def usage
+      raw[:usage]
+    end
+
+    # Number of tokens in the prompt
+    #
+    # @return [Integer, nil]
+    def prompt_tokens
+      usage&.dig(:prompt_tokens)
+    end
+
+    # Number of tokens in the completion
+    #
+    # @return [Integer, nil]
+    def completion_tokens
+      usage&.dig(:completion_tokens)
+    end
+
+    # Total tokens used (prompt + completion)
+    #
+    # @return [Integer, nil]
+    def total_tokens
+      usage&.dig(:total_tokens)
+    end
+
+    # Model used for the completion
+    #
+    # @return [String, nil]
+    def model
+      raw[:model]
+    end
+
+    # Unique ID for this completion
+    #
+    # @return [String, nil]
+    def id
+      raw[:id]
+    end
+
+    # Whether the response completed successfully
+    #
+    # @return [Boolean]
+    def success?
+      (content && !content.empty?) || finish_reason == "stop"
+    end
+
+    # Tool calls if any were made
+    #
+    # @return [Array<Hash>, nil]
+    def tool_calls
+      message&.dig(:tool_calls)
+    end
+
+    # Convert response content back to a Message for conversation history
+    #
+    # @return [Helicone::Message]
+    def to_message
+      Message.new(role: role, content: content)
+    end
+
+    # Delegate hash-like access to raw response
+    #
+    # @param key [Symbol] Key to access
+    # @return [Object, nil]
+    def [](key)
+      raw[key]
+    end
+
+    # Dig into nested data in raw response
+    #
+    # @param keys [Array<Symbol>] Keys to dig through
+    # @return [Object, nil]
+    def dig(*keys)
+      raw.dig(*keys)
+    end
+  end
+end

data/lib/helicone/tool.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Helicone
+  class Tool
+    class << self
+      attr_reader :tool_description, :tool_parameters
+
+      def inherited(subclass)
+        super
+        # Ensure subclasses get their own class instance variables
+        subclass.instance_variable_set(:@tool_description, nil)
+        subclass.instance_variable_set(:@tool_parameters, nil)
+      end
+
+      # Set the tool description
+      #
+      # @param text [String] Description of what this tool does
+      # @return [void]
+      def description(text)
+        @tool_description = text.strip
+      end
+
+      # Set the tool parameters schema
+      #
+      # @param schema [Hash] JSON Schema for the tool parameters
+      # @return [void]
+      def parameters(schema)
+        @tool_parameters = schema
+      end
+
+      # Get or set a custom tool name
+      #
+      # @param custom_name [String, nil] Custom name to set, or nil to get current name
+      # @return [String] The tool name
+      def tool_name(custom_name = nil)
+        if custom_name
+          @tool_name = custom_name
+        else
+          @tool_name || derive_function_name
+        end
+      end
+
+      # Generate the function name from class name
+      #
+      # @return [String] The function name for API calls
+      def function_name
+        @tool_name || derive_function_name
+      end
+
+      # Generate OpenAI tool definition
+      #
+      # @return [Hash] Tool definition formatted for OpenAI API
+      def to_openai_tool
+        {
+          type: "function",
+          function: {
+            name: function_name,
+            description: tool_description,
+            parameters: tool_parameters || { type: "object", properties: {}, required: [] }
+          }
+        }
+      end
+
+      private
+
+      # Derive function name from class name without Rails dependencies
+      # Converts "MyModule::SomeToolClass" to "some_tool_class" (without _tool suffix)
+      #
+      # @return [String]
+      def derive_function_name
+        # Get the class name without module prefix (like demodulize)
+        class_name = name.to_s.split("::").last
+
+        # Convert CamelCase to snake_case (like underscore)
+        snake_case = class_name
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+
+        # Remove _tool suffix if present
+        snake_case.sub(/_tool$/, "")
+      end
+    end
+
+    attr_reader :context
+
+    # Initialize a tool instance
+    #
+    # @param context [Object] Context object passed from the agent
+    def initialize(context = nil)
+      @context = context
+    end
+
+    # Execute the tool with the given arguments
+    #
+    # @param args [Hash] Arguments parsed from the tool call
+    # @return [Hash] Result to be returned to the LLM
+    def execute(**args)
+      raise NotImplementedError, "Subclasses must implement #execute"
+    end
+  end
+end

data/lib/helicone/tool_call.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Helicone
+  class ToolCall
+    attr_reader :id, :name, :arguments
+
+    # Initialize a tool call
+    #
+    # @param id [String] The unique ID for this tool call
+    # @param name [String] The name of the function to call
+    # @param arguments [String, Hash, nil] Arguments (JSON string or Hash)
+    def initialize(id:, name:, arguments:)
+      @id = id
+      @name = name
+      @arguments = if arguments.nil?
+        {}
+      elsif arguments.is_a?(String)
+        deep_symbolize_keys(JSON.parse(arguments))
+      else
+        deep_symbolize_keys(arguments)
+      end
+    end
+
+    # Parse tool calls from an API response (expects symbolized keys)
+    #
+    # @param response [Helicone::Response, Array<Hash>] Response object or tool_calls array
+    # @return [Array<Helicone::ToolCall>]
+    def self.from_response(response)
+      tool_calls = response.is_a?(Response) ? response.tool_calls : response
+      return [] if tool_calls.nil?
+
+      tool_calls.map do |tc|
+        new(
+          id: tc[:id],
+          name: tc.dig(:function, :name),
+          arguments: tc.dig(:function, :arguments)
+        )
+      end
+    end
+
+    # Build a tool result message to send back to the API
+    #
+    # @param tool_call_id [String] The ID of the tool call being responded to
+    # @param content [String, Hash] The tool result
+    # @return [Helicone::Message]
+    def self.result(tool_call_id:, content:)
+      Message.tool_result(tool_call_id: tool_call_id, content: content)
+    end
+
+    # Convert to hash for inspection
+    #
+    # @return [Hash]
+    def to_h
+      {
+        id: id,
+        name: name,
+        arguments: arguments
+      }
+    end
+
+    # Access arguments like a hash (supports both string and symbol keys)
+    #
+    # @param key [String, Symbol] Key to access
+    # @return [Object, nil]
+    def [](key)
+      arguments[key.to_sym]
+    end
+
+    # Dig into nested data in arguments
+    #
+    # @param keys [Array<String, Symbol>] Keys to dig through
+    # @return [Object, nil]
+    def dig(*keys)
+      arguments.dig(*keys.map(&:to_sym))
+    end
+
+    private
+
+    # Recursively symbolize keys in a hash
+    #
+    # @param obj [Object] Object to process
+    # @return [Object] Object with symbolized keys
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = deep_symbolize_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_symbolize_keys(item) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/helicone/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Helicone
+  VERSION = "0.0.1"
+end

data/lib/helicone.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "openai"
+require "json"
+
+require_relative "helicone/version"
+require_relative "helicone/configuration"
+require_relative "helicone/message"
+require_relative "helicone/response"
+require_relative "helicone/tool_call"
+require_relative "helicone/tool"
+require_relative "helicone/agent"
+require_relative "helicone/agent_result"
+require_relative "helicone/client"
+
+module Helicone
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: helicone-rb
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Genevere
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A Ruby client that wraps the OpenAI API through the Helicone AI Gateway,
+  providing session tracking, cost attribution, and an agentic framework for building
+  AI applications with tool/function calling.
+email:
+- hello@genevere.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".tool-versions"
+- LICENSE
+- README.md
+- Rakefile
+- helicone.gemspec
+- lib/helicone.rb
+- lib/helicone/agent.rb
+- lib/helicone/agent_result.rb
+- lib/helicone/client.rb
+- lib/helicone/configuration.rb
+- lib/helicone/message.rb
+- lib/helicone/response.rb
+- lib/helicone/tool.rb
+- lib/helicone/tool_call.rb
+- lib/helicone/version.rb
+homepage: https://github.com/genevere-inc/helicone-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/genevere-inc/helicone-rb
+  source_code_uri: https://github.com/genevere-inc/helicone-rb
+  changelog_uri: https://github.com/genevere-inc/helicone-rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for Helicone AI Gateway with agentic tool support
+test_files: []