The Freight Desk

The Freight Desk: a quoting capability whose tariff book is written as cross-field contract rules (new this round). Per-key checks catch nonsense; rules: catch the LEGAL-LOOKING orders that violate policy - and every broken rule is reported at once, because a shipper fixing their manifest deserves the whole list, not a scavenger hunt.

source on github

a real captured run

THE FREIGHT DESK (4 tariff rules on the contract)

  #1 QUOTED  $3600.00  (sea, 12000kg)
  #2 QUOTED  $2016.00  (air, 480kg)
  #3 REFUSED - 3 rule(s) broken:
       - [air_weight_limit] air freight is limited to 500kg (fields: mode, weight_kg)
       - [no_hazardous_air] hazardous cargo may not fly (fields: mode, hazardous)
       - [high_value_by_sea] insured value over 100k requires sea mode (fields: mode, insured_value)
  #4 QUOTED  $2200.00  (road, 2000kg)
  #5 MALFORMED - mode, weight_kg, destination invalid (never reached the tariff book)

manifest #3 broke THREE rules and heard about all three at once.
manifest #5 never reached the tariff book: per-key validation
rejects nonsense before cross-field rules spend time on it.

source

# frozen_string_literal: true

# The Freight Desk: a quoting capability whose tariff book is written
# as cross-field contract rules (new this round). Per-key checks catch
# nonsense; rules: catch the LEGAL-LOOKING orders that violate policy -
# and every broken rule is reported at once, because a shipper fixing
# their manifest deserves the whole list, not a scavenger hunt.
#
#   bundle exec ruby examples/freight_rules.rb
#
# Runs offline and deterministically.

require class="s">"bundler/setup"
require class="s">"agentic"

spec = Agentic:class="y">:CapabilitySpecification.new(
  name: class="s">"quote_freight",
  description: class="s">"Quote a freight shipment",
  version: class="s">"1.0.0",
  inputs: {
    mode: {type: class="s">"string", required: true, enum: %w[air sea road]},
    weight_kg: {type: class="s">"number", required: true, min: 1, max: 30_000},
    hazardous: {type: class="s">"boolean", required: true},
    insured_value: {type: class="s">"number", required: true, min: 0},
    destination: {type: class="s">"string", required: true, non_empty: true}
  },
  rules: {
    air_weight_limit: {
      message: class="s">"air freight is limited to 500kg",
      fields: [class="y">:mode, class="y">:weight_kg],
      check: ->(i) { i[class="y">:mode] != class="s">"air" || i[class="y">:weight_kg] <= 500 }
    },
    no_hazardous_air: {
      message: class="s">"hazardous cargo may not fly",
      fields: [class="y">:mode, class="y">:hazardous],
      check: ->(i) { !(i[class="y">:mode] == class="s">"air" && i[class="y">:hazardous]) }
    },
    high_value_by_sea: {
      message: class="s">"insured value over 100k requires sea mode",
      fields: [class="y">:mode, class="y">:insured_value],
      check: ->(i) { i[class="y">:insured_value] <= 100_000 || i[class="y">:mode] == class="s">"sea" }
    },
    road_is_domestic: {
      message: class="s">"road freight only reaches domestic destinations",
      fields: [class="y">:mode, class="y">:destination],
      check: ->(i) { i[class="y">:mode] != class="s">"road" || i[class="y">:destination].start_with?(class="s">"domestic:") }
    }
  }
)

RATES = {class="s">"air" => 4.20, class="s">"sea" => 0.30, class="s">"road" => 1.10}.freeze
Agentic.register_capability(spec, Agentic:class="y">:CapabilityProvider.new(
  capability: spec,
  implementation: ->(i) { {quote: (i[class="y">:weight_kg] * RATES.fetch(i[class="y">:mode])).round(2)} }
))

desk = Agentic:class="y">:AgentCapabilityRegistry.instance.get_provider(class="s">"quote_freight")

MANIFESTS = [
  {mode: class="s">"sea", weight_kg: 12_000, hazardous: true, insured_value: 250_000, destination: class="s">"port of rotterdam"},
  {mode: class="s">"air", weight_kg: 480, hazardous: false, insured_value: 20_000, destination: class="s">"berlin"},
  {mode: class="s">"air", weight_kg: 900, hazardous: true, insured_value: 150_000, destination: class="s">"tokyo"},
  {mode: class="s">"road", weight_kg: 2_000, hazardous: false, insured_value: 5_000, destination: class="s">"domestic:austin"},
  {mode: class="s">"teleport", weight_kg: -5, hazardous: false, insured_value: 10, destination: class="s">""}
].freeze

puts class="s">"THE FREIGHT DESK (#{spec.rules.size} tariff rules on the contract)"
puts
MANIFESTS.each_with_index do |manifest, index|
  quote = desk.execute(manifest)
  puts format(class="s">"  #%d QUOTED  $%.2f  (%s, %dkg)", index + 1, quote[class="y">:quote], manifest[class="y">:mode], manifest[class="y">:weight_kg])
rescue Agentic:class="y">:Errors:class="y">:ValidationError => e
  if e.rule_violations.any?
    puts class="s">"  ##{index + 1} REFUSED - #{e.rule_violations.size} rule(s) broken:"
    e.rule_violations.each do |violation|
      puts class="s">"       - [#{violation[class="y">:rule]}] #{violation[class="y">:message]} " \
        class="s">"(fields: #{violation[class="y">:fields].join(", class="s">")})"
    end
  else
    puts class="s">"  ##{index + 1} MALFORMED - #{e.violations.keys.join(", class="s">")} invalid " \
      class="s">"(never reached the tariff book)"
  end
end

puts
puts class="s">"manifest #3 broke THREE rules and heard about all three at once."
puts class="s">"manifest #5 never reached the tariff book: per-key validation"
puts class="s">"rejects nonsense before cross-field rules spend time on it."