llm.rb 0.17.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcb896bf97c2b2a07987e7d44088244e79bf35220478dd3ac93fc349a91c5f7c
-  data.tar.gz: e33c4f4c87d72568ac94af0f4494e6a40ade164dbc894de1c772fc1bd6c92705
+  metadata.gz: 207a44401195a654a57ebf8050d211fc2c1722420a647dedcc447031aead1451
+  data.tar.gz: aa8abf7d5104d0a93033a43041057d1af96f8f45dde7f924243788cd0b14621e
 SHA512:
-  metadata.gz: 660dee96aa651f293818492ab74efa92893cf2f39dc43dd04c84841ca13071769cabf5ee03060406295af6759ed005e76594abb0de1b6b4d00b1a0b5f0915284
-  data.tar.gz: 89166bce1fb90718b8b99e2a8b6bea1fbe3cbbeb33c7fdcb0362febc7f969caaaab7e5072514793ebc8e911d7c98ebe9f46ec0b7d29257a299e9e99fca497a15
+  metadata.gz: 8faf81ef91911ecbcd81694232f6e314caed8dab2ca8b30a241d8e346c3a4a084f0d46bb9e5e94f191a3dc7676c1c865f7062d440498d94e2e0b30a57a5a3510
+  data.tar.gz: 3ba71c5c46b5ebbec12d136f24cff08d0da11ea807b81db1319c31b1dae18cb6786ad8ed759f3333d7e2f0f1ee3c69ee7ae85cf95e6d82b3e5552f0d516a279e

data/README.md

@@ -1,9 +1,15 @@
+> **⚠️ Maintenance Mode ⚠️** <br>
+> Please note that the primary author of llm.rb is pivoting away from
+> Ruby and towards [Golang](https://golang.org) for future projects.
+> Although llm.rb will be maintained for the foreseeable future it is not
+> where my primary interests are anymore. Thanks for understanding.
+
 ## About
 
 llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-includes OpenAI, Gemini, Anthropic, xAI (Grok), DeepSeek, Ollama, and
-LlamaCpp. The toolkit includes full support for chat, streaming, tool calling,
-audio, images, files, and structured outputs (JSON Schema).
+includes OpenAI, Gemini, Anthropic, xAI (Grok), [zAI](https://z.ai), DeepSeek,
+Ollama, and LlamaCpp. The toolkit includes full support for chat, streaming,
+tool calling, audio, images, files, and structured outputs (JSON Schema).
 
 ## Quick start
 
@@ -28,6 +34,8 @@ GitHub Copilot but for the terminal.
   a blog post that implements image editing with Gemini
 * [Fast sailing with persistent connections](https://0x1eef.github.io/posts/persistent-connections-with-llm.rb/) &ndash;
   a blog post that optimizes performance with a thread-safe connection pool
+* [How to build agents (with llm.rb)](https://0x1eef.github.io/posts/how-to-build-agents-with-llm.rb/) &ndash;
+  a blog post that implements agentic behavior via tools
 
 #### Ecosystem
 
@@ -87,22 +95,22 @@ While the Features section above gives you the high-level picture, the table bel
 breaks things down by provider, so you can see exactly what’s supported where.
 
 
-| Feature / Provider                  | OpenAI | Anthropic | Gemini | DeepSeek | xAI (Grok) | Ollama | LlamaCpp |
-|--------------------------------------|:------:|:---------:|:------:|:--------:|:----------:|:------:|:--------:|
-| **Chat Completions**                 | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
-| **Streaming**                        | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
-| **Tool Calling**                     | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
-| **JSON Schema / Structured Output**  | ✅     | ❌        | ✅     | ❌       | ✅         | ✅*    | ✅*      |
-| **Embeddings**                       | ✅     | ✅        | ✅     | ✅       | ❌         | ✅     | ✅       |
-| **Multimodal Prompts** *(text, documents, audio, images, videos, URLs, etc)* | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
-| **Files API**                        | ✅     | ✅        | ✅     | ❌       | ❌         | ❌     | ❌       |
-| **Models API**                       | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
-| **Audio (TTS / Transcribe / Translate)** | ✅  | ❌        | ✅     | ❌       | ❌         | ❌     | ❌       |
-| **Image Generation & Editing**       | ✅     | ❌        | ✅     | ❌       | ✅         | ❌     | ❌       |
-| **Local Model Support**              | ❌     | ❌        | ❌     | ❌       | ❌         | ✅     | ✅       |
-| **Vector Stores (RAG)**               | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
-| **Responses**                        | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
-| **Moderations**                      | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
+| Feature / Provider                  | OpenAI | Anthropic | Gemini | DeepSeek | xAI (Grok) | zAI    | Ollama | LlamaCpp |
+|--------------------------------------|:------:|:---------:|:------:|:--------:|:----------:|:------:|:------:|:--------:|
+| **Chat Completions**                 | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅     | ✅       |
+| **Streaming**                        | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅     | ✅       |
+| **Tool Calling**                     | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅     | ✅       |
+| **JSON Schema / Structured Output**  | ✅     | ❌        | ✅     | ❌       | ✅         | ❌     | ✅*    | ✅*      |
+| **Embeddings**                       | ✅     | ✅        | ✅     | ✅       | ❌         | ❌     | ✅     | ✅       |
+| **Multimodal Prompts** *(text, documents, audio, images, videos, URLs, etc)* | ✅     | ✅        | ✅     | ✅       | ✅         | ❌     | ✅     | ✅       |
+| **Files API**                        | ✅     | ✅        | ✅     | ❌       | ❌         | ❌     | ❌     | ❌       |
+| **Models API**                       | ✅     | ✅        | ✅     | ✅       | ✅         | ❌     | ✅     | ✅       |
+| **Audio (TTS / Transcribe / Translate)** | ✅  | ❌        | ✅     | ❌       | ❌         | ❌     | ❌     | ❌       |
+| **Image Generation & Editing**       | ✅     | ❌        | ✅     | ❌       | ✅         | ❌     | ❌     | ❌       |
+| **Local Model Support**              | ❌     | ❌        | ❌     | ❌       | ❌         | ❌     | ✅     | ✅       |
+| **Vector Stores (RAG)**               | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌     | ❌       |
+| **Responses**                        | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌     | ❌       |
+| **Moderations**                      | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌     | ❌       |
 
 \* JSON Schema support in Ollama/LlamaCpp depends on the model, not the API.
 
@@ -141,7 +149,7 @@ llm = LLM.llamacpp(key: nil)
 The llm.rb library can maintain a process-wide connection pool
 for each provider that is instantiated. This feature can improve
 performance but it is optional, the implementation depends on
-[net-http-persistent](https://github.com/dbrain/net-http-persistent),
+[net-http-persistent](https://github.com/drbrain/net-http-persistent),
 and the gem should be installed separately:
 
 ```ruby
@@ -684,16 +692,6 @@ else there's the API reference. It covers classes and methods that the README gl
 over or doesn't cover at all. The API reference is available at
 [0x1eef.github.io/x/llm.rb](https://0x1eef.github.io/x/llm.rb).
 
-### Guides
-
-* [An introduction to RAG](https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/) &ndash;
-  a blog post that implements the RAG pattern
-* [How to estimate the age of a person in a photo](https://0x1eef.github.io/posts/age-estimation-with-llm.rb/) &ndash;
-  a blog post that implements an age estimation tool
-* [How to edit an image with Gemini](https://0x1eef.github.io/posts/how-to-edit-images-with-gemini/) &ndash;
-  a blog post that implements image editing with Gemini
-* [docs/](docs/) &ndash; the docs directory contains additional guides
-
 ## Install
 
 llm.rb can be installed via rubygems.org:
@@ -704,4 +702,4 @@ llm.rb can be installed via rubygems.org:
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)
 <br>
-See [LICENSE](./LICENSE)
+See [LICENSE](./LICENSE)

data/lib/llm/client.rb

@@ -32,6 +32,5 @@ module LLM
 
     def client_id = "#{host}:#{port}:#{timeout}:#{ssl}"
     def clients = self.class.clients
-    def mutex = self.class.mutex
   end
 end

data/lib/llm/provider.rb

@@ -87,57 +87,23 @@ class LLM::Provider
     raise NotImplementedError
   end
 
-  ##
-  # Starts a new lazy chat powered by the chat completions API
-  # @note
-  #  This method creates a lazy version of a
-  #  {LLM::Bot LLM::Bot} object.
-  # @param prompt (see LLM::Provider#complete)
-  # @param params (see LLM::Provider#complete)
-  # @return [LLM::Bot]
-  def chat(prompt, params = {})
-    role = params.delete(:role)
-    LLM::Bot.new(self, params).chat(prompt, role:)
-  end
-
   ##
   # Starts a new chat powered by the chat completions API
-  # @note
-  #  This method creates a non-lazy version of a
-  #  {LLM::Bot LLM::Bot} object.
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
-  # @raise (see LLM::Provider#complete)
   # @return [LLM::Bot]
-  def chat!(prompt, params = {})
+  def chat(prompt, params = {})
     role = params.delete(:role)
     LLM::Bot.new(self, params).chat(prompt, role:)
   end
 
-  ##
-  # Starts a new lazy chat powered by the responses API
-  # @note
-  #  This method creates a lazy variant of a
-  #  {LLM::Bot LLM::Bot} object.
-  # @param prompt (see LLM::Provider#complete)
-  # @param params (see LLM::Provider#complete)
-  # @raise (see LLM::Provider#complete)
-  # @return [LLM::Bot]
-  def respond(prompt, params = {})
-    role = params.delete(:role)
-    LLM::Bot.new(self, params).respond(prompt, role:)
-  end
-
   ##
   # Starts a new chat powered by the responses API
-  # @note
-  #  This method creates a non-lazy variant of a
-  #  {LLM::Bot LLM::Bot} object.
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Bot]
-  def respond!(prompt, params = {})
+  def respond(prompt, params = {})
     role = params.delete(:role)
     LLM::Bot.new(self, params).respond(prompt, role:)
   end

data/lib/llm/providers/openai/response/completion.rb

@@ -18,9 +18,10 @@ module LLM::OpenAI::Response
     alias_method :messages, :choices
 
     def model = body.model
-    def prompt_tokens = body.usage["prompt_tokens"]
-    def completion_tokens = body.usage["completion_tokens"]
-    def total_tokens = body.usage["total_tokens"]
+    def prompt_tokens = usage["prompt_tokens"]
+    def completion_tokens = usage["completion_tokens"]
+    def total_tokens = usage["total_tokens"]
+    def usage = body.usage || {}
 
     private
 

data/lib/llm/providers/openai/response/enumerable.rb

@@ -7,5 +7,17 @@ module LLM::OpenAI::Response
       return enum_for(:each) unless block_given?
       data.each { yield(_1) }
     end
+
+    ##
+    # @return [Boolean]
+    def empty?
+      data.empty?
+    end
+
+    ##
+    # @return [Integer]
+    def size
+      data.size
+    end
   end
 end

data/lib/llm/providers/openai.rb

@@ -70,7 +70,7 @@ module LLM
       role, stream = params.delete(:role), params.delete(:stream)
       params[:stream] = true if stream.respond_to?(:<<) || stream == true
       params[:stream_options] = {include_usage: true}.merge!(params[:stream_options] || {}) if params[:stream]
-      req = Net::HTTP::Post.new("/v1/chat/completions", headers)
+      req = Net::HTTP::Post.new(completions_path, headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
       body = JSON.dump({messages: format(messages, :complete).flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
@@ -184,6 +184,10 @@ module LLM
 
     private
 
+    def completions_path
+      "/v1/chat/completions"
+    end
+
     def headers
       (@headers || {}).merge(
         "Content-Type" => "application/json",

data/lib/llm/providers/zai.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The ZAI class implements a provider for [zAI](https://docs.z.ai/guides/overview/quick-start).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.zai(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm, stream: $stdout)
+  #   bot.chat("Greetings Robot", role: :user).flush
+  class ZAI < OpenAI
+    ##
+    # @param [String] host A regional host or the default ("api.z.ai")
+    # @param key (see LLM::Provider#initialize)
+    def initialize(host: "api.z.ai", **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @return [LLM::XAI::Images]
+    def images
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def audio
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def moderations
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def responses
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def vector_stores
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # #see https://docs.z.ai/guides/llm/glm-4.5#glm-4-5-flash glm-4.5-flash
+    # @return [String]
+    def default_model
+      "glm-4.5-flash"
+    end
+
+    private
+
+    def completions_path
+      "/api/paas/v4/chat/completions"
+    end
+  end
+end

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "0.17.0"
+  VERSION = "1.0.1"
 end

data/lib/llm.rb

@@ -23,7 +23,7 @@ module LLM
 
   ##
   # Thread-safe monitors for different contexts
-  @monitors = { require: Monitor.new, clients: Monitor.new, inherited: Monitor.new }
+  @monitors = {require: Monitor.new, clients: Monitor.new, inherited: Monitor.new}
 
   module_function
 
@@ -84,6 +84,15 @@ module LLM
     LLM::XAI.new(**)
   end
 
+  ##
+  # @param key (see LLM::ZAI#initialize)
+  # @param host (see LLM::ZAI#initialize)
+  # @return (see LLM::ZAI#initialize)
+  def zai(**)
+    lock(:require) { require_relative "llm/providers/zai" unless defined?(LLM::ZAI) }
+    LLM::ZAI.new(**)
+  end
+
   ##
   # Define a function
   # @example

data/llm.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary = <<~SUMMARY
   llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-  includes OpenAI, Gemini, Anthropic, xAI (grok), DeepSeek, Ollama, and
+  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 (JSON Schema).
   SUMMARY

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Antar Azri
@@ -165,7 +165,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '4.0'
 description: llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-  includes OpenAI, Gemini, Anthropic, xAI (grok), DeepSeek, Ollama, and LlamaCpp.
+  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 (JSON Schema).
 email:
@@ -264,6 +264,7 @@ files:
 - lib/llm/providers/openai/vector_stores.rb
 - lib/llm/providers/xai.rb
 - lib/llm/providers/xai/images.rb
+- lib/llm/providers/zai.rb
 - lib/llm/response.rb
 - lib/llm/schema.rb
 - lib/llm/schema/array.rb
@@ -303,7 +304,7 @@ requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
 summary: llm.rb is a zero-dependency Ruby toolkit for Large Language Models that includes
-  OpenAI, Gemini, Anthropic, xAI (grok), DeepSeek, Ollama, and LlamaCpp. The toolkit
-  includes full support for chat, streaming, tool calling, audio, images, files, and
-  structured outputs (JSON Schema).
+  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 (JSON Schema).
 test_files: []