llm.rb 10.0.0 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ba756238fa72e58ba774567a0c8e2a6d7351cb6313f9c8c08cbdeec8ec9cfa4
-  data.tar.gz: cba8295670dab2843cec902ae97b7ae14e775359380ba401ca5a0066eb60ad0e
+  metadata.gz: 24c3c2930dd3ab321999075b34ef2e5c6d445fec5c873b00ef071caeef3c1406
+  data.tar.gz: 0d6921f20dc327f7c424f7282ff3c76f5073ad3eec7f21d483ee7623e4c782f7
 SHA512:
-  metadata.gz: b8347b2adfe05a4700ec42e0ed5992a1332355bd20330590d8b3de214d980476a490855ff7e69b5b36c75f3684304c4ee61bdff9ecbcf8001f0b477b8010d064
-  data.tar.gz: a41512ffbc52b3665118161251441152389ca9daba1a6f4e010303490938dc33393da62f5e821521b2a9f4b45d85fd219b558fa7d2e185c24f43777d26e36a14
+  metadata.gz: 3b96ea3336114822ccb2defee4da43089df6e004cebdf27987562f7f339bc2a733cc169d64f9752cc51d0346a069ba3921e99db69c2de1f795abfa69f260a730
+  data.tar.gz: b4135fad5bd1c5499b1177c27d6eb9c2da5a84b50a5492e82fe6396821c2b4a5e0891e55cb557d07e5ee4ec912b7ecdd8c7df223ebe76109aa74b7ede5227195

data/CHANGELOG.md

@@ -2,20 +2,126 @@
 
 ## Unreleased
 
-## v10.0.0
+## v11.0.0
 
-Changes since `v9.0.0`.
+Changes since `v10.0.0`.
+
+This release removes several deprecated or unused APIs, including the `#chat`
+alias from contexts and agents, the `LLM::Function#register` alias, and the
+unused positional `llm` argument from MCP constructors. Generated MCP and A2A
+tools are no longer added to the global tool registry by default.
+
+On the additions side, it introduces the A2A (Agent2Agent) protocol client,
+a new `#ask` convenience interface on contexts and agents, one-shot stdio MCP
+requests outside `#session`, `LLM::Function#def` as a short alias for
+`LLM::Function#define`, `LLM::File#exist?`, and `LLM::Tool.a2a?`.
+
+### Breaking
 
-This release unifies context turns under `#talk`, removes the
-deprecated `LLM::Bot` alias, and adds shared option resolution
-through `LLM::Utils`.
+* **Remove the unused `llm` argument from MCP clients** <br>
+  Remove the unused positional `llm` argument from `LLM::MCP.new`,
+  `LLM::MCP.stdio`, `LLM::MCP.http`, and `LLM.mcp`.
+
+* **Stop globally registering generated MCP and A2A tools** <br>
+  Generated tools returned by `LLM::Tool.mcp(...)` and
+  `LLM::Tool.a2a(...)` are no longer added to the global
+  `LLM::Tool.registry` or `LLM::Function.registry`. They still work
+  when passed directly to a context or agent, but registry-based lookup
+  now only sees normal loaded `LLM::Tool` subclasses.
+
+* **Remove `LLM::Function#register`** <br>
+  Remove the `LLM::Function#register` alias and prefer
+  `LLM::Function#define` or `LLM::Function#def` when binding a
+  function to its implementation. The `register` alias was too easy to
+  confuse with the class-level `LLM::Tool.register` and
+  `LLM::Function.register` registry APIs.
+
+* **Remove the `#chat` alias from contexts and agents** <br>
+  Remove the `LLM::Context#chat` and `LLM::Agent#chat` aliases. Prefer
+  `#talk` for all context and agent turns.
+
+### Add
 
-Class-level agent tunables can now be resolved lazily via Proc,
-`Array[...]` schema/tool param types are supported, and a `key?`
-method has been added on providers.
+* **Add `LLM::Function#def`** <br>
+  Add `LLM::Function#def` as a short alias for
+  `LLM::Function#define` when binding a function instance to its
+  implementation.
+
+* **Add `LLM::MCP#session`** <br>
+  Add `LLM::MCP#session` as an alias for `LLM::MCP#run`, and prefer it
+  in examples for scoped stdio MCP sessions that should stay alive
+  across discovery and tool calls.
+
+* **Add `#ask` to contexts and agents** <br>
+  Add `LLM::Context#ask` and `LLM::Agent#ask` as a RubyLLM-compatible
+  convenience interface over `#talk`. `#ask` accepts a prompt, optional
+  `with:` attachments, an optional `stream:` target, and an optional
+  block for streamed chunks, and returns an `LLM::Response`.
+
+* **Add `LLM::File#exist?`** <br>
+  Add `LLM::File#exist?` as a small convenience wrapper for checking
+  whether a local file exists on disk.
+
+* **Allow one-shot stdio MCP requests outside `#session`** <br>
+  Allow `mcp.tools`, `mcp.prompts`, `mcp.find_prompt(...)`, and
+  `mcp.call_tool(...)` to work outside `mcp.session` by starting and
+  stopping a stdio transport on demand when needed. This makes stdio
+  MCP usable without an explicit session block, while keeping
+  `mcp.session` as the preferred pattern for efficient, stateful
+  stdio workflows.
+
+* **Add A2A client support** <br>
+  Add `LLM::A2A`, a client for the Agent2Agent (A2A) protocol with
+  REST and JSON-RPC bindings. Remote agent skills can be exposed as
+  `LLM::Tool` classes and used through `LLM::Context` or `LLM::Agent`,
+  and the client also supports direct messaging, streaming, task
+  operations, push notification configuration, extended agent cards,
+  persistent HTTP transport selection, and optional REST `base_path`
+  prefixing.
+
+  Refactor shared MCP/A2A HTTP transport setup into
+  `LLM::Transport::Utils`, and extend
+  `LLM::Transport::StreamDecoder` to accept a callback block directly.
+
+* **Add `LLM::Tool.a2a?`** <br>
+  Add `LLM::Tool.a2a?` and mark generated A2A-backed tool classes so
+  callers can distinguish them from local or MCP tools.
+
+### Fix
+
+* **Fix context and agent JSON serialization through `LLM.json`** <br>
+  Fix `LLM::Context#to_json` and `LLM::Agent#to_json` to serialize
+  through `LLM.json.dump(...)` instead of plain `to_json`. 
+
+* **Fix block-form ORM agent DSL forwarding** <br>
+  Fix block-form `model { ... }`, `tools { ... }`, and
+  `schema { ... }` declarations in the ActiveRecord and Sequel agent
+  wrappers so persisted agent models configure the internal agent class
+  the same way as `LLM::Agent`.
+
+* **Fix missing `skills` in ORM agent wrappers** <br>
+  Fix the ActiveRecord and Sequel agent wrappers to expose `skills`, so
+  persisted agent models can declare skills the same way as
+  `LLM::Agent`.
+
+* **Fix `acts_as_agent#ctx` return type** <br>
+  Fix the ActiveRecord `acts_as_agent` wrapper so its `ctx` helper
+  returns the wrapped `LLM::Agent` instead of returning the underlying
+  `LLM::Context` directly.
+
+## v10.0.0
+
+Changes since `v9.0.0`.
 
-Agent tool confirmation hooks let selected tools be approved or
-cancelled before execution. Keep reading to learn more.
+This release removes the `LLM::Context#respond` method, and
+also removes the deprecated `LLM::Bot` alias. **All** class-level
+agent tunables can now be resolved lazily via a Symbol (method name),
+or a Proc. The `LLM::Agent` class can now confirm a tool call
+before it happens, and the `LLM::Schema` class has been extended
+to support `Array[String,Integer]` as a shorthand for
+`Array[AnyOf[String, Integer]]`. The `LLM::Stream` class has
+had its public method surface reduced to help avoid accidental
+collisions.
 
 ### Breaking
 

data/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="llm.rb">
+  <a href="https://github.com/llmrb/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>
@@ -11,7 +11,7 @@
     <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-10.0.0-green.svg?" alt="Version">
+    <img src="https://img.shields.io/badge/version-11.0.0-green.svg?" alt="Version">
   </a>
 </p>
 
@@ -21,8 +21,9 @@ llm.rb is Ruby's most capable AI runtime.
 
 It runs on Ruby's standard library by default. loads optional pieces
 only when needed, and offers a single runtime for providers, agents,
-tools, skills, MCP, streaming, files, and persisted state. As a bonus,
-llm.rb is also [available for mruby](https://github.com/llmrb/mruby-llm).
+tools, skills, MCP, A2A (Agent2Agent), RAG (vector stores & embeddings),
+streaming, files, and persisted state. As a bonus, llm.rb is also
+[available for mruby](https://github.com/llmrb/mruby-llm).
 
 It supports OpenAI, OpenAI-compatible endpoints, Anthropic, Google
 Gemini, DeepSeek, xAI, Z.ai, AWS Bedrock, Ollama, and llama.cpp. It
@@ -134,7 +135,9 @@ or
 [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html).
 In this example, the MCP server runs over stdio and
 [LLM::Context](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
-uses the same tool loop as local tools:
+uses the same tool loop as local tools. For **stdio**, `mcp.session`
+is the preferred pattern because it keeps one MCP session alive across
+discovery and tool calls:
 
 ```ruby
 require "llm"
@@ -142,20 +145,96 @@ require "llm"
 llm = LLM.openai(key: ENV["KEY"])
 mcp = LLM::MCP.stdio(argv: ["ruby", "server.rb"])
 
-mcp.run do
+mcp.session do
   ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
   ctx.talk "Use the available tools to inspect the environment."
   ctx.talk(ctx.wait(:call)) while ctx.functions?
 end
 ```
 
+MCP can also be used without `session`. Although it works it is generally
+not recommended for the **stdio** transport because it is inefficient
+to start and stop a fresh MCP process for tool discovery and each tool
+call:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM::MCP.stdio(argv: ["ruby", "server.rb"])
+
+ctx = LLM::Context.new(llm, tools: mcp.tools)
+ctx.talk("Use the available tools to inspect the environment.")
+ctx.talk(ctx.wait(:call)) while ctx.functions?
+```
+
+The HTTP transport can be used with or without the `session` method,
+and unlike the stdio transport it can remain efficient without the
+`session` method through a persistent connection pool that is available
+through the [LLM::Transport.net_http_persistent](https://0x1eef.github.io/x/llm.rb/LLM/Transport.html#method-c-net_http_persistent) transport:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM::MCP.http(
+  url: "https://remote-mcp.example.com",
+  transport: LLM::Transport.net_http_persistent
+)
+
+ctx = LLM::Context.new(llm, tools: mcp.tools)
+ctx.talk("Use the available tools to inspect the environment.")
+ctx.talk(ctx.wait(:call)) while ctx.functions?
+```
+
+#### A2A (Agent 2 Agent)
+
+The
+[LLM::A2A](https://0x1eef.github.io/x/llm.rb/LLM/A2A.html)
+object lets llm.rb use skills provided by a remote A2A agent. Those
+skills are exposed through the same runtime as local tools, so you can
+pass them to either
+[LLM::Context](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
+or
+[LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html).
+
+Use remote skills as local tools:
+
+```ruby
+require "llm"
+
+a2a = LLM::A2A.rest(
+  url: "https://remote-agent.example.com",
+  headers: {"Authorization" => "Bearer token"}
+)
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, tools: a2a.skills)
+ctx.talk "Analyze this CSV and summarize the trends."
+ctx.talk(ctx.wait(:call)) while ctx.functions?
+```
+
+Use persistent HTTP connections:
+
+```ruby
+require "llm"
+
+a2a = LLM::A2A.rest(
+  url: "https://remote-agent.example.com",
+  transport: LLM::Transport.net_http_persistent
+)
+```
+
+For more on direct messaging, task operations, push notification
+configs, and JSON-RPC, see the
+[LLM::A2A API docs](https://0x1eef.github.io/x/llm.rb/LLM/A2A.html).
+
 #### Skills
 
 Skills are reusable instructions loaded from a `SKILL.md` directory. They let
-you package behavior and tool access together, and they plug into the same
-runtime as tools, agents, and MCP. When a skill runs, llm.rb spawns a
-subagent with the skill instructions, access to only the tools listed in the
-skill, and recent conversation context:
+you package behavior and tool access together, and they plug into the
+same runtime as tools, agents, MCP, and A2A. When a skill runs, llm.rb
+spawns a subagent with the skill instructions, access to only the tools
+listed in the skill, and recent conversation context:
 
 ```yaml
 ---
@@ -277,6 +356,27 @@ ctx2.restore(string:)
 ctx2.talk "What is my favorite language?"
 ```
 
+#### ask
+
+[`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
+also provides `ask`, a convenience interface that is compatible with
+RubyLLM's `ask` method. It accepts a prompt, an optional `with:`
+attachment path or paths, an optional `stream:` target, and an optional
+block that chunks are yielded to. It returns an
+[`LLM::Response`](https://0x1eef.github.io/x/llm.rb/LLM/Response.html),
+so use `.content` when you want the text directly:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+
+puts ctx.ask("Hello world").content
+puts ctx.ask("Summarize this document.", with: "README.md").content
+ctx.ask("Stream this reply.") { $stdout << _1 }
+```
+
 ## Installation
 
 ```bash
@@ -315,17 +415,18 @@ or [`ctx.remote_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#r
 Those tagged objects carry the metadata the provider adapter needs to turn one
 Ruby prompt into the provider-specific multimodal request schema.
 
-`ctx.local_file(path)` tags a local path as a `:local_file` object around
-`LLM.File(path)`. If the model understands that file type, you can include it
-directly in the prompt array instead of uploading it first through a provider
-Files API:
+If the model understands that file type, you can attach a local file directly
+with `ctx.ask(..., with: path)` instead of uploading it first through a
+provider Files API. Under the hood, llm.rb tags the path as a
+[`ctx.local_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#local_file-instance_method)
+object:
 
 ```ruby
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 ctx = LLM::Context.new(llm)
-ctx.talk ["Summarize this document.", ctx.local_file("README.md")]
+puts ctx.ask("Summarize this document.", with: "README.md").content
 ```
 
 #### Context Compaction
@@ -602,26 +703,9 @@ mcp = LLM::MCP.http(
   persistent: true
 )
 
-mcp.start
 ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
 ctx.talk("Pull information about my GitHub account.")
 ctx.talk(ctx.wait(:call)) while ctx.functions?
-mcp.stop
-```
-
-For scoped work, `mcp.run do ... end` is shorter and handles cleanup for you:
-
-```ruby
-mcp = LLM::MCP.http(
-  url: "https://api.githubcopilot.com/mcp/",
-  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"},
-  persistent: true
-)
-mcp.run do
-  ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
-  ctx.talk("Pull information about my GitHub account.")
-  ctx.talk(ctx.wait(:call)) while ctx.functions?
-end
 ```
 
 ## Resources

data/lib/llm/a2a/card/capabilities.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class LLM::A2A::Card
+  ##
+  # Represents the agent's optional capabilities.
+  class Capabilities
+    ##
+    # @param [Hash] data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns whether the agent supports streaming.
+    # @return [Boolean]
+    def streaming
+      @data.streaming == true
+    end
+
+    ##
+    # Returns whether the agent supports push notifications.
+    # @return [Boolean]
+    def push_notifications
+      @data.pushNotifications == true
+    end
+
+    ##
+    # Returns whether the agent exposes an extended card.
+    # @return [Boolean]
+    def extended_agent_card
+      @data.extendedAgentCard == true
+    end
+
+    ##
+    # Returns the declared agent extensions.
+    # @return [Array<LLM::Object>]
+    def extensions
+      @extensions ||= (@data.extensions || []).map { LLM::Object.from(_1) }
+    end
+  end
+end

data/lib/llm/a2a/card/interface.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class LLM::A2A::Card
+  ##
+  # Represents a protocol interface supported by the agent.
+  class Interface
+    ##
+    # @param [Hash] data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns the interface URL.
+    # @return [String]
+    def url
+      @data.url
+    end
+
+    ##
+    # Returns the protocol binding name.
+    # @return [String]
+    def protocol_binding
+      @data.protocolBinding || @data.protocol_binding
+    end
+
+    ##
+    # Returns the A2A protocol version.
+    # @return [String]
+    def protocol_version
+      @data.protocolVersion || @data.protocol_version
+    end
+  end
+end

data/lib/llm/a2a/card/provider.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class LLM::A2A::Card
+  ##
+  # Represents the service provider of an agent.
+  class Provider
+    ##
+    # @param [Hash] data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns the provider website URL.
+    # @return [String]
+    def url
+      @data.url
+    end
+
+    ##
+    # Returns the provider organization name.
+    # @return [String]
+    def organization
+      @data.organization
+    end
+  end
+end

data/lib/llm/a2a/card/skill.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class LLM::A2A::Card
+  ##
+  # Represents a single skill/capability of an agent.
+  class Skill
+    ##
+    # @param [Hash] data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns the unique identifier for the skill.
+    # @return [String]
+    def id
+      @data.id
+    end
+
+    ##
+    # Returns the human-readable skill name.
+    # @return [String]
+    def name
+      @data.name
+    end
+
+    ##
+    # Returns the detailed skill description.
+    # @return [String]
+    def description
+      @data.description
+    end
+
+    ##
+    # Returns capability tags for the skill.
+    # @return [Array<String>]
+    def tags
+      @data.tags || []
+    end
+
+    ##
+    # Returns example prompts for the skill.
+    # @return [Array<String>]
+    def examples
+      @data.examples || []
+    end
+
+    ##
+    # Returns the supported input media types.
+    # @return [Array<String>]
+    def input_modes
+      @data.inputModes || @data.input_modes || []
+    end
+
+    ##
+    # Returns the supported output media types.
+    # @return [Array<String>]
+    def output_modes
+      @data.outputModes || @data.output_modes || []
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{LLM::Utils.object_id(self)} @id=#{id.inspect} @name=#{name.inspect}>"
+    end
+  end
+end

data/lib/llm/a2a/card.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+class LLM::A2A
+  ##
+  # Represents an A2A Agent Card — a self-describing manifest for an
+  # agent that provides metadata including the agent's identity,
+  # capabilities, skills, supported communication methods, and security
+  # requirements.
+  #
+  # Agent Cards are published at `/.well-known/agent-card.json` and
+  # allow clients to discover an agent's capabilities before interacting.
+  #
+  # @example
+  #   a2a = LLM::A2A.rest(url: "https://agent.example.com")
+  #   card = a2a.card
+  #   puts card.name          # => "GeoSpatial Route Planner Agent"
+  #   puts card.description   # => "Provides advanced route planning..."
+  #   card.skills.each { |s| puts "#{s.name}: #{s.description}" }
+  class Card
+    require_relative "card/skill"
+    require_relative "card/interface"
+    require_relative "card/capabilities"
+    require_relative "card/provider"
+
+    ##
+    # @param [Hash] data The raw Agent Card JSON data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns a human-readable name for the agent.
+    # @return [String]
+    def name
+      @data.name
+    end
+
+    ##
+    # Returns a human-readable description of the agent.
+    # @return [String]
+    def description
+      @data.description
+    end
+
+    ##
+    # Returns the agent version.
+    # @return [String]
+    def version
+      @data.version
+    end
+
+    ##
+    # Returns the advertised A2A protocol version.
+    # @return [String, nil]
+    def protocol_version
+      @data.protocolVersion || @data.protocol_version
+    end
+
+    ##
+    # Returns the documentation URL, when present.
+    # @return [String, nil]
+    def documentation_url
+      @data.documentationUrl || @data.documentation_url
+    end
+
+    ##
+    # Returns the icon URL, when present.
+    # @return [String, nil]
+    def icon_url
+      @data.iconUrl || @data.icon_url
+    end
+
+    ##
+    # Returns the skills provided by the agent.
+    # @return [Array<LLM::A2A::Card::Skill>]
+    def skills
+      @skills ||= (@data.skills || []).map { Skill.new(_1) }
+    end
+
+    ##
+    # Returns the interfaces supported by the agent.
+    # @return [Array<LLM::A2A::Card::Interface>]
+    def interfaces
+      @interfaces ||= (@data.supportedInterfaces || @data.supported_interfaces || []).map { Interface.new(_1) }
+    end
+
+    ##
+    # Returns the optional capabilities declaration.
+    # @return [LLM::A2A::Card::Capabilities, nil]
+    def capabilities
+      raw = @data.capabilities
+      raw ? Capabilities.new(raw) : nil
+    end
+
+    ##
+    # Returns the agent card signatures.
+    # @return [Array<LLM::Object>]
+    def signatures
+      @signatures ||= (@data.signatures || []).map { LLM::Object.from(_1) }
+    end
+
+    ##
+    # Returns the security scheme definitions.
+    # @return [Hash<String, Hash>, nil]
+    def security_schemes
+      @data.securitySchemes || @data.security_schemes
+    end
+
+    ##
+    # Returns the security requirements.
+    # @return [Array<Hash>, nil]
+    def security_requirements
+      @data.security || @data.security_requirements
+    end
+
+    ##
+    # Returns the declared provider information.
+    # @return [LLM::A2A::Card::Provider, nil]
+    def provider
+      raw = @data.provider
+      raw ? Provider.new(raw) : nil
+    end
+
+    ##
+    # Returns the default input media types.
+    # @return [Array<String>]
+    def default_input_modes
+      @data.defaultInputModes || @data.default_input_modes || []
+    end
+
+    ##
+    # Returns the default output media types.
+    # @return [Array<String>]
+    def default_output_modes
+      @data.defaultOutputModes || @data.default_output_modes || []
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{LLM::Utils.object_id(self)} @name=#{name.inspect} @skills=#{skills.size}>"
+    end
+  end
+end