helicone-rb 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30551d818f767a29ad080d1ec1beffc42a5346e0e4f94f9cbe112b6c7aaaa9b5
-  data.tar.gz: 3505af534452304f15f075a0fbde6d334c8a1b3cc8a4a85f61abc292fe564226
+  metadata.gz: 22d855f83be3572fa91710cb1a63483ac70e07717b9a77103ca752d71931ad09
+  data.tar.gz: 26a6eca90b9d1c9ff1cee79ae8a774da5a65fec8088c30bae1956c493242e336
 SHA512:
-  metadata.gz: 2e09d82c356de9e0ca25af6846e582c63bbc773fab7c7f257e0e06a2dcf4ebbb0ee6af983457a7fd61fa9b5ec84116e7621017cf4fb8216649bdfc23fd6d14a9
-  data.tar.gz: 44affe9ff8922ba1254567b88cb7ac4b280aa3b95eac4162969c6ac606e6be5194f8b2b1784feaba1cdc73d340d67cef078f5bf7e63b4caa36b401a02ce384d8
+  metadata.gz: de7718c83e259ded888212a02c63f2cac6f02eb457ded45361efa1d903a2490a0774425dccab4861da8dd40d48888ab3a156ab769dac1c8f64d42e59b427aa41
+  data.tar.gz: 60bc8baed47ae2599f8a7f7f5ecfeca1e791b9b1ddf1123a61e99d7e2f1368254dfeef3a29d0d3941f27c1b1215fe1ac28220ce5ec74c292e610ea9c132d6763

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:
@@ -79,7 +112,7 @@ response = client.ask("What is the capital of France?")
 # With system prompt
 response = client.ask(
   "Explain quantum computing",
-  system: "You are a physics teacher. Explain concepts simply."
+  system_prompt: "You are a physics teacher. Explain concepts simply."
 )
 ```
 
@@ -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/client.rb

@@ -66,12 +66,12 @@ module Helicone
     #
     # @param prompt [String] User prompt text
     # @param model [String] Model ID to use for completion
-    # @param system [String] Optional system prompt
+    # @param system_prompt [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)
+    def ask(prompt, model: nil, system_prompt: nil, **options)
       messages = []
-      messages << Message.system(system) if system
+      messages << Message.system(system_prompt) if system_prompt
       messages << Message.user_text(prompt)
 
       response = chat(messages: messages, model: model, **options)
@@ -83,13 +83,13 @@ module Helicone
     # @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 system_prompt [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)
+    def ask_with_image(prompt, image_url, model: nil, system_prompt: nil, detail: "auto", **options)
       messages = []
-      messages << Message.system(system) if system
+      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)

data/lib/helicone/version.rb

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

data/sample.rb

@@ -23,7 +23,7 @@ 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")
+client.ask("Tell me a joke", system_prompt: "You are a comedian")
 
 # With a specific model
 client.ask("Explain Ruby blocks", model: "gpt-4o-mini")
@@ -115,7 +115,7 @@ end
 # Run the agent
 agent = Helicone::Agent.new(
 tools: [WeatherTool, CalculatorTool],
-system: "You are a helpful assistant with access to weather and calculator tools."
+system_prompt: "You are a helpful assistant with access to weather and calculator tools."
 )
 
 result = agent.run("What's the weather in San Francisco?")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: helicone-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Genevere