helicone-rb 0.0.4 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e47a2406f0ff4091abc0a4720eaa015bd157b76dc8c231c1d9b3e6fe2ed97c4
-  data.tar.gz: 6c9debdd6b54fead261c3ba10b7cee76aa25b4e0ea15c1b3324b1e8d56713ff7
+  metadata.gz: e88e12d27963faaf420d13dc78cda2eada0f86fd97fb22570c310ac91610bf03
+  data.tar.gz: fa8f16816537172ec4ef2c859791e63e816860fe23a5e72bc78b361177587d9a
 SHA512:
-  metadata.gz: d06ffd02119a05aa69abffd784e545f00c914554e2ccf36c7dce952aa24417055ba6ea4d10c17d6979d736b754f19d6bdfbad04044d02f91ddc6ce4df1c95960
-  data.tar.gz: 20f39820ca78bd10e6ff7205b42cd78f24865632281da0c07456b2c5af5ff90f49ab79f1e48984cbffa5cffc6c1c455ed424ab5c5c47a84486d5758193730a10
+  metadata.gz: 5a3b285e947a350c25e2b7d68b5c415b38ed1415eaaa366078ed356405e19989f1fc4674e4709113dfc09a3b089534edbb03fbebdfa169d5f0b1d13ec28612fb
+  data.tar.gz: b8feec47c41a127a1108328c729ee11398d83c360b8498aacb71781c9a035aba6cba874851647cfc706dd93a08961593ce1f889cabc087c472850f8e427a3b5b

data/README.md

@@ -1,7 +1,11 @@
+> **Beta** - This library is under active development. APIs may change.
+
 # 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.
 
+
+
 ## Why Helicone?
 
 [Helicone](https://helicone.ai) is an AI gateway that sits between your application and LLM providers (OpenAI, Anthropic, etc.). It provides:
@@ -16,6 +20,35 @@ A Ruby client for the [Helicone AI Gateway](https://helicone.ai), wrapping the O
 
 *The Helicone dashboard shows all your LLM requests with latency, cost, and token usage at a glance.*
 
+### Under the hood
+This is an API that interacts with **any OpenAI-format /chat/completions LLM endpoint.**
+[Helicone](https://helicone.ai) acts as a proxy, similar to OpenRouter, with built in telemetry and more.
+
+This library adds the ability to interact with Helicone specific features like [Session waterfall tracking](https://github.com/genevere-inc/helicone-rb/tree/main?tab=readme-ov-file#session-and-account-tracking).
+
+### Alternatives
+
+**[RubyLLM](https://rubyllm.com/)** 
+
+This library is great for an opinioned quick start, but I found it has too much magic under the hood that makes using proxies like Helicone and OpenRouter very difficult.
+
+**[`alexrudall/ruby-openai`](https://github.com/alexrudall/ruby-openai)**
+
+This gem uses this great library under the hood. If you don't need tool calling or helicone, you can use this instead.
+
+**[`openai/openai-ruby`](https://github.com/openai/openai-ruby)**
+
+This is the official gem from OpenAI. It's severely lacking in functionality.
+
+**[`Traceloop`](https://traceloop.com/)**
+
+A telemetry tool built on top of OpenTelemetry. Their `traceloop-sdk` gem did not work out of the box as of June 2025, but accepts OpenTelemetry endpoints and works quite well for visualizing agentic workflows.
+
+Note that it **does not** act as a _proxy_ in the way Helicone and OpenRouter do, which may help if you need to use LLM hosts directly, or may be a drawback given it lacks the fallback mechanisms the proxies include.
+
+_Note:_ I've used this in production and it works very reliably for tracking, but cost aggregation has never worked correctly. For that and other challenges, switched to Helicone.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -223,7 +256,7 @@ end
 ```ruby
 agent = Helicone::Agent.new(
   tools: [WeatherTool, CalendarTool],
-  system: "You are a helpful assistant with access to weather and calendar tools.",
+  system_prompt: "You are a helpful assistant with access to weather and calendar tools.",
   context: current_user  # Passed to tool#initialize
 )
 

data/lib/helicone/agent.rb

@@ -11,17 +11,17 @@ module Helicone
     # @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 system_prompt [String] System prompt
     # @param messages [Array<Helicone::Message>] Initial messages (for continuing conversations)
-    def initialize(client: nil, tools: [], context: nil, system: nil, messages: [])
+    def initialize(client: nil, tools: [], context: nil, system_prompt: 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))
+      if system_prompt && @messages.none? { |m| m.respond_to?(:role) && m.role == "system" }
+        @messages.unshift(Message.system(system_prompt))
       end
     end
 

data/lib/helicone/version.rb

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

data/sample.rb

@@ -0,0 +1,177 @@
+require 'helicone'
+
+
+  # ============================================
+  # Configuration
+  # ============================================
+
+  Helicone.configure do |config|
+    config.default_model = "gpt-4o-mini"
+    config.logger = Logger.new(STDOUT, level: Logger::DEBUG)
+  end
+
+if ENV["HELICONE_API_KEY"].nil?
+  fail StandardError, "HELICONE_API_KEY is not set"
+end
+
+# ============================================
+# Basic Usage - Simple Questions
+# ============================================
+
+client = Helicone::Client.new
+client.ask("What is 2 + 2?")
+# => "2 + 2 equals 4."
+
+# With a system prompt
+client.ask("Tell me a joke", system: "You are a comedian")
+
+# With a specific model
+client.ask("Explain Ruby blocks", model: "gpt-4o-mini")
+
+# ============================================
+# With Session/Account Tracking
+# ============================================
+
+client = Helicone::Client.new(
+session_id: "conv_123",
+session_name: "Customer Support Chat",
+account_id: "user_456",
+account_name: "Acme Corp"
+)
+
+client.ask("Help me with my order")
+
+# ============================================
+# Multi-turn Conversation
+# ============================================
+
+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!"
+
+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 - Ask About Images
+# ============================================
+
+client.ask_with_image(
+"What's in this image?",
+"https://example.com/photo.jpg",
+detail: "high"
+)
+
+# ============================================
+# Using the Agent with Tools
+# ============================================
+
+# Define a tool
+class WeatherTool < Helicone::Tool
+description "Get current weather for a location"
+
+parameters(
+    type: "object",
+    properties: {
+    location: { type: "string", description: "City name" }
+    },
+    required: ["location"]
+)
+
+def execute(location:)
+    # In reality, call a weather API
+    { temperature: 72, conditions: "sunny", location: location }
+end
+end
+
+class CalculatorTool < Helicone::Tool
+description "Evaluate a math expression"
+
+parameters(
+    type: "object",
+    properties: {
+    expression: { type: "string", description: "Math expression like '2 + 2'" }
+    },
+    required: ["expression"]
+)
+
+def execute(expression:)
+    { result: eval(expression) }
+rescue => e
+    { error: e.message }
+end
+end
+
+# Run the agent
+agent = Helicone::Agent.new(
+tools: [WeatherTool, CalculatorTool],
+system: "You are a helpful assistant with access to weather and calculator tools."
+)
+
+result = agent.run("What's the weather in San Francisco?")
+puts result.content
+puts "Iterations: #{result.iterations}"
+puts "Tool calls made: #{result.tool_calls_made}"
+
+# Continue the conversation
+result = agent.continue("What about New York?")
+puts result.content
+
+# ============================================
+# Agent with Context
+# ============================================
+
+# Context is passed to tool instances
+class DatabaseTool < Helicone::Tool
+description "Query the database"
+
+parameters(
+    type: "object",
+    properties: {
+    query: { type: "string" }
+    },
+    required: ["query"]
+)
+
+def execute(query:)
+    # Access context passed from agent
+    user_id = context[:user_id]
+    { results: "Data for user #{user_id}: #{query}" }
+end
+end
+
+agent = Helicone::Agent.new(
+tools: [DatabaseTool],
+context: { user_id: 123, db: some_db_connection }
+)
+
+result = agent.run("Find my recent orders")
+
+# ============================================
+# Inspecting Responses
+# ============================================
+
+client = Helicone::Client.new
+response = client.chat(
+messages: [Helicone::Message.user_text("Hello")]
+)
+
+response.content          # => "Hello! How can I help?"
+response.role             # => "assistant"
+response.model            # => "gpt-4o"
+response.finish_reason    # => "stop"
+response.prompt_tokens    # => 10
+response.completion_tokens # => 15
+response.total_tokens     # => 25
+response.success?         # => true
+response.raw              # => full raw response hash

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: helicone-rb
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.1
 platform: ruby
 authors:
 - Genevere
@@ -93,6 +93,7 @@ files:
 - readme-assets/helicone-dashboard.png
 - readme-assets/helicone-model-registry.png
 - readme-assets/helicone-session-flamegraph.png
+- sample.rb
 homepage: https://github.com/genevere-inc/helicone-rb
 licenses:
 - MIT