langchainrb 0.7.5 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4c388275b83a0e4260f4ae9271f4c164a8d34ea5ea9585916d91e7e9c17c980
-  data.tar.gz: 8daa400de3ed80bb3fb9c53cc19ef4d56f137c2aa157bd268dbda488d0fca432
+  metadata.gz: 7f29aad35bc35dc95eb8673b11578b51c7449a19818989d9da5e640c6fb219c7
+  data.tar.gz: 4d0c4d3d424a82c7f02fb9e49ca52a5bdca5dfbce19fbfa22f2d74ef46d81eb7
 SHA512:
-  metadata.gz: 4bae87c050be6a8fa011c1ae5de4b119abac498669f2e63ca1829e11b7b5ecca7610330be670d24fd6cb98c2e2599c593e9922378985efc586d76c124efb865e
-  data.tar.gz: 2a39b084c6a239aeb0de22bfc87629d2f2909b23eabfcf71a835a1f1624d84afe3ea106afdafb8f1fb301b7934d73abc7253c9b8bd3f6c9b170231ebb5af0936
+  metadata.gz: 91b6f4fc5056308eab9119dcfda1be16857e6e9e6e531977148b1e8f31b72090794b67e6855afb95633b8f836b8d20921bc5a069afdc745d1114892143a177e1
+  data.tar.gz: f7a7949ab2efd960eacf3a93f7beaa9104403a93619b8c95ea094901c2d3d19b89980c81d293ae16035c5ff51fe021a09f2e81e2c0ed6854bff87d30e6def925

data/CHANGELOG.md

@@ -1,5 +1,83 @@
 ## [Unreleased]
 
+## [0.12.0] - 2024-04-22
+- [BREAKING] Rename `dimension` parameter to `dimensions` everywhere
+
+## [0.11.4] - 2024-04-19
+- New `Langchain::LLM::AWSBedrock#chat()` to wrap Bedrock Claude requests
+- New `Langchain::LLM::OllamaResponse#total_tokens()` method
+
+## [0.11.3] - 2024-04-16
+- New `Langchain::Processors::Pptx` to parse .pptx files
+- New `Langchain::LLM::Anthropic#chat()` support
+- Misc fixes
+
+## [0.11.2]
+- New `Langchain::Assistant#clear_thread!` and `Langchain::Assistant#instructions=` methods
+
+## [0.11.1]
+- Langchain::Tool::Vectorsearch that wraps Langchain::Vectorsearch::* classes. This allows the Assistant to call the tool and inject data from vector DBs.
+
+## [0.11.0]
+- Delete previously deprecated `Langchain::Agent::ReActAgent` and `Langchain::Agent::SQLQueryAgent` classes
+- New `Langchain::Agent::FileSystem` tool that can read files, write to files, and list the contents of a directory
+
+## [0.10.3]
+- Bump dependencies
+- Ollama#complete fix
+- Misc fixes
+
+## [0.10.2]
+- New Langchain::LLM::Mistral
+- Drop Ruby 3.0 support
+- Fixes Zeitwerk::NameError
+
+## [0.10.1] - GEM VERSION YANKED
+
+## [0.10.0]
+- Delete `Langchain::Conversation` class
+
+## [0.9.5]
+- Now using OpenAI's "text-embedding-3-small" model to generate embeddings
+- Added `remove_texts(ids:)` method to Qdrant and Chroma
+- Add Ruby 3.3 support
+
+## [0.9.4]
+- New `Ollama#summarize()` method
+- Improved README
+- Fixes + specs
+
+## [0.9.3]
+- Add EML processor
+- Tools can support multiple-methods
+- Bump gems and bug fixes
+
+## [0.9.2]
+- Fix vectorsearch#ask methods
+- Bump cohere-ruby gem
+
+## [0.9.1]
+- Add support for new OpenAI models
+- Add Ollama#chat method
+- Fix and refactor of `Langchain::LLM::Ollama`, responses can now be streamed.
+
+## [0.9.0]
+- Introducing new `Langchain::Assistant` that will be replacing `Langchain::Conversation` and `Langchain::Agent`s.
+- `Langchain::Conversation` is deprecated.
+
+## [0.8.2]
+- Introducing new `Langchain::Chunker::Markdown` chunker (thanks @spikex)
+- Fixes
+
+## [0.8.1]
+- Support for Epsilla vector DB
+- Fully functioning Google Vertex AI LLM
+- Bug fixes
+
+## [0.8.0]
+- [BREAKING] Updated llama_cpp.rb to 0.9.4. The model file format used by the underlying llama.cpp library has changed to GGUF. llama.cpp ships with scripts to convert existing files and GGUF format models can be downloaded from HuggingFace.
+- Introducing Langchain::LLM::GoogleVertexAi LLM provider
+
 ## [0.7.5] - 2023-11-13
 - Fixes
 

data/README.md

@@ -15,8 +15,7 @@ Available for paid consulting engagements! [Email me](mailto:andrei@sourcelabs.i
 
 ## Use Cases
 * Retrieval Augmented Generation (RAG) and vector search
-* Chat bots
-* [AI agents](https://github.com/andreibondarev/langchainrb/tree/main/lib/langchain/agent/agents.md)
+* [Assistants](#assistants) (chat bots)
 
 ## Table of Contents
 
@@ -26,10 +25,11 @@ Available for paid consulting engagements! [Email me](mailto:andrei@sourcelabs.i
 - [Prompt Management](#prompt-management)
 - [Output Parsers](#output-parsers)
 - [Building RAG](#building-retrieval-augment-generation-rag-system)
-- [Building chat bots](#building-chat-bots)
+- [Assistants](#assistants)
 - [Evaluations](#evaluations-evals)
 - [Examples](#examples)
 - [Logging](#logging)
+- [Problems](#problems)
 - [Development](#development)
 - [Discord](#discord)
 
@@ -43,6 +43,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     gem install langchainrb
 
+Additional gems may be required. They're not included by default so you can include only what you need.
+
 ## Usage
 
 ```ruby
@@ -50,26 +52,30 @@ require "langchain"
 ```
 
 ## Large Language Models (LLMs)
-Langchain.rb wraps all supported LLMs in a unified interface allowing you to easily swap out and test out different models.
+Langchain.rb wraps supported LLMs in a unified interface allowing you to easily swap out and test out different models.
 
 #### Supported LLMs and features:
-| LLM providers                                    | embed()            | complete()         | chat()              | summarize()        | Notes              |
-| --------                                         |:------------------:| :-------:          | :-----------------: | :-------:          | :----------------- |
-| [OpenAI](https://openai.com/)                    | :white_check_mark: | :white_check_mark: | :white_check_mark:  | ❌                 | Including Azure OpenAI |
-| [AI21](https://ai21.com/)                        | ❌                 | :white_check_mark: | ❌                  | :white_check_mark: |                    |
-| [Anthropic](https://milvus.io/)                  | ❌                 | :white_check_mark: | ❌                  | ❌                 |                    |
-| [AWS Bedrock](https://aws.amazon.com/bedrock)    | :white_check_mark: | :white_check_mark: | ❌                  | ❌                 | Provides AWS, Cohere, AI21, Antropic and Stability AI models |
-| [Cohere](https://www.pinecone.io/)               | :white_check_mark: | :white_check_mark: | :white_check_mark:  | :white_check_mark: |                    |
-| [GooglePalm](https://ai.google/discover/palm2/) | :white_check_mark: | :white_check_mark: | :white_check_mark:  | :white_check_mark: |                    |
-| [HuggingFace](https://huggingface.co/)          | :white_check_mark: | ❌                 | ❌                  | ❌                 |                    |
-| [Ollama](https://ollama.ai/)                     | :white_check_mark: | :white_check_mark: | ❌                  | ❌                 |                    |
-| [Replicate](https://replicate.com/)              | :white_check_mark: | :white_check_mark: | :white_check_mark:  | :white_check_mark: |                    |
+| LLM providers                                                                                   | `embed()`          | `complete()`       | `chat()`            | `summarize()`      | Notes              |
+| --------                                                                                        |:------------------:| :-------:          | :-----------------: | :-------:          | :----------------- |
+| [OpenAI](https://openai.com/?utm_source=langchainrb&utm_medium=github)                          | ✅                 | ✅                 | ✅                  | ❌                 | Including Azure OpenAI |
+| [AI21](https://ai21.com/?utm_source=langchainrb&utm_medium=github)                              | ❌                 | ✅                 | ❌                  | ✅                 |                    |
+| [Anthropic](https://anthropic.com/?utm_source=langchainrb&utm_medium=github)                    | ❌                 | ✅                 | ✅                  | ❌                 |                    |
+| [AWS Bedrock](https://aws.amazon.com/bedrock?utm_source=langchainrb&utm_medium=github)          | ✅                 | ✅                 | ✅                  | ❌                 | Provides AWS, Cohere, AI21, Antropic and Stability AI models |
+| [Cohere](https://cohere.com/?utm_source=langchainrb&utm_medium=github)                          | ✅                 | ✅                 | ✅                  | ✅                 |                    |
+| [GooglePalm](https://ai.google/discover/palm2?utm_source=langchainrb&utm_medium=github)         | ✅                 | ✅                 | ✅                  | ✅                 |                    |
+| [Google Vertex AI](https://cloud.google.com/vertex-ai?utm_source=langchainrb&utm_medium=github) | ✅                 | ✅                 | ❌                  | ✅                 |                    |
+| [HuggingFace](https://huggingface.co/?utm_source=langchainrb&utm_medium=github)                 | ✅                 | ❌                 | ❌                  | ❌                 |                    |
+| [Mistral AI](https://mistral.ai/?utm_source=langchainrb&utm_medium=github)                      | ✅                 | ❌                 | ✅                  | ❌                 |                    |
+| [Ollama](https://ollama.ai/?utm_source=langchainrb&utm_medium=github)                           | ✅                 | ✅                 | ✅                  | ✅                 |                    |
+| [Replicate](https://replicate.com/?utm_source=langchainrb&utm_medium=github)                    | ✅                 | ✅                 | ✅                  | ✅                 |                    |
+
+
 
 #### Using standalone LLMs:
 
 #### OpenAI
 
-Add `gem "ruby-openai", "~> 5.2.0"` to your Gemfile.
+Add `gem "ruby-openai", "~> 6.3.0"` to your Gemfile.
 
 ```ruby
 llm = Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"])
@@ -81,27 +87,22 @@ llm = Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"], llm_options: {
 
 Generate vector embeddings:
 ```ruby
-llm.embed(text: "foo bar")
-```
-
-Generate a text completion:
-```ruby
-llm.complete(prompt: "What is the meaning of life?")
+llm.embed(text: "foo bar").embedding
 ```
 
 Generate a chat completion:
 ```ruby
-llm.chat(prompt: "Hey! How are you?")
+llm.chat(messages: [{role: "user", content: "What is the meaning of life?"}]).completion
 ```
 
 Summarize the text:
 ```ruby
-llm.complete(text: "...")
+llm.summarize(text: "...").completion
 ```
 
 You can use any other LLM by invoking the same interface:
 ```ruby
-llm = Langchain::LLM::GooglePalm.new(...)
+llm = Langchain::LLM::GooglePalm.new(api_key: ENV["GOOGLE_PALM_API_KEY"], default_options: { ... })
 ```
 
 ### Prompt Management
@@ -247,7 +248,7 @@ Then parse the llm response:
 
 ```ruby
 llm = Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"])
-llm_response = llm.chat(prompt: prompt_text)
+llm_response = llm.chat(messages: [{role: "user", content: prompt_text}]).completion
 parser.parse(llm_response)
 # {
 #   "name" => "Kim Ji-hyun",
@@ -303,15 +304,17 @@ Langchain.rb provides a convenient unified interface on top of supported vectors
 
 #### Supported vector search databases and features:
 
-| Database                                         | Open-source        | Cloud offering     |
-| --------                                         |:------------------:| :------------:     |
-| [Chroma](https://trychroma.com/)                 | :white_check_mark: | :white_check_mark: |
-| [Hnswlib](https://github.com/nmslib/hnswlib/)    | :white_check_mark: | ❌                 |
-| [Milvus](https://milvus.io/)                     | :white_check_mark: | :white_check_mark: Zilliz Cloud |
-| [Pinecone](https://www.pinecone.io/)             | ❌                 | :white_check_mark: |
-| [Pgvector](https://github.com/pgvector/pgvector) | :white_check_mark: | :white_check_mark: |
-| [Qdrant](https://qdrant.tech/)                   | :white_check_mark: | :white_check_mark: |
-| [Weaviate](https://weaviate.io/)                 | :white_check_mark: | :white_check_mark: |
+| Database                                                                                   | Open-source        | Cloud offering     |
+| --------                                                                                   |:------------------:| :------------:     |
+| [Chroma](https://trychroma.com/?utm_source=langchainrb&utm_medium=github)                  | ✅                 | ✅                 |
+| [Epsilla](https://epsilla.com/?utm_source=langchainrb&utm_medium=github)                   | ✅                 | ✅                 |
+| [Hnswlib](https://github.com/nmslib/hnswlib/?utm_source=langchainrb&utm_medium=github)     | ✅                 | ❌                 |
+| [Milvus](https://milvus.io/?utm_source=langchainrb&utm_medium=github)                      | ✅                 | ✅ Zilliz Cloud    |
+| [Pinecone](https://www.pinecone.io/?utm_source=langchainrb&utm_medium=github)              | ❌                 | ✅                 |
+| [Pgvector](https://github.com/pgvector/pgvector/?utm_source=langchainrb&utm_medium=github) | ✅                 | ✅                 |
+| [Qdrant](https://qdrant.tech/?utm_source=langchainrb&utm_medium=github)                    | ✅                 | ✅                 |
+| [Weaviate](https://weaviate.io/?utm_source=langchainrb&utm_medium=github)                  | ✅                 | ✅                 |
+| [Elasticsearch](https://www.elastic.co/?utm_source=langchainrb&utm_medium=github)          | ✅                 | ✅                 |
 
 ### Using Vector Search Databases 🔍
 
@@ -337,11 +340,13 @@ client = Langchain::Vectorsearch::Weaviate.new(
 You can instantiate any other supported vector search database:
 ```ruby
 client = Langchain::Vectorsearch::Chroma.new(...)   # `gem "chroma-db", "~> 0.6.0"`
+client = Langchain::Vectorsearch::Epsilla.new(...)  # `gem "epsilla-ruby", "~> 0.0.3"`
 client = Langchain::Vectorsearch::Hnswlib.new(...)  # `gem "hnswlib", "~> 0.8.1"`
 client = Langchain::Vectorsearch::Milvus.new(...)   # `gem "milvus", "~> 0.9.2"`
 client = Langchain::Vectorsearch::Pinecone.new(...) # `gem "pinecone", "~> 0.1.6"`
 client = Langchain::Vectorsearch::Pgvector.new(...) # `gem "pgvector", "~> 0.2"`
-client = Langchain::Vectorsearch::Qdrant.new(...)   # `gem"qdrant-ruby", "~> 0.9.3"`
+client = Langchain::Vectorsearch::Qdrant.new(...)   # `gem "qdrant-ruby", "~> 0.9.3"`
+client = Langchain::Vectorsearch::Elasticsearch.new(...)   # `gem "elasticsearch", "~> 8.2.0"`
 ```
 
 Create the default schema:
@@ -367,7 +372,7 @@ my_docx = Langchain.root.join("path/to/my.docx")
 
 client.add_data(paths: [my_pdf, my_text, my_docx])
 ```
-Supported file formats: docx, html, pdf, text, json, jsonl, csv, xlsx.
+Supported file formats: docx, html, pdf, text, json, jsonl, csv, xlsx, eml, pptx.
 
 Retrieve similar documents based on the query string passed in:
 ```ruby
@@ -392,46 +397,92 @@ client.similarity_search_by_vector(
 
 RAG-based querying
 ```ruby
-client.ask(
-  question:
-)
+client.ask(question: "...")
 ```
 
-## Building chat bots
+## Assistants
+Assistants are Agent-like objects that leverage helpful instructions, LLMs, tools and knowledge to respond to user queries. Assistants can be configured with an LLM of your choice (currently only OpenAI), any vector search database and easily extended with additional tools.
 
-### Conversation class
+### Available Tools 🛠️
 
-Choose and instantiate the LLM provider you'll be using:
+| Name         | Description                                        | ENV Requirements                                              | Gem Requirements                          |
+| ------------ | :------------------------------------------------: | :-----------------------------------------------------------: | :---------------------------------------: |
+| "calculator" | Useful for getting the result of a math expression |                                                               | `gem "eqn", "~> 1.6.5"`                   |
+| "database"   | Useful for querying a SQL database |                                                               | `gem "sequel", "~> 5.68.0"`                   |
+| "file_system"   | Interacts with the file system |                                                               |       |
+| "ruby_code_interpreter" | Interprets Ruby expressions             |                                                               | `gem "safe_ruby", "~> 1.0.4"`             |
+| "google_search"     | A wrapper around Google Search                     | `ENV["SERPAPI_API_KEY"]` (https://serpapi.com/manage-api-key) | `gem "google_search_results", "~> 2.0.0"` |
+| "weather"  | Calls Open Weather API to retrieve the current weather        |      `ENV["OPEN_WEATHER_API_KEY"]` (https://home.openweathermap.org/api_keys)               | `gem "open-weather-ruby-client", "~> 0.3.0"`    |
+| "wikipedia"  | Calls Wikipedia API to retrieve the summary        |                                                               | `gem "wikipedia-client", "~> 1.17.0"`     |
+
+### Demos
+1. [Building an AI Assistant that operates a simulated E-commerce Store](https://www.loom.com/share/83aa4fd8dccb492aad4ca95da40ed0b2)
+2. [New Langchain.rb Assistants interface](https://www.loom.com/share/e883a4a49b8746c1b0acf9d58cf6da36)
+
+### Creating an Assistant
+1. Instantiate an LLM of your choice
 ```ruby
 llm = Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"])
 ```
-Instantiate the Conversation class:
+2. Instantiate a Thread. Threads keep track of the messages in the Assistant conversation.
+```ruby
+thread = Langchain::Thread.new
+```
+You can pass old message from previously using the Assistant:
 ```ruby
-chat = Langchain::Conversation.new(llm: llm)
+thread.messages = messages
 ```
+Messages contain the conversation history and the whole message history is sent to the LLM every time. A Message belongs to 1 of the 4 roles:
+* `Message(role: "system")` message usually contains the instructions.
+* `Message(role: "user")` messages come from the user.
+* `Message(role: "assistant")` messages are produced by the LLM.
+* `Message(role: "tool")` messages are sent in response to tool calls with tool outputs.
 
-(Optional) Set the conversation context:
+3. Instantiate an Assistant
 ```ruby
-chat.set_context("You are a chatbot from the future")
+assistant = Langchain::Assistant.new(
+  llm: llm,
+  thread: thread,
+  instructions: "You are a Meteorologist Assistant that is able to pull the weather for any location",
+  tools: [
+    Langchain::Tool::GoogleSearch.new(api_key: ENV["SERPAPI_API_KEY"])
+  ]
+)
+```
+### Using an Assistant
+You can now add your message to an Assistant.
+```ruby
+assistant.add_message content: "What's the weather in New York City?"
 ```
 
-Exchange messages with the LLM
+Run the Assistant to generate a response. 
 ```ruby
-chat.message("Tell me about future technologies")
+assistant.run
 ```
 
-To stream the chat response:
+If a Tool is invoked you can manually submit an output.
 ```ruby
-chat = Langchain::Conversation.new(llm: llm) do |chunk|
-  print(chunk)
-end
+assistant.submit_tool_output tool_call_id: "...", output: "It's 70 degrees and sunny in New York City"
+```
+
+Or run the assistant with `auto_tool_execution: tool` to call Tools automatically.
+```ruby
+assistant.add_message content: "How about San Diego, CA?"
+assistant.run(auto_tool_execution: true)
+```
+You can also combine the two by calling:
+```ruby
+assistant.add_message_and_run content: "What about Sacramento, CA?", auto_tool_execution: true
 ```
 
-Open AI Functions support
+### Accessing Thread messages
+You can access the messages in a Thread by calling `assistant.thread.messages`.
 ```ruby
-chat.set_functions(functions)
+assistant.thread.messages
 ```
 
+The Assistant checks the context window limits before every request to the LLM and remove oldest thread messages one by one if the context window is exceeded.
+
 ## Evaluations (Evals)
 The Evaluations module is a collection of tools that can be used to evaluate and track the performance of the output products by LLM and your RAG (Retrieval Augmented Generation) pipelines.
 
@@ -463,13 +514,19 @@ Additional examples available: [/examples](https://github.com/andreibondarev/lan
 
 ## Logging
 
-LangChain.rb uses standard logging mechanisms and defaults to `:warn` level. Most messages are at info level, but we will add debug or warn statements as needed.
+Langchain.rb uses standard logging mechanisms and defaults to `:warn` level. Most messages are at info level, but we will add debug or warn statements as needed.
 To show all log messages:
 
 ```ruby
 Langchain.logger.level = :debug
 ```
 
+## Problems
+If you're having issues installing `unicode` gem required by `pragmatic_segmenter`, try running:
+```bash
+gem install unicode -- --with-cflags="-Wno-incompatible-function-pointer-types"
+```
+
 ## Development
 
 1. `git clone https://github.com/andreibondarev/langchainrb.git`

data/lib/langchain/assistants/assistant.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Langchain
+  # Assistants are Agent-like objects that leverage helpful instructions, LLMs, tools and knowledge to respond to user queries.
+  # Assistants can be configured with an LLM of your choice (currently only OpenAI), any vector search database and easily extended with additional tools.
+  class Assistant
+    attr_reader :llm, :thread, :instructions
+    attr_accessor :tools
+
+    # Create a new assistant
+    #
+    # @param llm [Langchain::LLM::Base] LLM instance that the assistant will use
+    # @param thread [Langchain::Thread] The thread that'll keep track of the conversation
+    # @param tools [Array<Langchain::Tool::Base>] Tools that the assistant has access to
+    # @param instructions [String] The system instructions to include in the thread
+    def initialize(
+      llm:,
+      thread:,
+      tools: [],
+      instructions: nil
+    )
+      raise ArgumentError, "Invalid LLM; currently only Langchain::LLM::OpenAI is supported" unless llm.instance_of?(Langchain::LLM::OpenAI)
+      raise ArgumentError, "Thread must be an instance of Langchain::Thread" unless thread.is_a?(Langchain::Thread)
+      raise ArgumentError, "Tools must be an array of Langchain::Tool::Base instance(s)" unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(Langchain::Tool::Base) }
+
+      @llm = llm
+      @thread = thread
+      @tools = tools
+      @instructions = instructions
+
+      # The first message in the thread should be the system instructions
+      # TODO: What if the user added old messages and the system instructions are already in there? Should this overwrite the existing instructions?
+      add_message(role: "system", content: instructions) if instructions
+    end
+
+    # Add a user message to the thread
+    #
+    # @param content [String] The content of the message
+    # @param role [String] The role attribute of the message. Default: "user"
+    # @param tool_calls [Array<Hash>] The tool calls to include in the message
+    # @param tool_call_id [String] The ID of the tool call to include in the message
+    # @return [Array<Langchain::Message>] The messages in the thread
+    def add_message(content: nil, role: "user", tool_calls: [], tool_call_id: nil)
+      message = build_message(role: role, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+      thread.add_message(message)
+    end
+
+    # Run the assistant
+    #
+    # @param auto_tool_execution [Boolean] Whether or not to automatically run tools
+    # @return [Array<Langchain::Message>] The messages in the thread
+    def run(auto_tool_execution: false)
+      if thread.messages.empty?
+        Langchain.logger.warn("No messages in the thread")
+        return
+      end
+
+      running = true
+
+      while running
+        # TODO: I think we need to look at all messages and not just the last one.
+        case (last_message = thread.messages.last).role
+        when "system"
+          # Do nothing
+          running = false
+        when "assistant"
+          if last_message.tool_calls.any?
+            if auto_tool_execution
+              run_tools(last_message.tool_calls)
+            else
+              # Maybe log and tell the user that there's outstanding tool calls?
+              running = false
+            end
+          else
+            # Last message was from the assistant without any tools calls.
+            # Do nothing
+            running = false
+          end
+        when "user"
+          # Run it!
+          response = chat_with_llm
+
+          if response.tool_calls
+            # Re-run the while(running) loop to process the tool calls
+            running = true
+            add_message(role: response.role, tool_calls: response.tool_calls)
+          elsif response.chat_completion
+            # Stop the while(running) loop and add the assistant's response to the thread
+            running = false
+            add_message(role: response.role, content: response.chat_completion)
+          end
+        when "tool"
+          # Run it!
+          response = chat_with_llm
+          running = true
+
+          if response.tool_calls
+            add_message(role: response.role, tool_calls: response.tool_calls)
+          elsif response.chat_completion
+            add_message(role: response.role, content: response.chat_completion)
+          end
+        end
+      end
+
+      thread.messages
+    end
+
+    # Add a user message to the thread and run the assistant
+    #
+    # @param content [String] The content of the message
+    # @param auto_tool_execution [Boolean] Whether or not to automatically run tools
+    # @return [Array<Langchain::Message>] The messages in the thread
+    def add_message_and_run(content:, auto_tool_execution: false)
+      add_message(content: content, role: "user")
+      run(auto_tool_execution: auto_tool_execution)
+    end
+
+    # Submit tool output to the thread
+    #
+    # @param tool_call_id [String] The ID of the tool call to submit output for
+    # @param output [String] The output of the tool
+    # @return [Array<Langchain::Message>] The messages in the thread
+    def submit_tool_output(tool_call_id:, output:)
+      # TODO: Validate that `tool_call_id` is valid
+      add_message(role: "tool", content: output, tool_call_id: tool_call_id)
+    end
+
+    # Delete all messages in the thread
+    #
+    # @return [Array] Empty messages array
+    def clear_thread!
+      # TODO: If this a bug? Should we keep the "system" message?
+      thread.messages = []
+    end
+
+    # Set new instructions
+    #
+    # @param [String] New instructions that will be set as a system message
+    # @return [Array<Langchain::Message>] The messages in the thread
+    def instructions=(new_instructions)
+      @instructions = new_instructions
+
+      # Find message with role: "system" in thread.messages and delete it from the thread.messages array
+      thread.messages.delete_if(&:system?)
+
+      # Set new instructions by adding new system message
+      message = build_message(role: "system", content: new_instructions)
+      thread.messages.unshift(message)
+    end
+
+    private
+
+    # Call to the LLM#chat() method
+    #
+    # @return [Langchain::LLM::BaseResponse] The LLM response object
+    def chat_with_llm
+      Langchain.logger.info("Sending a call to #{llm.class}", for: self.class)
+
+      params = {messages: thread.openai_messages}
+
+      if tools.any?
+        params[:tools] = tools.map(&:to_openai_tools).flatten
+        # TODO: Not sure that tool_choice should always be "auto"; Maybe we can let the user toggle it.
+        params[:tool_choice] = "auto"
+      end
+
+      llm.chat(**params)
+    end
+
+    # Run the tools automatically
+    #
+    # @param tool_calls [Array<Hash>] The tool calls to run
+    def run_tools(tool_calls)
+      # Iterate over each function invocation and submit tool output
+      tool_calls.each do |tool_call|
+        tool_call_id = tool_call.dig("id")
+
+        function_name = tool_call.dig("function", "name")
+        tool_name, method_name = function_name.split("-")
+        tool_arguments = JSON.parse(tool_call.dig("function", "arguments"), symbolize_names: true)
+
+        tool_instance = tools.find do |t|
+          t.name == tool_name
+        end or raise ArgumentError, "Tool not found in assistant.tools"
+
+        output = tool_instance.send(method_name, **tool_arguments)
+
+        submit_tool_output(tool_call_id: tool_call_id, output: output)
+      end
+
+      response = chat_with_llm
+
+      if response.tool_calls
+        add_message(role: response.role, tool_calls: response.tool_calls)
+      elsif response.chat_completion
+        add_message(role: response.role, content: response.chat_completion)
+      end
+    end
+
+    # Build a message
+    #
+    # @param role [String] The role of the message
+    # @param content [String] The content of the message
+    # @param tool_calls [Array<Hash>] The tool calls to include in the message
+    # @param tool_call_id [String] The ID of the tool call to include in the message
+    # @return [Langchain::Message] The Message object
+    def build_message(role:, content: nil, tool_calls: [], tool_call_id: nil)
+      Message.new(role: role, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+    end
+
+    # TODO: Fix the message truncation when context window is exceeded
+  end
+end

data/lib/langchain/assistants/message.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Langchain
+  # Langchain::Message are the messages that are sent to LLM chat methods
+  class Message
+    attr_reader :role, :content, :tool_calls, :tool_call_id
+
+    ROLES = %w[
+      system
+      assistant
+      user
+      tool
+    ].freeze
+
+    # @param role [String] The role of the message
+    # @param content [String] The content of the message
+    # @param tool_calls [Array<Hash>] Tool calls to be made
+    # @param tool_call_id [String] The ID of the tool call to be made
+    def initialize(role:, content: nil, tool_calls: [], tool_call_id: nil) # TODO: Implement image_file: reference (https://platform.openai.com/docs/api-reference/messages/object#messages/object-content)
+      raise ArgumentError, "Role must be one of #{ROLES.join(", ")}" unless ROLES.include?(role)
+      raise ArgumentError, "Tool calls must be an array of hashes" unless tool_calls.is_a?(Array) && tool_calls.all? { |tool_call| tool_call.is_a?(Hash) }
+
+      @role = role
+      # Some Tools return content as a JSON hence `.to_s`
+      @content = content.to_s
+      @tool_calls = tool_calls
+      @tool_call_id = tool_call_id
+    end
+
+    # Convert the message to an OpenAI API-compatible hash
+    #
+    # @return [Hash] The message as an OpenAI API-compatible hash
+    def to_openai_format
+      {}.tap do |h|
+        h[:role] = role
+        h[:content] = content if content # Content is nil for tool calls
+        h[:tool_calls] = tool_calls if tool_calls.any?
+        h[:tool_call_id] = tool_call_id if tool_call_id
+      end
+    end
+
+    def assistant?
+      role == "assistant"
+    end
+
+    def system?
+      role == "system"
+    end
+
+    def user?
+      role == "user"
+    end
+
+    def tool?
+      role == "tool"
+    end
+  end
+end