llm.rb 4.8.0 → 4.10.0

data/lib/llm/schema/parser.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Parser LLM::Schema::Parser} module provides
+  # methods for parsing a JSON schema into {LLM::Schema::Leaf}
+  # objects. It is used by {LLM::Schema LLM::Schema} to convert
+  # external JSON schema definitions into the schema objects used
+  # throughout llm.rb.
+  module Parser
+    METADATA_KEYS = %w[description default enum const].freeze
+
+    ##
+    # Parses a JSON schema into an {LLM::Schema::Leaf}.
+    # @param [Hash] schema
+    #  The JSON schema to parse
+    # @raise [TypeError]
+    #  When the schema is not supported
+    # @return [LLM::Schema::Leaf]
+    def parse(schema, root = nil)
+      schema = normalize_schema(schema)
+      root ||= schema
+      schema = resolve_ref(schema, root)
+      case schema["type"]
+      when "object" then apply(parse_object(schema, root), schema)
+      when "array" then apply(parse_array(schema, root), schema)
+      when "string" then apply(parse_string(schema), schema)
+      when "integer" then apply(parse_integer(schema), schema)
+      when "number" then apply(parse_number(schema), schema)
+      when "boolean" then apply(schema().boolean, schema)
+      when "null" then apply(schema().null, schema)
+      when ::Array then apply(schema().any_of(*schema["type"].map { parse(schema.except("type", *METADATA_KEYS).merge("type" => _1), root) }), schema.except("type"))
+      when nil then parse_union(schema, root)
+      else raise TypeError, "unsupported schema type #{schema["type"].inspect}"
+      end
+    end
+
+    private
+
+    def parse_object(schema, root)
+      properties = (schema["properties"] || {})
+        .transform_keys(&:to_s)
+        .transform_values { parse(_1, root) }
+      required = schema["required"] || []
+      required.each do |key|
+        next unless properties[key]
+        properties[key].required
+      end
+      schema().object(properties)
+    end
+
+    def parse_array(schema, root)
+      items = schema["items"] ? parse(schema["items"], root) : schema().null
+      schema().array(items)
+    end
+
+    def parse_union(schema, root)
+      return apply(schema().any_of(*schema["anyOf"].map { parse(_1, root) }), schema) if schema.key?("anyOf")
+      return apply(schema().one_of(*schema["oneOf"].map { parse(_1, root) }), schema) if schema.key?("oneOf")
+      return apply(schema().all_of(*schema["allOf"].map { parse(_1, root) }), schema) if schema.key?("allOf")
+      return parse(infer_type(schema), root) if infer_type(schema)
+      raise TypeError, "unsupported schema type #{schema["type"].inspect}"
+    end
+
+    def parse_string(schema)
+      leaf = schema().string
+      leaf.min(schema["minLength"]) if schema.key?("minLength")
+      leaf.max(schema["maxLength"]) if schema.key?("maxLength")
+      leaf
+    end
+
+    def parse_integer(schema)
+      leaf = schema().integer
+      leaf.min(schema["minimum"]) if schema.key?("minimum")
+      leaf.max(schema["maximum"]) if schema.key?("maximum")
+      leaf.multiple_of(schema["multipleOf"]) if schema.key?("multipleOf")
+      leaf
+    end
+
+    def parse_number(schema)
+      leaf = schema().number
+      leaf.min(schema["minimum"]) if schema.key?("minimum")
+      leaf.max(schema["maximum"]) if schema.key?("maximum")
+      leaf.multiple_of(schema["multipleOf"]) if schema.key?("multipleOf")
+      leaf
+    end
+
+    def apply(leaf, schema)
+      leaf.description(schema["description"]) if schema.key?("description")
+      leaf.default(schema["default"]) if schema.key?("default")
+      leaf.enum(*schema["enum"]) if schema.key?("enum")
+      leaf.const(schema["const"]) if schema.key?("const")
+      leaf
+    end
+
+    def normalize_schema(schema)
+      case schema
+      when LLM::Object
+        normalize_schema(schema.to_h)
+      when Hash
+        schema.each_with_object({}) do |(key, value), out|
+          out[key.to_s] = normalize_schema(value)
+        end
+      when Array
+        schema.map { normalize_schema(_1) }
+      else
+        schema
+      end
+    end
+
+    def resolve_ref(schema, root)
+      return schema unless schema.key?("$ref")
+      ref = schema["$ref"]
+      raise TypeError, "unsupported schema ref #{ref.inspect}" unless ref.start_with?("#/")
+      target = ref.delete_prefix("#/").split("/").reduce(root) { |node, key| node.fetch(key) }
+      normalize_schema(target).merge(schema.except("$ref"))
+    rescue KeyError
+      raise TypeError, "unresolvable schema ref #{ref.inspect}"
+    end
+
+    def infer_type(schema)
+      if schema.key?("const")
+        schema.merge("type" => type_of(schema["const"]))
+      elsif schema.key?("enum")
+        type = type_of(schema["enum"].first)
+        return unless type && schema["enum"].all? { type_of(_1) == type }
+        schema.merge("type" => type)
+      elsif schema.key?("default")
+        schema.merge("type" => type_of(schema["default"]))
+      end
+    end
+
+    def type_of(value)
+      case value
+      when ::Hash then "object"
+      when ::Array then "array"
+      when ::String then "string"
+      when ::Integer then "integer"
+      when ::Float then "number"
+      when ::TrueClass, ::FalseClass then "boolean"
+      when ::NilClass then "null"
+      end
+    end
+  end
+end

data/lib/llm/schema.rb

@@ -31,9 +31,13 @@
 #  end
 class LLM::Schema
   require_relative "schema/version"
+  require_relative "schema/parser"
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
+  require_relative "schema/all_of"
+  require_relative "schema/any_of"
+  require_relative "schema/one_of"
   require_relative "schema/string"
   require_relative "schema/enum"
   require_relative "schema/number"
@@ -41,6 +45,26 @@ class LLM::Schema
   require_relative "schema/boolean"
   require_relative "schema/null"
 
+  @__monitor = Monitor.new
+  extend LLM::Schema::Parser
+
+  ##
+  # @api private
+  module Utils
+    extend self
+
+    def resolve(schema, type)
+      if LLM::Schema::Leaf === type
+        type
+      elsif Class === type && type.respond_to?(:object)
+        type.object
+      else
+        target = type.name.split("::").last.downcase
+        schema.public_send(target)
+      end
+    end
+  end
+
   ##
   # Configures a monitor for a subclass
   # @return [void]
@@ -61,14 +85,7 @@ class LLM::Schema
   #  A hash of options
   def self.property(name, type, description, options = {})
     lock do
-      if LLM::Schema::Leaf === type
-        prop = type
-      elsif Class === type && type.respond_to?(:object)
-        prop = type.object
-      else
-        target = type.name.split("::").last.downcase
-        prop = schema.public_send(target)
-      end
+      prop = Utils.resolve(schema, type)
       options = {description:}.merge(options)
       options.each { (_2 == true) ? prop.public_send(_1) : prop.public_send(_1, *_2) }
       object[name] = prop
@@ -116,6 +133,30 @@ class LLM::Schema
     Array.new(*items)
   end
 
+  ##
+  # Returns an anyOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::AnyOf]
+  def any_of(*values)
+    AnyOf.new(values)
+  end
+
+  ##
+  # Returns an allOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::AllOf]
+  def all_of(*values)
+    AllOf.new(values)
+  end
+
+  ##
+  # Returns a oneOf union
+  # @param [Array<LLM::Schema::Leaf>] values The union values
+  # @return [LLM::Schema::OneOf]
+  def one_of(*values)
+    OneOf.new(values)
+  end
+
   ##
   # Returns a string
   # @return [LLM::Schema::String]

data/lib/llm/server_tool.rb

@@ -8,10 +8,10 @@
 #
 # @example
 #   #!/usr/bin/env ruby
-#   llm = LLM.gemini ENV["KEY"]
-#   ses = LLM::Session.new(llm, tools: [LLM::ServerTool.new(:google_search)])
-#   ses.talk("Summarize today's news", role: :user)
-#   print ses.messages.find(&:assistant?).content, "\n"
+#   llm = LLM.google ENV["KEY"]
+#   ctx = LLM::Context.new(llm, tools: [LLM::ServerTool.new(:google_search)])
+#   ctx.talk("Summarize today's news", role: :user)
+#   print ctx.messages.find(&:assistant?).content, "\n"
 class LLM::ServerTool < Struct.new(:name, :options, :provider)
   ##
   # @return [String]
@@ -24,7 +24,7 @@ class LLM::ServerTool < Struct.new(:name, :options, :provider)
   def to_h
     case provider.class.to_s
     when "LLM::Anthropic" then options.merge("name" => name.to_s)
-    when "LLM::Gemini" then {name => options}
+    when "LLM::Google" then {name => options}
     else options.merge("type" => name.to_s)
     end
   end

data/lib/llm/session.rb

@@ -1,3 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "bot"
+require_relative "context"
+
+module LLM
+  # Backward-compatible alias for LLM::Context
+  # @deprecated Use {LLM::Context} instead. Scheduled for removal in v6.0.
+  Session = Context
+
+  # Scheduled for removal in v6.0
+  deprecate_constant :Session
+end

data/lib/llm/tool.rb

@@ -22,22 +22,96 @@ class LLM::Tool
   extend LLM::Tool::Param
 
   types = [
-    :Leaf, :String, :Enum, :Array,
+    :Leaf, :String, :Enum,
+    :AllOf, :AnyOf, :OneOf,
     :Object, :Integer, :Number,
-    :Boolean, :Null
+    :Array, :Boolean, :Null
   ]
   types.each do |constant|
     const_set constant, LLM::Schema.const_get(constant)
   end
 
+  ##
+  # @param [LLM::MCP] mcp
+  #  The MCP client that will execute the tool call
+  # @param [Hash] tool
+  #  A tool (as a raw Hash)
+  # @return [Class<LLM::Tool>]
+  #  Returns a subclass of LLM::Tool
+  def self.mcp(mcp, tool)
+    klass = Class.new(LLM::Tool) do
+      name tool["name"]
+      description tool["description"]
+      params { tool["inputSchema"] || {type: "object", properties: {}} }
+
+      define_singleton_method(:inspect) do
+        "<LLM::Tool:0x#{object_id.to_s(16)} name=#{tool["name"]} (mcp)>"
+      end
+      singleton_class.alias_method :to_s, :inspect
+
+      define_singleton_method(:mcp?) do
+        true
+      end
+
+      define_method(:call) do |**args|
+        mcp.call_tool(tool["name"], args)
+      end
+    end
+    unregister(klass)
+  end
+
+  ##
+  # Returns all subclasses of LLM::Tool
+  # @note
+  #  This method excludes tools who haven't defined a name
+  #  as well as tools defined via MCP.
+  # @return [Array<LLM::Tool>]
+  def self.registry
+    lock do
+      @registry.select(&:name)
+    end
+  end
+  @registry = []
+
+  ##
+  # Clear the registry
+  # @return [void]
+  def self.clear_registry!
+    lock do
+      @registry.clear
+      nil
+    end
+  end
+
+  ##
+  # Register a tool in the registry
+  # @param [LLM::Tool] tool
+  # @api private
+  def self.register(tool)
+    lock do
+      @registry << tool
+    end
+  end
+
+  ##
+  # Unregister a tool from the registry
+  # @param [LLM::Tool] tool
+  # @api private
+  def self.unregister(tool)
+    lock do
+      @registry.delete(tool)
+    end
+  end
+
   ##
   # Registers the tool as a function when inherited
   # @param [Class] klass The subclass
   # @return [void]
-  def self.inherited(klass)
+  def self.inherited(tool)
     LLM.lock(:inherited) do
-      klass.instance_eval { @__monitor ||= Monitor.new }
-      klass.function.register(klass)
+      tool.instance_eval { @__monitor ||= Monitor.new }
+      tool.function.register(tool)
+      LLM::Tool.register(tool)
     end
   end
 
@@ -75,7 +149,7 @@ class LLM::Tool
   # @api private
   def self.function
     lock do
-      @function ||= LLM::Function.new(self)
+      @function ||= LLM::Function.new(nil)
     end
   end
 
@@ -84,4 +158,12 @@ class LLM::Tool
   def self.lock(&)
     @__monitor.synchronize(&)
   end
+  @__monitor = Monitor.new
+
+  ##
+  # Returns true if the tool is an MCP tool
+  # @return [Boolean]
+  def self.mcp?
+    false
+  end
 end

data/lib/llm/tracer/logger.rb

@@ -23,7 +23,7 @@ module LLM
     ##
     # @param (see LLM::Tracer#on_request_start)
     # @return [void]
-    def on_request_start(operation:, model: nil)
+    def on_request_start(operation:, model: nil, **)
       case operation
       when "chat" then start_chat(operation:, model:)
       when "retrieval" then start_retrieval(operation:)

data/lib/llm/tracer/telemetry.rb

@@ -20,10 +20,10 @@ module LLM
   #   llm = LLM.openai(key: ENV["KEY"])
   #   llm.tracer = LLM::Tracer::Telemetry.new(llm)
   #
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk "hello"
-  #   ses.talk "how are you?"
-  #   ses.tracer.spans.each { |span| pp span }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "hello"
+  #   ctx.talk "how are you?"
+  #   ctx.tracer.spans.each { |span| pp span }
   #
   # @example OTLP export
   #   #!/usr/bin/env ruby
@@ -36,9 +36,9 @@ module LLM
   #   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?"
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "hello"
+  #   ctx.talk "how are you?"
   class Tracer::Telemetry < Tracer
     ##
     # param [LLM::Provider] provider

data/lib/llm/tracer.rb

@@ -147,7 +147,7 @@ module LLM
     # Merges extra attributes for the current trace/span. Used by applications
     # (e.g. chatbot) to add metadata, span inputs, or span outputs to the next
     # span or to the trace. No-op by default; {LLM::Tracer::Langsmith} merges
-    # into thread-local storage and emits them as langsmith/GenAI attributes.
+    # into fiber-local storage and emits them as langsmith/GenAI attributes.
     #
     # @param [Hash, nil] metadata
     #  Key-value pairs merged into trace/span metadata (e.g. langsmith.metadata.*).
@@ -190,7 +190,7 @@ module LLM
     ##
     # Returns and clears extra inputs for the next span. Called by the telemetry
     # tracer when starting a span. Subclasses (e.g. Langsmith) override to
-    # return thread-local inputs; default returns {}.
+    # return fiber-local inputs; default returns {}.
     #
     # @return [Hash] Attribute key => value to set on the span at start
     def consume_extra_inputs
@@ -200,7 +200,7 @@ module LLM
     ##
     # Returns and clears extra outputs for the current span. Called by the
     # telemetry tracer when finishing a span. Subclasses override to return
-    # thread-local outputs; default returns {}.
+    # fiber-local outputs; default returns {}.
     #
     # @return [Hash] Attribute key => value to set on the span at finish
     def consume_extra_outputs

data/lib/llm/usage.rb

@@ -8,4 +8,9 @@
 # It can also help track usage of the context window (which may
 # vary by model).
 class LLM::Usage < Struct.new(:input_tokens, :output_tokens, :reasoning_tokens, :total_tokens, keyword_init: true)
+  ##
+  # @return [String]
+  def to_json(...)
+    LLM.json.dump({input_tokens:, output_tokens:, reasoning_tokens:, total_tokens:})
+  end
 end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -6,6 +6,8 @@ module LLM
   require_relative "llm/tracer"
   require_relative "llm/error"
   require_relative "llm/contract"
+  require_relative "llm/registry"
+  require_relative "llm/cost"
   require_relative "llm/usage"
   require_relative "llm/prompt"
   require_relative "llm/schema"
@@ -19,7 +21,7 @@ module LLM
   require_relative "llm/multipart"
   require_relative "llm/file"
   require_relative "llm/provider"
-  require_relative "llm/session"
+  require_relative "llm/context"
   require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
@@ -30,7 +32,22 @@ 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, registry: Monitor.new}
+
+  ##
+  # Model registry
+  @registry = {}
+
+  ##
+  # @param [Symbol, LLM::Provider] llm
+  #  The name of a provider, or an instance of LLM::Provider
+  # @return [LLM::Object]
+  def self.registry_for(llm)
+    lock(:registry) do
+      name = Symbol === llm ? llm : llm.name
+      @registry[name] ||= Registry.for(name)
+    end
+  end
 
   module_function
 
@@ -76,10 +93,10 @@ module LLM
 
   ##
   # @param (see LLM::Provider#initialize)
-  # @return (see LLM::Gemini#initialize)
-  def gemini(**)
-    lock(:require) { require_relative "llm/providers/gemini" unless defined?(LLM::Gemini) }
-    LLM::Gemini.new(**)
+  # @return (see LLM::Google#initialize)
+  def google(**)
+    lock(:require) { require_relative "llm/providers/google" unless defined?(LLM::Google) }
+    LLM::Google.new(**)
   end
 
   ##
@@ -132,6 +149,22 @@ module LLM
     LLM::ZAI.new(**)
   end
 
+  ##
+  # @param [LLM::Provider, nil] llm
+  #  The provider to use for MCP transports that need one
+  # @param [Hash, nil] stdio
+  # @option stdio [Array<String>] :argv
+  #  The command to run for the MCP process
+  # @option stdio [Hash] :env
+  #  The environment variables to set for the MCP process
+  # @option stdio [String, nil] :cwd
+  #  The working directory for the MCP process
+  # @return [LLM::MCP]
+  def mcp(llm = nil, **)
+    lock(:require) { require_relative "llm/mcp" unless defined?(LLM::MCP) }
+    LLM::MCP.new(llm, **)
+  end
+
   ##
   # Define a function
   # @example

data/llm.gemspec

@@ -5,17 +5,52 @@ require_relative "lib/llm/version"
 Gem::Specification.new do |spec|
   spec.name = "llm.rb"
   spec.version = LLM::VERSION
-  spec.authors = ["Antar Azri", "0x1eef"]
-  spec.email = ["azantar@proton.me", "0x1eef@proton.me"]
+  spec.authors = ["Antar Azri", "0x1eef", "Christos Maris", "Rodrigo Serrano"]
+  spec.email = ["azantar@proton.me", "0x1eef@hardenedbsd.org"]
 
   spec.summary = <<~SUMMARY
-  llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-  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.
+  llm.rb is a Ruby-centric toolkit for building real LLM-powered systems — where
+  LLMs are part of your architecture, not just API calls. It gives you explicit
+  control over contexts, tools, concurrency, and providers, so you can compose
+  reliable, production-ready workflows without hidden abstractions.
   SUMMARY
 
-  spec.description = spec.summary
+  spec.description = <<~DESCRIPTION
+  llm.rb is a Ruby-centric toolkit for building real LLM-powered systems — where
+  LLMs are part of your architecture, not just API calls. It gives you explicit
+  control over contexts, tools, concurrency, and providers, so you can compose
+  reliable, production-ready workflows without hidden abstractions.
+
+  Built for engineers who want to understand and control their LLM systems. No
+  frameworks, no hidden magic — just composable primitives for building real
+  applications, from scripts to full systems like Relay.
+
+  ## Key Features
+
+  - **Contexts are central** — Hold history, tools, schema, usage, cost, persistence, and execution state
+  - **Tool execution is explicit** — Run local, provider-native, and MCP tools sequentially or concurrently
+  - **One API across providers** — Unified interface for OpenAI, Anthropic, Google, xAI, zAI, DeepSeek, Ollama, and LlamaCpp
+  - **Thread-safe where it matters** — Providers are shareable, while contexts stay isolated and stateful
+  - **Production-ready** — Cost tracking, observability, persistence, and performance tuning built in
+  - **Stdlib-only by default** — Runs on Ruby standard library, with optional features loaded only when used
+
+  ## Capabilities
+
+  - Chat & Contexts with persistence
+  - Streaming responses
+  - Tool calling with JSON Schema validation
+  - Concurrent execution (threads, fibers, async tasks)
+  - Agents with auto-execution
+  - Structured outputs
+  - MCP (Model Context Protocol) support
+  - Multimodal inputs (text, images, audio, documents)
+  - Audio generation, transcription, translation
+  - Image generation and editing
+  - Files API for document processing
+  - Embeddings and vector stores
+  - Local model registry for capabilities, limits, and pricing
+  DESCRIPTION
+
   spec.license = "0BSD"
   spec.required_ruby_version = ">= 3.2.0"
 
@@ -23,10 +58,12 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = "https://github.com/llmrb/llm.rb"
   spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm.rb"
   spec.metadata["documentation_uri"] = "https://0x1eef.github.io/x/llm.rb"
+  spec.metadata["changelog_uri"] = "https://0x1eef.github.io/x/llm.rb/file.CHANGELOG.html"
 
   spec.files = Dir[
     "README.md", "LICENSE",
     "lib/*.rb", "lib/**/*.rb",
+    "data/*.json",
     "llm.gemspec"
   ]
   spec.require_paths = ["lib"]
@@ -44,4 +81,4 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "net-http-persistent", "~> 4.0"
   spec.add_development_dependency "opentelemetry-sdk", "~> 1.10"
   spec.add_development_dependency "logger", "~> 1.7"
-end
+end