helicone-rb 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2be72b17bc38b9d451b2888a29407c7af83212d26c580ec22de03cdb9a97c0fb
-  data.tar.gz: 17682bc18311ebc1c2be4e3607db90b3e9d7c2fc90bfeedae38e8bef67e79321
+  metadata.gz: 30551d818f767a29ad080d1ec1beffc42a5346e0e4f94f9cbe112b6c7aaaa9b5
+  data.tar.gz: 3505af534452304f15f075a0fbde6d334c8a1b3cc8a4a85f61abc292fe564226
 SHA512:
-  metadata.gz: 5641f51284e72fdcc5a74f68b38fb9afe0cd11607dda855e6193ec555c6c8aae5d2507b4ce0a7e39161ec5a6fd2e22d0a0d19200e895641167a93cffd50914ef
-  data.tar.gz: 5ea90b79077f3ffc5b19c98ae8ab998790bd8580bb63ecf70fc7f3ee74d9e447f61a4d518007bcc2c17a988adcda0df26cfa0f6e1ae110838b2037f8dab3ff80
+  metadata.gz: 2e09d82c356de9e0ca25af6846e582c63bbc773fab7c7f257e0e06a2dcf4ebbb0ee6af983457a7fd61fa9b5ec84116e7621017cf4fb8216649bdfc23fd6d14a9
+  data.tar.gz: 44affe9ff8922ba1254567b88cb7ac4b280aa3b95eac4162969c6ac606e6be5194f8b2b1784feaba1cdc73d340d67cef078f5bf7e63b4caa36b401a02ce384d8

data/README.md

@@ -2,6 +2,20 @@
 
 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:
+
+- **Unified billing** - One API key, one bill, access to multiple providers
+- **Request logging** - Every API call is logged with full request/response details
+- **Cost tracking** - See exactly what you're spending per user, session, or feature
+- **Latency monitoring** - Track response times and identify slow requests
+- **Rate limiting & caching** - Built-in protection and optimization
+
+![Helicone Dashboard](readme-assets/helicone-dashboard.png)
+
+*The Helicone dashboard shows all your LLM requests with latency, cost, and token usage at a glance.*
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -24,14 +38,30 @@ gem install helicone-rb
 
 ## Configuration
 
-Configure the gem with your API key and optional settings:
+First, [sign up for a Helicone account](https://us.helicone.ai/signup) to get your API key.
+
+Set the `HELICONE_API_KEY` environment variable:
+
+```bash
+export HELICONE_API_KEY=sk-helicone-your-key-here
+```
+
+That's it! The gem reads from `ENV["HELICONE_API_KEY"]` automatically.
+
+Helicone handles billing and routes requests to OpenAI or other providers. See the [model registry](https://www.helicone.ai/models) for supported models including GPT-4, Claude, Llama, and more.
+
+![Helicone Model Registry](readme-assets/helicone-model-registry.png)
+
+*Browse all available models with pricing, context windows, and capabilities in the Helicone model registry.*
+
+### Optional Configuration
+
+You can optionally configure the default model and logger:
 
 ```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
+  config.default_model = "gpt-4o"             # default
+  config.logger = Logger.new($stdout)         # default
 end
 ```
 
@@ -98,7 +128,7 @@ response = client.chat(messages: [message])
 
 ## Session and Account Tracking
 
-Track conversations and costs in the Helicone dashboard:
+Track conversations and attribute costs to specific users or accounts in the Helicone dashboard:
 
 ```ruby
 client = Helicone::Client.new(
@@ -109,6 +139,12 @@ client = Helicone::Client.new(
 )
 ```
 
+Sessions group related requests together, letting you see the full flow of a conversation or agentic workflow:
+
+![Helicone Session Flamegraph](readme-assets/helicone-session-flamegraph.png)
+
+*The session view shows each request in a conversation as a flamegraph, with timing and token usage for each step. Great for debugging agent loops and understanding where time and tokens are spent.*
+
 ## Agentic Framework
 
 Build AI agents that can use tools to accomplish tasks.
@@ -254,6 +290,14 @@ bundle install
 bundle exec rspec
 ```
 
+### Live Integration Tests
+
+To run tests against the actual Helicone API:
+
+```bash
+HELICONE_LIVE_TEST=true HELICONE_API_KEY=your_key bundle exec rspec spec/helicone/integration_spec.rb
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/genevere-inc/helicone-rb.

data/lib/helicone/client.rb

@@ -6,17 +6,14 @@ module Helicone
 
     # 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
-
+    def initialize(session_id: nil, session_name: nil, account_id: nil, account_name: nil)
       @client = OpenAI::Client.new(
-        access_token: api_key || config.api_key,
-        uri_base: config.uri_base
+        access_token: ENV["HELICONE_API_KEY"],
+        uri_base: Helicone::URI_BASE
       )
 
       # Add Helicone session headers if provided

data/lib/helicone/configuration.rb

@@ -3,15 +3,16 @@
 require "logger"
 
 module Helicone
+  URI_BASE = "https://ai-gateway.helicone.ai/v1"
+
   class Configuration
-    attr_accessor :api_key, :uri_base, :logger, :default_model
+    attr_accessor :logger, :default_model
 
     # Initialize configuration with defaults
     #
     # @return [Configuration]
     def initialize
-      @uri_base = "https://oai.helicone.ai/v1"
-      @default_model = "gpt-4"
+      @default_model = "gpt-4o"
       @logger = Logger.new($stdout, level: Logger::INFO)
     end
   end

data/lib/helicone/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Helicone
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 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.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Genevere
@@ -90,6 +90,10 @@ files:
 - lib/helicone/tool.rb
 - lib/helicone/tool_call.rb
 - lib/helicone/version.rb
+- 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