llm.rb 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c5f60cafc446edf8d1be15367ca77eb89e467785c77fbc7f758c29e761e8db
-  data.tar.gz: db9ec411a0c441e471a19a98624e0973815867c28ab89f8bcebc108b4dc11b3b
+  metadata.gz: 567ae33357581ae1602a337ee53dbc86328b4b6c3ee5af5f0b86cf810c039e64
+  data.tar.gz: 4a3d332aad0a2f824966a850c6be36e48894a871d1831f70527e46df5614b207
 SHA512:
-  metadata.gz: f06f9c0367ad3d3428ce7c5046aebd37e4bfea9eac483b5c08a448bac58e9c205d3566a246d3022e9bd6d1669a9f9b5244a475262b24303d845464f7ec3ce4de
-  data.tar.gz: 45e86e63614eb9f5c96111f6ba11d9ec3aae89572dd3959987ca4d0a190cd2d6f5c8ab8ad516cdf68512ec1c1285117616493b3670b4538564c097ec1aaa0ede
+  metadata.gz: 6c04ea5dcf20e9757b0bac1d0eb4cc27176fe966f4ad6fd0f5f06b708d8653522be25b454c9e831f2a5d30fa7676f04d289692fb94ae3bd06f98ab0576ccf7f3
+  data.tar.gz: 2f0d46d75e75382a601863fc0c10e4218efb3029c0650d021586007895d6647fd006eeffd7c6e7027204fcb75168be0e4f51b974d08df95397f1a233baa4239b

data/LICENSE

@@ -1,6 +1,6 @@
-Copyright (C) 2025
+Copyright (C) 2026
 Antar Azri <azantar@proton.me>
-0x1eef <0x1eef@proton.me>
+0x1eef <0x1eef@hardenedbsd.org>
 
 Permission to use, copy, modify, and/or distribute this
 software for any purpose with or without fee is hereby

data/README.md

@@ -1,6 +1,11 @@
-> **Minimal footprint** <br>
-> Zero dependencies outside Ruby’s standard library. <br>
-> Zero runtime dependencies.
+<p align="center">
+  <a href="llm.rb"><img src="https://github.com/llmrb/llm.rb/raw/main/llm.png" width="200" height="200" border="0" alt="llm.rb"></a>
+</p>
+<p align="center">
+  <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
+  <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.2.0-green.svg?" alt="Version"></a>
+</p>
 
 ## About
 
@@ -9,104 +14,167 @@ includes OpenAI, Gemini, Anthropic, xAI (Grok), zAI, DeepSeek, Ollama,
 and LlamaCpp. The toolkit includes full support for chat, streaming,
 tool calling, audio, images, files, and structured outputs.
 
+And it is licensed under the [0BSD License](https://choosealicense.com/licenses/0bsd/) &ndash;
+one of the most permissive open source licenses, with minimal conditions for use,
+modification, and/or distribution. Attribution is appreciated, but not required
+by the license. Built with [good music](https://www.youtube.com/watch?v=SNvaqwTbn14)
+and a lot of ☕️.
+
 ## Quick start
 
 #### REPL
 
-A simple chatbot that maintains a conversation and streams responses in real-time:
+The [LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html) class provides
+a session with an LLM provider that maintains conversation history and context across
+multiple requests. The following example implements a simple REPL loop, and the response
+is streamed to the terminal in real-time as it arrives from the provider. The provider
+happens to be OpenAI in this case but it could be any other provider, and `$stdout`
+could be any object that implements the `#<<` method:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV.fetch("KEY"))
-bot = LLM::Bot.new(llm, stream: $stdout)
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm, stream: $stdout)
 loop do
   print "> "
-  bot.chat(STDIN.gets)
+  ses.talk(STDIN.gets)
   puts
 end
 ```
 
-#### Prompts
+#### Schema
+
+The [LLM::Schema](https://0x1eef.github.io/x/llm.rb/LLM/Schema.html) class provides
+a simple DSL for describing the structure of a response that an LLM emits according
+to a JSON schema. The schema lets a client describe what JSON object an LLM should
+emit, and the LLM will abide by the schema to the best of its ability:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+require "pp"
+
+class Report < LLM::Schema
+  property :category, String, "Report category", required: true
+  property :summary, String, "Short summary", required: true
+  property :services, Array[String], "Impacted services", required: true
+  property :timestamp, String, "When it happened", optional: true
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm, schema: Report)
+res = ses.talk("Structure this report: 'Database latency spiked at 10:42 UTC, causing 5% request timeouts for 12 minutes.'")
+pp res.messages.first(&:assistant?).content!
+
+##
+# {
+#   "category" => "Performance Incident",
+#   "summary" => "Database latency spiked, causing 5% request timeouts for 12 minutes.",
+#   "services" => ["Database"],
+#   "timestamp" => "2024-06-05T10:42:00Z"
+# }
+```
 
-> ℹ️  **Tip:** Some providers (such as OpenAI) support `system` and `developer`
-> roles, but the examples in this README stick to `user` roles since they are
-> supported across all providers.
+#### Tools
 
-A prompt builder that produces a chain of messages that can be sent in one request:
+The [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html) class lets you
+define callable tools for the model. Each tool is described to the LLM as a function
+it can invoke to fetch information or perform an action. The model decides when to
+call tools based on the conversation; when it does, llm.rb runs the tool and sends
+the result back on the next request. The following example implements a simple tool
+that runs shell commands:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV.fetch("KEY"))
-bot = LLM::Bot.new(llm)
+class System < LLM::Tool
+  name "system"
+  description "Run a shell command"
+  param :command, String, "Command to execute", required: true
 
-prompt = bot.build_prompt do
-  it.user "Answer concisely."
-  it.user "Was 2024 a leap year?"
-  it.user "How many days were in that year?"
+  def call(command:)
+    {success: system(command)}
+  end
 end
 
-res = bot.chat(prompt)
-res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm, tools: [System])
+ses.talk("Run `date`.")
+ses.talk(ses.functions.map(&:call)) # report return value to the LLM
 ```
 
-#### Schema
+#### Agents
 
-A bot that instructs the LLM to respond in JSON, and according to the given schema:
+The [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html)
+class provides a class-level DSL for defining reusable, preconfigured
+assistants with defaults for model, tools, schema, and instructions.
+Instructions are injected only on the first request, and unlike
+[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html),
+an [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html)
+will automatically call tools when needed:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-class Estimation < LLM::Schema
-  property :age, Integer, "Estimated age", required: true
-  property :confidence, Number, "0.0–1.0", required: true
-  property :notes, String, "Short notes", optional: true
+class SystemAdmin < LLM::Agent
+  model "gpt-4.1"
+  instructions "You are a Linux system admin"
+  tools Shell
+  schema Result
 end
 
-llm = LLM.openai(key: ENV.fetch("KEY"))
-bot = LLM::Bot.new(llm, schema: Estimation)
-img = llm.images.create(prompt: "A man in his 30s")
-res = bot.chat bot.image_url(img.urls.first)
-data = res.choices.find(&:assistant?).content!
-
-puts "age: #{data["age"]}"
-puts "confidence: #{data["confidence"]}"
-puts "notes: #{data["notes"]}" if data["notes"]
+llm = LLM.openai(key: ENV["KEY"])
+agent = SystemAdmin.new(llm)
+res = agent.talk("Run 'date'")
 ```
 
-#### Tools
+#### Prompts
 
-A bot equipped with a tool that is capable of running system commands:
+The [LLM::Prompt](https://0x1eef.github.io/x/llm.rb/LLM/Prompt.html)
+class represents a single request composed of multiple messages.
+It is useful when a single turn needs more than one message, for example:
+system instructions plus one or more user messages, or a replay of
+prior context:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-class System < LLM::Tool
-  name "system"
-  description "Run a shell command"
-  param :command, String, "Command to execute", required: true
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm)
 
-  def call(command:)
-    {success: system(command)}
-  end
+prompt = ses.prompt do
+  system "Be concise and show your reasoning briefly."
+  user "If a train goes 60 mph for 1.5 hours, how far does it travel?"
+  user "Now double the speed for the same time."
 end
 
-llm  = LLM.openai(key: ENV.fetch("KEY"))
-bot  = LLM::Bot.new(llm, tools: [System])
+ses.talk(prompt)
+```
+
+But prompts are not session-scoped. [LLM::Prompt](https://0x1eef.github.io/x/llm.rb/LLM/Prompt.html)
+is a first-class object that you can build and pass around independently of a session.
+This enables patterns where you compose a prompt in one part of your code,
+and execute it through a session elsewhere:
 
-prompt = bot.build_prompt do
-  it.user "You can run safe shell commands."
-  it.user "Run `date`."
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm)
+
+prompt = LLM::Prompt.new(llm) do
+  system "Be concise and show your reasoning briefly."
+  user "If a train goes 60 mph for 1.5 hours, how far does it travel?"
+  user "Now double the speed for the same time."
 end
 
-bot.chat(prompt)
-bot.chat(bot.functions.map(&:call))
-bot.messages.select(&:assistant?).each { |m| puts "[#{m.role}] #{m.content}" }
+ses.talk(prompt)
 ```
 
 ## Features
@@ -115,11 +183,18 @@ bot.messages.select(&:assistant?).each { |m| puts "[#{m.role}] #{m.content}" }
 - ✅  Unified API across providers
 - 📦  Zero runtime deps (stdlib-only)
 - 🧩  Pluggable JSON adapters (JSON, Oj, Yajl, etc)
-- ♻️  Optional persistent HTTP pool (net-http-persistent)
+- 🧱  Builtin tracer API ([LLM::Tracer](https://0x1eef.github.io/x/llm.rb/LLM/Tracer.html))
+
+#### Optionals
+
+- ♻️  Optional persistent HTTP pool via net-http-persistent ([net-http-persistent](https://github.com/drbrain/net-http-persistent))
+- 📈  Optional telemetry support via OpenTelemetry ([opentelemetry-sdk](https://github.com/open-telemetry/opentelemetry-ruby))
+- 🪵  Optional logging support via Ruby's standard library ([ruby/logger](https://github.com/ruby/logger))
 
 #### Chat, Agents
 - 🧠  Stateless + stateful chat (completions + responses)
 - 🤖  Tool calling / function execution
+- 🔁  Agent tool-call auto-execution (bounded)
 - 🗂️  JSON Schema structured output
 - 📡  Streaming responses
 
@@ -230,115 +305,97 @@ res3 = llm.responses.create "message 3", previous_response_id: res2.response_id
 puts res3.output_text
 ```
 
-#### Thread Safety
-
-The llm.rb library is thread-safe and can be used in a multi-threaded
-environments but it is important to keep in mind that the
-[LLM::Provider](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
-and
-[LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html)
-classes should be instantiated once per thread, and not shared
-between threads. Generally the library tries to avoid global or
-shared state but where it exists reentrant locks are used to
-ensure thread-safety.
-
-### Conversations
+#### Telemetry
 
-#### Completions
+The llm.rb library includes telemetry support through its tracer API, and it
+can be used to trace LLM requests. It can be useful for debugging, monitoring,
+and observability. The primary use case in mind is integration with tools like
+[LangSmith](https://www.langsmith.com/).
 
-The following example creates an instance of
-[LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html)
-and enters into a conversation where each call to "bot.chat" immediately
-sends a request to the provider, updates the conversation history, and
-returns an [LLM::Response](https://0x1eef.github.io/x/llm.rb/LLM/Response.html).
-The full conversation history is automatically included in
-each subsequent request:
+The telemetry implementation uses the [opentelemetry-sdk](https://github.com/open-telemetry/opentelemetry-ruby)
+and is based on the [gen-ai telemetry spec(s)](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/).
+This feature is optional, disabled by default, and the [opentelemetry-sdk](https://github.com/open-telemetry/opentelemetry-ruby)
+gem should be installed separately. Please also note that llm.rb will take care of
+loading and configuring the [opentelemetry-sdk](https://github.com/open-telemetry/opentelemetry-ruby)
+library for you, and llm.rb configures an in-memory exporter that doesn't have
+external dependencies by default:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
+require "pp"
 
-llm  = LLM.openai(key: ENV["KEY"])
-bot  = LLM::Bot.new(llm)
-image_url = "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg"
-image_path = "/tmp/llm-logo.png"
-pdf_path = "/tmp/llm-handbook.pdf"
-
-prompt = bot.build_prompt do
-  it.user ["Tell me about this image", bot.image_url(image_url)]
-  it.user ["Tell me about this image", bot.local_file(image_path)]
-  it.user ["Tell me about this PDF", bot.local_file(pdf_path)]
-end
-bot.chat(prompt)
-bot.messages.each { |m| puts "[#{m.role}] #{m.content}" }
-```
+llm = LLM.openai(key: ENV["KEY"])
+llm.tracer = LLM::Tracer::Telemetry.new(llm)
 
-#### Streaming
+ses = LLM::Session.new(llm)
+ses.talk "Hello world!"
+ses.talk "Adios."
+ses.tracer.spans.each { |span| pp span }
+```
 
-The following example streams the messages in a conversation
-as they are generated in real-time. The `stream` option can
-be set to an IO object, or the value `true` to enable streaming.
-When streaming, the `bot.chat` method will block until the entire
-stream is received. At the end, it returns the `LLM::Response` object
-containing the full aggregated content:
+The llm.rb library also supports export through the OpenTelemetry Protocol (OTLP).
+OTLP is a standard protocol for exporting telemetry data, and it is supported by
+multiple observability tools. By default the export is batched in the background,
+and happens automatically but short lived scripts might need to
+[explicitly flush](https://0x1eef.github.io/x/llm.rb/LLM/Tracer/Telemetry#flush!-instance_method)
+the exporter before they exit &ndash; otherwise some telemetry data could be lost:
 
 ```ruby
-#!/usr/bin/env ruby
-require "llm"
+ #!/usr/bin/env ruby
+ require "llm"
+ require "opentelemetry-exporter-otlp"
 
-llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm, stream: $stdout)
-image_url = "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg"
-image_path = "/tmp/llm-logo.png"
-pdf_path = "/tmp/llm-handbook.pdf"
-
-prompt = bot.build_prompt do
-  it.user ["Tell me about this image", bot.image_url(image_url)]
-  it.user ["Tell me about this image", bot.local_file(image_path)]
-  it.user ["Tell me about the PDF", bot.local_file(pdf_path)]
-end
-bot.chat(prompt)
-```
+ endpoint = "https://api.smith.langchain.com/otel/v1/traces"
+ exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint:)
+
+ llm = LLM.openai(key: ENV["KEY"])
+ llm.tracer = LLM::Tracer::Telemetry.new(llm, exporter:)
 
-### Schema
+ ses = LLM::Session.new(llm)
+ ses.talk "hello"
+ ses.talk "how are you?"
 
-All LLM providers except Anthropic and DeepSeek allow a client to describe
-the structure of a response that a LLM emits according to a schema that is
-described by JSON. The schema lets a client describe what JSON object
-an LLM should emit, and the LLM will abide by the schema to the best of
-its ability:
+ at_exit do
+   # Helpful for short-lived scripts, otherwise the exporter
+   # might not have time to flush pending telemetry data
+   ses.tracer.flush!
+ end
+ ```
+
+#### Logger
+
+The llm.rb library includes simple logging support through its
+tracer API, and Ruby's standard library ([ruby/logger](https://github.com/ruby/logger)).
+This feature is optional, disabled by default, and it can be useful for debugging and/or
+monitoring requests to LLM providers. The `path` or `io` options can be used to choose
+where logs are written to, and by default it is set to `$stdout`:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-class Player < LLM::Schema
-  property :name, String, "The player's name", required: true
-  property :position, Array[Number], "The player's [x, y] position", required: true
-end
-
 llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm, schema: Player)
-prompt = bot.build_prompt do
-  it.user "The player's name is Sam and their position is (7, 12)."
-  it.user "Return the player's name and position"
-end
+llm.tracer = LLM::Tracer::Logger.new(llm, io: $stdout)
 
-player = bot.chat(prompt).content!
-puts "name: #{player['name']}"
-puts "position: #{player['position'].join(', ')}"
+ses = LLM::Session.new(llm)
+ses.talk "Hello world!"
+ses.talk "Adios."
 ```
 
-### Tools
-
-#### Introduction
+#### Thread Safety
 
-All providers support a powerful feature known as tool calling, and although
-it is a little complex to understand at first, it can be powerful for building
-agents. There are three main interfaces to understand: [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html),
-[LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html), and
-[LLM::ServerTool](https://0x1eef.github.io/x/llm.rb/LLM/ServerTool.html).
+The llm.rb library is thread-safe and can be used in a multi-threaded
+environments but it is important to keep in mind that the
+[LLM::Provider](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
+and
+[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html)
+classes should be instantiated once per thread, and not shared
+between threads. Generally the library tries to avoid global or
+shared state but where it exists reentrant locks are used to
+ensure thread-safety.
 
+### Tools
 
 #### LLM::Function
 
@@ -346,13 +403,7 @@ The following example demonstrates [LLM::Function](https://0x1eef.github.io/x/ll
 and how it can define a local function (which happens to be a tool), and how
 a provider (such as OpenAI) can then detect when we should call the function.
 Its most notable feature is that it can act as a closure and has access to
-its surrounding scope, which can be useful in some situations.
-
-The
-[LLM::Bot#functions](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html#functions-instance_method)
-method returns an array of functions that can be called after a `chat` interaction
-if the LLM detects a function should be called. You would then typically call these
-functions and send their results back to the LLM in a subsequent `chat` call:
+its surrounding scope, which can be useful in some situations:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -373,14 +424,14 @@ tool = LLM.function(:system) do |fn|
   end
 end
 
-bot = LLM::Bot.new(llm, tools: [tool])
-bot.chat "Your task is to run shell commands via a tool.", role: :user
+ses = LLM::Session.new(llm, tools: [tool])
+ses.talk "Your task is to run shell commands via a tool.", role: :user
 
-bot.chat "What is the current date?", role: :user
-bot.chat bot.functions.map(&:call) # report return value to the LLM
+ses.talk "What is the current date?", role: :user
+ses.talk ses.functions.map(&:call) # report return value to the LLM
 
-bot.chat "What operating system am I running? (short version please!)", role: :user
-bot.chat bot.functions.map(&:call) # report return value to the LLM
+ses.talk "What operating system am I running?", role: :user
+ses.talk ses.functions.map(&:call) # report return value to the LLM
 
 ##
 # {stderr: "", stdout: "Thu May  1 10:01:02 UTC 2025"}
@@ -420,14 +471,14 @@ class System < LLM::Tool
 end
 
 llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm, tools: [System])
-bot.chat "Your task is to run shell commands via a tool.", role: :user
+ses = LLM::Session.new(llm, tools: [System])
+ses.talk "Your task is to run shell commands via a tool.", role: :user
 
-bot.chat "What is the current date?", role: :user
-bot.chat bot.functions.map(&:call) # report return value to the LLM
+ses.talk "What is the current date?", role: :user
+ses.talk ses.functions.map(&:call) # report return value to the LLM
 
-bot.chat "What operating system am I running? (short version please!)", role: :user
-bot.chat bot.functions.map(&:call) # report return value to the LLM
+ses.talk "What operating system am I running?", role: :user
+ses.talk ses.functions.map(&:call) # report return value to the LLM
 
 ##
 # {stderr: "", stdout: "Thu May  1 10:01:02 UTC 2025"}
@@ -450,53 +501,36 @@ it has been uploaded. The file (a specialized instance of
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm)
+ses = LLM::Session.new(llm)
 file = llm.files.create(file: "/tmp/llm-book.pdf")
-res = bot.chat ["Tell me about this file", file]
-res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
+res = ses.talk ["Tell me about this file", file]
+res.messages.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ### Prompts
 
 #### Multimodal
 
-While LLMs inherently understand text, they can also process and
-generate other types of media such as audio, images, video, and
-even URLs. To provide these multimodal inputs to the LLM, llm.rb
-uses explicit tagging methods on the `LLM::Bot` instance.
-These methods wrap your input into a special `LLM::Object`,
-clearly indicating its type and intent to the underlying LLM
-provider.
-
-For instance, to specify an image URL, you would use
-`bot.image_url`. For a local file, `bot.local_file`. For an
-already uploaded file managed by the LLM provider's Files API,
-`bot.remote_file`. This approach ensures clarity and allows
-llm.rb to correctly format the input for each provider's
-specific requirements.
+LLMs are great with text, but many can also handle images, audio, video,
+and URLs. With llm.rb you pass those inputs by tagging them with one of
+the following methods. And for multipart prompts, we can pass an array
+where each element is a part of the input. See the example below for
+details, in the meantime here are the methods to know for multimodal
+inputs:
 
-An array can be used for a prompt with multiple parts, where each
-element contributes to the overall input:
+* `ses.image_url` for an image URL
+* `ses.local_file` for a local file
+* `ses.remote_file` for a file already uploaded via the provider's Files API
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm)
-image_url = "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg"
-image_path = "/tmp/llm-logo.png"
-pdf_path = "/tmp/llm-book.pdf"
-
-res1 = bot.chat ["Tell me about this image URL", bot.image_url(image_url)]
-res1.choices.each { |m| puts "[#{m.role}] #{m.content}" }
-
-file = llm.files.create(file: pdf_path)
-res2 = bot.chat ["Tell me about this PDF", bot.remote_file(file)]
-res2.choices.each { |m| puts "[#{m.role}] #{m.content}" }
-
-res3 = bot.chat ["Tell me about this image", bot.local_file(image_path)]
-res3.choices.each { |m| puts "[#{m.role}] #{m.content}" }
+ses = LLM::Session.new(llm)
+res = ses.talk ["Tell me about this image URL", ses.image_url(url)]
+res = ses.talk ["Tell me about this PDF", ses.remote_file(file)]
+res = ses.talk ["Tell me about this image", ses.local_file(path)]
 ```
 
 ### Audio
@@ -674,9 +708,9 @@ end
 ##
 # Select a model
 model = llm.models.all.find { |m| m.id == "gpt-3.5-turbo" }
-bot = LLM::Bot.new(llm, model: model.id)
-res = bot.chat "Hello #{model.id} :)"
-res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
+ses = LLM::Session.new(llm, model: model.id)
+res = ses.talk "Hello #{model.id} :)"
+res.messages.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ## Install