llm.rb 13.1.0 → 14.0.0

data/resources/deepdive/advanced/guard.md

@@ -0,0 +1,371 @@
+
+## Guard
+
+### Introduction
+
+#### Overview
+
+[`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+is the superclass for context-level supervisors. A guard is bound
+to a context and inspects each pending tool call before it runs.
+It can let the call through, cancel it, block it with an error, or
+answer for it with a synthesized result. Beyond loop detection,
+guards handle policy, validation, quotas, cost control, caching,
+and approval workflows.
+
+#### How it works
+
+A guard is a subclass of
+[`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+that implements
+[`LLM::Guard#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html#call-instance_method).
+The guard is stamped onto the functions the context binds, and when a
+function's task runs the guard is checked on the calling thread before
+the tool is handed to the strategy. `call` receives the pending
+`function:` and returns an
+[`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+to close that single call, or `nil` to let it run. The guard inspects
+the current conversation through the `messages` helper and reads the
+pending call through the function's own accessors.
+
+Configure a guard by passing a class through the `guard:` option;
+options given in `guard_options:` are forwarded to `call` as keyword
+arguments:
+
+```ruby
+class RateLimitGuard < LLM::Guard
+  def call(function:, limit: 10)
+    if messages.count(&:tool_return?) >= limit
+      function.return(error: true, type: "guard_error",
+                      message: "too many tool calls")
+    end
+  end
+end
+
+agent = LLM::Agent.new(
+  llm,
+  guard: RateLimitGuard,
+  guard_options: {limit: 3}
+)
+agent.talk "Research the market", tools: [FetchNews, FetchStocks]
+```
+
+#### Why would I use it?
+
+A guard is the one hook that sees every pending tool call and the
+full conversation at once. It can observe what the model is about
+to do, cancel a call that needs approval, block one that violates
+policy, answer a cheap question without running a tool, or stop
+work when a budget is spent. Because the guard runs before the
+tool, anything it intercepts never executes.
+
+#### Notes
+
+[`LLM::Guard::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Null.html)
+is the default guard for
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html);
+it never blocks tool work.
+[`LLM::Context#guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#guard)
+returns the configured guard class. Because `call` returns an
+[`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+rather than a warning string, a guard can block an individual tool
+call while the rest of the batch still executes. The guard is stamped
+onto every function the context binds, so it runs whenever a task is
+spawned — including tool calls a stream queues itself during a
+streaming turn. A blocked call yields its return without executing.
+
+The runtime binds a guard instance to the context and stamps it onto
+the functions it resolves, so a guard cannot carry state in instance
+variables between calls. Anything a guard needs to remember, like
+how many calls already ran, must come from the conversation
+(`messages`) or from class-level state.
+
+### Inspect
+
+#### Overview
+
+The guard receives the pending
+[`LLM::Function`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
+and can read what the model is about to do before anything runs.
+The function exposes its `name`, `arguments`, and parameter schema,
+so a guard can base its decision on the actual call rather than on
+the whole conversation. The guard also holds the context, so the
+message history, token usage, and cost are visible too.
+
+#### How it works
+
+When you want to inspect a pending call before it runs, read the
+function's accessors inside `call`.
+[`LLM::Function#name`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#name)
+is the tool name, and
+[`LLM::Function#arguments`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#arguments)
+is an
+[`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+with the parsed arguments. The full parameter schema is available
+through
+[`LLM::Function#params`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#params).
+Returning `nil` lets the call run, so an inspection-only guard is a
+pure observer:
+
+```ruby
+class AuditGuard < LLM::Guard
+  def call(function:)
+    warn "pending: #{function.name}(#{function.arguments.inspect})"
+    nil  # let it run
+  end
+end
+```
+
+#### Why would I use it?
+
+Inspecting the pending call is the basis for policy, validation,
+and audit. A guard can log every call into a telemetry stream, or
+reject a single call because its arguments violate a rule while
+letting every other call through. The same read underpins the
+richer decisions in the rest of this document.
+
+#### Notes
+
+The guard sees the parsed arguments exactly as the model requested
+them. Reading them costs nothing and never executes the tool.
+Returning `nil` means the call proceeds normally.
+
+### Cancel
+
+#### Overview
+
+Cancelling is distinct from blocking with an error.
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+produces a return the model reads as a declined call, not a failed
+one. The conversation stays honest: the model asked for something,
+and the runtime declined it with a reason.
+
+#### How it works
+
+When you want to cancel a single pending call, call the
+[`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel)
+method with a `reason:` and return the result from `call`. The
+pending call never executes, and the rest of the batch still runs.
+A guard can cancel one call in a two-call batch and the other call
+still executes:
+
+```ruby
+class ApprovalGuard < LLM::Guard
+  def call(function:)
+    if function.name == "delete-file"
+      function.cancel(reason: "delete requires human approval")
+    end
+  end
+end
+```
+
+#### Why would I use it?
+
+Cancellation suits approval workflows and environment rules. A call
+that needs a human in the loop, a tool that is disabled for a
+particular user, or an operation that must not run in production
+can all be declined without pretending the tool failed. Because
+cancellation is per call, it declines only the offending tool and
+leaves the rest of the batch intact.
+
+#### Notes
+
+The model receives
+`{cancelled: true, reason: "delete requires human approval"}` as
+that call's result and can react, for example by asking for
+permission or skipping the operation. A cancelled call still counts
+as resolved, like any tool return, so the model keeps moving. The
+reason string is what the model sees, so write it as guidance
+("ask the user first") rather than a raw error dump.
+
+### Block
+
+#### Overview
+
+Blocking is how a guard enforces policy. A blocked call never runs,
+and the model receives an in-band error explaining why. Unlike a
+cancellation, an error tells the model the tool could not produce
+a result at all.
+
+#### How it works
+
+When you want to block a call, return an
+[`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+with `error: true`. The `type` and `message` are free-form, and the
+model sees them inside the return value. Returning `nil` lets the
+call through:
+
+```ruby
+class PolicyGuard < LLM::Guard
+  def call(function:)
+    if function.name == "shell"
+      function.return(error: true, type: "policy_error",
+                      message: "shell is disabled")
+    end
+  end
+end
+```
+
+#### Why would I use it?
+
+Blocking denies a dangerous tool, rejects an out-of-policy
+argument, or stops a quota violation before it happens. The model
+receives the return and can adapt, so the conversation stays valid.
+
+#### Notes
+
+A blocked call never executes. The return it produces is sent back
+through the model like any tool result, so the model sees why the
+call was blocked and can change course.
+
+### Answer
+
+#### Overview
+
+A guard's return is injected into the conversation as if the tool
+had executed, so a guard can answer for a tool that never runs.
+From the model's side, a synthesized result is indistinguishable
+from a real one.
+
+#### How it works
+
+When you want to answer a pending call yourself, return a value
+through the
+[`LLM::Function#return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
+helper. The value you pass becomes the tool's result as-is, so it
+must look like a plausible answer:
+
+```ruby
+class CacheGuard < LLM::Guard
+  CACHE = {"get-weather:tokyo" => {forecast: "sunny"}}
+
+  def call(function:)
+    key = "#{function.name}:#{function.arguments[:city]}"
+    function.return(CACHE[key]) if CACHE.key?(key)
+  end
+end
+```
+
+#### Why would I use it?
+
+Standing in for a tool is how you cache expensive calls, mock tools
+in tests, or degrade gracefully when a service is down. The same
+hook can return a fixed answer for tools that should not run in a
+given environment.
+
+#### Notes
+
+[`LLM::Function#unavailable`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
+marks a tool as not found, and
+[`LLM::Function#budget_spent`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html)
+reports that the tool budget is exhausted. Both are returns too,
+so they flow back to the model like any tool result. A guard that
+synthesizes a result runs instead of the tool, so side effects the
+tool would have performed, like a database write, are skipped.
+
+### Budget
+
+#### Overview
+
+A guard can read the accumulated usage and cost of the conversation
+through the context. That makes it the natural place to enforce a
+hard ceiling: stop calling tools once a cost or token budget is
+spent, or once the context window is nearly full.
+
+#### How it works
+
+When you want to enforce a budget, compare
+[`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage)
+or
+[`LLM::Context#cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cost-instance_method)
+against a limit inside `call`. Pass the limit through
+`guard_options:` so it can be tuned per context. Returning a
+cancellation or an error closes the call before it runs:
+
+```ruby
+class BudgetGuard < LLM::Guard
+  def call(function:, limit: 0.05)
+    if ctx.cost.total >= limit
+      function.cancel(reason: "cost ceiling reached, ask before continuing")
+    end
+  end
+end
+
+ctx = LLM::Context.new(
+  llm,
+  guard: BudgetGuard,
+  guard_options: {limit: 0.01}
+)
+```
+
+#### Why would I use it?
+
+Budgets matter for long autonomous runs where the model decides how
+many tools to call. A cost ceiling keeps a runaway agent from
+spending money, and a quota derived from `messages` (as in the
+rate-limit example above) keeps a single user from exhausting
+shared resources. The same comparison works with
+[`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage)
+against
+[`LLM::Context#context_window`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_window)
+to keep the conversation inside the model's window.
+
+#### Notes
+
+The cost reported by
+[`LLM::Context#cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cost-instance_method)
+reflects the conversation so far, so a limit is enforced per call:
+once the ceiling is crossed, the next pending call is declined. The
+guard is not a replacement for
+[`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method),
+which caps the number of tool calls in a single turn. The two
+compose: the budget caps call count, and a guard enforces cost.
+
+### Loop
+
+#### Overview
+
+[`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
+is the built-in loop-detection guard. It reduces each assistant
+tool call to a `[tool name, arguments]` signature and checks whether
+the tail of the sequence is repeating.
+
+#### How it works
+
+When you want to detect repeated tool-call patterns, enable
+[`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
+and tune the `threshold:` option, which is the number of repeated
+patterns required before the guard intervenes (default `3`). When
+the guard detects a repeat, it returns an in-band
+[`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+with type `"guard_error"` and a message that tells the model it is
+stuck and should change approach:
+
+```ruby
+ctx = LLM::Context.new(
+  llm,
+  guard: LLM::Guard::Loop,
+  guard_options: {threshold: 2}
+)
+ctx.talk "Research the market", tools: [FetchNews, FetchStocks]
+```
+
+#### Why would I use it?
+
+Loop detection matters for long, autonomous agent runs. Without it,
+a model that repeats a tool call with the same arguments can
+bounce between calls forever. The guard turns that into a bounded
+conversation: after the threshold, the model receives a message
+telling it to stop and try a different strategy.
+
+#### Notes
+
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+enables
+[`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
+by default, so agents get loop protection without configuration.
+A custom guard can be passed through the `guard:` option to replace
+the loop guard entirely. Guards and the agent's tool budget
+complement each other: a guard blocks work that looks stuck, while
+[`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+caps the total number of tool calls in a single turn.

data/resources/deepdive/advanced/tracer.md

@@ -0,0 +1,180 @@
+
+## Tracer
+
+### Introduction
+
+#### Overview
+
+Tracers let you observe what the runtime is doing. They hook into
+requests, tool calls, compactions, and other events. Debug a
+misbehaving agent, monitor request latency, or export spans to
+an observability backend. A provider-wide tracer intercepts every
+request through that provider. An agent-local tracer only covers
+requests made by that agent.
+
+#### How it works
+
+When you want to observe runtime events, subclass
+[`LLM::Tracer`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html)
+and implement the hooks you need, or use one of the built-in
+tracers. The built-in tracers include
+[`LLM::Tracer::Logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html)
+(writes structured JSON to stdout or a file),
+[`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+(writes human-readable single-line logs to stderr), and
+[`LLM::Tracer::Telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Telemetry.html)
+(exports spans via OTLP for OpenTelemetry). Attach a tracer to a
+provider or an agent:
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+llm.tracer = LLM::Tracer::PrettyLogger.new(llm)
+agent = LLM::Agent.new(llm)
+agent.talk "Hello"
+```
+
+#### Why would I use it?
+
+Tracers give you visibility into what the runtime is doing. Debug
+a misbehaving agent by tracing every request it makes. Monitor
+request latency and token usage across providers. Export spans to
+OpenTelemetry for integration with existing observability pipelines.
+[`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+is the best choice during development for compact, human-readable
+output.
+[`LLM::Tracer::Logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html)
+provides structured JSON, and
+[`LLM::Tracer::Telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Telemetry.html)
+exports spans to OpenTelemetry for production observability.
+
+#### Notes
+
+The tracer is extensible. You can implement custom hooks for any
+runtime event. The scope can be an individual agent or every
+request a provider makes. Three built-in tracers are available:
+[`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+(human-readable),
+[`LLM::Tracer::Logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html)
+(structured JSON), and
+[`LLM::Tracer::Telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Telemetry.html)
+(OpenTelemetry).
+
+### Provider
+
+#### Overview
+
+A provider-wide tracer intercepts every request made through that
+provider. All agents sharing the same provider share the same
+tracer. Use this to trace at the infrastructure level without
+configuring each agent individually.
+
+#### How it works
+
+When you want every request through a provider to be traced, set
+the tracer on the provider directly. Every request made through
+that provider, regardless of which agent initiates it, flows
+through the same tracer hooks. The provider holds a reference to the
+tracer and passes it to every new context it creates. This ensures
+consistent observability without configuring each agent individually.
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+llm.tracer = LLM::Tracer::Logger.new(llm, io: $stdout)
+```
+
+#### Why would I use it?
+
+A provider-wide tracer captures every request at the infrastructure level.
+All agents sharing the same provider share the same tracer.
+
+#### Notes
+
+The tracer can also write to a file with the `path:` option to
+[`LLM::Tracer::Logger.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html#initialize-instance_method).
+
+### Agent
+
+#### Overview
+
+An agent-local tracer only covers requests made by that agent.
+Attach it via the `tracer:` keyword argument to
+[`LLM::Agent.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#initialize-instance_method)
+and it follows that agent wherever it goes. Different agents can
+have different tracers.
+
+#### How it works
+
+When you want a tracer for a specific agent, pass it to the agent
+on creation. Only requests made by
+that agent flow through the tracer, leaving other agents on the
+same provider unaffected.
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, tracer: LLM::Tracer::Logger.new(llm, io: $stdout))
+```
+
+#### Why would I use it?
+
+Agent-local tracers let each agent log differently.
+One agent might log to stdout, another to a file, a third to
+OpenTelemetry.
+
+#### Notes
+
+The tracer can also write to a file with the `path:` option to
+[`LLM::Tracer::Logger.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html#initialize-instance_method).
+
+### PrettyLogger
+
+#### Overview
+
+[`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+writes human-readable single-line logs to stderr. Unlike
+[`LLM::Tracer::Logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html)
+(which emits structured JSON), the pretty logger is designed for
+interactive development sessions where you want to see request and
+tool-call activity at a glance.
+
+#### How it works
+
+Each request and tool call produces a single line on stderr with
+the model, duration, and a summary of the activity. The logger
+accepts an `io:` option to redirect output.
+
+##### Provider-wide
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+llm.tracer = LLM::Tracer::PrettyLogger.new(llm)
+```
+
+##### Agent-local
+
+```ruby
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, tracer: LLM::Tracer::PrettyLogger.new(llm))
+```
+
+##### Custom output
+
+```ruby
+tracer = LLM::Tracer::PrettyLogger.new(llm, io: $stdout)
+tracer = LLM::Tracer::PrettyLogger.new(llm, io: File.open("trace.log", "a"))
+```
+
+#### Why would I use it?
+
+The pretty logger is the best choice for development. The output is
+compact enough to follow in real time while still showing the model
+name, duration, and tool calls. Switch to
+[`LLM::Tracer::Logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html)
+when you need structured JSON for programmatic analysis, or to
+[`LLM::Tracer::Telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Telemetry.html)
+when you need OpenTelemetry exports.
+
+#### Notes
+
+The pretty logger writes to `$stderr` by default. Set `io:` to
+redirect output. All three built-in tracers share the same interface,
+so switching between them requires changing only the class name.

data/resources/deepdive/advanced/transformer.md

@@ -0,0 +1,67 @@
+
+## Transformer
+
+### Introduction
+
+#### Overview
+
+[`LLM::Transformer`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html)
+is the superclass for message transformers. A transformer is bound
+to a context and rewrites a single message before it is sent to the
+provider. This lets you scrub sensitive data, inject context, or
+otherwise modify outgoing messages without changing your prompt
+code.
+
+#### How it works
+
+A transformer is a subclass of
+[`LLM::Transformer`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html)
+that implements
+[`LLM::Transformer#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html#call-instance_method).
+The method receives the message to transform and returns a
+message.
+You can mutate the message in place or return a new one; either way,
+the returned message is what gets sent.
+
+Configure the transformer on a context with the `transformer:` option,
+passing a class rather than an instance. The runtime instantiates it
+once per turn. Options passed through `transformer_options:` are
+forwarded to `call` as keyword arguments. The transformer runs on
+the most recent message in both chat completions and Responses API
+turns, before the request reaches the provider:
+
+```ruby
+class RedactEmails < LLM::Transformer
+  def call(message:)
+    content = message.content.to_s.gsub(/[\w.+-]+@[\w-]+\.[\w.]+/, "[EMAIL]")
+    LLM::Message.new(message.role, content, message.extra)
+  end
+end
+
+llm = LLM.deepseek(key: ENV["KEY"])
+ctx = LLM::Context.new(
+  llm,
+  transformer: RedactEmails
+)
+ctx.talk "Contact support@example.com for help"
+```
+
+#### Why would I use it?
+
+Transformers give you a single hook point for all outgoing messages.
+Common uses include redacting PII before it leaves your process,
+injecting a timestamp or request ID, or normalizing content for a
+particular provider. Because the transformer runs automatically on
+every turn, you never need to remember to apply the transform in
+your prompt code.
+
+#### Notes
+
+[`LLM::Transformer::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer/Null.html)
+is the default transformer; it returns the message unchanged. The
+`transformer_options:` hash is passed to `call` on every turn.
+Streams can observe transformation through the
+[`LLM::Stream#on_transform`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_transform-instance_method)
+and
+[`LLM::Stream#on_transform_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_transform_finish-instance_method)
+callbacks, which receive the transformer instance.

data/resources/deepdive/advanced/transports.md

@@ -0,0 +1,45 @@
+
+## Transports
+
+### Introduction
+
+#### Overview
+
+The transport option selects which HTTP library is used for network
+communication.
+[`LLM::Provider`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html),
+[`LLM::MCP`](https://r.uby.dev/api-docs/llm.rb/LLM/MCP.html), and
+[`LLM::A2A`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A.html)
+all accept this option. Three backends are available out of the box:
+`net/http` is always there, `net/http/persistent` pools connections,
+and `curb` wraps libcurl. Each implements the same internal interface
+so switching between them is a one-word change.
+
+#### How it works
+
+**Net/HTTP** (`:net_http`) is the
+default and is always available. **Net/HTTP/Persistent**
+(`:net_http_persistent`) maintains a connection pool so the cost
+of tearing down and setting up connections is kept low. **Curb**
+(`:curb`) provides bindings for libcurl.
+
+```ruby
+llm = LLM.deepseek(key: "...", transport: :net_http)
+mcp = LLM::MCP.http(url: "...", transport: :net_http_persistent)
+a2a = LLM::A2A.rest(url: "...", transport: :curb)
+```
+
+#### Why would I use it?
+
+Different environments have different HTTP needs.
+
+The default `net/http` transport is always available and works
+everywhere. The persistent transport reduces connection overhead
+when your agent makes many requests to the same provider in quick
+succession. Curb gives you libcurl bindings for environments where
+that is already configured or preferred.
+
+#### Notes
+
+The persistent transport is built on top of `net/http`. Curb
+requires the `curb` gem.