llm.rb 4.9.0 → 4.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e876d90bb27d23cb36f97ee0edbc1fe8079a09f473b3a38a31fbd0247f3b9035
-  data.tar.gz: 82fce429783bcc2b8cb3bf8efc4b705ecc4e793cd6b0301ec616b48ec2d68f97
+  metadata.gz: a2af34506e099996b451951da8fb892ecdacebe9f29217bbf7a9e3ee3382d942
+  data.tar.gz: f49edb6d166ae113618139f0b118f37acbbd001b9b256d76d5c66b2828915a88
 SHA512:
-  metadata.gz: e2164d4b134ad12316e1ffa1bdf0d73bc52e14c2514e48bfd6a4963dcb9b3f1bcec932728627a49fec1e4a941e576784d48ae50c59ee174eaa8191dda54123c3
-  data.tar.gz: 02bf971e89ee97485f83b87a44eef3cdfec0dc4eb5fc7aad3f1383dce34ef3f889a89ae77738933945248c8ea7d76062270cba2fad2d734eba77ea105abffbe4
+  metadata.gz: 8dbdbde04bf04fd714ce5ab3689f078f6a77243853bdb7ea287124295b2a5b5878493a36e4ec0c703a10466306f13ca503de9132b2a8a31c2c39b2f721b1bf78
+  data.tar.gz: 5bcb9be7c664bbee548cdc305878bc62fe1c8b5ab23d64630719084dab3581b8f4abf875a235a0e33ee05430cda8d69b0b6cc8fce538abafa4e8f85bbbbaead0

data/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Changelog
+
+## Unreleased
+
+Changes since `v4.11.0`.
+
+## v4.11.0
+
+Changes since `v4.10.0`.
+
+### Add
+
+- Add `LLM::Stream` for richer streaming callbacks, including `on_content`,
+  `on_reasoning_content`, and `on_tool_call` for concurrent tool execution.
+- Add `LLM::Stream#wait` as a shortcut for `queue.wait`.
+- Add `LLM::Context#wait` as a shortcut for the configured stream's `wait`.
+- Add `LLM::Context#call(:functions)` as a shortcut for `functions.call`.
+- Add `LLM::Function.registry` and enhanced support for MCP tools in
+  `LLM::Tool.registry` for tool resolution during streaming.
+- Add normalized `LLM::Response` for OpenAI Responses, providing `content`,
+  `content!`, `messages` / `choices`, `usage`, and `reasoning_content`.
+- Add `mode: :responses` to `LLM::Context` for routing `talk` through the
+  Responses API.
+- Add `LLM::Context#returns` for collecting pending tool returns from the context.
+- Add persistent HTTP connection pooling for repeated MCP tool calls via
+  `LLM.mcp(http: ...).persist!`.
+- Add explicit MCP transport constructors via `LLM::MCP.stdio(...)` and
+  `LLM::MCP.http(...)`.
+
+### Fix
+
+- Fix Google tool-call handling by synthesizing stable ids when Gemini does
+  not provide a direct tool-call id.
+
+## v4.10.0
+
+Changes since `v4.9.0`.
+
+### Add
+
+- Add HTTP transport for MCP with `LLM::MCP::Transport::HTTP` for remote servers
+- Add JSON Schema union types (`any_of`, `all_of`, `one_of`) with parser integration
+- Add JSON Schema type array union support (e.g., `"type": ["object", "null"]`)
+- Add JSON Schema type inference from `const`, `enum`, or `default` fields
+
+### Change
+
+- Update `LLM::MCP` constructor for exclusive `http:` or `stdio:` transport
+- Update `LLM::MCP` documentation for HTTP transport support
+
+## v4.9.0
+
+Changes since `v4.8.0`.
+
+### Add
+
+- Add fiber-based concurrency with `LLM::Function::FiberGroup` and
+  `LLM::Function::TaskGroup` classes for lightweight async execution.
+- Add `:thread`, `:task`, and `:fiber` strategy parameter to
+  `LLM::Function#spawn` for explicit concurrency control.
+- Add stdio MCP client support, including remote tool discovery and
+  invocation through `LLM.mcp`, `LLM::Context`, and existing function/tool
+  APIs.
+- Add model registry support via `LLM::Registry`, including model
+  metadata lookup, pricing, modalities, limits, and cost estimation.
+- Add context access to a model context window via
+  `LLM::Context#context_window`.
+- Add tracking of defined tools in the tool registry.
+- Add `LLM::Schema::Enum`, enabling `Enum[...]` as a schema/tool
+  parameter type.
+- Add top-level Anthropic system instruction support using Anthropic's
+  provider-specific request format.
+- Add richer tracing hooks and extra metadata support for
+  LangSmith/OpenTelemetry-style traces.
+- Add rack/websocket and Relay-related example work, including MCP-focused
+  examples.
+- Add concurrent tool execution with `LLM::Function#spawn`,
+  `LLM::Function::Array` (`call`, `wait`, `spawn`), and
+  `LLM::Function::ThreadGroup`.
+- Add `LLM::Function::ThreadGroup#alive?` method for non-blocking
+  monitoring of concurrent tool execution.
+- Add `LLM::Function::ThreadGroup#value` alias for `ThreadGroup#wait` for
+  consistency with Ruby's `Thread#value`.
+
+### Change
+
+- Rename `LLM::Session` to `LLM::Context` throughout the codebase to better
+  reflect the concept of a stateful interaction environment.
+- Rename `LLM::Gemini` to `LLM::Google` to better reflect provider naming.
+- Standardize model objects across providers around a smaller common
+  interface.
+- Switch registry cost internals from `LLM::Estimate` to `LLM::Cost`.
+- Update image generation defaults so OpenAI and xAI consistently return
+  base64-encoded image data by default.
+- Update `LLM::Bot` deprecation warning from v5.0 to v6.0, giving users
+  more time to migrate to `LLM::Context`.
+- Rework the README and screencast documentation to better cover MCP,
+  registry, contexts, prompts, concurrency, providers, and example flow.
+- Expand the README with architecture, production, and provider guidance
+  while improving readability and example ordering.
+
+### Fix
+
+- Fix local schema `$ref` resolution in `LLM::Schema::Parser`.
+- Fix multiple MCP issues around stdio env handling, request IDs, registry
+  interaction, tool registration, and filtering of MCP tools from the
+  standard tool registry.
+- Fix stream parsing issues, including chunk-splitting bugs and safer
+  handling of streamed error responses.
+- Fix prompt handling across contexts, agents, and provider adapters so
+  prompt turns remain consistent in history and completions.
+- Fix several tool/context issues, including function return wrapping,
+  tool lookup after deserialization, unnamed subclass filtering, and
+  thread-safety around tool registry mutations.
+- Fix Google tool-call handling to preserve `thoughtSignature`.
+- Fix `LLM::Tracer::Logger` argument handling.
+- Fix packaging/docs issues such as registry files in the gemspec and
+  stale provider docs.
+- Fix Google provider handling of `nil` function IDs during context
+  deserialization.
+- Fix MCP stdio transport by increasing poll timeout for better
+  reliability.
+- Fix Google provider to properly cast non-Hash tool results into Hash
+  format for API compatibility.
+- Fix schema parser to support recursive normalization of `Array`,
+  `LLM::Object`, and nested structures.
+- Fix DeepSeek provider to tolerate malformed tool arguments.
+- Fix `LLM::Function::TaskGroup#alive?` to properly delegate to
+  `Async::Task#alive?`.
+- Fix various RuboCop errors across the codebase.
+- Fix DeepSeek provider to handle JSON that might be valid but unexpected.
+
+### Notes
+
+Notable merged work in this range includes:
+
+- `feat(function): add fiber-based concurrency for async environments (#64)`
+- `feat(mcp): add stdio MCP support (#134)`
+- `Add LLM::Registry + cost support (#133)`
+- `Consistent model objects across providers (#131)`
+- `Add rack + websocket example (#130)`
+- `feat(gemspec): add changelog URI (#136)`
+- `feat(function): alias ThreadGroup#wait as ThreadGroup#value (#62)`
+- README and screencast refresh across `#66`, `#67`, `#68`, `#71`, and
+  `#72`
+- `chore(bot): update deprecation warning from v5.0 to v6.0`
+- `fix(deepseek): tolerate malformed tool arguments`
+- `refactor(context): Rename Session as Context (#70)`
+
+Comparison base:
+- Latest tag: `v4.8.0` (`6468f2426ee125823b7ae43b4af507b125f96ffc`)
+- HEAD used for this changelog: `915c48da6fda9bef1554ff613947a6ce26d382e3`

data/README.md

@@ -4,7 +4,7 @@
 <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.9.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.11.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -32,6 +32,11 @@ llm.rb is built around the state and execution model around them:
   They hold history, tools, schema, usage, cost, persistence, and execution state.
 - **Tool execution is explicit** <br>
   Run local, provider-native, and MCP tools sequentially or concurrently with threads, fibers, or async tasks.
+- **Run tools while streaming** <br>
+  Start tool work while a response is still streaming instead of waiting for the turn to finish. <br>
+  This lets tool latency overlap with model output and is one of llm.rb's strongest execution features.
+- **HTTP MCP can reuse connections** <br>
+  Opt into persistent HTTP pooling for repeated remote MCP tool calls with `persist!`.
 - **One API across providers and capabilities** <br>
   The same model covers chat, files, images, audio, embeddings, vector stores, and more.
 - **Thread-safe where it matters** <br>
@@ -75,12 +80,14 @@ llm.rb is built in layers, each providing explicit control:
 llm.rb provides a complete set of primitives for building LLM-powered systems:
 
 - **Chat & Contexts** — stateless and stateful interactions with persistence
-- **Streaming** — real-time responses across providers
+- **Streaming** — real-time responses across providers, including structured stream callbacks
+- **Reasoning Support** — full stream, message, and response support when providers expose reasoning
 - **Tool Calling** — define and execute functions with automatic orchestration
+- **Run Tools While Streaming** — begin tool work before the model finishes its turn
 - **Concurrent Execution** — threads, async tasks, and fibers
 - **Agents** — reusable, preconfigured assistants with tool auto-execution
 - **Structured Outputs** — JSON schema-based responses
-- **MCP Support** — integrate external tool servers dynamically
+- **MCP Support** — integrate external tool servers dynamically over stdio or HTTP
 - **Multimodal Inputs** — text, images, audio, documents, URLs
 - **Audio** — text-to-speech, transcription, translation
 - **Images** — generation and editing
@@ -93,6 +100,50 @@ llm.rb provides a complete set of primitives for building LLM-powered systems:
 
 ## Quick Start
 
+#### Run Tools While Streaming
+
+llm.rb can start tool execution from streamed tool-call events before the
+assistant turn is fully finished. That means tool latency can overlap with
+streaming output instead of happening strictly after it. If your model emits
+tool calls early, this can noticeably reduce end-to-end latency for real
+systems.
+
+This is different from plain concurrent tool execution. The tool starts while
+the response is still arriving, not after the turn has fully completed.
+
+For example:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+class System < LLM::Tool
+  name "system"
+  description "Run a shell command"
+  params { _1.object(command: _1.string.required) }
+
+  def call(command:)
+    {success: Kernel.system(command)}
+  end
+end
+
+class Stream < LLM::Stream
+  def on_content(content)
+    print content
+  end
+
+  def on_tool_call(tool, error)
+    queue << (error || tool.spawn(:thread))
+  end
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, stream: Stream.new, tools: [System])
+
+ctx.talk("Run `date` and tell me what command you ran.")
+ctx.talk(ctx.wait(:thread)) while ctx.functions.any?
+```
+
 #### Concurrent Tools
 
 llm.rb provides explicit concurrency control for tool execution. The
@@ -112,7 +163,7 @@ ctx = LLM::Context.new(llm, stream: $stdout, tools: [FetchWeather, FetchNews, Fe
 
 # Execute multiple independent tools concurrently
 ctx.talk("Summarize the weather, headlines, and stock price.")
-ctx.talk(ctx.functions.wait(:thread)) while ctx.functions.any?
+ctx.talk(ctx.wait(:thread)) while ctx.functions.any?
 ```
 
 #### MCP
@@ -120,34 +171,59 @@ ctx.talk(ctx.functions.wait(:thread)) while ctx.functions.any?
 llm.rb integrates with the Model Context Protocol (MCP) to dynamically discover
 and use tools from external servers. This example starts a filesystem MCP
 server over stdio and makes its tools available to a context, enabling the LLM
-to interact with the local file system through a standardized interface:
+to interact with the local file system through a standardized interface.
+Use `LLM::MCP.stdio` or `LLM::MCP.http` when you want to make the transport
+explicit. Like `LLM::Context`, an MCP client is stateful and should remain
+isolated to a single thread:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
-mcp = LLM.mcp(stdio: {argv: ["npx", "-y", "@modelcontextprotocol/server-filesystem", Dir.pwd]})
+mcp = LLM::MCP.stdio(argv: ["npx", "-y", "@modelcontextprotocol/server-filesystem", Dir.pwd])
 
 begin
   mcp.start
   ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
   ctx.talk("List the directories in this project.")
-  ctx.talk(ctx.functions.call) while ctx.functions.any?
+  ctx.talk(ctx.call(:functions)) while ctx.functions.any?
+ensure
+  mcp.stop
+end
+```
+
+You can also connect to an MCP server over HTTP. This is useful when the
+server already runs remotely and exposes MCP through a URL instead of a local
+process. If you expect repeated tool calls, use `persist!` to reuse a
+process-wide HTTP connection pool. This requires the optional
+`net-http-persistent` gem:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM::MCP.http(
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {"Authorization" => "Bearer #{ENV.fetch("GITHUB_PAT")}"}
+).persist!
+
+begin
+  mcp.start
+  ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
+  ctx.talk("List the available GitHub MCP toolsets.")
+  ctx.talk(ctx.call(:functions)) while ctx.functions.any?
 ensure
   mcp.stop
 end
 ```
 
-#### Streaming Chat
+#### Simple Streaming
 
-This example demonstrates llm.rb's streaming support. The `stream: $stdout`
-parameter tells the context to write responses incrementally as they arrive
-from the LLM. The `Context` object manages the conversation history, and
-`talk()` sends your input while automatically appending both your message and
-the LLM's response to the context. Streams accept any object with `#<<`,
-giving you flexibility to pipe output to files, network sockets, or custom
-buffers:
+At the simplest level, any object that implements `#<<` can receive visible
+output as it arrives. This works with `$stdout`, `StringIO`, files, sockets,
+and other Ruby IO-style objects:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -162,14 +238,80 @@ loop do
 end
 ```
 
+#### Advanced Streaming
+
+llm.rb also supports the [`LLM::Stream`](lib/llm/stream.rb) interface for
+structured streaming events:
+
+- `on_content` for visible assistant output
+- `on_reasoning_content` for separate reasoning output
+- `on_tool_call` for streamed tool-call notifications
+
+Subclass [`LLM::Stream`](lib/llm/stream.rb) when you want features like
+`queue` and `wait`, or implement the same methods on your own object. Keep these
+callbacks fast: they run inline with the parser.
+
+`on_tool_call` lets tools start before the model finishes its turn, for
+example with `tool.spawn(:thread)`, `tool.spawn(:fiber)`, or
+`tool.spawn(:task)`. This is the mechanism behind running tools while
+streaming.
+
+If a stream cannot execute a tool, `error` is an `LLM::Function::Return` that
+communicates the failure back to the LLM. That lets the tool-call path recover
+and keeps the session alive. It also leaves control in the callback: it can
+send `error`, spawn the tool when `error == nil`, or handle the situation
+however it sees fit.
+
+In normal use this should be rare, since `on_tool_call` is usually called with
+a resolved tool and `error == nil`. To resolve a tool call, the tool must be
+found in `LLM::Function.registry`. That covers `LLM::Tool` subclasses,
+including MCP tools, but not `LLM.function` closures, which are excluded
+because they may be bound to local state:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+# Assume `System < LLM::Tool` is already defined.
+
+class Stream < LLM::Stream
+  attr_reader :content, :reasoning_content
+
+  def initialize
+    @content = +""
+    @reasoning_content = +""
+  end
+
+  def on_content(content)
+    @content << content
+    print content
+  end
+
+  def on_reasoning_content(content)
+    @reasoning_content << content
+  end
+
+  def on_tool_call(tool, error)
+    queue << (error || tool.spawn(:thread))
+  end
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, stream: Stream.new, tools: [System])
+
+ctx.talk("Run `date` and `uname -a`.")
+while ctx.functions.any?
+  ctx.talk(ctx.wait(:thread))
+end
+```
+
 #### Tool Calling
 
 Tools in llm.rb can be defined as classes inheriting from `LLM::Tool` or as
 closures using `LLM.function`. When the LLM requests a tool call, the context
 stores `Function` objects in `ctx.functions`. The `call()` method executes all
-pending functions and returns their results to the LLM. Tools support
-structured parameters with JSON Schema validation and automatically adapt to
-each provider's API format (OpenAI, Anthropic, Google, etc.):
+pending functions and returns their results to the LLM. Tools describe
+structured parameters with JSON Schema and adapt those definitions to each
+provider's tool-calling format (OpenAI, Anthropic, Google, etc.):
 
 ```ruby
 #!/usr/bin/env ruby
@@ -188,18 +330,17 @@ end
 llm = LLM.openai(key: ENV["KEY"])
 ctx = LLM::Context.new(llm, stream: $stdout, tools: [System])
 ctx.talk("Run `date`.")
-ctx.talk(ctx.functions.call) while ctx.functions.any?
+ctx.talk(ctx.call(:functions)) while ctx.functions.any?
 ```
 
 #### Structured Outputs
 
-The `LLM::Schema` system lets you define JSON schemas that LLMs must follow.
+The `LLM::Schema` system lets you define JSON schemas for structured outputs.
 Schemas can be defined as classes with `property` declarations or built
 programmatically using a fluent interface. When you pass a schema to a context,
-llm.rb automatically configures the provider's JSON mode and validates
-responses against your schema. The `content!` method returns the parsed JSON
-object, while errors are captured as structured data rather than raising
-exceptions:
+llm.rb adapts it into the provider's structured-output format when that
+provider supports one. The `content!` method then parses the assistant's JSON
+response into a Ruby object:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -209,6 +350,7 @@ require "pp"
 class Report < LLM::Schema
   property :category, Enum["performance", "security", "outage"], "Report category", required: true
   property :summary, String, "Short summary", required: true
+  property :impact, OneOf[String, Integer], "Primary impact, as text or a count", required: true
   property :services, Array[String], "Impacted services", required: true
   property :timestamp, String, "When it happened", optional: true
 end
@@ -221,6 +363,7 @@ pp res.content!
 # {
 #   "category" => "performance",
 #   "summary" => "Database latency spiked, causing 5% request timeouts for 12 minutes.",
+#   "impact" => "5% request timeouts",
 #   "services" => ["Database"],
 #   "timestamp" => "2024-06-05T10:42:00Z"
 # }
@@ -379,20 +522,24 @@ puts "Cost: $#{model_info.cost.input}/1M input tokens"
 
 #### Responses API
 
-llm.rb also supports OpenAI's Responses API through `llm.responses` and
-`ctx.respond`. This API can maintain response state server-side and can reduce
-how much conversation state needs to be sent on each turn:
+llm.rb also supports OpenAI's Responses API through `LLM::Context` with
+`mode: :responses`. The important switch is `store:`. With `store: false`, the
+Responses API stays stateless while still using the Responses endpoint, which
+is useful for models or features that are only available through the Responses
+API. With `store: true`, OpenAI can keep
+response state server-side and reduce how much conversation state needs to be
+sent on each turn:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
-ctx = LLM::Context.new(llm)
+ctx = LLM::Context.new(llm, mode: :responses, store: false)
 
-ctx.respond("Your task is to answer the user's questions", role: :developer)
-res = ctx.respond("What is the capital of France?")
-puts res.output_text
+ctx.talk("Your task is to answer the user's questions", role: :developer)
+res = ctx.talk("What is the capital of France?")
+puts res.content
 ```
 
 #### Context Persistence