mistri 0.0.3 → 0.1.0

data/lib/mistri/partial_json.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Parses the JSON prefix a model has emitted so far, so in-flight tool-call
+  # arguments are readable before the closing brace arrives. Best effort by
+  # contract: never raises, drops a dangling key or half-written token, and
+  # returns {} for hopeless input.
+  module PartialJson
+    def self.parse(text)
+      s = text.to_s.strip
+      return {} if s.empty?
+
+      value = Parser.new(s).parse
+      value.equal?(Parser::NOTHING) ? {} : value
+    rescue StandardError, SystemStackError
+      {}
+    end
+
+    # Recursive descent over the prefix. Truncation trips @partial, and every
+    # frame unwinds keeping the structure built so far.
+    class Parser
+      NOTHING = Object.new
+      LITERALS = { "true" => true, "false" => false, "null" => nil }.freeze
+
+      # Nesting past this is treated as truncated: a model's real tool
+      # arguments never nest this deep, and the cap keeps a pathological input
+      # from overflowing the stack.
+      MAX_DEPTH = 256
+
+      def initialize(source)
+        @s = source
+        @n = source.length
+        @i = 0
+        @partial = false
+        @depth = 0
+      end
+
+      def parse = value
+
+      private
+
+      def value
+        skip_ws
+        return truncated if eof?
+
+        case @s[@i]
+        when '"' then string
+        when "{" then nested { object }
+        when "[" then nested { array }
+        else scalar
+        end
+      end
+
+      def nested
+        return truncated if @depth >= MAX_DEPTH
+
+        @depth += 1
+        begin
+          yield
+        ensure
+          @depth -= 1
+        end
+      end
+
+      def object
+        @i += 1
+        obj = {}
+        until @partial
+          skip_ws
+          break truncated if eof?
+          break @i += 1 if @s[@i] == "}"
+          break unless @s[@i] == '"'
+
+          key, val = pair
+          obj[key] = val unless key.equal?(NOTHING) || val.equal?(NOTHING)
+          skip_ws
+          @i += 1 if !eof? && @s[@i] == ","
+        end
+        obj
+      end
+
+      # One key/value. A truncation before the value completes the key's
+      # last-known state: mid-key or mid-separator drops the pair entirely.
+      def pair
+        key = string
+        return [NOTHING, NOTHING] if @partial
+
+        skip_ws
+        return [NOTHING, truncated] if eof?
+        return [NOTHING, NOTHING] unless @s[@i] == ":"
+
+        @i += 1
+        [key, value]
+      end
+
+      def array
+        @i += 1
+        arr = []
+        until @partial
+          skip_ws
+          break truncated if eof?
+          break @i += 1 if @s[@i] == "]"
+
+          element = value
+          arr << element unless element.equal?(NOTHING)
+          skip_ws
+          @i += 1 if !eof? && @s[@i] == ","
+        end
+        arr
+      end
+
+      def string
+        start = @i
+        @i += 1
+        escaped = false
+        while @i < @n
+          case
+          when escaped then escaped = false
+          when @s[@i] == "\\" then escaped = true
+          when @s[@i] == '"'
+            @i += 1
+            return decode(@s[start...@i])
+          end
+          @i += 1
+        end
+        truncated
+        salvage_string(@s[start..])
+      end
+
+      # Close an unterminated string, first shedding a half-written escape: a
+      # partial \uXXXX, or a lone trailing backslash. A backslash is only
+      # dangling when the trailing run of them is odd; an even run is complete
+      # escaped backslashes and must be kept.
+      def salvage_string(fragment)
+        candidate = fragment.sub(/\\u[0-9a-fA-F]{0,3}\z/, "")
+        trailing = candidate[/\\+\z/]
+        candidate = candidate[0..-2] if trailing&.length&.odd?
+        decode(%(#{candidate}"))
+      end
+
+      def scalar
+        start = @i
+        @i += 1 while @i < @n && !"},] \n\r\t".include?(@s[@i])
+        token = @s[start...@i]
+        # A structural character in value position: consume it so the caller's
+        # loop always makes progress.
+        return (@i += 1) && NOTHING if token.empty?
+
+        truncated if eof?
+        literal(token) { number(token) }
+      end
+
+      def literal(token)
+        return LITERALS[token] if LITERALS.key?(token)
+
+        if @partial
+          match = LITERALS.keys.find { |word| word.start_with?(token) }
+          return LITERALS[match] if match
+        end
+        yield
+      end
+
+      def number(token)
+        Integer(token)
+      rescue ArgumentError
+        begin
+          finite(Float(token))
+        rescue ArgumentError
+          trimmed_number(token)
+        end
+      end
+
+      # A number cut mid-token: shed the dangling exponent, decimal point, or
+      # bare minus and retry.
+      def trimmed_number(token)
+        trimmed = token.sub(/[eE][+-]?\z/, "").sub(/\.\z/, "")
+        return NOTHING if trimmed.empty? || trimmed == "-"
+
+        finite(Float(trimmed))
+      rescue ArgumentError
+        NOTHING
+      end
+
+      # A model that emits 1e999 yields Float::INFINITY, which JSON cannot
+      # generate, so it would crash replay and persistence. Drop it.
+      def finite(number)
+        number.finite? ? number : NOTHING
+      end
+
+      def decode(json_string)
+        JSON.parse(json_string)
+      rescue JSON::ParserError
+        NOTHING
+      end
+
+      def skip_ws
+        @i += 1 while @i < @n && " \n\r\t".include?(@s[@i])
+      end
+
+      def eof? = @i >= @n
+
+      def truncated
+        @partial = true
+        NOTHING
+      end
+    end
+  end
+end

data/lib/mistri/providers/anthropic/assembler.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    class Anthropic
+      # Folds the Messages API stream into the event union, building the
+      # assistant message block by block. Every emitted event carries an
+      # immutable snapshot of the message so far; in-flight tool arguments
+      # parse via PartialJson so consumers can read them mid-stream.
+      #
+      # Unknown event and block types are skipped by contract: the API adds
+      # types over time and a live stream must survive them.
+      class Assembler
+        def initialize(model:)
+          @model = model
+          @blocks = []
+          @current = nil
+          @usage = Usage.zero
+          @stop_reason = nil
+          @done = false
+        end
+
+        def feed(record, &)
+          case record["type"]
+          when "message_start" then @usage = parse_usage(record.dig("message", "usage"))
+          when "content_block_start" then start_block(record, &)
+          when "content_block_delta" then delta_block(record, &)
+          when "content_block_stop" then stop_block(record, &)
+          when "message_delta" then message_delta(record)
+          when "message_stop" then @done = true
+          when "error" then @error = wire_error(record["error"])
+          end
+        end
+
+        # Close the stream: the terminal event reflects how it ended. A stream
+        # that ended without message_stop was truncated (a dropped proxy, say),
+        # not user-aborted, so it fails for the loop to retry rather than
+        # reading as a cancellation.
+        def finish(&emit)
+          return fail_stream(@error, &emit) if @error
+          return fail_stream("stream ended without message_stop", &emit) unless @done
+
+          @message = assemble(stop_reason: @stop_reason || StopReason::STOP)
+          emit&.call(Event.new(type: :done, reason: @message.stop_reason, message: @message))
+          @message
+        end
+
+        def abort(&emit)
+          finalize_current
+          @message = assemble(stop_reason: StopReason::ABORTED, error_message: "aborted")
+          emit&.call(Event.new(type: :error, reason: StopReason::ABORTED, message: @message,
+                               error_message: "aborted"))
+          @message
+        end
+
+        # In-stream failures carry a wire type; overloaded ones must classify
+        # as retryable, not fold into prose.
+        def wire_error(payload)
+          message = payload&.dig("message") || "provider error"
+          klass = payload&.dig("type").to_s.include?("overloaded") ? OverloadedError : ProviderError
+          klass.new(message)
+        end
+
+        def fail_stream(reason, &emit)
+          finalize_current
+          text = case reason
+                 when ProviderError then "#{reason.class}: #{reason.describe}"
+                 when Exception then "#{reason.class}: #{reason.message}"
+                 else reason.to_s
+                 end
+          @message = assemble(stop_reason: StopReason::ERROR, error_message: text,
+                              error: ErrorData.for(reason))
+          emit&.call(Event.new(type: :error, reason: StopReason::ERROR, message: @message,
+                               error_message: text))
+          @message
+        end
+
+        def message = @message ||= finish
+
+        Builder = Struct.new(:kind, :index, :text, :json, :signature, :id, :name, :redacted)
+
+        private
+
+        def start_block(record, &)
+          block = record["content_block"] || {}
+          kind = { "text" => :text, "thinking" => :thinking, "redacted_thinking" => :thinking,
+                   "tool_use" => :toolcall }[block["type"]]
+          return unless kind
+
+          @current = Builder.new(kind, @blocks.size, +"", +"", nil,
+                                 block["id"], block["name"], block["type"] == "redacted_thinking")
+          @current.signature = block["data"] if @current.redacted
+          emit_event(:"#{kind}_start", content_index: @current.index, &)
+        end
+
+        def delta_block(record, &)
+          return unless @current
+
+          delta = record["delta"] || {}
+          case delta["type"]
+          when "text_delta" then text_delta(delta["text"], &)
+          when "thinking_delta" then thinking_delta(delta["thinking"], &)
+          when "signature_delta"
+            @current.signature = "#{@current.signature}#{delta["signature"]}"
+          when "input_json_delta" then input_delta(delta["partial_json"], &)
+          end
+        end
+
+        def text_delta(text, &)
+          @current.text << text.to_s
+          emit_event(:text_delta, content_index: @current.index, delta: text, &)
+        end
+
+        def thinking_delta(text, &)
+          @current.text << text.to_s
+          emit_event(:thinking_delta, content_index: @current.index, delta: text, &)
+        end
+
+        def input_delta(fragment, &)
+          @current.json << fragment.to_s
+          emit_event(:toolcall_delta, content_index: @current.index, delta: fragment, &)
+        end
+
+        def stop_block(_record, &)
+          return unless @current
+
+          block = finalize_current
+          kind = block.is_a?(ToolCall) ? :toolcall : block.type
+          fields = { content_index: @blocks.size - 1 }
+          fields[:tool_call] = block if block.is_a?(ToolCall)
+          fields[:content] = @blocks.last.is_a?(ToolCall) ? nil : builder_text(block)
+          emit_event(:"#{kind}_end", **fields.compact, &)
+        end
+
+        def message_delta(record)
+          reason = record.dig("delta", "stop_reason")
+          @stop_reason = map_stop_reason(reason) if reason
+          # message_delta usage is cumulative; merge output counts over the
+          # opening snapshot rather than summing.
+          output = record.dig("usage", "output_tokens")
+          @usage = @usage.with(output: output.to_i) if output
+        end
+
+        def finalize_current
+          return unless @current
+
+          built = build_block(@current)
+          @blocks << built
+          @current = nil
+          built
+        end
+
+        def build_block(builder)
+          case builder.kind
+          when :text then Content::Text.new(text: builder.text)
+          when :thinking
+            Content::Thinking.new(thinking: builder.text, signature: builder.signature,
+                                  redacted: builder.redacted)
+          when :toolcall
+            ToolCall.new(id: builder.id, name: builder.name,
+                         arguments: parsed_arguments(builder.json), signature: nil)
+          end
+        end
+
+        def parsed_arguments(json)
+          parsed = json.strip.empty? ? {} : PartialJson.parse(json)
+          parsed.is_a?(Hash) ? parsed : {}
+        end
+
+        def builder_text(block)
+          block.respond_to?(:text) ? block.text : block.thinking
+        end
+
+        def emit_event(type, **fields, &emit)
+          emit&.call(Event.new(type:, partial: assemble, **fields))
+        end
+
+        def assemble(**meta)
+          blocks = @blocks.dup
+          blocks << build_block(@current) if @current
+          Message.assistant(content: blocks, model: @model, provider: :anthropic,
+                            usage: @usage, **meta)
+        end
+
+        # pause_turn (a server tool paused a long turn) maps to tool_use so the
+        # loop continues the turn rather than ending it.
+        def map_stop_reason(reason)
+          { "end_turn" => StopReason::STOP, "stop_sequence" => StopReason::STOP,
+            "max_tokens" => StopReason::LENGTH, "tool_use" => StopReason::TOOL_USE,
+            "pause_turn" => StopReason::TOOL_USE }.fetch(reason, StopReason::STOP)
+        end
+
+        def parse_usage(raw)
+          return Usage.zero unless raw
+
+          cache_creation = raw["cache_creation"] || {}
+          Usage.new(input: raw["input_tokens"].to_i, output: raw["output_tokens"].to_i,
+                    cache_read: raw["cache_read_input_tokens"].to_i,
+                    cache_write: raw["cache_creation_input_tokens"].to_i,
+                    cache_write_1h: cache_creation["ephemeral_1h_input_tokens"].to_i)
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/anthropic/serializer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    class Anthropic
+      # Serializes protocol messages into Anthropic Messages API wire shapes.
+      #
+      # Wire rules that matter: consecutive tool results merge into one user
+      # turn (parallel tool calls demand their results together), thinking
+      # blocks replay with their signature and must never be altered, redacted
+      # thinking replays as its opaque payload, and cache_control marks the
+      # last system block and the last user message so the stable prefix and
+      # the growing history both cache.
+      module Serializer
+        module_function
+
+        def system_blocks(system, cache:)
+          return nil if system.nil? || system.empty?
+
+          blocks = [{ type: "text", text: system }]
+          blocks.last[:cache_control] = { type: "ephemeral" } if cache
+          blocks
+        end
+
+        def messages(history, cache: false)
+          turns = history.reject(&:system?).chunk_while { |a, b| a.tool? && b.tool? }
+          wire = turns.map do |group|
+            group.first.tool? ? tool_results(group) : message(group.first)
+          end
+          mark_last_user_turn(wire) if cache
+          wire
+        end
+
+        def tools(definitions)
+          definitions.map do |tool|
+            spec = tool.transform_keys(&:to_sym)
+            wire = { name: spec[:name], description: spec[:description],
+                     input_schema: spec[:input_schema] }
+            wire[:eager_input_streaming] = true if spec[:eager_input_streaming]
+            wire
+          end
+        end
+
+        def message(msg)
+          { role: msg.role.to_s, content: msg.content.filter_map { |block| block(block) } }
+        end
+
+        def tool_results(group)
+          { role: "user", content: group.map do |msg|
+            blocks = msg.content.filter_map { |block| block(block) }
+            # The API rejects an empty tool_result; a space stands in for a
+            # tool that returned nothing.
+            blocks = [{ type: "text", text: " " }] if blocks.empty?
+            { type: "tool_result", tool_use_id: msg.tool_call_id, content: blocks }
+          end }
+        end
+
+        # Returns nil for a block the API would reject (empty text, unusable
+        # thinking), so callers filter_map it out.
+        def block(block)
+          case block
+          when Content::Text then text_block(block)
+          when Content::Thinking then thinking_block(block)
+          when Content::Image
+            { type: "image",
+              source: { type: "base64", media_type: block.mime_type, data: block.data } }
+          when ToolCall
+            { type: "tool_use", id: block.id, name: block.name, input: block.arguments }
+          else
+            raise SchemaError, "cannot serialize #{block.class} for Anthropic"
+          end
+        end
+
+        # The API rejects empty text content blocks.
+        def text_block(block)
+          block.text.empty? ? nil : { type: "text", text: block.text }
+        end
+
+        # Thinking replays only with its signature. Redacted thinking carries
+        # its opaque payload; a normal thinking block missing its signature
+        # (an aborted turn cut before signature_delta) cannot replay, so it
+        # degrades to its text, or drops when even that is empty.
+        def thinking_block(block)
+          return { type: "redacted_thinking", data: block.signature } if block.redacted?
+          if block.signature
+            return { type: "thinking", thinking: block.thinking,
+                     signature: block.signature }
+          end
+
+          block.thinking.empty? ? nil : { type: "text", text: block.thinking }
+        end
+
+        def mark_last_user_turn(wire)
+          last_user = wire.rindex { |turn| turn[:role] == "user" }
+          return unless last_user
+
+          content = wire[last_user][:content]
+          return unless content.is_a?(Array) && content.any?
+
+          content.last[:cache_control] =
+            { type: "ephemeral" }
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/anthropic.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    # The Anthropic Messages API, streamed. Defaults target the current model
+    # generation: adaptive thinking with summarized display (so thinking
+    # streams for the UI), prompt caching on, 32k output headroom.
+    #
+    # Provider failures fold into the stream as an error turn rather than
+    # raising: the loop decides whether to retry, and the host always gets a
+    # message back.
+    class Anthropic
+      VERSION_HEADER = "2023-06-01"
+      DEFAULT_THINKING = { type: "adaptive", display: "summarized" }.freeze
+
+      # Messages API parameters passed through verbatim from a stream override.
+      PASSTHROUGH = %i[temperature top_p top_k stop_sequences metadata
+                       tool_choice service_tier].freeze
+      # The ceiling for an uncatalogued model: high enough for headroom, low
+      # enough that every current model accepts it. Catalog a model to unlock
+      # its real output limit.
+      UNKNOWN_MODEL_MAX_TOKENS = 64_000
+
+      def initialize(api_key:, model: "claude-opus-4-8", origin: "https://api.anthropic.com",
+                     max_tokens: nil, thinking: DEFAULT_THINKING, cache: true,
+                     **transport_options)
+        @api_key = api_key
+        @model = model
+        @max_tokens = max_tokens
+        @thinking = thinking
+        @cache = cache
+        @transport = Transport.new(origin: origin, **transport_options)
+      end
+
+      attr_reader :model
+
+      def stream(messages:, system: nil, tools: [], signal: nil, **overrides, &emit)
+        model = overrides.fetch(:model, @model)
+        assembler = Anthropic::Assembler.new(model: model)
+        body = build_body(model, messages, system, tools, overrides)
+        outcome = @transport.stream_post("/v1/messages", body: body, headers: headers,
+                                                         signal: signal) do |record|
+          assembler.feed(
+            record, &emit
+          )
+        end
+        outcome == :aborted ? assembler.abort(&emit) : assembler.finish(&emit)
+      rescue Error => e
+        assembler.fail_stream(e, &emit)
+      end
+
+      def close = @transport.close
+
+      private
+
+      def build_body(model, messages, system, tools, overrides)
+        body = {
+          model: model,
+          max_tokens: max_tokens_for(model, overrides),
+          stream: true,
+          messages: Serializer.messages(messages, cache: @cache)
+        }
+        system_blocks = Serializer.system_blocks(system, cache: @cache)
+        body[:system] = system_blocks if system_blocks
+        body[:tools] = Serializer.tools(tools) if tools.any?
+        thinking = thinking_for(model, overrides)
+        body[:thinking] = thinking if thinking
+        if (schema = overrides[:output_schema])
+          body[:output_config] = { format: { type: "json_schema",
+                                             schema: Schema.strict(schema) } }
+        end
+        body.merge(PASSTHROUGH.each_with_object({}) do |key, params|
+          params[key] = overrides[key] if overrides.key?(key)
+        end)
+      end
+
+      # Adaptive thinking 400s on budget-only models like Haiku 4.5, so the
+      # adaptive default is dropped for a model the catalog marks :budget; a
+      # host that wants thinking there passes an explicit budget config. An
+      # unknown model keeps the default, since new models are adaptive.
+      def thinking_for(model, overrides)
+        thinking = overrides.fetch(:thinking, @thinking)
+        return thinking unless thinking && thinking[:type] == "adaptive"
+        return nil if Models.thinking(model) == :budget
+
+        thinking
+      end
+
+      # The API requires max_tokens and bills only actual output, so the
+      # default is the model's own catalogued ceiling: full headroom, no
+      # silent truncation. An uncatalogued model falls back safely.
+      def max_tokens_for(model, overrides)
+        overrides.fetch(:max_tokens) do
+          @max_tokens || Models.max_output(model) || UNKNOWN_MODEL_MAX_TOKENS
+        end
+      end
+
+      def headers
+        { "x-api-key" => @api_key, "anthropic-version" => VERSION_HEADER }
+      end
+    end
+  end
+end
+
+require_relative "anthropic/serializer"
+require_relative "anthropic/assembler"