fast-completions 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2cecdfed6a68aef560e112239c184f36f20d906b7122ae1311cbeb92b726b4d
-  data.tar.gz: cb1ecd28ceecb63144bc7ad9b9328ffd9624033c26d793c691496d67ea909551
+  metadata.gz: 5741f8a7684abbb66479904f8b49d14afebfd783cf3069e2e2c91717a0765238
+  data.tar.gz: 1a20474b48f9278d815b1561101a34cc229ac37c1cfcaeb83ffe9f1ba5bbcf9a
 SHA512:
-  metadata.gz: 12dcd5ced8e6c2ecee077178c138425ccae68061e6e0b42c6ec6540f952a3a93d3862ca319f761cfdebef89c04fc21024c09883f072a9949a0dc1a4ccace96d0
-  data.tar.gz: 934df8a658af5d27c9da6aca37ab8e0d999f5ff633149227c646888af30c8b63e6629452b227aab5d34e74aa5fd128bd283bab405bba0993d3e0fed0f06cc881
+  metadata.gz: bae0596f622cdee7289c271939aca77dc8e10d539aeed94b8c18388ad445957db4b19beb45a6359da7c971d3173d24e42ca917720499cfd081b398fd4e70f3ec
+  data.tar.gz: 30d7cc0ac12964163ca196e3e6a87e2e9e150de3db334ad342d55d923b55f0c522073108def6618c727a78593c5fb5d67f90d2e6d3267e794753575d9ab36bfe

data/CHANGELOG.md

@@ -3,6 +3,27 @@
 Notable changes to the fast-completions gem. The format is prose-first,
 one section per released version, newest first.
 
+## 0.4.0 (2026-10-14)
+
+- Strict-sampling tool schemas (pi constrained-sampling, JSON-schema half):
+  tools declare `constrained_sampling` — `false` (explicit opt-out) or
+  `{"type" => "json_schema", "strict" => "prefer"|"require"}`; any other
+  shape raises `ArgumentError` at declaration (grammar-constrained sampling
+  stays out of scope — `type: "grammar"` raises). On a dialect declaring
+  `supports_strict_mode`, a declared tool ships the strict rewrite of its
+  parameters — every property required, non-required null-less properties
+  wrapped in an `anyOf` of the property and `{"type": "null"}`,
+  `additionalProperties: false` appended — with `"strict": true` right after
+  `parameters`; every other function tool on a strict dialect ships
+  `"strict": false` with parameters verbatim (the declared Hash is never
+  mutated — the rewrite deep-copies); tools on non-strict dialects carry no
+  strict key ever, parameters verbatim. `"prefer"` falls back to verbatim
+  silently when the schema is unsupportable; `"require"` raises the new
+  `ConstrainedSamplingError` with pi's message templates. The Dialect
+  vocabulary grows to 14 keys (`supports_strict_mode`, default `false` —
+  OpenAI compatibility alone does not imply strict tool support); the
+  shipped `:zai` declares `true` (pi's glm compat).
+
 ## 0.3.0 (2026-10-15)
 
 - Mid-stream salvage: a failure after a 2xx status — a mid-body connection

data/lib/fast/completions/constrained_sampling.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Fast
+  module Completions
+    # JSON-schema constrained sampling (I63) — the strict rewrite that lets
+    # a declared tool ship forced property emission on a strict dialect.
+    # Port of pi packages/ai/src/api/constrained-sampling.ts @ f1b2e77f5
+    # (the JSON-schema half; the grammar half is deliberately NOT ported —
+    # nothing half-anticipates grammar). Message bytes are pi's literals
+    # verbatim: they are the parity observable. Check order inside
+    # make_json_schema_node_strict is pi's exactly — which message throws
+    # first is observable behavior.
+    module ConstrainedSampling
+      # pi constrained-sampling.ts :17-34 (16 keys — the frozen order IS
+      # the first-present-key-wins order). NOTE: the iteration Grounds say
+      # "20 keys"; pi's array holds 16 and the Grounds enumerate the same
+      # 16 in the same order — the count numeral in the brief is wrong,
+      # pi is the oracle.
+      UNSUPPORTED_STRICT_SCHEMA_KEYS = [
+        "$ref",
+        "$defs",
+        "definitions",
+        "allOf",
+        "oneOf",
+        "patternProperties",
+        "dependentSchemas",
+        "dependencies",
+        "unevaluatedProperties",
+        "propertyNames",
+        "contains",
+        "prefixItems",
+        "not",
+        "if",
+        "then",
+        "else",
+      ].freeze
+
+      module_function
+
+      # pi :156-178. `true` (strict) or `nil` (loose). Only
+      # UnsupportedStrictJsonSchemaError is caught — any other error
+      # propagates (pi's rethrow).
+      def resolve_json_schema_strict_sampling(tool, supports_strict_mode)
+        config = tool.constrained_sampling
+        return nil if config.nil? || config == false || config["type"] != "json_schema"
+
+        if supports_strict_mode
+          begin
+            make_strict_json_schema(tool.parameters)
+            return true
+          rescue UnsupportedStrictJsonSchemaError => reason
+            return nil if config["strict"] != "require" # silent loose fallback
+
+            raise ConstrainedSamplingError,
+              "Tool \"#{tool.name}\" requires JSON-schema constrained sampling, but #{reason.message}."
+          end
+        end
+        if config["strict"] == "require"
+          raise ConstrainedSamplingError,
+            "Tool \"#{tool.name}\" requires JSON-schema constrained sampling, but strict tools are unsupported."
+        end
+        nil
+      end
+
+      # pi makeStrictJsonSchema :137-151: deep-copy FIRST (the caller's
+      # schema — nested included — is never mutated), then the root arms
+      # use the root-specific message (differs from the nested
+      # "boolean schemas…" arm), then the root type must be "object".
+      def make_strict_json_schema(schema)
+        cloned = deep_copy(schema)
+        raise UnsupportedStrictJsonSchemaError, "root schema must have type object" unless cloned.is_a?(Hash)
+
+        make_json_schema_node_strict(cloned)
+        raise UnsupportedStrictJsonSchemaError, "root schema must have type object" unless cloned["type"] == "object"
+
+        cloned
+      end
+
+      # pi makeJsonSchemaNodeStrict :64-134, IN PLACE on the (cloned) node.
+      def make_json_schema_node_strict(node)
+        # JS isJsonSchemaObject: object, not null, not array. Everything
+        # else — booleans, null, arrays, scalars — throws here (a nil
+        # property value hits this arm: JS undefined equivalence).
+        raise UnsupportedStrictJsonSchemaError, "boolean schemas are unsupported" unless node.is_a?(Hash)
+
+        # JS `schema[key] !== undefined`: present-with-any-value (JSON null
+        # included) throws; Ruby key? is the exact equivalence.
+        UNSUPPORTED_STRICT_SCHEMA_KEYS.each do |key|
+          raise UnsupportedStrictJsonSchemaError, "#{key} schemas are unsupported" if node.key?(key)
+        end
+
+        # pi's optional isUnsupportedKeyword provider hook is NOT ported:
+        # pi's own call sites pass none (Recorded residual R2).
+
+        if node.key?("anyOf") # pi :76-89
+          raise UnsupportedStrictJsonSchemaError, "anyOf must contain at least one schema" if
+            !node["anyOf"].is_a?(Array) || node["anyOf"].empty?
+
+          node["anyOf"].each do |variant|
+            raise UnsupportedStrictJsonSchemaError, "object and array unions are unsupported" if structured_schema?(variant)
+
+            make_json_schema_node_strict(variant)
+          end
+        end
+
+        if node.key?("items") # pi :91-96
+          raise UnsupportedStrictJsonSchemaError, "tuple schemas are unsupported" if node["items"].is_a?(Array)
+
+          make_json_schema_node_strict(node["items"])
+        end
+
+        # JS `schema.type === "object"` — the string, strictly.
+        object_schema = node["type"] == "object"
+        if node.key?("properties") && !object_schema
+          raise UnsupportedStrictJsonSchemaError, "properties require type object"
+        end
+        return unless object_schema # non-object-typed nodes return here
+
+        # JS `!== false`: only exactly boolean false passes.
+        if node.key?("additionalProperties") && node["additionalProperties"] != false
+          raise UnsupportedStrictJsonSchemaError, "schema-valued or true additionalProperties is unsupported"
+        end
+        if node.key?("properties") && !node["properties"].is_a?(Hash)
+          raise UnsupportedStrictJsonSchemaError, "object properties must be a schema map"
+        end
+        if node.key?("required") &&
+            (!node["required"].is_a?(Array) || node["required"].any? { |key| !key.is_a?(String) })
+          raise UnsupportedStrictJsonSchemaError, "object required must be a string array"
+        end
+
+        properties = node.key?("properties") ? node["properties"] : {}
+        property_names = properties.keys
+        required = node.key?("required") ? node["required"] : []
+        if required.any? { |key| !property_names.include?(key) }
+          raise UnsupportedStrictJsonSchemaError, "required contains an unknown property"
+        end
+
+        properties.each do |key, property|
+          make_json_schema_node_strict(property)
+          if !required.include?(key) && !schema_allows_null(property)
+            # Reassignment keeps the key's hash position (JS and Ruby alike).
+            properties[key] = {"anyOf" => [property, {"type" => "null"}]}
+          end
+        end
+        node["required"] = property_names          # existing key keeps its position
+        node["additionalProperties"] = false       # absent key appends
+      end
+
+      # pi schemaAllowsNull :54-60. The const arm needs the key-present
+      # check: JS `schema.const === null` is false when the key is absent
+      # (undefined ≠ null); Ruby `hash["const"].nil?` alone would read an
+      # ABSENT const as null-allowing and skip the wrap.
+      def schema_allows_null(schema)
+        return false unless schema.is_a?(Hash)
+
+        type = schema["type"]
+        return true if type == "null" || (type.is_a?(Array) && type.include?("null"))
+        return true if schema.key?("const") && schema["const"].nil?
+        return true if schema["enum"].is_a?(Array) && schema["enum"].include?(nil)
+
+        schema["anyOf"].is_a?(Array) && schema["anyOf"].any? { |variant| schema_allows_null(variant) }
+      end
+
+      # pi isStructuredSchema :42-51.
+      def structured_schema?(schema)
+        return false unless schema.is_a?(Hash)
+
+        types =
+          if schema["type"].is_a?(String) then [schema["type"]]
+          elsif schema["type"].is_a?(Array) then schema["type"]
+          else []
+          end
+        types.include?("object") || types.include?("array") ||
+          schema.key?("properties") || schema.key?("items")
+      end
+
+      # structuredClone's role: fresh containers all the way down, so the
+      # rewrite (property wraps, required/additionalProperties writes)
+      # never reaches the declared Hash. Leaves (strings, numbers, booleans,
+      # nil) are immutable in Ruby — no copy needed; frozen strings dup
+      # clean by simply being carried over.
+      def deep_copy(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, val), copy| copy[key] = deep_copy(val) }
+        when Array then value.map { |val| deep_copy(val) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/fast/completions/dialects.rb

@@ -6,7 +6,7 @@ module Fast
     # the codec arms. Nothing here is provider detection, a catalog, or a
     # base-URL constant — the consumer declares, the codec obeys (§4).
     #
-    # The vocabulary is CLOSED to the 13 keys declared below. Unknown keys
+    # The vocabulary is CLOSED to the 14 keys declared below. Unknown keys
     # and unknown enum values raise ArgumentError AT DECLARATION TIME —
     # fail loud, never silently mistranslate (the no-universal-translation
     # discipline).
@@ -27,6 +27,9 @@ module Fast
         supports_thinking_token_budget: [false, nil],
         send_session_affinity_headers: [false, nil],
         session_affinity_format: [:openai, %i[openai openai_nosession openrouter].freeze],
+        # I63 (pi detectCompat :1675): OpenAI compatibility alone does not
+        # imply strict JSON-schema tool support — data, not detection.
+        supports_strict_mode: [false, nil],
       }.freeze
 
       attr_reader :name
@@ -154,6 +157,7 @@ module Fast
       supports_developer_role false
       supports_reasoning_effort true
       supports_store false
+      supports_strict_mode true # pi zai.json glm compat: supportsStrictMode:true
     end
 
     Dialects.declare(:deepseek) do

data/lib/fast/completions/errors.rb

@@ -61,6 +61,20 @@ module Fast
 
     class CancelledError < StandardError; end        # NOT < Error (D8)
 
+    # I63 constrained sampling (pi api/constrained-sampling.ts). INTERNAL:
+    # a tool schema outside the strict subset pi's makeStrictJsonSchema
+    # accepts — the reason bytes are pi's literals verbatim. Never escapes
+    # the resolver: "prefer" falls back to loose on it, "require" converts
+    # it to the public ConstrainedSamplingError (pi rethrows only other
+    # error classes).
+    class UnsupportedStrictJsonSchemaError < Error; end
+
+    # PUBLIC: a strict:"require" tool whose schema cannot be strict-rewritten,
+    # or that runs on a dialect without supports_strict_mode — pi's two
+    # message templates verbatim (the inner reason carries no trailing
+    # period; the template adds it).
+    class ConstrainedSamplingError < Error; end
+
     # Internal: error classification helpers (Specification §8).
     module Errors
       # pi utils/overflow.ts :33-96 — the FULL pattern list, ported

data/lib/fast/completions/protocol.rb

@@ -66,18 +66,32 @@ module Fast
       end
 
       # §9.8 / pi buildParams :853-863: tools iff declared (declaration
-      # order; parameters VERBATIM — the consumer's schema is the bytes);
-      # zai tool_stream right after; the `tools: []` fallback when tool
-      # history exists with no declared tools.
+      # order). Parameters stay VERBATIM — the consumer's schema is the
+      # bytes — EXCEPT the I63 strict arm: a tool declaring
+      # constrained_sampling on a strict dialect ships the strict REWRITE
+      # (pi convertTools :1505-1516, getJsonSchemaToolParameters) and the
+      # function object carries "strict" right after "parameters" (pi key
+      # order: name, description, parameters, strict) — declared-strict
+      # true, undeclared/loose false. VERBATIM remains the discipline for
+      # undeclared tools and non-strict dialects: no strict key ever there,
+      # and the emitted parameters are the declared object itself
+      # (object-identity emission). zai tool_stream right after; the
+      # `tools: []` fallback when tool history exists with no declared
+      # tools.
       def apply_tools(params, tools, messages, dialect)
         if tools.any?
+          strict_capable = dialect.supports_strict_mode
           params[:tools] = tools.map do |tool|
-            {"type" => "function",
-             "function" => {
-               "name" => tool.name,
-               "description" => tool.description,
-               "parameters" => tool.parameters,
-             }}
+            strict = ConstrainedSampling.resolve_json_schema_strict_sampling(tool, strict_capable)
+            function = {
+              "name" => tool.name,
+              "description" => tool.description,
+              "parameters" => strict == true ? ConstrainedSampling.make_strict_json_schema(tool.parameters) : tool.parameters,
+            }
+            # pi :1513 — the explicit key on EVERY function tool when the
+            # dialect supports strict mode ("Some reject unknown fields").
+            function["strict"] = strict || false if strict_capable
+            {"type" => "function", "function" => function}
           end
           params[:tool_stream] = true if dialect.zai_tool_stream
         elsif tool_history?(messages)

data/lib/fast/completions/tool.rb

@@ -25,12 +25,34 @@ module Fast
           end
           @parameters || {"type" => "object", "properties" => {}}
         end
+
+        # pi types.ts :736-754: constrainedSampling?: false |
+        # {type:"json_schema", strict:"prefer"|"require"}. Default nil
+        # (undeclared — no strict participation); false is the explicit
+        # opt-out, wire-equivalent to nil. ANY other shape raises here, at
+        # declaration time — fail loud, never silently mistranslate
+        # (unknown type — grammar included, the named exclusion — unknown
+        # strict value, missing keys, non-Hash values).
+        UNSET = Object.new.freeze # nil is NOT a passable value (raises below)
+
+        def constrained_sampling(config = UNSET)
+          return @constrained_sampling if config.equal?(UNSET)
+
+          unless config == false || (config.is_a?(Hash) &&
+              config["type"] == "json_schema" && %w[prefer require].include?(config["strict"]))
+            raise ArgumentError,
+              "constrained_sampling must be false or {\"type\" => \"json_schema\", " \
+              "\"strict\" => \"prefer\"|\"require\"}; got #{config.inspect}"
+          end
+          @constrained_sampling = config
+        end
       end
 
       # Instance readers forward to the class declaration.
       def description = self.class.description
       def tool_name = self.class.tool_name
       def parameters = self.class.parameters
+      def constrained_sampling = self.class.constrained_sampling
 
       # The wire name: the declared tool_name if set, else the class name (§11).
       def name

data/lib/fast/completions/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Completions
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/fast/completions.rb

@@ -11,6 +11,7 @@ require_relative "completions/types"
 require_relative "completions/dialects"
 require_relative "completions/sse"
 require_relative "completions/codec"
+require_relative "completions/constrained_sampling"
 require_relative "completions/protocol"
 require_relative "completions/client"
 require_relative "completions/tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-completions
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -38,6 +38,7 @@ files:
 - lib/fast/completions/chat.rb
 - lib/fast/completions/client.rb
 - lib/fast/completions/codec.rb
+- lib/fast/completions/constrained_sampling.rb
 - lib/fast/completions/dialects.rb
 - lib/fast/completions/errors.rb
 - lib/fast/completions/protocol.rb