llm.rb 13.1.0 → 14.0.0

data/resources/deepdive/protocols/mcp.md

@@ -0,0 +1,111 @@
+
+## MCP
+
+### Introduction
+
+#### Overview
+
+The Model Context Protocol (MCP) connects agents to external tools
+and data sources through a standardized interface. Instead of
+wiring each service directly into your agent, you run an MCP
+server that exposes its capabilities. The runtime translates the
+server's tool list into
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+subclasses the model can call.
+
+#### How it works
+
+The stdio transport runs the server as a child process and
+communicates over stdin/stdout. Use
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+to avoid launching the same process multiple times.
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+mcp   = LLM::MCP.stdio(argv: ["npx", "-y", "@forgejo/mcp-server"])
+agent = LLM::Agent.new(llm)
+
+mcp.session do
+  agent.talk "What's happening on forgejo?", tools: mcp.tools
+end
+```
+
+#### Why would I use it?
+
+MCP decouples tool implementation from the agent. Add tools by
+launching a new MCP server. Update them by restarting an existing
+one. Remove them without touching the agent's code.
+
+#### Notes
+
+For stdio, use
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+to avoid launching the same process multiple times. For HTTP,
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+carries little benefit.
+
+### HTTP
+
+#### Overview
+
+The HTTP transport connects to a remote MCP server over HTTP.
+It is the right choice for cloud-hosted servers like GitHub's
+MCP endpoint. Tools exposed by the server become
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+subclasses the model can call. The server does not need to run
+locally or even on the same machine. Configure headers for
+authentication and pick a transport backend for connection
+management.
+
+#### How it works
+
+When you want to connect to a remote MCP server, provide a URL and
+optional headers. The server's tool list is fetched and translated
+into
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) subclasses the model can call.
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+mcp   = LLM::MCP.http(
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {
+    "Authorization" => "Bearer #{ENV.fetch('GITHUB_PAT')}"
+  },
+  transport: :net_http_persistent
+)
+agent = LLM::Agent.new(llm)
+agent.talk "What's happening on GitHub?", tools: mcp.tools
+```
+
+#### Why would I use it?
+
+The HTTP transport connects to remote MCP servers. This matters
+when the server is not running locally or when tools are maintained
+by a different team and exposed as a service.
+
+#### Notes
+
+For HTTP,
+[`LLM::MCP#session`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html#session)
+carries little benefit.
+
+##### Persistent connections
+
+Set `persistent: true` to reuse HTTP connections across requests
+to the same MCP server. This uses
+[`Net::HTTP::Persistent`](https://github.com/drbrain/net-http-persistent)
+under the hood and avoids the overhead of opening a new TCP
+connection for every request.
+
+```ruby
+mcp = LLM::MCP.http(
+  url: "https://api.githubcopilot.com/mcp/",
+  headers: {"Authorization" => "Bearer #{ENV.fetch('GITHUB_PAT')}"},
+  persistent: true
+)
+```
+

data/resources/deepdive.md

@@ -53,12 +53,14 @@ place to start if you are new to llm.rb.
 
 - [Agents](deepdive/fundamentals/agents.md)
 - [Tools](deepdive/fundamentals/tools.md)
+- [Built-in tools](deepdive/fundamentals/builtin_tools.md)
 - [Skills](deepdive/fundamentals/skills.md)
 - [Schema](deepdive/fundamentals/schema.md)
 - [Stream](deepdive/fundamentals/stream.md)
 - [Database](deepdive/fundamentals/database.md)
 - [Concurrency](deepdive/fundamentals/concurrency.md)
 - [REPL](deepdive/fundamentals/repl.md)
+- [Embeddings](deepdive/fundamentals/embeddings.md)
 
 ## Advanced
 
@@ -66,6 +68,8 @@ place to start if you are new to llm.rb.
 - [Compaction](deepdive/advanced/compaction.md)
 - [Cancellation](deepdive/advanced/cancellation.md)
 - [Transports](deepdive/advanced/transports.md)
+- [Transformer](deepdive/advanced/transformer.md)
+- [Guard](deepdive/advanced/guard.md)
 - [Tracer](deepdive/advanced/tracer.md)
 
 ## Protocols
@@ -77,4 +81,6 @@ place to start if you are new to llm.rb.
 
 - [Images](deepdive/everything_else/images.md)
 - [Audio](deepdive/everything_else/audio.md)
-- [OCR](deepdive/everything_else/ocr.md)
+- [OCR](deepdive/everything_else/ocr.md)
+- [LLM::Object](deepdive/everything_else/object.md)
+- [LLM::Cost](deepdive/everything_else/cost.md)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 13.1.0
+  version: 14.0.0
 platform: ruby
 authors:
 - robert
@@ -299,6 +299,7 @@ files:
 - data/deepseek.json
 - data/google.json
 - data/mistral.json
+- data/moonshot.json
 - data/openai.json
 - data/xai.json
 - data/zai.json
@@ -357,8 +358,10 @@ files:
 - lib/llm/function/thread/group.rb
 - lib/llm/function/thread/task.rb
 - lib/llm/function/tracing.rb
+- lib/llm/guard.rb
+- lib/llm/guard/loop.rb
+- lib/llm/guard/null.rb
 - lib/llm/json_adapter.rb
-- lib/llm/loop_guard.rb
 - lib/llm/mcp.rb
 - lib/llm/mcp/command.rb
 - lib/llm/mcp/error.rb
@@ -435,6 +438,7 @@ files:
 - lib/llm/providers/mistral.rb
 - lib/llm/providers/mistral/request_adapter.rb
 - lib/llm/providers/mistral/request_adapter/completion.rb
+- lib/llm/providers/moonshot.rb
 - lib/llm/providers/ollama.rb
 - lib/llm/providers/ollama/error_handler.rb
 - lib/llm/providers/ollama/models.rb
@@ -478,11 +482,14 @@ files:
 - lib/llm/repl.rb
 - lib/llm/repl/bar.rb
 - lib/llm/repl/buffer.rb
+- lib/llm/repl/color.rb
 - lib/llm/repl/command.rb
 - lib/llm/repl/commands/compact.rb
 - lib/llm/repl/commands/exit.rb
 - lib/llm/repl/commands/help.rb
 - lib/llm/repl/input.rb
+- lib/llm/repl/input/char.rb
+- lib/llm/repl/input/row.rb
 - lib/llm/repl/markdown.rb
 - lib/llm/repl/markdown/table.rb
 - lib/llm/repl/node.rb
@@ -537,6 +544,8 @@ files:
 - lib/llm/tracer/null.rb
 - lib/llm/tracer/pretty_logger.rb
 - lib/llm/tracer/telemetry.rb
+- lib/llm/transformer.rb
+- lib/llm/transformer/null.rb
 - lib/llm/transport.rb
 - lib/llm/transport/curb.rb
 - lib/llm/transport/execution.rb
@@ -557,6 +566,30 @@ files:
 - lib/sequel/plugins/llm.rb
 - llm.gemspec
 - resources/deepdive.md
+- resources/deepdive/advanced/cancellation.md
+- resources/deepdive/advanced/compaction.md
+- resources/deepdive/advanced/context.md
+- resources/deepdive/advanced/guard.md
+- resources/deepdive/advanced/tracer.md
+- resources/deepdive/advanced/transformer.md
+- resources/deepdive/advanced/transports.md
+- resources/deepdive/everything_else/audio.md
+- resources/deepdive/everything_else/cost.md
+- resources/deepdive/everything_else/images.md
+- resources/deepdive/everything_else/object.md
+- resources/deepdive/everything_else/ocr.md
+- resources/deepdive/fundamentals/agents.md
+- resources/deepdive/fundamentals/builtin_tools.md
+- resources/deepdive/fundamentals/concurrency.md
+- resources/deepdive/fundamentals/database.md
+- resources/deepdive/fundamentals/embeddings.md
+- resources/deepdive/fundamentals/repl.md
+- resources/deepdive/fundamentals/schema.md
+- resources/deepdive/fundamentals/skills.md
+- resources/deepdive/fundamentals/stream.md
+- resources/deepdive/fundamentals/tools.md
+- resources/deepdive/protocols/a2a.md
+- resources/deepdive/protocols/mcp.md
 homepage: https://r.uby.dev/llm/
 licenses:
 - MIT
@@ -584,7 +617,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby's capable AI runtime
 test_files: []

data/lib/llm/loop_guard.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-##
-# {LLM::LoopGuard LLM::LoopGuard} is the built-in implementation of
-# llm.rb's `guard` capability.
-#
-# A guard is a context-level supervisor for agentic execution. It can inspect
-# the current runtime state and return a warning string when pending tool work
-# should be blocked before the loop keeps going.
-#
-# {LLM::LoopGuard LLM::LoopGuard} detects when a context is repeating the same
-# tool-call pattern instead of making progress.
-#
-# The public interface is intentionally small:
-# - `call(ctx)` returns `nil` when no intervention is needed
-# - `call(ctx)` returns a warning string when pending tool execution should be blocked
-#
-# {LLM::Context LLM::Context} can use that warning to return in-band
-# {LLM::GuardError LLM::GuardError} tool errors, and
-# {LLM::Agent LLM::Agent} enables this guard by default through its wrapped
-# context.
-#
-class LLM::LoopGuard
-  ##
-  # The default number of repeated tool-call patterns required before
-  # the guard intervenes.
-  # @return [Integer]
-  DEFAULT_THRESHOLD = 3
-
-  ##
-  # Returns the repetition threshold.
-  # @return [Integer]
-  attr_reader :threshold
-
-  ##
-  # @param [Hash] config
-  # @option config [Integer] :threshold
-  #  How many repeated tool-call patterns must appear at the tail of the
-  #  sequence before the guard returns a warning.
-  def initialize(config = {})
-    @threshold = config.fetch(:threshold, DEFAULT_THRESHOLD)
-  end
-
-  ##
-  # Checks the current context for repeated tool-call patterns.
-  #
-  # This method inspects assistant tool calls only. It reduces each call to a
-  # `[tool_name, arguments]` signature and checks whether the tail of the
-  # sequence is repeating.
-  #
-  # @param [LLM::Context] ctx
-  # @return [String, nil]
-  #  Returns a warning string when pending tool execution should be blocked,
-  #  or `nil` when execution should continue.
-  def call(ctx)
-    repetitions = detect(ctx.messages.to_a)
-    repetitions ? warning(repetitions) : nil
-  end
-
-  private
-
-  def detect(messages)
-    signatures = extract_signatures(messages)
-    return if signatures.size < threshold
-    check_repeating_pattern(signatures)
-  end
-
-  def warning(repetitions)
-    <<~MSG
-      SYSTEM NOTICE: Repeated tool-call pattern detected - the same pattern has repeated #{repetitions} times.
-      You are stuck in a loop and not making progress. Stop and try a fundamentally different approach:
-      - Re-read the relevant context before retrying
-      - Try a different tool or strategy
-      - Break the problem into smaller steps
-      - If a tool keeps failing, investigate why before retrying
-    MSG
-  end
-
-  def extract_signatures(messages)
-    messages
-      .select { _1.respond_to?(:functions) && _1.assistant? }
-      .flat_map { |message| message.functions.map { [_1.name.to_s, _1.arguments.to_s] } }
-  end
-
-  def check_repeating_pattern(sequence)
-    max_pattern_len = sequence.size / threshold
-    (1..max_pattern_len).each do |pattern_len|
-      count = count_tail_repetitions(sequence, pattern_len)
-      return count if count >= threshold
-    end
-    nil
-  end
-
-  def count_tail_repetitions(sequence, length)
-    return 0 if sequence.size < length
-    pattern = sequence.last(length)
-    count = 1
-    pos = sequence.size - length
-    while pos >= length
-      candidate = sequence[(pos - length)...pos]
-      break unless candidate == pattern
-      count += 1
-      pos -= length
-    end
-    count
-  end
-end