boxcars 0.10.1 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35a54151586860bccd1bd38579540f1130802c439cf9a64ea4f66f888dd927a1
-  data.tar.gz: 8b8b583b53b3d6223450c73376d94b073f393f46ee275532a0bb696c1ff261ea
+  metadata.gz: 224720d4944dee8add70e0cbb0db0768c7db74c2541547e600d485f7923cec20
+  data.tar.gz: 8f17b105ad4db7a707c08a6ed00923a20003bd30dbe76ad913e689a9de55bc68
 SHA512:
-  metadata.gz: 14d6cbf78d9fc5b95d1e956c9f66a5cc1747779f4170043f8469297f3ffc899a7760f39fd0f30377a1524b9a50b852a83bd69728f241b97dd97e6def4ee8c727
-  data.tar.gz: 19a99e7c1fd1670cec2ea0c0f2091b81943d0606ebff2817f7d24b444f0ed2246039cfef07d1768c95b043ecaf821153aa2bd9e724f07bb4d58e30ff79fc399d
+  metadata.gz: 74c8326c4ba3512466437d2c35056f50f28255f7b97ae5b0b2ea21743751eca30b7ee91040fd59f2b2684900864cc079e76f3f1894299635cad441552f6ba8aa
+  data.tar.gz: 31700d6ac344c9d66490cd3957bd96cee085605acc8550aa9f03edc7017ee38662392b3cf19d8d547282806bb82c4b5ae569b3da0fccb8c11633b2c84b9b1a91

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+### Recent Updates
+
+- Tool-calling runtime naming simplified:
+  - `Boxcars::ToolTrain` is now the preferred class name.
+  - `Boxcars::MCP.tool_train(...)` is the preferred MCP helper.
+  - Compatibility aliases remain available for `ToolCallingTrain` / `tool_calling_train`.
+- Added live multi-provider smoke coverage:
+  - `spec/boxcars/llms_live_spec.rb` (opt-in via `RUN_LIVE_LLM_SPECS=true`)
+  - `rake spec:llms_live`
+  - Provider include/skip controls and per-provider timeout overrides for stable live runs.
+- Provider and extraction reliability updates:
+  - Cohere default model updated to `command-a-03-2025`.
+  - OpenAI-compatible answer extraction hardened for provider-specific message payload shapes.
+  - Live smoke defaults updated for Gemini/Google/Cerebras token budgets.
+
 ### Upgrade Guide (v0.9 -> v1.0 planned)
 
 This section tracks the modernization work that is being added in v0.9 with a compatibility window before v1.0 removals.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boxcars (0.10.1)
+    boxcars (0.10.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -19,7 +19,7 @@ Inspired by LangChain, Boxcars brings a Ruby-first design that favors practical
 
 - Tool composability by default: package domain logic as `Boxcar` objects and reuse them across assistants, jobs, and services.
 - Lower cognitive load for Ruby/Rails developers: one consistent programming model (`Boxcar`, `Train`, `Engine`) for controllers, jobs, and service objects instead of one-off wrappers per provider.
-- Multiple orchestration modes: keep legacy text ReAct (`Boxcars::ZeroShot`) or use native provider tool calling (`Boxcars::ToolCallingTrain`).
+- Multiple orchestration modes: keep legacy text ReAct (`Boxcars::ZeroShot`) or use native provider tool calling (`Boxcars::ToolTrain`).
 - Structured output paths: enforce JSON contracts with JSON Schema through `JSONEngineBoxcar`.
 - MCP-ready integration: connect MCP servers over stdio and merge MCP tools with local Boxcars in one tool-calling runtime.
 - Provider flexibility without a rewrite: use OpenAI, Anthropic, Groq, Gemini, Ollama, Perplexity, and more through shared engine patterns.
@@ -39,6 +39,7 @@ Notebook migration expectations for the OpenAI client migration are documented i
 ### Current Upgrade Notes (toward v1.0)
 
 - `Boxcars::Openai` now defaults to `gpt-5-mini` and uses the official OpenAI client path.
+- `Boxcars::Cohere` now defaults to `command-a-03-2025` (legacy `command-r*` model IDs were retired by Cohere).
 - Runtime ActiveSupport/ActiveRecord targets are now `~> 8.1`.
 - Swagger workflows now use Faraday guidance. `rest-client` is no longer a Boxcars runtime dependency.
 - `intelligence` and `gpt4all` are now optional dependencies:
@@ -59,7 +60,7 @@ gem "gpt4all"
 All of these concepts are in a module named Boxcars:
 
 - Boxcar - an encapsulation that performs something of interest (such as search, math, SQL, an Active Record Query, or an API call to a service). A Boxcar can use an Engine (described below) to do its work, and if not specified but needed, the default Engine is used `Boxcars.engine`.
-- Train - Given a list of Boxcars and optionally an Engine, a Train breaks down a problem into pieces for individual Boxcars to solve. The individual results are then combined until a final answer is found. `Boxcars::ZeroShot` is the legacy text ReAct implementation, and `Boxcars::ToolCallingTrain` is the newer native tool-calling runtime.
+- Train - Given a list of Boxcars and optionally an Engine, a Train breaks down a problem into pieces for individual Boxcars to solve. The individual results are then combined until a final answer is found. `Boxcars::ZeroShot` is the legacy text ReAct implementation, and `Boxcars::ToolTrain` is the newer native tool-calling runtime.
 - Prompt - used by an Engine to generate text results. Our Boxcars have built-in prompts, but you have the flexibility to change or augment them if you so desire.
 - Engine - an entity that generates text from a Prompt. OpenAI's LLM text generator is the default Engine if no other is specified, and you can override the default engine if so desired (`Boxcars.configuration.default_engine`). We have an Engine for Anthropic's Claude API named `Boxcars::Anthropic`, and another Engine for local GPT named `Boxcars::Gpt4allEng` (requires the optional `gpt4all` gem).
 - VectorStore - a place to store and query vectors.
@@ -246,7 +247,7 @@ engine = Boxcars::Engines.engine(model: "gpt-4o")
 mcp_client = Boxcars::MCP.stdio(command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
 
 begin
-  train = Boxcars::MCP.tool_calling_train(
+  train = Boxcars::MCP.tool_train(
     engine: engine,
     boxcars: [Boxcars::Calculator.new],
     clients: [mcp_client],
@@ -259,7 +260,7 @@ ensure
 end
 ```
 
-`Boxcars::MCP.tool_calling_train(...)` combines local Boxcars and MCP-discovered tools into a `Boxcars::ToolCallingTrain`.
+`Boxcars::MCP.tool_train(...)` combines local Boxcars and MCP-discovered tools into a `Boxcars::ToolTrain`.
 
 ### More Examples
 See [this](https://github.com/BoxcarsAI/boxcars/blob/main/notebooks/boxcars_examples.ipynb) Jupyter Notebook for more examples.
@@ -512,7 +513,7 @@ end
 Override the model for specific engine instances:
 
 ```ruby
-# Global default is gemini-flash, but use different models per boxcar
+# Global default is gemini-2.5-flash, but use different models per boxcar
 default_engine = Boxcars::Engines.engine                    # Uses global default
 gpt_engine = Boxcars::Engines.engine(model: "gpt-4o")       # Uses GPT-4o
 claude_engine = Boxcars::Engines.engine(model: "sonnet")    # Uses Claude Sonnet

data/Rakefile

@@ -21,7 +21,7 @@ namespace :spec do
     spec/boxcars/engines_spec.rb
     spec/boxcars/engine/capabilities_spec.rb
     spec/boxcars/boxcar_tool_spec.rb
-    spec/boxcars/tool_calling_train_spec.rb
+    spec/boxcars/tool_train_spec.rb
     spec/boxcars/json_engine_boxcar_schema_spec.rb
     spec/boxcars/mcp_helpers_spec.rb
     spec/boxcars/mcp_stdio_client_spec.rb
@@ -51,6 +51,11 @@ namespace :spec do
     sh "bundle exec rspec #{NOTEBOOK_SMOKE_SPECS.join(' ')}"
   end
 
+  desc "Run live smoke checks for all configured LLM providers (.env supported)"
+  task :llms_live do
+    sh "RUN_LIVE_LLM_SPECS=true NO_VCR=true bundle exec rspec spec/boxcars/llms_live_spec.rb"
+  end
+
   desc "Run live notebook compatibility checks (requires OPENAI_ACCESS_TOKEN)"
   task :notebooks_live do
     sh "bundle exec ruby script/notebooks_live_check.rb"

data/UPGRADING.md

@@ -6,7 +6,7 @@ This guide covers the migration path for the modernization work added in v0.9 an
 
 v0.9 introduces:
 
-- Native tool-calling runtime via `Boxcars::ToolCallingTrain`
+- Native tool-calling runtime via `Boxcars::ToolTrain`
 - MCP as a first-class integration path
 - JSON Schema support for `JSONEngineBoxcar`
 - Deprecated model alias warnings with optional strict mode
@@ -16,6 +16,11 @@ v1.0 is expected to:
 - Remove deprecated model aliases
 - Prefer explicit model names (with a small curated alias set)
 
+## Provider Model Refresh Notes (v0.10.x)
+
+- Cohere retired legacy `command-r*` model IDs. Boxcars now defaults Cohere to `command-a-03-2025`.
+- If you pinned older Cohere IDs (`command-r`, `command-r-plus`, etc.), update to an available model in your Cohere account.
+
 ## Constructor Cleanup: `prompts:` Removed From Engine Initializers
 
 Engine constructors no longer accept a `prompts:` keyword argument.
@@ -151,7 +156,7 @@ Boxcars::Engines.strict_deprecated_aliases = true
 
 ## 3. Migrate ReAct/Text Trains to Native Tool Calling (Optional, Recommended)
 
-Existing `ZeroShot` / XML trains continue to work. `ToolCallingTrain` is the opt-in modern runtime.
+Existing `ZeroShot` / XML trains continue to work. `ToolTrain` is the opt-in modern runtime.
 
 ### Before (legacy text ReAct)
 
@@ -165,7 +170,7 @@ puts train.run("What is 12 * 9 and what is the weather in Austin?")
 
 ```ruby
 boxcars = [Boxcars::Calculator.new, Boxcars::GoogleSearch.new]
-train = Boxcars::ToolCallingTrain.new(
+train = Boxcars::ToolTrain.new(
   boxcars: boxcars,
   engine: Boxcars::Engines.engine(model: "gpt-4o")
 )
@@ -174,7 +179,7 @@ puts train.run("What is 12 * 9 and what is the weather in Austin?")
 
 ### Notes
 
-- `ToolCallingTrain` requires an engine that supports native tool-calling.
+- `ToolTrain` requires an engine that supports native tool-calling.
 - OpenAI chat models and OpenAI Responses API (`gpt-5` style) are supported by the current runtime path.
 
 ## 4. Add MCP Tools (Optional, Recommended)
@@ -189,7 +194,7 @@ mcp = Boxcars::MCP.stdio(
 )
 
 begin
-  train = Boxcars::MCP.tool_calling_train(
+  train = Boxcars::MCP.tool_train(
     engine: engine,
     boxcars: [Boxcars::Calculator.new],
     clients: [mcp],
@@ -236,7 +241,7 @@ boxcar = Boxcars::JSONEngineBoxcar.new(json_schema: schema, json_schema_strict:
 
 1. Replace deprecated aliases in application code.
 2. Enable strict alias mode in CI.
-3. Migrate one workflow from `ZeroShot` to `ToolCallingTrain`.
+3. Migrate one workflow from `ZeroShot` to `ToolTrain`.
 4. Add MCP tools where they simplify app-specific integrations.
 5. Add JSON Schema to `JSONEngineBoxcar` uses that need reliable structure.
 6. Upgrade to v1.0 after strict mode stays green.
@@ -266,7 +271,7 @@ This shared factory seam is used by all OpenAI-compatible engines, so client wir
 
 - Prefer `Boxcars::Engines.engine(...)` or engine classes directly (`Boxcars::Openai`, `Boxcars::Groq`, etc.).
 - Avoid depending on the exact underlying client object class returned inside engine internals.
-- Prefer explicit model names and `ToolCallingTrain` for new builds.
+- Prefer explicit model names and `ToolTrain` for new builds.
 
 ### OpenAI client defaults (v0.10+)
 
@@ -362,7 +367,7 @@ OPENAI_ACCESS_TOKEN=... bundle exec rake spec:vcr_openai_refresh
 
 - `Boxcars::Openai` public constructor and `#run` behavior
 - `Boxcars::Engines.engine(model: ...)`
-- `ToolCallingTrain` usage
+- `ToolTrain` usage
 - `JSONEngineBoxcar` usage (including `json_schema:` support)
 - MCP + Boxcar composition APIs
 

data/lib/boxcars/engine/cohere.rb

@@ -11,7 +11,7 @@ module Boxcars
 
     # The default parameters to use when asking the engine.
     DEFAULT_PARAMS = {
-      model: "command-r-plus",
+      model: "command-a-03-2025",
       max_tokens: 4000,
       max_input_tokens: 1000,
       temperature: 0.2
@@ -101,6 +101,7 @@ module Boxcars
 
       if raw_response.status == 200
         parsed_json = normalize_generate_response(JSON.parse(raw_response.body))
+        parsed_json["text"] ||= extract_cohere_text(parsed_json)
 
         if parsed_json["error"]
           response_data[:success] = false
@@ -112,9 +113,13 @@ module Boxcars
                                        []
                                      end
           input_tokens = parsed_json.dig("meta", "tokens", "input_tokens") ||
-                         parsed_json.dig("meta", "billed_units", "input_tokens")
+                         parsed_json.dig("meta", "billed_units", "input_tokens") ||
+                         parsed_json.dig("usage", "tokens", "input_tokens") ||
+                         parsed_json.dig("usage", "billed_units", "input_tokens")
           output_tokens = parsed_json.dig("meta", "tokens", "output_tokens") ||
-                          parsed_json.dig("meta", "billed_units", "output_tokens")
+                          parsed_json.dig("meta", "billed_units", "output_tokens") ||
+                          parsed_json.dig("usage", "tokens", "output_tokens") ||
+                          parsed_json.dig("usage", "billed_units", "output_tokens")
           if input_tokens || output_tokens
             parsed_json["usage"] ||= {
               "prompt_tokens" => input_tokens.to_i,
@@ -193,23 +198,78 @@ module Boxcars
     end
 
     def post_cohere_chat(params, api_key)
-      cohere_connection(api_key).post { |req| req.body = params.to_json }
+      v2_response = cohere_connection(api_key, version: :v2).post do |req|
+        req.body = cohere_v2_payload(params).to_json
+      end
+
+      return v2_response unless v2_response.status.to_i == 404
+
+      cohere_connection(api_key, version: :v1).post do |req|
+        req.body = cohere_v1_payload(params).to_json
+      end
     end
 
-    def cohere_connection(api_key)
-      Faraday.new('https://api.cohere.ai/v1/chat') do |faraday|
+    def cohere_connection(api_key, version:)
+      endpoint = version == :v2 ? 'https://api.cohere.com/v2/chat' : 'https://api.cohere.ai/v1/chat'
+      Faraday.new(endpoint) do |faraday|
         faraday.request :url_encoded
         faraday.headers['Authorization'] = "Bearer #{api_key}"
         faraday.headers['Content-Type'] = 'application/json'
       end
     end
 
+    def cohere_v2_payload(params)
+      payload = {
+        model: params[:model],
+        messages: [{ role: "user", content: params[:message].to_s }]
+      }
+
+      payload[:max_tokens] = params[:max_tokens] if params.key?(:max_tokens)
+      payload[:temperature] = params[:temperature] if params.key?(:temperature)
+      payload[:p] = params[:p] if params.key?(:p)
+      payload[:k] = params[:k] if params.key?(:k)
+      payload[:stop_sequences] = params[:stop_sequences] if params.key?(:stop_sequences)
+      payload
+    end
+
+    def cohere_v1_payload(params)
+      params
+    end
+
     def ensure_cohere_api_key!(api_key, error_class:, message:)
       return unless api_key.to_s.strip.empty?
 
       raise error_class, message
     end
 
+    def extract_cohere_text(parsed_json)
+      text = parsed_json["text"]
+      return text if text.is_a?(String) && !text.strip.empty?
+
+      message_content = parsed_json.dig("message", "content")
+      case message_content
+      when String
+        stripped = message_content.strip
+        return stripped unless stripped.empty?
+      when Array
+        texts = message_content.filter_map do |part|
+          next unless part.is_a?(Hash)
+
+          if part["text"].is_a?(String)
+            part["text"]
+          elsif part["text"].is_a?(Hash)
+            part["text"]["value"] || part["text"]["text"]
+          elsif part["content"].is_a?(String)
+            part["content"]
+          end
+        end
+        joined = texts.join("\n").strip
+        return joined unless joined.empty?
+      end
+
+      nil
+    end
+
     def parse_cohere_response_body(body)
       JSON.parse(body, symbolize_names: true)
     end

data/lib/boxcars/engine/openai.rb

@@ -276,7 +276,9 @@ module Boxcars
     def extract_answer_from_choices(choices)
       raise Error, "OpenAI: No choices found in response" unless choices.is_a?(Array) && choices.any?
 
-      content = choices.map { |c| c.dig("message", "content") }.compact
+      content = choices.filter_map do |choice|
+        extract_choice_message_text(choice)
+      end
       return content.join("\n").strip unless content.empty?
 
       text = choices.map { |c| c["text"] }.compact
@@ -285,6 +287,65 @@ module Boxcars
       raise Error, "OpenAI: Could not extract answer from choices"
     end
 
+    def extract_choice_message_text(choice)
+      return nil unless choice.is_a?(Hash)
+
+      message = choice["message"]
+      return nil unless message.is_a?(Hash)
+
+      content = message["content"]
+      extract_text_from_message_content(content)
+    end
+
+    def extract_text_from_message_content(content)
+      case content
+      when String
+        stripped = content.strip
+        return stripped unless stripped.empty?
+      when Array
+        texts = content.filter_map do |part|
+          extract_text_from_message_part(part)
+        end
+        joined = texts.join("\n").strip
+        return joined unless joined.empty?
+      when Hash
+        text = content["text"] || content["content"] || content["value"]
+        if text.is_a?(String)
+          stripped = text.strip
+          return stripped unless stripped.empty?
+        end
+      end
+
+      nil
+    end
+
+    def extract_text_from_message_part(part)
+      return nil unless part.is_a?(Hash)
+
+      text = part["text"]
+      if text.is_a?(String)
+        stripped = text.strip
+        return stripped unless stripped.empty?
+      elsif text.is_a?(Hash)
+        value = text["value"] || text["text"]
+        if value.is_a?(String)
+          stripped = value.strip
+          return stripped unless stripped.empty?
+        end
+      end
+
+      # Some providers place text directly on the part.
+      %w[content value].each do |field|
+        value = part[field]
+        next unless value.is_a?(String)
+
+        stripped = value.strip
+        return stripped unless stripped.empty?
+      end
+
+      nil
+    end
+
     def extract_answer_from_output(output_items) # rubocop:disable Metrics/PerceivedComplexity,Metrics/MethodLength
       return nil unless output_items.is_a?(Array) && output_items.any?
 

data/lib/boxcars/mcp.rb

@@ -11,7 +11,7 @@ module Boxcars
       StdioClient.new(command:, args:, **kwargs).connect!
     end
 
-    # Build a ToolCallingTrain from local Boxcars plus tools discovered from
+    # Build a ToolTrain from local Boxcars plus tools discovered from
     # one or more MCP clients.
     #
     # @param engine [Boxcars::Engine] Tool-calling capable engine (required)
@@ -19,10 +19,10 @@ module Boxcars
     # @param clients [Array<Boxcars::MCP::Client>] MCP clients to discover tools from
     # @param client_name_prefixes [Hash,Integer=>String] Optional prefixes by client index or object_id
     # @param mcp_return_direct [Boolean] Whether discovered MCP boxcars return direct
-    # @param train_kwargs [Hash] Additional args for Boxcars::ToolCallingTrain
-    def self.tool_calling_train(engine:, boxcars: [], clients: [], client_name_prefixes: {}, mcp_return_direct: false, **train_kwargs)
-      unless defined?(Boxcars::ToolCallingTrain)
-        raise Boxcars::Error, "Boxcars::ToolCallingTrain is not loaded. Require 'boxcars' before using MCP helpers."
+    # @param train_kwargs [Hash] Additional args for Boxcars::ToolTrain
+    def self.tool_train(engine:, boxcars: [], clients: [], client_name_prefixes: {}, mcp_return_direct: false, **train_kwargs)
+      unless defined?(Boxcars::ToolTrain)
+        raise Boxcars::Error, "Boxcars::ToolTrain is not loaded. Require 'boxcars' before using MCP helpers."
       end
 
       combined_boxcars = Array(boxcars).dup
@@ -33,7 +33,12 @@ module Boxcars
         )
       end
 
-      Boxcars::ToolCallingTrain.new(boxcars: combined_boxcars, engine:, **train_kwargs)
+      Boxcars::ToolTrain.new(boxcars: combined_boxcars, engine:, **train_kwargs)
+    end
+
+    # Backwards-compatible helper alias for initial v0.10 naming.
+    def self.tool_calling_train(...)
+      tool_train(...)
     end
 
     def self.mcp_client_prefix(client, index, client_name_prefixes)

data/lib/boxcars/train/{tool_calling_train.rb → tool_train.rb}

@@ -4,7 +4,7 @@ require "json"
 
 module Boxcars
   # A Train runtime that uses native LLM tool-calling instead of text ReAct parsing.
-  class ToolCallingTrain < Train
+  class ToolTrain < Train
     attr_accessor :wants_next_actions
 
     # Lightweight prompt wrapper so engine adapters can send an exact message list.
@@ -381,4 +381,7 @@ module Boxcars
       )
     end
   end
+
+  # Backwards-compatible alias for the initial v0.10 naming.
+  ToolCallingTrain = ToolTrain
 end

data/lib/boxcars/train.rb

@@ -254,4 +254,4 @@ require "boxcars/train/train_finish"
 require "boxcars/train/zero_shot"
 require "boxcars/train/xml_train"
 require "boxcars/train/xml_zero_shot"
-require "boxcars/train/tool_calling_train"
+require "boxcars/train/tool_train"

data/lib/boxcars/version.rb

@@ -2,5 +2,5 @@
 
 module Boxcars
   # The current version of the gem.
-  VERSION = "0.10.1"
+  VERSION = "0.10.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxcars
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.10.2
 platform: ruby
 authors:
 - Francis Sullivan
@@ -89,7 +89,7 @@ files:
 - lib/boxcars/result.rb
 - lib/boxcars/ruby_repl.rb
 - lib/boxcars/train.rb
-- lib/boxcars/train/tool_calling_train.rb
+- lib/boxcars/train/tool_train.rb
 - lib/boxcars/train/train_action.rb
 - lib/boxcars/train/train_finish.rb
 - lib/boxcars/train/xml_train.rb