mistri 0.0.3 → 0.2.0

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"

data/lib/mistri/providers/fake.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Providers
+    # A scriptable provider: it streams each scripted turn as a well-formed
+    # event sequence and returns the assembled assistant message, so hosts test
+    # agent behavior hermetically while exercising real streaming semantics.
+    #
+    #   provider = Mistri::Providers::Fake.new(turns: [
+    #     { text: "Hello!" },
+    #     { tool_calls: [{ name: "search", arguments: { "q" => "ruby" } }] },
+    #   ])
+    #
+    # A turn may combine :thinking, :text, and :tool_calls, or carry :error to
+    # stream a failed turn. :stop_reason overrides the inferred reason.
+    class Fake
+      MODEL = "fake-1"
+
+      # Every #stream call is recorded here, so a test can assert what the
+      # agent actually sent.
+      attr_reader :requests
+
+      def model = MODEL
+
+      def initialize(turns: [], chunk_size: 12)
+        @turns = turns.map { |turn| turn.transform_keys(&:to_sym) }
+        @chunk_size = [chunk_size, 1].max
+        @requests = []
+      end
+
+      def stream(messages: [], **options, &emit)
+        # Snapshot the array: the loop appends replies to it in place.
+        @requests << { messages: messages.dup, options: }
+        turn = @turns.shift
+        raise ConfigurationError, "fake provider has no scripted turns left" unless turn
+
+        blocks = []
+        emit_event(emit, :start, blocks)
+        return finish_error(turn, blocks, emit) if turn[:error]
+
+        stream_block(:thinking, turn[:thinking], blocks, emit) if turn[:thinking]
+        stream_block(:text, turn[:text], blocks, emit) if turn[:text]
+        Array(turn[:tool_calls]).each_with_index do |call, position|
+          stream_tool_call(call, position, blocks, emit)
+        end
+        finish(turn, blocks, emit)
+      end
+
+      private
+
+      def stream_block(kind, full_text, blocks, emit)
+        index = blocks.size
+        emit_event(emit, :"#{kind}_start", blocks, content_index: index)
+        built = +""
+        full_text.scan(/.{1,#{@chunk_size}}/m) do |chunk|
+          built << chunk
+          emit_event(emit, :"#{kind}_delta", blocks + [build_block(kind, built)],
+                     content_index: index, delta: chunk)
+        end
+        blocks << build_block(kind, full_text)
+        emit_event(emit, :"#{kind}_end", blocks, content_index: index, content: full_text)
+      end
+
+      def build_block(kind, text)
+        kind == :text ? Content::Text.new(text:) : Content::Thinking.new(thinking: text)
+      end
+
+      def stream_tool_call(spec, position, blocks, emit)
+        spec = spec.transform_keys(&:to_sym)
+        call = ToolCall.new(id: spec[:id] || "call_#{position + 1}", name: spec[:name],
+                            arguments: (spec[:arguments] || {}).transform_keys(&:to_s))
+        index = blocks.size
+        emit_event(emit, :toolcall_start, blocks, content_index: index)
+        emit_event(emit, :toolcall_delta, blocks, content_index: index,
+                                                  delta: JSON.generate(call.arguments))
+        blocks << call
+        emit_event(emit, :toolcall_end, blocks, content_index: index, tool_call: call)
+      end
+
+      def finish(turn, blocks, emit)
+        reason = turn[:stop_reason] ||
+                 (blocks.any?(ToolCall) ? StopReason::TOOL_USE : StopReason::STOP)
+        message = assemble(blocks, usage: turn[:usage] || Usage.zero, stop_reason: reason)
+        emit&.call(Event.new(type: :done, reason:, message:))
+        message
+      end
+
+      def finish_error(turn, blocks, emit)
+        error = { "type" => turn.fetch(:error_type, "Error") }
+        error["status"] = turn[:status] if turn[:status]
+        message = assemble(blocks, usage: Usage.zero, stop_reason: StopReason::ERROR,
+                                   error_message: turn[:error], error: error)
+        emit&.call(Event.new(type: :error, reason: StopReason::ERROR, message:,
+                             error_message: turn[:error]))
+        message
+      end
+
+      def assemble(blocks, **meta)
+        Message.assistant(content: blocks, model: MODEL, provider: :fake, **meta)
+      end
+
+      def emit_event(emit, type, blocks, **fields)
+        emit&.call(Event.new(type:, partial: assemble(blocks), **fields))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Providers
+    class Gemini
+      # Folds streamGenerateContent records into the event union. Each record
+      # carries delta parts: plain text extends a text block, thought parts a
+      # thinking block, and a functionCall arrives whole, so its three events
+      # emit back to back. A kind switch closes the open block.
+      #
+      # Thought signatures ride on individual parts and are captured onto the
+      # block they arrived with, verbatim, for replay.
+      class Assembler
+        def initialize(model:)
+          @model = model
+          @blocks = []
+          @current = nil
+          @usage = Usage.zero
+          @finish_reason = nil
+        end
+
+        def feed(record, &)
+          if (error = record["error"])
+            @error = ProviderError.new(error["message"] || "provider error",
+                                       status: error["code"])
+            return
+          end
+
+          candidate = record.dig("candidates", 0) || {}
+          Array(candidate.dig("content", "parts")).each { |part| fold_part(part, &) }
+          @finish_reason = candidate["finishReason"] if candidate["finishReason"]
+          @usage = parse_usage(record["usageMetadata"]) if record["usageMetadata"]
+        end
+
+        # A stream that ended without a finishReason was truncated, not
+        # cancelled: fail it so the loop can treat it as retryable.
+        def finish(&emit)
+          return fail_stream(@error, &emit) if @error
+          return fail_stream("stream ended without a finish reason", &emit) unless @finish_reason
+
+          close_current(&emit)
+          @message = assemble(stop_reason: stop_reason)
+          emit&.call(Event.new(type: :done, reason: @message.stop_reason, message: @message))
+          @message
+        end
+
+        def abort(&)
+          close_current
+          terminal(StopReason::ABORTED, "aborted", &)
+        end
+
+        def fail_stream(reason, &)
+          close_current
+          text = case reason
+                 when ProviderError then "#{reason.class}: #{reason.describe}"
+                 when Exception then "#{reason.class}: #{reason.message}"
+                 else reason.to_s
+                 end
+          terminal(StopReason::ERROR, text, error: ErrorData.for(reason), &)
+        end
+
+        def message = @message ||= finish
+
+        Builder = Struct.new(:kind, :index, :text, :signature)
+
+        private
+
+        def fold_part(part, &)
+          if part.key?("functionCall")
+            fold_function_call(part, &)
+          elsif part.key?("text")
+            fold_text(part, part["thought"] ? :thinking : :text, &)
+          end
+        end
+
+        def fold_text(part, kind, &)
+          close_current(&) if @current && @current.kind != kind
+          unless @current
+            @current = Builder.new(kind, @blocks.size, +"", nil)
+            emit_event(:"#{kind}_start", content_index: @current.index, &)
+          end
+          @current.text << part["text"].to_s
+          @current.signature = part["thoughtSignature"] if part["thoughtSignature"]
+          delta_type = kind == :text ? :text_delta : :thinking_delta
+          emit_event(delta_type, content_index: @current.index, delta: part["text"], &)
+        end
+
+        # A function call arrives complete in one part: start, one delta with
+        # the full arguments, end.
+        def fold_function_call(part, &)
+          close_current(&)
+          call_spec = part["functionCall"] || {}
+          arguments = call_spec["args"].is_a?(Hash) ? call_spec["args"] : {}
+          call = ToolCall.new(id: call_spec["id"] || "call_#{@blocks.size + 1}",
+                              name: call_spec["name"], arguments: arguments,
+                              signature: part["thoughtSignature"])
+          index = @blocks.size
+          emit_event(:toolcall_start, content_index: index, &)
+          emit_event(:toolcall_delta, content_index: index,
+                                      delta: JSON.generate(arguments), &)
+          @blocks << call
+          emit_event(:toolcall_end, content_index: index, tool_call: call, &)
+        end
+
+        def close_current(&)
+          return unless @current
+
+          block = build_current
+          @blocks << block
+          kind = @current.kind
+          index = @current.index
+          @current = nil
+          emit_event(:"#{kind}_end", content_index: index,
+                                     content: kind == :text ? block.text : block.thinking, &)
+        end
+
+        def build_current
+          if @current.kind == :text
+            Content::Text.new(text: @current.text, signature: @current.signature)
+          else
+            Content::Thinking.new(thinking: @current.text, signature: @current.signature)
+          end
+        end
+
+        def stop_reason
+          return StopReason::TOOL_USE if @blocks.any?(ToolCall)
+          return StopReason::LENGTH if @finish_reason == "MAX_TOKENS"
+
+          StopReason::STOP
+        end
+
+        def terminal(reason, text, error: nil, &emit)
+          @message = assemble(stop_reason: reason, error_message: text, error: error)
+          emit&.call(Event.new(type: :error, reason: reason, message: @message,
+                               error_message: text))
+          @message
+        end
+
+        def emit_event(type, **fields, &emit)
+          emit&.call(Event.new(type:, partial: assemble, **fields))
+        end
+
+        def assemble(**meta)
+          blocks = @blocks.dup
+          blocks << build_current if @current
+          Message.assistant(content: blocks, model: @model, provider: :gemini,
+                            usage: @usage, **meta)
+        end
+
+        def parse_usage(raw)
+          prompt = raw["promptTokenCount"].to_i
+          cache_read = raw["cachedContentTokenCount"].to_i
+          reasoning = raw["thoughtsTokenCount"].to_i
+          Usage.new(input: [prompt - cache_read, 0].max,
+                    output: raw["candidatesTokenCount"].to_i + reasoning,
+                    cache_read: cache_read, reasoning: reasoning)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    class Gemini
+      # Serializes protocol messages into generateContent contents.
+      #
+      # Wire rules that matter: roles are user and model, consecutive tool
+      # results merge into one user turn of functionResponse parts, and
+      # thought signatures echo back verbatim on the exact part they arrived
+      # with, but only for messages this provider produced; a foreign
+      # signature would be rejected. Thinking summaries are output-only and
+      # never replay.
+      module Serializer
+        module_function
+
+        def contents(history)
+          groups = history.reject(&:system?).chunk_while { |a, b| a.tool? && b.tool? }
+          turns = groups.filter_map do |group|
+            group.first.tool? ? tool_turn(group) : turn(group.first)
+          end
+          merge_user_runs(turns)
+        end
+
+        # A steered run puts a user message right behind tool results, and
+        # both serialize as user turns. Gemini expects turns to alternate, so
+        # consecutive user turns merge into one.
+        def merge_user_runs(turns)
+          turns.chunk_while { |a, b| a[:role] == "user" && b[:role] == "user" }
+               .map do |run|
+            run.length == 1 ? run.first : { role: "user", parts: run.flat_map { |t| t[:parts] } }
+          end
+        end
+
+        def system_instruction(system)
+          return nil if system.nil? || system.empty?
+
+          { parts: [{ text: system }] }
+        end
+
+        def tools(definitions)
+          declarations = definitions.map do |tool|
+            spec = tool.transform_keys(&:to_sym)
+            { name: spec[:name], description: spec[:description],
+              parameters: spec[:input_schema] }
+          end
+          [{ functionDeclarations: declarations }]
+        end
+
+        def turn(msg)
+          parts = msg.assistant? ? assistant_parts(msg) : user_parts(msg)
+          return nil if parts.empty?
+
+          { role: msg.assistant? ? "model" : "user", parts: parts }
+        end
+
+        # Gemini pairs a functionResponse to its call by NAME; a wrong name
+        # silently mismatches, so a missing one fails loudly instead.
+        def tool_turn(group)
+          { role: "user", parts: group.map do |msg|
+            unless msg.tool_name
+              raise SchemaError, "Gemini tool results need tool_name to pair with their call"
+            end
+
+            { functionResponse: { name: msg.tool_name,
+                                  response: { "result" => result_text(msg) } } }
+          end }
+        end
+
+        # Non-text blocks in a tool result have no functionResponse encoding;
+        # note the omission rather than dropping it silently.
+        def result_text(msg)
+          omitted = msg.content.count { |block| !block.is_a?(Content::Text) }
+          text = msg.text.to_s
+          omitted.positive? ? "#{text}\n[#{omitted} non-text block(s) omitted]".strip : text
+        end
+
+        def user_parts(msg)
+          msg.content.map do |block|
+            case block
+            when Content::Text then { text: block.text }
+            when Content::Image
+              { inlineData: { mimeType: block.mime_type, data: block.data } }
+            else
+              raise SchemaError, "cannot serialize #{block.class} for Gemini user input"
+            end
+          end
+        end
+
+        def assistant_parts(msg)
+          own = msg.provider == :gemini
+          msg.content.filter_map do |block|
+            case block
+            when Content::Text then signed({ text: block.text }, block.signature, own)
+            when ToolCall
+              signed({ functionCall: { name: block.name, args: block.arguments } },
+                     block.signature, own)
+            end
+          end
+        end
+
+        def signed(part, signature, own)
+          part[:thoughtSignature] = signature if own && signature
+          part
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/gemini.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    # The Gemini API (v1beta generateContent), streamed over SSE and
+    # stateless: the full history replays every turn.
+    #
+    # Thinking is deliberately unconstrained: no budget, no level, only
+    # includeThoughts so summaries stream for the UI. The model's own defaults
+    # decide how much to think, and a host override passes through verbatim.
+    # maxOutputTokens is omitted for the same reason: the API defaults to the
+    # model's ceiling.
+    class Gemini
+      DEFAULT_THINKING = { includeThoughts: true }.freeze
+
+      def initialize(api_key:, model: "gemini-2.5-flash",
+                     origin: "https://generativelanguage.googleapis.com",
+                     thinking: DEFAULT_THINKING, **transport_options)
+        @api_key = api_key
+        @model = model
+        @thinking = thinking
+        @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 = Gemini::Assembler.new(model: model)
+        body = build_body(messages, system, tools, overrides)
+        path = "/v1beta/models/#{model}:streamGenerateContent?alt=sse"
+        outcome = @transport.stream_post(path, 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(messages, system, tools, overrides)
+        body = { contents: Serializer.contents(messages) }
+        instruction = Serializer.system_instruction(system)
+        body[:systemInstruction] = instruction if instruction
+        body[:tools] = Serializer.tools(tools) if tools.any?
+        config = {}
+        thinking = overrides.fetch(:thinking, @thinking)
+        config[:thinkingConfig] = thinking if thinking
+        # Constrained decoding combines with tools only on 3-series models
+        # (preview); with tools present the task loop's validate-and-fix
+        # pass carries the guarantee instead.
+        if (schema = overrides[:output_schema]) && tools.empty?
+          config[:responseMimeType] = "application/json"
+          config[:responseJsonSchema] = Schema.strict(schema)
+        end
+        body[:generationConfig] = config unless config.empty?
+        body
+      end
+
+      def headers
+        { "x-goog-api-key" => @api_key }
+      end
+    end
+  end
+end
+
+require_relative "gemini/serializer"
+require_relative "gemini/assembler"