anthropic 1.1.1 → 1.9.0

data/lib/anthropic/helpers/input_schema/json_schema_converter.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module InputSchema
+      # To customize the JSON schema conversion for a type, implement the `JsonSchemaConverter` interface.
+      module JsonSchemaConverter
+        # @api private
+        POINTERS = Object.new.tap do
+          _1.define_singleton_method(:inspect) do
+            "#<#{Anthropic::Helpers::InputSchema::JsonSchemaConverter}::POINTERS>"
+          end
+        end.freeze
+        # @api private
+        NO_REF = Object.new.tap do
+          _1.define_singleton_method(:inspect) do
+            "#<#{Anthropic::Helpers::InputSchema::JsonSchemaConverter}::NO_REF>"
+          end
+        end.freeze
+
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # The exact JSON schema produced is subject to improvement between minor release versions.
+        #
+        # @param state [Hash{Symbol=>Object}]
+        #
+        #   @option state [Hash{Object=>String}] :defs
+        #
+        #   @option state [Array<String>] :path
+        #
+        # @return [Hash{Symbol=>Object}]
+        def to_json_schema_inner(state:) = (raise NotImplementedError)
+
+        # rubocop:enable Lint/UnusedMethodArgument
+
+        # Internal helpers methods.
+        class << self
+          # @api private
+          #
+          # @param schema [Hash{Symbol=>Object}]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def to_nilable(schema)
+            null = "null"
+            case schema
+            in {"$ref": String} | {allOf: _}
+              # For references (simple or with allOf pattern for descriptions),
+              # wrap in anyOf with null. The allOf pattern is used when we need
+              # to add a description to a $ref (JSON Schema doesn't allow
+              # additional properties alongside $ref).
+              {anyOf: [schema, {type: null}]}
+            in {anyOf: schemas}
+              null = {type: null}
+              schemas.any? { _1 == null || _1 == {type: ["null"]} } ? schema : {anyOf: [*schemas, null]}
+            in {type: String => type}
+              type == null ? schema : schema.update(type: [type, null])
+            in {type: Array => types}
+              types.include?(null) ? schema : schema.update(type: [*types, null])
+            end
+          end
+
+          # @api private
+          #
+          # @param schema [Hash{Symbol=>Object}]
+          def assoc_meta!(schema, meta:)
+            xformed = meta.transform_keys(Anthropic::Helpers::InputSchema::PROPERTY_MAPPING)
+            schema.merge!(xformed)
+          end
+
+          # @api private
+          #
+          # @param state [Hash{Symbol=>Object}]
+          #
+          #   @option state [Hash{Object=>String}] :defs
+          #
+          #   @option state [Array<String>] :path
+          #
+          # @param type [Object]
+          #
+          # @param blk [Proc]
+          #
+          def cache_def!(state, type:, &blk)
+            defs, path = state.fetch_values(:defs, :path)
+            if (stored = defs[type])
+              pointers = stored.fetch(Anthropic::Helpers::InputSchema::JsonSchemaConverter::POINTERS)
+              pointers.first.except(Anthropic::Helpers::InputSchema::JsonSchemaConverter::NO_REF).tap do
+                pointers << _1
+              end
+            else
+              ref_path = String.new
+              ref = {"$ref": ref_path}
+              stored = {
+                Anthropic::Helpers::InputSchema::JsonSchemaConverter::POINTERS => [ref]
+              }
+              defs.store(type, stored)
+              schema = blk.call
+              ref_path.replace("#/$defs/#{path.join('/')}")
+              stored.update(schema)
+              ref
+            end
+          end
+
+          # @api private
+          #
+          # @param type [Anthropic::Helpers::InputSchema::JsonSchemaConverter, Class]
+          #
+          # @return [Hash{Symbol=>Object}]
+          def to_json_schema(type)
+            defs = {}
+            state = {defs: defs, path: []}
+            schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema_inner(
+              type,
+              state: state
+            )
+            reused_defs = {}
+            defs.each_value do |acc|
+              sch = acc.except(Anthropic::Helpers::InputSchema::JsonSchemaConverter::POINTERS)
+              pointers = acc.fetch(Anthropic::Helpers::InputSchema::JsonSchemaConverter::POINTERS)
+
+              no_refs, refs = pointers.partition do
+                _1.delete(Anthropic::Helpers::InputSchema::JsonSchemaConverter::NO_REF)
+              end
+
+              case refs
+              in [ref]
+                ref.replace(ref.except(:$ref).merge(sch))
+              in [_, ref, *]
+                reused_defs.store(ref.fetch(:$ref), sch)
+                refs.each do
+                  next if (meta = _1.except(:$ref)).empty?
+                  # JSON Schema does not allow keyword properties to be defined alongside a $ref.
+                  # If we have a keyword property associated with a $ref, it must be wrapped in an allOf.
+                  _1.replace(allOf: [_1.slice(:$ref), meta])
+                end
+              else
+              end
+              no_refs.each { _1.replace(_1.except(:$ref).merge(sch)) }
+            end
+
+            xformed = reused_defs.transform_keys { _1.delete_prefix("#/$defs/") }
+            xformed.empty? ? schema : {"$defs": xformed}.update(schema)
+          end
+
+          # @api private
+          #
+          # @param type [Anthropic::Helpers::InputSchema::JsonSchemaConverter, Class]
+          #
+          # @param state [Hash{Symbol=>Object}]
+          #
+          #   @option state [Hash{Object=>String}] :defs
+          #
+          #   @option state [Array<String>] :path
+          #
+          # @return [Hash{Symbol=>Object}]
+          def to_json_schema_inner(type, state:)
+            case type
+            in {"$ref": String}
+              return type
+            in Anthropic::Helpers::InputSchema::JsonSchemaConverter
+              return type.to_json_schema_inner(state: state)
+            in Class
+              case type
+              in -> { _1 <= NilClass }
+                return {type: "null"}
+              in -> { _1 <= Integer }
+                return {type: "integer"}
+              in -> { _1 <= Float }
+                return {type: "number"}
+              in -> { _1 <= Symbol || _1 <= String }
+                return {type: "string"}
+              else
+              end
+            in _ if Anthropic::Internal::Util.primitive?(type)
+              return {const: type.is_a?(Symbol) ? type.to_s : type}
+            else
+            end
+
+            models = %w[
+              NilClass
+              String
+              Symbol
+              Integer
+              Float
+              Anthropic::Boolean
+              Anthropic::ArrayOf
+              Anthropic::EnumOf
+              Anthropic::UnionOf
+              Anthropic::BaseModel
+            ]
+            # rubocop:disable Layout/LineLength
+            message = "#{type} does not implement the #{Anthropic::Helpers::InputSchema::JsonSchemaConverter} interface. Please use one of the supported types: #{models}"
+            # rubocop:enable Layout/LineLength
+            raise ArgumentError.new(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/anthropic/helpers/input_schema/parsed_json.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module InputSchema
+      # @abstract
+      #
+      # Like Anthropic::Internal::Type::Unknown, but for parsed JSON values, which can be incomplete or malformed.
+      class ParsedJson < Anthropic::Internal::Type::Unknown
+        class << self
+          # @api private
+          #
+          # No coercion needed for Unknown type.
+          #
+          # @param value [Object]
+          #
+          # @param state [Hash{Symbol=>Object}] .
+          #
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
+          #
+          #   @option state [Hash{Symbol=>Object}] :exactness
+          #
+          #   @option state [Class<StandardError>] :error
+          #
+          #   @option state [Integer] :branched
+          #
+          # @return [Object]
+          def coerce(value, state:)
+            (state[:error] = value) if value.is_a?(StandardError)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/anthropic/helpers/input_schema/property_mapping.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module InputSchema
+      # rubocop:disable Style/MutableConstant
+      PROPERTY_MAPPING = {
+        # Numeric properties:
+        minimum: :minimum,
+        maximum: :maximum,
+        exclusive_minimum: :exclusiveMinimum,
+        exclusive_maximum: :exclusiveMaximum,
+        multiple_of: :multipleOf,
+
+        # String properties:
+        min_length: :minLength,
+        max_length: :maxLength,
+        pattern: :pattern,
+        format: :format,
+        content_media_type: :contentMediaType,
+        content_encoding: :contentEncoding,
+
+        # Array properties:
+        min_items: :minItems,
+        max_items: :maxItems,
+        unique_items: :uniqueItems,
+        prefix_items: :prefixItems,
+        contains: :contains,
+        min_contains: :minContains,
+        max_contains: :maxContains,
+
+        # Object properties:
+        pattern_properties: :patternProperties,
+        dependent_schemas: :dependentSchemas,
+        dependent_required: :dependentRequired,
+        property_names: :propertyNames,
+
+        # Metadata:
+        default: :default,
+        examples: :examples,
+
+        doc: :description
+      }
+      # rubocop:enable Style/MutableConstant
+    end
+  end
+end

data/lib/anthropic/helpers/input_schema/union_of.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module InputSchema
+      # @generic Member
+      #
+      # @example
+      #   example = Anthropic::UnionOf[Float, Anthropic::ArrayOf[Integer]]
+      class UnionOf
+        include Anthropic::Internal::Type::Union
+        include Anthropic::Helpers::InputSchema::JsonSchemaConverter
+
+        # @api private
+        #
+        # @param state [Hash{Symbol=>Object}]
+        #
+        #   @option state [Hash{Object=>String}] :defs
+        #
+        #   @option state [Array<String>] :path
+        #
+        # @return [Hash{Symbol=>Object}]
+        def to_json_schema_inner(state:)
+          Anthropic::Helpers::InputSchema::JsonSchemaConverter.cache_def!(state, type: self) do
+            path = state.fetch(:path)
+            mergeable_keys = {[:anyOf] => 0, [:type] => 0}
+            schemas = variants.to_enum.with_index.map do
+              new_state = {**state, path: [*path, "?.#{_2}"]}
+              Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema_inner(
+                _1,
+                state: new_state
+              )
+            end
+
+            schemas.each do |schema|
+              mergeable_keys.each_key { mergeable_keys[_1] += 1 if schema.keys == _1 }
+            end
+            mergeable = mergeable_keys.any? { _1.last == schemas.length }
+            mergeable ? Anthropic::Internal::Util.deep_merge(*schemas, concat: true) : {anyOf: schemas}
+          end
+        end
+
+        private_class_method :new
+
+        def self.[](...) = new(...)
+
+        # @param variants [Array<generic<Member>>]
+        def initialize(*variants)
+          variants.each do |v|
+            v.is_a?(Proc) ? variant(v) : variant(-> { v })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/anthropic/helpers/input_schema.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    # Helpers for the structured output API.
+    #
+    # see https://platform.Anthropic.com/docs/guides/structured-outputs
+    # see https://json-schema.org
+    #
+    # Based on the DSL in {Anthropic::Internal::Type}, but currently only support the limited subset of JSON schema types used in structured output APIs.
+    #
+    # Supported types: {NilClass} {String} {Symbol} {Integer} {Float} {Anthropic::Boolean}, {Anthropic::EnumOf}, {Anthropic::UnionOf}, {Anthropic::ArrayOf}, {Anthropic::BaseModel}
+    module InputSchema
+    end
+  end
+end

data/lib/anthropic/helpers/streaming/events.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module Streaming
+      class TextEvent < Anthropic::Internal::Type::BaseModel
+        # @!attribute type
+        #
+        #   @return [Symbol, :text]
+        required :type, const: :text
+
+        # @!attribute text
+        #   The text delta received in this streaming event.
+        #
+        #   @return [String]
+        required :text, String
+
+        # @!attribute snapshot
+        #   The entire accumulated text up to this point in the stream.
+        #
+        #   @return [String]
+        required :snapshot, String
+      end
+
+      class CitationEvent < Anthropic::Internal::Type::BaseModel
+        # @!attribute type
+        #
+        #   @return [Symbol, :citation]
+        required :type, const: :citation
+
+        # @!attribute citation
+        #   The new citation received in this streaming event.
+        #
+        #   @return [Anthropic::Models::CitationCharLocation, Anthropic::Models::CitationPageLocation, Anthropic::Models::CitationContentBlockLocation, Anthropic::Models::CitationsWebSearchResultLocation]
+        required :citation, union: -> { Anthropic::CitationsDelta::Citation }
+
+        # @!attribute snapshot
+        #   All of the accumulated citations up to this point in the stream.
+        #
+        #   @return [Array<Anthropic::Models::CitationCharLocation, Anthropic::Models::CitationPageLocation, Anthropic::Models::CitationContentBlockLocation, Anthropic::Models::CitationsWebSearchResultLocation>]
+        required :snapshot,
+                 -> {
+                   Anthropic::Internal::Type::ArrayOf[union: Anthropic::CitationsDelta::Citation]
+                 }
+      end
+
+      class ThinkingEvent < Anthropic::Internal::Type::BaseModel
+        # @!attribute type
+        #
+        #   @return [Symbol, :thinking]
+        required :type, const: :thinking
+
+        # @!attribute thinking
+        #   The thinking delta received in this streaming event.
+        #
+        #   @return [String]
+        required :thinking, String
+
+        # @!attribute snapshot
+        #   The accumulated thinking content up to this point in the stream.
+        #
+        #   @return [String]
+        required :snapshot, String
+      end
+
+      class SignatureEvent < Anthropic::Internal::Type::BaseModel
+        # @!attribute type
+        #
+        #   @return [Symbol, :signature]
+        required :type, const: :signature
+
+        # @!attribute signature
+        #   The signature of the thinking block.
+        #
+        #   @return [String]
+        required :signature, String
+      end
+
+      class InputJsonEvent < Anthropic::Internal::Type::BaseModel
+        # @!attribute type
+        #
+        #   @return [Symbol, :input_json]
+        required :type, const: :input_json
+
+        # @!attribute partial_json
+        #   A partial JSON string delta received in this streaming event.
+        #
+        #   Example:
+        #   ```
+        #   "{'location':,"
+        #   ```
+        #
+        #   @return [String]
+        required :partial_json, String
+
+        # @!attribute snapshot
+        #   The currently accumulated parsed object up to this point in the stream.
+        #
+        #   Example:
+        #   ```
+        #   {'location': 'San Francisco, CA'}
+        #   ```
+        #
+        #   @return [Object]
+        required :snapshot, Anthropic::Internal::Type::Unknown
+      end
+
+      class MessageStopEvent < Anthropic::Models::RawMessageStopEvent
+        # @!attribute type
+        #
+        #   @return [Symbol, :message_stop]
+        required :type, const: :message_stop
+
+        # @!attribute message
+        #   The completed message when streaming ends.
+        #
+        #   @return [Anthropic::Models::Message]
+        required :message, Anthropic::Models::Message
+      end
+
+      class ContentBlockStopEvent < Anthropic::Models::RawContentBlockStopEvent
+        # @!attribute index
+        #   The index of the content block that has stopped streaming.
+        #
+        #   @return [Integer]
+        required :index, Integer
+
+        # @!attribute type
+        #
+        #   @return [Symbol, :content_block_stop]
+        required :type, const: :content_block_stop
+
+        # @!attribute content_block
+        #   The completed content block when streaming for this block ends.
+        #
+        #   @return [Anthropic::Models::TextBlock, Anthropic::Models::ToolUseBlock]
+        required :content_block, Anthropic::Models::ContentBlock
+      end
+    end
+  end
+end