ai-chat 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3f66755a7b1d08ff7fe7e502e69140e11e193dfd238a83abcd032ca83bbd37d
-  data.tar.gz: 4bea8f4f0d9c08ed7f42163e6ab16198f217cf67452075c0e119a0b76144b011
+  metadata.gz: a820e2eb8c832c3f7b0ba877f8eb9418d9b681ba96af0b40c6aea0c9a31c598e
+  data.tar.gz: e2705f17dda7e4ee70f91ec78d5a114e6b4d12bc7e5194b5d6652dfac61c35c7
 SHA512:
-  metadata.gz: 5b9108a61768cc64b5027bab0a918022bb4fba3641406d6ee3ef67f8bec7a0718510392240f72eb56e39a11c412660d25301436b9f625020326d86a845ab7f07
-  data.tar.gz: bf82ac462f4879fc6c923d616377cd4d402b2b1fa1b02c62064f29b764e2246a669e5b57f51af262eb5e66f3130be48625a78576dbfb1fb2034057fcbbae6a07
+  metadata.gz: '07239a1c4c435d6877995f3915a0b8f167c885e4d4b02f9b5768abc182c29727c4daa2948237c36daec9874d58eca617457794233a65be15555ba4a86b0a4e0c'
+  data.tar.gz: 4e240275ae5ed5a3bc15b0618a5090c5be37e48e4609f2c58bca6a3938159934a12875f4a2aa06dc6b6004995813c378ec507ea0a552c1bb20f2264ccad5ba29

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2025 Jelani Woods
+Copyright (c) 2024 Raghu Betina
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,6 +1,6 @@
-# AI::Chat
+# OpenAI Chat
 
-This gem provides a class called `AI::Chat` that is intended to make it as easy as possible to use cutting-edge Large Language Models.
+This gem provides a class called `OpenAI::Chat` that is intended to make it as easy as possible to use OpenAI's cutting-edge generative AI models.
 
 ## Installation
 
@@ -9,7 +9,7 @@ This gem provides a class called `AI::Chat` that is intended to make it as easy
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "ai-chat", "< 1.0.0"
+gem "openai-chat", "< 1.0.0"
 ```
 
 And then, at a command prompt:
@@ -23,7 +23,7 @@ bundle install
 Or, install it directly with:
 
 ```
-gem install ai-chat
+gem install openai-chat
 ```
 
 ## Simplest usage
@@ -31,47 +31,176 @@ gem install ai-chat
 In your Ruby program:
 
 ```ruby
-require "ai-chat"
+require "openai/chat"
 
-# Create an instance of AI::Chat
-x = AI::Chat.new
+# Create an instance of OpenAI::Chat
+a = OpenAI::Chat.new
 
-# Add system-level instructions
-x.system("You are a helpful assistant that speaks like Shakespeare.")
+# Build up your conversation by adding messages
+a.add("If the Ruby community had an official motto, what might it be?")
 
-# Add a user message to the chat
-x.user("Hi there!")
+# 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?"}]
 
-# Get the next message from the model
-x.assistant!
-# => "Greetings, good sir or madam! How dost thou fare on this fine day? Pray, tell me how I may be of service to thee."
+# Generate the next message using AI
+a.generate! # => "Matz is nice and so we are nice" (or similar)
 
-# Rinse and repeat
-x.user("What's the best pizza in Chicago?")
-x.assistant!
-# => "Ah, the fair and bustling city of Chicago, renowned for its deep-dish delight that hath captured hearts and stomachs aplenty. Amongst the many offerings of this great city, 'tis often said that Lou Malnati's and Giordano's...."
+# 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 => #<OpenAI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>}
+#    ]
+
+# Continue the conversation
+a.add("What about Rails?")
+a.generate! # => "Convention over configuration."
+```
+
+## Understanding the Data Structure
+
+Every OpenAI chat is just an array of hashes. Each hash needs:
+- `:role`: who's speaking ("system", "user", or "assistant")
+- `:content`: what they're saying
+
+That's it! You're building something like this:
+
+```ruby
+[
+  {:role => "system", :content => "You are a helpful assistant"},
+  {:role => "user", :content => "Hello!"},
+  {:role => "assistant", :content => "Hi there! How can I help you today?", :response => #<OpenAI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>}
+]
+```
+
+That last bit, under `:response`, is an object that represents the JSON that the OpenAI API sent back to us. It contains information about the number of tokens consumed, as well as a response ID that we can use later if we want to pick up the conversation at that point. More on that later.
+
+## Adding Different Types of Messages
+
+```ruby
+require "openai/chat"
+
+b = OpenAI::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! # => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'"
+```
+
+### Convenience Methods
+
+Instead of always specifying the role, you can use these shortcuts:
+
+```ruby
+c = OpenAI::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?")
+```
+
+## Why This Design?
+
+We use the `add` method (and its shortcuts) to build up an array because:
+
+1. **It's educational**: You can see exactly what data structure you're building
+2. **It's debuggable**: Use `pp a.messages` anytime to inspect your conversation
+3. **It's flexible**: The same pattern works when loading existing conversations:
+
+```ruby
+# In a Rails app, you might do:
+d = OpenAI::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
 ```
 
 ## Configuration
 
-By default, the gem uses OpenAI's `gpt-4.1-mini` model. If you want to use a different model, you can set it:
+### Model
+
+By default, the gem uses OpenAI's `gpt-4.1-nano` model. If you want to use a different model, you can set it:
 
 ```ruby
-x.model = "o3"
+e = OpenAI::Chat.new
+e.model = "o4-mini"
 ```
 
+As of 2025-07-29, the list of chat models that you probably want to choose from are:
+
+#### Foundation models 
+
+- gpt-4.1-nano
+- gpt-4.1-mini
+- gpt-4.1
+
+#### Reasoning models
+
+- o4-mini
+- o3
+
+### API key
+
 The gem by default looks for an environment variable called `OPENAI_API_KEY` and uses that if it finds it.
 
 You can specify a different environment variable name:
 
 ```ruby
-x = AI::Chat.new(api_key_env_var: "OPENAI_TOKEN")
+f = OpenAI::Chat.new(api_key_env_var: "MY_OPENAI_TOKEN")
 ```
 
 Or, you can pass an API key in directly:
 
 ```ruby
-x = AI::Chat.new(api_key: "your-api-key-goes-here")
+g = OpenAI::Chat.new(api_key: "your-api-key-goes-here")
+```
+
+## Inspecting Your Conversation
+
+You can call `.messages` to get an array containing the conversation so far:
+
+```ruby
+h = OpenAI::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
+# => "Here's how to boil an egg..."
 ```
 
 ## Structured Output
@@ -79,129 +208,316 @@ x = AI::Chat.new(api_key: "your-api-key-goes-here")
 Get back Structured Output by setting the `schema` attribute (I suggest using [OpenAI's handy tool for generating the JSON Schema](https://platform.openai.com/docs/guides/structured-outputs)):
 
 ```ruby
-x = AI::Chat.new
+i = OpenAI::Chat.new
 
-x.system("You are an expert nutritionist. The user will describe a meal. Estimate the calories, carbs, fat, and protein.")
+i.system("You are an expert nutritionist. The user will describe a meal. Estimate the calories, carbs, fat, and protein.")
 
-x.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}}'
+# 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}}'
 
-x.user("1 slice of pizza")
+i.user("1 slice of pizza")
 
-x.assistant!
-# => {"fat"=>15, "protein"=>5, "carbs"=>50, "total_calories"=>350}
+response = i.generate!
+# => {:fat=>15, :protein=>12, :carbs=>35, :total_calories=>285}
+
+# The response is parsed JSON, not a string!
+response[:total_calories]  # => 285
+```
+
+You can also provide the equivalent Ruby `Hash` rather than a `String` containing JSON.
+
+```ruby
+# Equivalent to assigning the String above
+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
+  }
+}
 ```
 
-## Include images
+The keys can be `String`s or `Symbol`s.
+
+## Including Images
 
 You can include images in your chat messages using the `user` method with the `image` or `images` parameter:
 
 ```ruby
+j = OpenAI::Chat.new
+
 # Send a single image
-x.user("What's in this image?", image: "path/to/local/image.jpg")
+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
-x.user("What are these images showing?", images: ["path/to/image1.jpg", "https://example.com/image2.jpg"])
+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!
 ```
 
 The gem supports three types of image inputs:
 
-- URLs: Pass an image URL starting with `http://` or `https://`.
-- File paths: Pass a string with a path to a local image file.
-- File-like objects: Pass an object that responds to `read` (like `File.open("image.jpg")` or a Rails uploaded file).
+- **URLs**: Pass an image URL starting with `http://` or `https://`
+- **File paths**: Pass a string with a path to a local image file
+- **File-like objects**: Pass an object that responds to `read` (like `File.open("image.jpg")` or Rails uploaded files)
+
+## Web Search
 
-You can send multiple images, and place them between bits of text, in a single user message:
+To give the model access to real-time information from the internet, you can enable the `web_search` feature. This uses OpenAI's built-in `web_search_preview` tool.
 
 ```ruby
-z = AI::Chat.new
-z.user(
-  [
-    {"image" => "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6a/Eubalaena_glacialis_with_calf.jpg/215px-Eubalaena_glacialis_with_calf.jpg"},
-    {"text" => "What is in the above image? What is in the below image?"},
-    {"image" => "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/Elephant_Diversity.jpg/305px-Elephant_Diversity.jpg"},
-    {"text" => "What are the differences between the images?"}
-  ]
-)
-z.assistant!
+m = OpenAI::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
 ```
 
-Both string and symbol keys are supported for the hash items:
+**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.
+
+## Building Conversations Without API Calls
+
+You can manually add assistant messages without making API calls, which is useful when reconstructing a past conversation:
 
 ```ruby
-z = AI::Chat.new
-z.user(
-  [
-    {image: "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6a/Eubalaena_glacialis_with_calf.jpg/215px-Eubalaena_glacialis_with_calf.jpg"},
-    {text: "What is in the above image? What is in the below image?"},
-    {image: "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/Elephant_Diversity.jpg/305px-Elephant_Diversity.jpg"},
-    {text: "What are the differences between the images?"}
-  ]
-)
-z.assistant!
+# Create a new chat instance
+k = OpenAI::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
 ```
 
-## Set assistant messages manually
+With this, you can loop through any conversation's history (perhaps after retrieving it from your database), recreate an `OpenAI::Chat`, and then continue it.
+
+## Reasoning Models
 
-You can manually add assistant messages:
+When using reasoning models like `o3` or `o4-mini`, you can specify a reasoning effort level to control how much reasoning the model does before producing its final response:
+
+```ruby
+l = OpenAI::Chat.new
+l.model = "o3-mini"
+l.reasoning_effort = "medium" # Can be "low", "medium", or "high"
 
-```rb
-x.assistant("Greetings, good sir or madam! How dost thou fare on this fine day? Pray, tell me how I may be of service to thee.")
+l.user("What does this error message mean? <insert error message>")
+l.generate!
 ```
 
-Useful if you are reconstructing a chat that has already happened.
+The `reasoning_effort` parameter guides the model on how many reasoning tokens to generate before creating a response to the prompt. Options are:
+- `"low"`: Favors speed and economical token usage.
+- `"medium"`: (Default) Balances speed and reasoning accuracy.
+- `"high"`: Favors more complete reasoning.
 
-## Getting and setting messages directly
+Setting to `nil` disables the reasoning parameter.
 
-- You can call `.messages` to get an array containing the conversation so far.
-- TODO: Setting `.messages` will replace the conversation with the provided array.
+## Advanced: Response Details
 
-## Testing with Real API Calls
+When you call `generate!` or `generate!`, the gem stores additional information about the API response:
 
-While this gem includes specs, they use mocked API responses. To test with real API calls:
+```ruby
+t = OpenAI::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 => #<OpenAI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>
+#    }
+
+# Access detailed information
+response = t.last_response
+response.id           # => "resp_abc123..."
+response.model        # => "gpt-4.1-nano"
+response.usage        # => {:prompt_tokens=>5, :completion_tokens=>7, :total_tokens=>12}
+
+# Helper methods
+t.last_response_id    # => "resp_abc123..."
+t.last_usage          # => {:prompt_tokens=>5, :completion_tokens=>7, :total_tokens=>12}
+t.total_tokens        # => 12
+```
 
-1. Navigate to the test program directory: `cd test_program`
-2. Create a `.env` file in the test_program directory with your API credentials:
+This information is useful for:
+
+- Debugging and monitoring token usage.
+- Understanding which model was actually used.
+- Future features like cost tracking.
+
+You can also, if you know a response ID, pick up an old conversation at that point in time:
+
+```ruby
+t = OpenAI::Chat.new
+t.user("Hello!")
+t.generate!
+old_id = t.last_response_id # => "resp_abc123..."
+
+# Some time in the future...
+
+u = OpenAI::Chat.new
+u.pick_up_from("resp_abc123...")
+u.messages # => [
+#      {:role=>"assistant", :response => #<OpenAI::Chat::Response id=resp_abc...}
+#    ]
+u.user("What should we do next?")
+u.generate!
 ```
-# Your OpenAI API key
-OPENAI_API_KEY=your_openai_api_key_here
+
+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.)
+
+## 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`:
+
+```ruby
+# Using the planet example with array of hashes
+p = OpenAI::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
 ```
-3. Install dependencies: `bundle install`
-4. Run the test program: `ruby test_ai_chat.rb`
 
-This test program runs through all the major features of the gem, making real API calls to OpenAI.
+You can still include images:
 
-## Reasoning Effort
+```ruby
+# Create a new chat instance
+q = OpenAI::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"] }
+]
+```
 
-When using reasoning models like `o3` or `o4-mini`, you can specify a reasoning effort level to control how much reasoning the model does before producing its final response:
+## Assigning `ActiveRecord::Relation`s
+
+If your chat history is contained in an `ActiveRecord::Relation`, you can assign it directly:
 
 ```ruby
-x = AI::Chat.new
-x.model = "o4-mini"
-x.reasoning_effort = "medium" # Can be "low", "medium", or "high"
+# Load from ActiveRecord
+@thread = Thread.find(42)
 
-x.user("Write a bash script that transposes a matrix represented as '[1,2],[3,4],[5,6]'")
-x.assistant!
+r = OpenAI::Chat.new
+r.messages = @thread.posts.order(:created_at)
+r.user("What should we discuss next?")
+r.generate! # Creates a new post record, too
 ```
 
-The `reasoning_effort` parameter guides the model on how many reasoning tokens to generate before creating a response to the prompt. Options are:
-- `"low"`: Favors speed and economical token usage
-- `"medium"`: (Default) Balances speed and reasoning accuracy
-- `"high"`: Favors more complete reasoning
+### Requirements
 
-Setting to `nil` disables the reasoning parameter.
+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 = OpenAI::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
 
-## TODOs
+To preserve response metadata, add an `openai_response` column to your messages table:
 
-- Add the ability to set all messages at once, ideally with an ActiveRecord Relation.
-- Add a way to access the whole API response body (rather than just the message content).
+```ruby
+# In your migration
+add_column :messages, :openai_response, :text
 
-## Contributing
+# In your model
+class Message < ApplicationRecord
+  serialize :openai_response, OpenAI::Chat::Response
+end
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/firstdraft/ai-chat. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/firstdraft/ai-chat/blob/main/CODE_OF_CONDUCT.md).
+# Usage
+@thread = Thread.find(42)
 
-## License
+t = OpenAI::Chat.new
+t.posts = @thread.messages
+t.user("Hello!")
+t.generate!
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+# The saved message will include token usage, model info, etc.
+last_message = @thread.messages.last
+last_message.openai_response.usage # => {:prompt_tokens=>10, ...}
+```
 
-## Code of Conduct
+## Other Features Being Considered
+
+- **Session management**: Save and restore conversations by ID
+- **Streaming responses**: Real-time streaming as the AI generates its response
+- **Cost tracking**: Automatic calculation and tracking of API costs
+
+## Testing with Real API Calls
 
-Everyone interacting in the AI Chat project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/firstdraft/ai-chat/blob/main/CODE_OF_CONDUCT.md).
+While this gem includes specs, they use mocked API responses. To test with real API calls:
+
+1. Navigate to the test program directory: `cd demo`
+2. Create a `.env` file in the test_program directory with your API credentials:
+    ```
+    # Your OpenAI API key
+    OPENAI_API_KEY=your_openai_api_key_here
+    ```
+3. Install dependencies: `bundle install`
+4. Run the test program: `ruby demo.rb`
+
+This test program runs through all the major features of the gem, making real API calls to OpenAI.