llm.rb 4.1.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc70b8eb2d7ce82b3959d2b7dc795a89511a1962ed443a5344bb00ef55863033
-  data.tar.gz: a9245348fccc085710ae28097b9ce9c0ec9ce8e8f5ea4e23f97a9bde5fc50fee
+  metadata.gz: f35a8e2b21d2bf7914c9b261897eaa6d9c6d0ff03dc51c0e751f86d22e08f093
+  data.tar.gz: 92ffab3eab12fd6393ef8e324360d13e9725403a9571cf6c28427be090021965
 SHA512:
-  metadata.gz: b1a0e67e1d938792da4cf52ff6b05dba568b71c77d28ef18c11510c7f0c37b21d5514f659ae6997193774755aede0bd5af4a1239247fc396b8a4815258723eb6
-  data.tar.gz: 87bfee8769ba983ffccef6bfb276922501e8cc68b2b4f2be6857408739b7307403c120de7db1b83c612a6af61e30860366419abb790662feb679ddf6f1234102
+  metadata.gz: 02cdeb6b969b4ec2d76ffce29236fb8c189cdf3a71ea121e2b218ffb8fdadff0005cfd4211bcdac6e17b9814f9533949f0bdec19efdd8fb2262096d5bd440dde
+  data.tar.gz: 3cf0abeefd9927df9e600a694387e0f7d334f9c614b6e64cd54cf3e5f82b6a73895d74c392a5a6f68a92c529155cfb3db067bf8b2ef85e0df4505105c759870c

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.3.0-green.svg?" alt="Version"></a>
+</p>
 
 ## About
 
@@ -9,30 +14,39 @@ 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
 
-The [LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Bot.html) class provides
+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:
+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["KEY"])
-bot = LLM::Bot.new(llm, stream: $stdout)
+ses = LLM::Session.new(llm, stream: $stdout)
 loop do
   print "> "
-  bot.chat(STDIN.gets)
+  ses.talk(STDIN.gets || break)
   puts
 end
 ```
 
 #### Schema
 
-The [LLM::Schema](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Schema.html) class provides
+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:
@@ -40,21 +54,32 @@ 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 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 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"])
-bot = LLM::Bot.new(llm, schema: Estimation)
-bot.chat("Estimate age and confidence for a man in his 30s.")
+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"
+# }
 ```
 
 #### Tools
 
-The [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Tool.html) class lets you
+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
@@ -76,19 +101,19 @@ class System < LLM::Tool
 end
 
 llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm, tools: [System])
-bot.chat("Run `date`.")
-bot.chat(bot.functions.map(&:call)) # report return value to the LLM
+ses = LLM::Session.new(llm, tools: [System])
+ses.talk("Run `date`.")
+ses.talk(ses.functions.map(&:call)) # report return value to the LLM
 ```
 
 #### Agents
 
-The [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Agent.html)
+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::Bot](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Bot.html),
-an [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Agent.html)
+[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
@@ -104,28 +129,52 @@ end
 
 llm = LLM.openai(key: ENV["KEY"])
 agent = SystemAdmin.new(llm)
-res = agent.chat("Run 'date'")
+res = agent.talk("Run 'date'")
 ```
 
 #### Prompts
 
-The [LLM::Bot#build_prompt](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Bot.html#build_prompt-instance_method)
-method provides a simple DSL for building a chain of messages that
-can be sent in a single request. A conversation with an LLM consists
-of messages that have a role (eg system, user), and content:
+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"
 
 llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm)
-prompt = bot.build_prompt do
-  it.system "Answer concisely."
-  it.user "Was 2024 a leap year?"
-  it.user "How many days were in that year?"
+ses = LLM::Session.new(llm)
+
+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
-bot.chat(prompt)
+
+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:
+
+```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
+
+ses.talk(prompt)
 ```
 
 ## Features
@@ -134,10 +183,17 @@ bot.chat(prompt)
 - ✅  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)
+- 💾  Save and restore sessions across processes
 - 🤖  Tool calling / function execution
 - 🔁  Agent tool-call auto-execution (bounded)
 - 🗂️  JSON Schema structured output
@@ -250,115 +306,151 @@ 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)
+
+ses = LLM::Session.new(llm)
+ses.talk "Hello world!"
+ses.talk "Adios."
+ses.tracer.spans.each { |span| pp span }
 ```
 
-#### Streaming
+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"
+ require "opentelemetry-exporter-otlp"
+
+ 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:)
+
+ ses = LLM::Session.new(llm)
+ ses.talk "hello"
+ ses.talk "how are you?"
 
-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:
+ 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"
 
 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)
+llm.tracer = LLM::Tracer::Logger.new(llm, io: $stdout)
+
+ses = LLM::Session.new(llm)
+ses.talk "Hello world!"
+ses.talk "Adios."
 ```
 
-### Schema
+#### Serialization
 
-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:
+[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html) can be
+serialized and deserialized across process boundaries and persisted to
+storage such as files, a `jsonb` column (PostgreSQL), or other backends
+through a JSON representation of the history encapsulated by
+[LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html)
+&ndash; inclusive of tool metadata as well:
 
+* Process 1
 ```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.system "The player's name is Sam and their position is (7, 12)."
-  it.user "Return the player's name and position"
-end
+ses = LLM::Session.new(llm)
+ses.talk "Howdy partner"
+ses.talk "I'll see you later"
+ses.save(path: "session.json")
+```
+* Process 2
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+require "pp"
 
-player = bot.chat(prompt).content!
-puts "name: #{player['name']}"
-puts "position: #{player['position'].join(', ')}"
+llm = LLM.openai(key: ENV["KEY"])
+ses = LLM::Session.new(llm)
+ses.restore(path: "session.json")
+ses.talk "Howdy partner. I'm back"
+pp ses.messages
 ```
 
-### Tools
+But how does it work without a file ? The [LLM::Session](https://0x1eef.github.io/x/llm.rb/LLM/Session.html)
+class implements `#to_json` and it can be used to obtain a JSON representation
+of a session that can be stored in a `jsonb` column in PostgreSQL, or any
+other storage backend. The session can then be restored from the JSON
+representation via the restore method and its `string` argument:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ses1 = LLM::Session.new(llm)
+ses1.talk "Howdy partner"
+ses1.talk "I'll see you later"
+
+json = ses1.to_json
+ses2 = LLM::Session.new(llm)
+ses2.restore(string: json)
+ses2.talk "Howdy partner. I'm back"
+```
 
-#### 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
 
@@ -366,13 +458,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
@@ -393,14 +479,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"}
@@ -440,14 +526,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"}
@@ -470,53 +556,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.
+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:
 
-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.
-
-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
@@ -694,9 +763,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
@@ -705,6 +774,12 @@ llm.rb can be installed via rubygems.org:
 
 	gem install llm.rb
 
+## Sources
+
+* [GitHub.com](https://github.com/llmrb/llm.rb)
+* [GitLab.com](https://gitlab.com/llmrb/llm.rb)
+* [Codeberg.org](https://codeberg.org/llmrb/llm.rb)
+
 ## License
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)