AI Chat

gem "ai-chat", "< 1.0.0"

require "ai-chat"

# Create an instance of AI::Chat
a = AI::Chat.new

# Build up your conversation by adding messages
a.add("If the Ruby community had an official motto, what might it be?")

# See the convo so far - it's just an array of hashes!
pp a.messages
# => [{:role=>"user", :content=>"If the Ruby community had an official motto, what might it be?"}]

# Generate the next message using AI
a.generate! # => { :role => "assistant", :content => "Matz is nice and so we are nice" (or similar) }

# Your array now includes the assistant's response
pp a.messages
# => [
#      {:role=>"user", :content=>"If the Ruby community had an official motto, what might it be?"},
#      {:role=>"assistant", :content=>"Matz is nice and so we are nice", :response => { id=resp_abc... model=gpt-5.1 tokens=12 } }
#    ]

# Continue the conversation
a.add("What about Rails?")
a.generate! # => { :role => "assistant", :content => "Convention over configuration."} 

[
  {:role => "system", :content => "You are a helpful assistant"},
  {:role => "user", :content => "Hello!"},
  {:role => "assistant", :content => "Hi there! How can I help you today?", :response => { id=resp_abc... model=gpt-5.1 tokens=12 } }
]

require "ai-chat"

b = AI::Chat.new

# Add system instructions
b.add("You are a helpful assistant that talks like Shakespeare.", role: "system")

# Add a user message (role defaults to "user")
b.add("If the Ruby community had an official motto, what might it be?")

# Check what we've built
pp b.messages
# => [
#      {:role=>"system", :content=>"You are a helpful assistant that talks like Shakespeare."},
#      {:role=>"user", :content=>"If the Ruby community had an official motto, what might it be?"}
#    ]

# Generate a response
b.generate! # => { :role => "assistant", :content => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'" }

c = AI::Chat.new

# These are equivalent:
c.add("You are helpful", role: "system")
c.system("You are helpful")

# These are equivalent:
c.add("Hello there!")
c.user("Hello there!")

# These are equivalent:
c.add("Hi! How can I help?", role: "assistant")
c.assistant("Hi! How can I help?")

# In a Rails app, you might do:
d = AI::Chat.new
d.messages = @conversation.messages  # Load existing messages
d.user("What should I do next?")     # Add a new question
d.generate!                         # Generate a response

e = AI::Chat.new
e.model = "gpt-4o"

f = AI::Chat.new(api_key_env_var: "MY_OPENAI_TOKEN")

g = AI::Chat.new(api_key: "your-api-key-goes-here")

h = AI::Chat.new
h.system("You are a helpful cooking assistant")
h.user("How do I boil an egg?")
h.generate!

# See the whole conversation
pp h.messages
# => [
#      {:role=>"system", :content=>"You are a helpful cooking assistant"},
#      {:role=>"user", :content=>"How do I boil an egg?"},
#      {:role=>"assistant", :content=>"Here's how to boil an egg..."}
#    ]

# Get just the last response
h.messages.last[:content]
# => "Here's how to boil an egg..."

# Or use the convenient shortcut
h.last[:content]
# => "Here's how to boil an egg..."

m = AI::Chat.new
m.web_search = true
m.user("What are the latest developments in the Ruby language?")
m.generate! # This may use web search to find current information

i = AI::Chat.new

i.system("You are an expert nutritionist. The user will describe a meal. Estimate the calories, carbs, fat, and protein.")

# The schema should be a JSON string (use OpenAI's tool to generate: https://platform.openai.com/docs/guides/structured-outputs)
i.schema = '{"name": "nutrition_values","strict": true,"schema": {"type": "object","properties": {"fat": {"type": "number","description": "The amount of fat in grams."},"protein": {"type": "number","description": "The amount of protein in grams."},"carbs": {"type": "number","description": "The amount of carbohydrates in grams."},"total_calories": {"type": "number","description": "The total calories calculated based on fat, protein, and carbohydrates."}},"required": ["fat","protein","carbs","total_calories"],"additionalProperties": false}}'

i.user("1 slice of pizza")

response = i.generate!
data = response[:content]
# => {:fat=>15, :protein=>12, :carbs=>35, :total_calories=>285}

# The response is parsed JSON, not a string!
data[:total_calories]  # => 285

# When you need complete control over the schema structure
i.schema = {
  format: {
    type: :json_schema,
    name: "nutrition_values",
    strict: true,
    schema: {
      type: "object",
      properties: {
        fat: { type: "number", description: "The amount of fat in grams." },
        protein: { type: "number", description: "The amount of protein in grams." }
      },
      required: ["fat", "protein"],
      additionalProperties: false
    }
  }
}

# The format shown in OpenAI's documentation
i.schema = {
  name: "nutrition_values",
  strict: true,
  schema: {
    type: "object",
    properties: {
      fat: { type: "number", description: "The amount of fat in grams." },
      protein: { type: "number", description: "The amount of protein in grams." }
    },
    required: [:fat, :protein],
    additionalProperties: false
  }
}

# The simplest format - just provide the schema itself
# The gem will wrap it with sensible defaults (name: "response", strict: true)
i.schema = {
  type: "object",
  properties: {
    fat: { type: "number", description: "The amount of fat in grams." },
    protein: { type: "number", description: "The amount of protein in grams." }
  },
  required: ["fat", "protein"],
  additionalProperties: false
}

# As a JSON string with full format
i.schema = '{"format":{"type":"json_schema","name":"nutrition_values","strict":true,"schema":{...}}}'

# As a JSON string with name/strict/schema
i.schema = '{"name":"nutrition_values","strict":true,"schema":{...}}'

# As a simple JSON schema string
i.schema = '{"type":"object","properties":{...}}'

AI::Chat.generate_schema!("A user profile with name (required), email (required), age (number), and bio (optional text).")
# => "{ ... }"

# Passing the API key directly
AI::Chat.generate_schema!("A user with full name (required), first_name (required), and last_name (required).", api_key: "MY_SECRET_API_KEY")

# Choosing a different API key name
AI::Chat.generate_schema!("A user with full name (required), first_name (required), and last_name (required).", api_key_env_var: "CUSTOM_KEY")

AI::Chat.generate_schema!("A user with full name (required), first_name (required), and last_name (required).", location: "my_schemas/user.json")

AI::Chat.generate_schema!("A user with full name (required), first_name (required), and last_name (required).", location: false)
# => { ... }

j = AI::Chat.new

# Send a single image
j.user("What's in this image?", image: "path/to/local/image.jpg")
j.generate!  # => "I can see a sunset over the ocean..."

# Send multiple images
j.user("Compare these images", images: ["image1.jpg", "image2.jpg"])
j.generate!  # => "The first image shows... while the second..."

# Mix URLs and local files
j.user("What's the difference?", images: [
  "local_photo.jpg",
  "https://example.com/remote_photo.jpg"
])
j.generate!

k = AI::Chat.new

# Send a single file
k.user("Summarize this document", file: "report.pdf")
k.generate!

# Send multiple files
k.user("Compare these documents", files: ["doc1.pdf", "doc2.txt", "data.json"])
k.generate!

l = AI::Chat.new

# Mix image and file in one message
l.user("Compare this photo with the document", 
       image: "photo.jpg", 
       file: "document.pdf")
l.generate!

# Mix multiple images and files
l.user("Analyze all these materials",
       images: ["chart1.png", "chart2.png"],
       files: ["report.pdf", "data.csv"])
l.generate!

a = AI::Chat.new
a.image_generation = true
a.user("Draw a picture of a kitten")
a.generate! # => { :content => "Here is your picture of a kitten:", ... }

a = AI::Chat.new
a.image_generation = true
a.image_folder = "./my_images"
a.user("Draw a picture of a kitten")
a.generate! # => { :content => "Here is your picture of a kitten:", ... }

pp a.messages
# => [
#   {:role=>"user", :content=>"Draw a picture of a kitten"},
#   {:role=>"assistant", :content=>"Here is your picture of a kitten:", :images => ["./images/20250804T11303912_resp_abc123/001.png"], :response => #<Response ...>}
# ]

# From the last message
images = a.messages.last[:images]
# => ["./images/20250804T11303912_resp_abc123/001.png"]

# From the response object
images = a.messages.last[:response].images
# => ["./images/20250804T11303912_resp_abc123/001.png"]

a = AI::Chat.new
a.image_generation = true
a.image_folder = "./images"
a.user("Draw a picture of a kitten")
a.generate! # => { :content => "Here is a picture of a kitten:", ... }
a.user("Make it even cuter")
a.generate! # => { :content => "Here is the kitten, but even cuter:", ... }

y = AI::Chat.new
y.code_interpreter = true
y.user("Plot y = 2x*3 when x is -5 to 5.")
y.generate! # => {:content => "Here is the graph.", ... }

chat = AI::Chat.new
chat.proxy = true
chat.user("Tell me a story")
chat.generate!
puts chat.last[:content]
# => "Once upon a time..."

# Create a new chat instance
k = AI::Chat.new

# Add previous messages
k.system("You are a helpful assistant who provides information about planets.")

k.user("Tell me about Mars.")
k.assistant("Mars is the fourth planet from the Sun....")

k.user("What's the atmosphere like?")
k.assistant("Mars has a very thin atmosphere compared to Earth....")

k.user("Could it support human life?")
k.assistant("Mars currently can't support human life without....")

# Now continue the conversation with an API-generated response
k.user("Are there any current missions to go there?")
response = k.generate!
puts response

l = AI::Chat.new
l.reasoning_effort = "low" # Can be "low", "medium", or "high"

l.user("What does this error message mean? <insert error message>")
l.generate!

t = AI::Chat.new
t.user("Hello!")
t.generate!

# Each assistant message includes a response object
pp t.messages.last
# => {
#      :role => "assistant",
#      :content => "Hello! How can I help you today?",
#      :response => { id=resp_abc... model=gpt-5.1 tokens=12 }
#    }

# Access detailed information
response = t.last[:response]
response[:id]           # => "resp_abc123..."
response[:model]        # => "gpt-5.1"
response[:usage]        # => {:prompt_tokens=>5, :completion_tokens=>7, :total_tokens=>12}

chat = AI::Chat.new
chat.user("Hello")
chat.generate!

puts chat.last_response_id # => "resp_abc123..."

chat.user("Goodbye")
chat.generate!

puts chat.last_response_id # => "resp_xyz789..." (a new ID)

chat = AI::Chat.new
chat.user("Hello")
chat.generate!

# Conversation ID is automatically set
puts chat.conversation_id  # => "conv_abc123..."

# Continue the conversation - context is automatically maintained
chat.user("What did I just say?")
chat.generate!  # Uses the same conversation automatically

# Load stored conversation_id from your database
chat = AI::Chat.new
chat.conversation_id = @thread.conversation_id  # From your database

chat.user("Continue our discussion")
chat.generate!  # Uses the loaded conversation

chat = AI::Chat.new
chat.web_search = true
chat.user("Search for Ruby tutorials")
chat.generate!

# Get all conversation items (chronological order by default)
page = chat.items

# Access item data
page.data.each do |item|
  case item.type
  when :message
    puts "#{item.role}: #{item.content.first.text}"
  when :web_search_call
    puts "Web search: #{item.action.query}"
    puts "Results: #{item.results.length}"
  when :reasoning
    puts "Reasoning: #{item.summary.first.text}"
  end
end

# For long conversations, you can request reverse chronological order
# (useful for pagination to get most recent items first)
recent_items = chat.items(order: :desc)

chat.verbose

# Output:
# ┌────────────────────────────────────────────────────────────────────────────┐
# │ Conversation: conv_6903c1eea6cc819695af3a1b1ebf9b390c3db5e8ec021c9a        │
# │ Items: 3                                                                   │
# └────────────────────────────────────────────────────────────────────────────┘
#
# [detailed colorized output of all items including web searches,
#  reasoning, tool calls, messages, etc.]

# Using the planet example with array of hashes
p = AI::Chat.new

# Set all messages at once instead of calling methods sequentially
p.messages = [
  { role: "system", content: "You are a helpful assistant who provides information about planets." },
  { role: "user", content: "Tell me about Mars." },
  { role: "assistant", content: "Mars is the fourth planet from the Sun...." },
  { role: "user", content: "What's the atmosphere like?" },
  { role: "assistant", content: "Mars has a very thin atmosphere compared to Earth...." },
  { role: "user", content: "Could it support human life?" },
  { role: "assistant", content: "Mars currently can't support human life without...." }
]

# Now continue the conversation with an API-generated response
p.user("Are there any current missions to go there?")
response = p.generate!
puts response

# Create a new chat instance
q = AI::Chat.new

# With images
q.messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What's in this image?", image: "path/to/image.jpg" },
]

# With multiple images
q.messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Compare these images", images: ["image1.jpg", "image2.jpg"] }
]