ai-chat 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2397a7d43d950bf70abd84c83d0e57b2cadb70fc127985fae4da4a9ecf142b8
-  data.tar.gz: d44a9d1999ce48cd0af92f367f5f0e2f586b8c19d1fc9e95ce8c7aa7e3fffa84
+  metadata.gz: b21d17972572c7c6282aa2a40c539f48967b47caad6ac0f80f99046337436576
+  data.tar.gz: b27033cec74910347d8f965e7aa4928b888a0d42aa8f14c48bc229014522cf7d
 SHA512:
-  metadata.gz: fdb13f4e405f46a21591f71ae818544bc60f7bc083e4b3eb9a8a6d57b9eba03995fe8b75828f3972e564dfa3ed3ed09aed4a8b7ae2260b3602cbede9d80afd8e
-  data.tar.gz: 427b5db79e006d0f6f9b20b83472a78c3234118807e4d43d472304426ca2d80d5b189d029924cd548d7004206914a4e63fd52ca93b1944e55e81276309a501d9
+  metadata.gz: 5fd677c3e077c29a9777c1c1fa57108798d39ad09fed0093db12ce0819c9a4a204bbc8cbbfd84b4236df48b9ee7e3a0ea0469d29745188d1a22d3f5789f5c65a
+  data.tar.gz: 4edb6917f52330c5a8dd27e825e1cc27201da82ab8cc7e4988d0514b3ed92969f0b8369be4ceec44fbaa3684545774060430ca110730e5dfe753686c4f292526

data/README.md

@@ -34,6 +34,11 @@ The `examples/` directory contains focused examples for specific features:
 - `08_advanced_usage.rb` - Advanced patterns (chaining, web search)
 - `09_edge_cases.rb` - Error handling and edge cases
 - `10_additional_patterns.rb` - Less common usage patterns (direct add method, web search + schema, etc.)
+- `11_mixed_content.rb` - Combining text and images in messages
+- `12_image_generation.rb` - Using the image generation tool
+- `13_code_interpreter.rb` - Using the code interpreter tool
+- `14_background_mode.rb` - Running responses in background mode
+- `15_conversation_features_comprehensive.rb` - All conversation features (auto-creation, inspection, loading, forking)
 
 Each example is self-contained and can be run individually:
 ```bash
@@ -82,7 +87,7 @@ 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! # => "Matz is nice and so we are nice" (or similar)
+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
@@ -93,7 +98,7 @@ pp a.messages
 
 # Continue the conversation
 a.add("What about Rails?")
-a.generate! # => "Convention over configuration."
+a.generate! # => { :role => "assistant", :content => "Convention over configuration."} 
 ```
 
 ## Understanding the Data Structure
@@ -135,7 +140,7 @@ pp b.messages
 #    ]
 
 # Generate a response
-b.generate! # => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'"
+b.generate! # => { :role => "assistant", :content => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'" }
 ```
 
 ### Convenience Methods
@@ -237,23 +242,24 @@ h.messages.last[:content]
 # => "Here's how to boil an egg..."
 
 # Or use the convenient shortcut
-h.last
+h.last[:content]
 # => "Here's how to boil an egg..."
 ```
 
 ## Web Search
 
-To give the model access to real-time information from the internet, we enable the `web_search` feature by default. This uses OpenAI's built-in `web_search_preview` tool.
+To give the model access to real-time information from the internet, you can enable web searching. This uses OpenAI's built-in `web_search_preview` tool.
 
 ```ruby
 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
 ```
 
 **Note:** This feature requires a model that supports the `web_search_preview` tool, such as `gpt-4o` or `gpt-4o-mini`. The gem will attempt to use a compatible model if you have `web_search` enabled.
 
-If you don't want the model to use web search, set `web_search` to `false`:
+If you don't want the model to use web search, set `web_search` to `false` (this is the default):
 
 ```ruby
 m = AI::Chat.new
@@ -277,10 +283,11 @@ i.schema = '{"name": "nutrition_values","strict": true,"schema": {"type": "objec
 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!
-response[:total_calories]  # => 285
+data[:total_calories]  # => 285
 ```
 
 ### Schema Formats
@@ -442,14 +449,14 @@ a = AI::Chat.new
 a.user("What color is the object in this photo?", image: "thing.png")
 a.generate! # => "Red"
 a.user("What is the object in the photo?")
-a.generate! # => "I don't see a photo"
+a.generate! # => { :content => "I don't see a photo", ... }
 
 b = AI::Chat.new
 b.user("What color is the object in this photo?", image: "thing.png")
 b.generate! # => "Red"
 b.user("What is the object in the photo?")
 b.previous_response_id = nil
-b.generate! # => "An apple"
+b.generate! # => { :content => "An apple", ... }
 ```
 
 If you don't set `previous_response_id` to `nil`, the model won't have the old image(s) to work with.
@@ -462,7 +469,7 @@ You can enable OpenAI's image generation tool:
 a = AI::Chat.new
 a.image_generation = true
 a.user("Draw a picture of a kitten")
-a.generate! # => "Here is your picture of a kitten:"
+a.generate! # => { :content => "Here is your picture of a kitten:", ... }
 ```
 
 By default, images are saved to `./images`. You can configure a different location:
@@ -472,7 +479,7 @@ a = AI::Chat.new
 a.image_generation = true
 a.image_folder = "./my_images"
 a.user("Draw a picture of a kitten")
-a.generate! # => "Here is your picture of a kitten:"
+a.generate! # => { :content => "Here is your picture of a kitten:", ... }
 ```
 
 Images are saved in timestamped subfolders using ISO 8601 basic format. For example:
@@ -510,11 +517,35 @@ a = AI::Chat.new
 a.image_generation = true
 a.image_folder = "./images"
 a.user("Draw a picture of a kitten")
-a.generate! # => "Here is a picture of a kitten:"
+a.generate! # => { :content => "Here is a picture of a kitten:", ... }
 a.user("Make it even cuter")
-a.generate! # => "Here is the kitten, but even cuter:"
+a.generate! # => { :content => "Here is the kitten, but even cuter:", ... }
 ```
 
+## Code Interpreter
+
+```ruby
+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.", ... }
+```
+
+## Proxying Through prepend.me
+
+You can proxy API calls through [prepend.me](https://prepend.me/).
+
+```rb
+chat = AI::Chat.new
+chat.proxy = true
+chat.user("Tell me a story")
+chat.generate!
+puts chat.last[:content]
+# => "Once upon a time..."
+```
+
+When proxy is enabled, **you must use the API key provided by prepend.me** in place of a real OpenAI API key. Refer to [the section on API keys](#api-key) for options on how to set your key.
+
 ## Building Conversations Without API Calls
 
 You can manually add assistant messages without making API calls, which is useful when reconstructing a past conversation:
@@ -614,6 +645,93 @@ u.generate!
 
 Unless you've stored the previous messages somewhere yourself, this technique won't bring them back. But OpenAI remembers what they were, so that you can at least continue the conversation. (If you're using a reasoning model, this technique also preserves all of the model's reasoning.)
 
+### Automatic Conversation Management
+
+Starting with your first `generate!` call, the gem automatically creates and manages a conversation with OpenAI. This conversation is stored server-side and tracks all messages, tool calls, reasoning, and other items.
+
+```ruby
+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
+```
+
+You can also load an existing conversation from your database:
+
+```ruby
+# 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
+```
+
+**Note on forking:** If you want to "fork" a conversation (create a branch), you can still use `previous_response_id`. If both `conversation_id` and `previous_response_id` are set, the gem will use `previous_response_id` and warn you.
+
+## Inspecting Conversation Details
+
+The gem provides two methods to inspect what happened during a conversation:
+
+### `items` - Programmatic Access
+
+Returns the raw conversation items for programmatic use (displaying in views, filtering, etc.):
+
+```ruby
+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)
+```
+
+### `verbose` - Terminal Output
+
+Pretty-prints the entire conversation with all details for debugging and learning:
+
+```ruby
+chat.verbose
+
+# Output:
+# ┌────────────────────────────────────────────────────────────────────────────┐
+# │ Conversation: conv_6903c1eea6cc819695af3a1b1ebf9b390c3db5e8ec021c9a        │
+# │ Items: 3                                                                   │
+# └────────────────────────────────────────────────────────────────────────────┘
+#
+# [detailed colorized output of all items including web searches,
+#  reasoning, tool calls, messages, etc.]
+```
+
+This is useful for:
+- **Learning** how the model uses tools (web search, code interpreter, etc.)
+- **Debugging** why the model made certain decisions
+- **Understanding** the full context beyond just the final response
+
 ## Setting messages directly
 
 You can use `.messages=()` to assign an `Array` of `Hashes`. Each `Hash` must have keys `:role` and `:content`, and optionally `:image` or `:images`:
@@ -658,69 +776,6 @@ q.messages = [
 ]
 ```
 
-## Assigning `ActiveRecord::Relation`s
-
-If your chat history is contained in an `ActiveRecord::Relation`, you can assign it directly:
-
-```ruby
-# Load from ActiveRecord
-@thread = Thread.find(42)
-
-r = AI::Chat.new
-r.messages = @thread.posts.order(:created_at)
-r.user("What should we discuss next?")
-r.generate! # Creates a new post record, too
-```
-
-### Requirements
-
-In order for the above to "magically" work, there are a few requirements. Your ActiveRecord model must have:
-
-- `.role` method that returns "system", "user", or "assistant"
-- `.content` method that returns the message text
-- `.image` method (optional) for single images - can return URLs, file paths, or Active Storage attachments
-- `.images` method (optional) for multiple images
-
-### Custom Column Names
-
-If your columns have different names:
-
-```ruby
-s = AI::Chat.new
-s.configure_message_attributes(
-  role: :message_type,     # Your column for role
-  content: :message_body,  # Your column for content
-  image: :attachment       # Your column/association for images
-)
-s.messages = @conversation.messages
-```
-
-### Saving Responses with Metadata
-
-To preserve response metadata, add an `openai_response` column to your messages table:
-
-```ruby
-# In your migration
-add_column :messages, :openai_response, :text
-
-# In your model
-class Message < ApplicationRecord
-  serialize :openai_response, AI::Chat::Response
-end
-
-# Usage
-@thread = Thread.find(42)
-
-t = AI::Chat.new
-t.posts = @thread.messages
-t.user("Hello!")
-t.generate!
-
-# The saved message will include token usage, model info, etc.
-last_message = @thread.messages.last
-last_message.openai_response.usage # => {:prompt_tokens=>10, ...}
-```
-
 ## Other Features Being Considered
 
 - **Session management**: Save and restore conversations by ID
@@ -740,3 +795,15 @@ While this gem includes specs, they use mocked API responses. To test with real
 3. Run the examples: `bundle exec ruby examples/all.rb`
 
 This test program runs through all the major features of the gem, making real API calls to OpenAI.
+
+## Contributing
+
+When contributing to this project:
+
+1. **Code Style**: This project uses StandardRB for linting. Run `bundle exec standardrb --fix` before committing to automatically fix style issues.
+
+2. **Testing**: Ensure all specs pass with `bundle exec rspec`.
+
+3. **Examples**: If adding a feature, consider adding an example in the `examples/` directory.
+
+4. **Documentation**: Update the README if your changes affect the public API.

data/ai-chat.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "ai-chat"
-  spec.version = "0.2.3"
+  spec.version = "0.3.0"
   spec.authors = ["Raghu Betina"]
   spec.email = ["raghu@firstdraft.com"]
   spec.homepage = "https://github.com/firstdraft/ai-chat"
@@ -12,19 +12,22 @@ Gem::Specification.new do |spec|
   spec.metadata = {
     "bug_tracker_uri" => "https://github.com/firstdraft/ai-chat/issues",
     "changelog_uri" => "https://github.com/firstdraft/ai-chat/blob/main/CHANGELOG.md",
-    "homepage_uri" => "https://github.com/firstdraft/ai-chat",
+    "homepage_uri" => "https://rubygems.org/gems/ai-chat",
     "label" => "AI Chat",
     "rubygems_mfa_required" => "true",
     "source_code_uri" => "https://github.com/firstdraft/ai-chat"
   }
 
   spec.required_ruby_version = "~> 3.2"
-  spec.add_runtime_dependency "openai", "~> 0.16"
+  spec.add_runtime_dependency "openai", "~> 0.34"
   spec.add_runtime_dependency "marcel", "~> 1.0"
-  spec.add_runtime_dependency "base64", "> 0.1.1"
+  spec.add_runtime_dependency "base64",  "~> 0.1", "> 0.1.1"
   spec.add_runtime_dependency "json", "~> 2.0"
+  spec.add_runtime_dependency "ostruct", "~> 0.2"
+  spec.add_runtime_dependency "tty-spinner", "~> 0.9.3"
+  spec.add_runtime_dependency "amazing_print", "~> 1.8"
 
-  spec.add_development_dependency "dotenv"
+  spec.add_development_dependency "dotenv", ">= 1.0.0"
   spec.add_development_dependency "refinements", "~> 11.1"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

data/lib/ai/amazing_print.rb

@@ -1,5 +1,5 @@
 require "amazing_print"
-
+# :reek:IrresponsibleModule
 module AmazingPrint
   module AI
     def self.included(base)
@@ -27,6 +27,10 @@ module AmazingPrint
       end
     end
 
+    # :reek:DuplicateMethodCall
+    # :reek:FeatureEnvy
+    # :reek:NilCheck
+    # :reek:TooManyStatements
     def format_ai_chat(chat)
       vars = []
       
@@ -53,6 +57,8 @@ module AmazingPrint
       format_object(chat, vars)
     end
 
+    # :reek:TooManyStatements
+    # :reek:DuplicateMethodCall
     def format_object(object, vars)
       data = vars.map do |(name, value)|
         name = colorize(name, :variable) unless @options[:plain]