ask-agent 0.4.7 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fefebee321ad33107e11e7c783845001e7fde3915929aa3c04530667472b296b
-  data.tar.gz: f5745683b396c62486b875ee82b27797a6feb20f729582591889e9ae432061f8
+  metadata.gz: 8a1f33fb0145ac0a1abf50990d15a6f4aa288a67fe8ec11f478cead3b9401a43
+  data.tar.gz: ebaa94902c33f6fe351b97108c6db085096a92ca4206706c8197cba5aaa5d8d5
 SHA512:
-  metadata.gz: 78905532187f65c8ba4d055398e8e3e9b9eaac62d02bbf001b934fccaadbd6dbb308677fb24387e6176c67398888dff25a9782279fd36c6ec07ddaa9c928b17b
-  data.tar.gz: 4dfa92ce9ddac07b363d085edcb6d55b7a493bced85c061d221e835c157598b87e9352de710b2a4fba495b01eea6915b82bbd6940b2e71463e5779ff6340c9d4
+  metadata.gz: 3a32c8330c3d443980a48df17507cdb4cfa56e67129f7e0fbabce12d9911705a621b85b60f7849ccd422496f46f2c3cc3e4f639cef11673f6530fbc5bd46480e
+  data.tar.gz: 2fd18590c038a8c1221c6422980aebff1edd38e634d53036cb231cae0eda36d15a9df8bcbb48cda146dd828670ebdbf10d9c88bc388b89e0f6fe65c8d7c3788e

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+## [0.5.0] — 2026-07-21
+
+### Added
+
+- **Middleware pipeline for LLM provider calls** — `Ask::Agent::Middleware::Pipeline` lets you wrap every `provider.chat(...)` call with cross-cutting behavior. Configured globally and automatically used by all `Chat` and `Session` instances.
+
+  ```ruby
+  Ask::Agent.configure do |c|
+    c.middleware.use :retry_on_failure, max_retries: 5
+    c.middleware.use :log_calls, logger: Rails.logger
+    c.middleware.use :default_settings, temperature: 0.7
+  end
+  ```
+
+  Three built-in middlewares:
+  - **`RetryOnFailure`** — Exponential backoff retry on `RateLimitError`, `ServerError`, and `ServiceUnavailable`. Does not retry on fatal errors (`Unauthorized`, `ModelNotFound`, `ConfigurationError`). Respects `retry_after` from provider responses.
+  - **`LogCalls`** — Logs every LLM call with model, tool count, message count, duration, and token usage. Custom logger support (defaults to `$stdout`).
+  - **`DefaultSettings`** — Injects default generation parameters (`temperature`, `max_tokens`, `top_p`, etc.) into the provider call request.
+
+  Custom middlewares extend `Ask::Agent::Middleware::Base` and override `#around_request`:
+
+  ```ruby
+  class MyMiddleware < Ask::Agent::Middleware::Base
+    def around_request(provider, request)
+      Rails.logger.info "Calling #{request[:model]}"
+      yield
+    end
+  end
+
+  Ask::Agent.configure { |c| c.middleware.use MyMiddleware }
+  ```
+
+- **Stream transform pipeline** — `Ask::Agent::StreamTransforms::Pipeline` processes each raw `Ask::Chunk` through a chain of transforms before yielding `ChatChunks` to the caller. Configured globally.
+
+  ```ruby
+  Ask::Agent.configure do |c|
+    c.stream_transforms.use :thinking_separator
+    c.stream_transforms.use :text_buffer, min_size: 100
+  end
+  ```
+
+  Three built-in transforms:
+  - **`ThinkingSeparator`** — Splits chunks that contain both `thinking` and visible `content` into two separate chunks, so you can handle thinking tokens independently.
+  - **`TextBuffer`** — Coalesces rapid text deltas into larger contiguous chunks (minimum configurable size). Reduces UI updates and log entries. Automatically flushes before non-content chunks and when the stream finishes.
+  - **`ExtractJson`** — Accumulates the streaming response and attempts to parse it as JSON. Provides `#extracted_json` and `#json?` accessors for post-stream inspection.
+
+  Custom transforms extend `Ask::Agent::StreamTransforms::Base` and override `#call`:
+
+  ```ruby
+  class FilterTransform < Ask::Agent::StreamTransforms::Base
+    def call(chunk, &block)
+      block.call(chunk) unless chunk.content == "drop_me"
+    end
+  end
+
+  Ask::Agent.configure { |c| c.stream_transforms.use FilterTransform }
+  ```
+
+### Changed
+
+- **`Ask::Agent::Configuration`** now exposes `#middleware` and `#stream_transforms` pipelines. Both are pre-initialized as empty pipelines — no breaking changes for existing users.
+- **`Ask::Agent::Chat`** reads middleware and stream transforms from global configuration on initialization. If configured, all provider calls go through the middleware chain and all stream chunks through the transform chain.
+- **Test helper** now includes local `ask-core`, `ask-auth`, `ask-instrumentation`, and `ask-llm-providers` in the load path so tests run against development code rather than installed gems.
+
 ## [0.4.5] — 2026-07-18
 
 ### Fixed

data/lib/ask/agent/chat.rb

@@ -24,6 +24,8 @@ module Ask
 
       attr_reader :messages
 
+      attr_writer :test_provider
+
       def initialize(model:, tools: [], temperature: nil, schema: nil, provider: nil, **)
         @model_id = model.respond_to?(:id) ? model.id : model.to_s
         @model_info = Ask::ModelCatalog.find(@model_id)
@@ -33,6 +35,11 @@ module Ask
         @messages = []
         @provider_override = provider
         @provider = nil
+
+        # Read configured middleware and stream transforms from global config
+        config = Ask::Agent.configuration
+        @middleware_pipeline = config.middleware.configured? ? config.middleware : nil
+        @transform_pipeline = config.stream_transforms.configured? ? config.stream_transforms : nil
       end
 
       def ask(message = nil, &block)
@@ -42,20 +49,7 @@ module Ask
         tool_defs = @tools.map { |t| Ask::ToolDef.from_tool(t) }
 
         calls_acc = {}
-
-        provider_model = @model_id
-        provider_tools = tool_defs
-        provider_temp = @temperature
-        provider_schema = @schema&.respond_to?(:to_json_schema) ? @schema.to_json_schema : @schema
-        provider_params = @extra_params || {}
-
-        result = chat_with_retry(stream, calls_acc, &block)
-
-        response_msg = if result.respond_to?(:chunks)
-          build_stream_response(result, calls_acc)
-        else
-          build_response(result)
-        end
+        response_msg = chat_with_retry(stream, calls_acc, &block)
 
         @messages << Ask::Message.new(
           role: :assistant,
@@ -104,10 +98,10 @@ module Ask
         @messages.clear
       end
 
-      attr_writer :test_provider
-
       private
 
+      MAX_CHAT_RETRIES = 3
+
       def provider
         @test_provider || @provider ||= build_provider
       end
@@ -119,11 +113,6 @@ module Ask
       end
 
       def provider_config(slug)
-        # Try credential names from most to least specific:
-        #   1. Flat key with full slug (opencode_go_api_key)
-        #   2. Nested path with full slug ([:opencode, :go, :api_key])
-        #   3. Flat key with base slug  (opencode_api_key)
-        #   4. Nested path with base slug ([:opencode, :api_key])
         slug_s = slug.to_s
         base_s = slug_s.include?("_") ? slug_s.split("_").first : nil
 
@@ -143,6 +132,115 @@ module Ask
         Ask::LLM::Config.new(config)
       end
 
+      # Build the request hash for the provider call.
+      # Middleware can mutate this hash to inject defaults, modify params, etc.
+      def build_request(stream)
+        {
+          messages: @messages.map(&:to_h),
+          model: @model_id,
+          tools: @tools.map { |t| Ask::ToolDef.from_tool(t) },
+          temperature: @temperature,
+          stream: stream,
+          schema: @schema&.respond_to?(:to_json_schema) ? @schema.to_json_schema : @schema,
+          extra_params: (@extra_params || {}).dup
+        }
+      end
+
+      # Dispatch a provider.chat(...) call. Uses the request hash that was
+      # already transformed by middleware (if any).
+      def call_provider(req, calls_acc, &block)
+        provider.chat(
+          req[:messages],
+          model: req[:model],
+          tools: req[:tools],
+          temperature: req[:temperature],
+          stream: req[:stream],
+          schema: req[:schema],
+          **req[:extra_params]
+        ) do |raw_chunk|
+          next unless block
+          process_chunk(raw_chunk, calls_acc, &block)
+        end
+      end
+
+      # Process a raw chunk through the stream transform pipeline (if configured),
+      # then yield ChatChunks to the caller's block.
+      def process_chunk(raw_chunk, calls_acc, &block)
+        if @transform_pipeline
+          # The transform chain will yield 0, 1, or many transformed chunks
+          wrapped = @transform_pipeline.wrap do |transformed|
+            accumulate_tool_calls(transformed, calls_acc)
+            block.call(ChatChunk.new(
+              content: transformed.content,
+              tool_calls: build_current_tool_calls(calls_acc),
+              thinking: transformed.respond_to?(:thinking) ? transformed.thinking : nil,
+              input_tokens: nil,
+              output_tokens: nil
+            ))
+          end
+          wrapped.call(raw_chunk)
+        else
+          accumulate_tool_calls(raw_chunk, calls_acc)
+          block.call(ChatChunk.new(
+            content: raw_chunk.content,
+            tool_calls: build_current_tool_calls(calls_acc),
+            thinking: raw_chunk.respond_to?(:thinking) ? raw_chunk.thinking : nil,
+            input_tokens: nil,
+            output_tokens: nil
+          ))
+        end
+      end
+
+      def chat_with_retry(stream, calls_acc, &block)
+        MAX_CHAT_RETRIES.times do |attempt|
+          begin
+            req = build_request(stream)
+
+            result = if @middleware_pipeline
+              @middleware_pipeline.invoke(provider, req) do
+                call_provider(req, calls_acc, &block)
+              end
+            else
+              call_provider(req, calls_acc, &block)
+            end
+
+            # Flush any buffered stream transforms (e.g. TextBuffer)
+            if block && @transform_pipeline
+              flush_transforms(&block)
+            end
+
+            return build_response_from_result(result, calls_acc, stream)
+          rescue Ask::RateLimitError => e
+            raise if attempt >= MAX_CHAT_RETRIES - 1
+
+            delay = e.retry_after || ((2**attempt) + rand(0.0..1.0))
+            sleep(delay)
+          end
+        end
+      end
+
+      # After the stream ends, flush any buffered state from transforms
+      # (e.g. TextBuffer's remaining buffer, pending metadata).
+      def flush_transforms(&block)
+        @transform_pipeline.flush do |chunk|
+          block.call(ChatChunk.new(
+            content: chunk.content,
+            tool_calls: {},
+            thinking: chunk.respond_to?(:thinking) ? chunk.thinking : nil,
+            input_tokens: nil,
+            output_tokens: nil
+          ))
+        end
+      end
+
+      def build_response_from_result(result, calls_acc, stream)
+        if result.respond_to?(:chunks)
+          build_stream_response(result, calls_acc)
+        else
+          build_response(result)
+        end
+      end
+
       def accumulate_tool_calls(raw_chunk, calls_acc)
         return unless raw_chunk.tool_call?
 
@@ -232,41 +330,6 @@ module Ask
         nil
       end
 
-      MAX_CHAT_RETRIES = 3
-
-      def chat_with_retry(stream, calls_acc, &block)
-        MAX_CHAT_RETRIES.times do |attempt|
-          begin
-            return provider.chat(
-              @messages.map(&:to_h),
-              model: @model_id,
-              tools: @tools.map { |t| Ask::ToolDef.from_tool(t) },
-              temperature: @temperature,
-              stream: stream,
-              schema: @schema&.respond_to?(:to_json_schema) ? @schema.to_json_schema : @schema,
-              **(@extra_params || {})
-            ) do |raw_chunk|
-              next unless block
-
-              accumulate_tool_calls(raw_chunk, calls_acc)
-
-              block.call(ChatChunk.new(
-                content: raw_chunk.content,
-                tool_calls: build_current_tool_calls(calls_acc),
-                thinking: raw_chunk.respond_to?(:thinking) ? raw_chunk.thinking : nil,
-                input_tokens: nil,
-                output_tokens: nil
-              ))
-            end
-          rescue Ask::RateLimitError => e
-            raise if attempt >= MAX_CHAT_RETRIES - 1
-
-            delay = e.retry_after || ((2 ** attempt) + rand(0.0..1.0))
-            sleep(delay)
-          end
-        end
-      end
-
       def emit_instrumentation(stream, response_msg)
         return unless defined?(Ask::Instrumentation)
 
@@ -277,7 +340,9 @@ module Ask
           output_tokens: response_msg.output_tokens,
           cost: response_msg.cost,
           tool_calls: response_msg.tool_call?,
-          stream: stream
+          stream: stream,
+          middleware: @middleware_pipeline&.configured?,
+          stream_transforms: @transform_pipeline&.configured?
         }.compact
 
         if stream

data/lib/ask/agent/configuration.rb

@@ -6,6 +6,12 @@ module Ask
       attr_accessor :default_model, :default_max_turns, :compactor_enabled,
                     :compactor_threshold, :parallel_tool_execution, :max_tool_retries
 
+      # @return [Middleware::Pipeline] the middleware pipeline for provider calls
+      attr_reader :middleware
+
+      # @return [StreamTransforms::Pipeline] the stream transforms pipeline
+      attr_reader :stream_transforms
+
       def initialize
         @default_model = "gpt-4o"
         @default_max_turns = 25
@@ -13,6 +19,9 @@ module Ask
         @compactor_threshold = 0.8
         @parallel_tool_execution = true
         @max_tool_retries = 3
+
+        @middleware = Middleware::Pipeline.new
+        @stream_transforms = StreamTransforms::Pipeline.new
       end
     end
   end

data/lib/ask/agent/middleware/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Middleware
+      # Base class for middleware that wraps LLM provider calls.
+      #
+      # Subclasses override {#around_request} to inject behavior before, after,
+      # or around the provider call. The default implementation yields to the
+      # next middleware in the chain (or the actual provider if this is the
+      # innermost wrapper).
+      #
+      # @example A logging middleware
+      #   class LogCalls < Base
+      #     def around_request(provider, request)
+      #       logger.info "LLM call: #{request[:model]}"
+      #       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      #       result = yield
+      #       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      #       logger.info "LLM call finished in #{elapsed.round(3)}s"
+      #       result
+      #     end
+      #   end
+      class Base
+        # Called before/after each provider.chat(...) call.
+        #
+        # @param provider [Object] the LLM provider instance
+        # @param request [Hash] the request parameters (:messages, :model, :tools, etc.)
+        # @yield call the next middleware (or the actual provider)
+        # @return [Object] the provider's response
+        def around_request(provider, request)
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/middleware/default_settings.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Middleware
+      # Injects default generation parameters for every LLM call.
+      #
+      # Settings are merged into the request – user-supplied values always take
+      # precedence (they appear in the original request hash and are preserved).
+      #
+      # @example
+      #   pipeline.use :default_settings, temperature: 0.5, max_tokens: 4096
+      class DefaultSettings < Base
+        # Settings that are safe to merge into the provider chat request.
+        ALLOWED_KEYS = %i[
+          temperature max_tokens top_p top_k stop_sequences
+          presence_penalty frequency_penalty seed
+        ].freeze
+
+        def initialize(**settings)
+          @settings = settings.select { |k, _v| ALLOWED_KEYS.include?(k) }
+        end
+
+        def around_request(provider, request)
+          return yield if @settings.empty?
+
+          merged = request.dup
+          @settings.each do |key, value|
+            merged[key] = value unless merged.key?(key)
+          end
+
+          # Re-invoke the chain with merged params.
+          # We override the request for downstream middleware but still yield
+          # to the original chain — the actual provider call in Chat#chat_with_retry
+          # uses the **(@extra_params || {}) merged into the provider call, so
+          # we must ensure our defaults are passed through.
+          #
+          # Instead of modifying the request shape, we inject defaults into
+          # the :extra_params key which Chat already merges into the provider call.
+          extra = (merged[:extra_params] || {}).merge(@settings) { |_k, orig, _default| orig }
+          merged[:extra_params] = extra
+
+          # Rebuild request to pass defaults through the chain
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/middleware/log_calls.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Middleware
+      # Logs LLM provider calls — request details, duration, token usage, and errors.
+      #
+      # Uses a configurable logger (defaults to `$stdout` via Ruby's `Logger`).
+      # Each call is logged at `INFO` level on success, `WARN` level on failure.
+      #
+      # @example
+      #   pipeline.use :log_calls, logger: Rails.logger
+      class LogCalls < Base
+        def initialize(logger: nil)
+          @logger = logger || default_logger
+        end
+
+        def around_request(provider, request)
+          model = request[:model]
+          tool_count = request[:tools]&.length.to_i
+          msg_count = request[:messages]&.length.to_i
+
+          @logger.info("[ask-agent] LLM call starting — model=#{model} tools=#{tool_count} messages=#{msg_count}")
+
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          begin
+            result = yield
+
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+            if result.respond_to?(:accumulated_usage)
+              usage = result.accumulated_usage
+              tokens = "#{usage[:input_tokens] || '?'}i / #{usage[:output_tokens] || '?'}o"
+              @logger.info("[ask-agent] LLM call completed — model=#{model} duration=#{elapsed.round(3)}s tokens=#{tokens}")
+            elsif result.respond_to?(:content)
+              @logger.info("[ask-agent] LLM call completed — model=#{model} duration=#{elapsed.round(3)}s content_length=#{result.content.to_s.length}")
+            else
+              @logger.info("[ask-agent] LLM call completed — model=#{model} duration=#{elapsed.round(3)}s")
+            end
+
+            result
+          rescue StandardError => e
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+            @logger.warn("[ask-agent] LLM call failed — model=#{model} duration=#{elapsed.round(3)}s error=#{e.class}(#{e.message})")
+            raise
+          end
+        end
+
+        private
+
+        def default_logger
+          require "logger"
+          Logger.new($stdout).tap { |l| l.formatter = ->(s, t, _p, msg) { "[#{t.strftime("%H:%M:%S")}] #{msg}\n" } }
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/middleware/pipeline.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Middleware
+      # A composable chain of middleware that wraps an LLM provider.
+      #
+      # Middleware are applied in order — the first middleware registered wraps
+      # the outermost layer and sees the request first.
+      #
+      # @example
+      #   pipeline = Pipeline.new
+      #   pipeline.use :retry_on_failure, max_retries: 5
+      #   pipeline.use :log_calls, logger: Rails.logger
+      #   pipeline.use :default_settings, temperature: 0.7
+      #
+      #   result = pipeline.invoke(provider, request) { provider.chat(**request) }
+      class Pipeline
+        KNOWN_MIDDLEWARES = {
+          retry_on_failure: "Ask::Agent::Middleware::RetryOnFailure",
+          log_calls: "Ask::Agent::Middleware::LogCalls",
+          default_settings: "Ask::Agent::Middleware::DefaultSettings"
+        }.freeze
+
+        def initialize
+          @entries = []
+        end
+
+        # Register a middleware in the chain.
+        #
+        # @param middleware [Symbol, Class] a symbol from KNOWN_MIDDLEWARES or a Middleware::Base subclass
+        # @param options [Hash] keyword arguments passed to the middleware's constructor
+        def use(middleware, **options)
+          klass = resolve(middleware)
+          @entries << { klass: klass, options: options }
+          self
+        end
+
+        # @return [Boolean] whether any middleware has been registered
+        def configured?
+          @entries.any?
+        end
+
+        # Iterate over the configured middleware entries.
+        def each(&block)
+          @entries.each(&block)
+        end
+
+        # Invoke the middleware chain around a provider call.
+        #
+        # Builds a chain of lambdas from the innermost (actual provider) outward,
+        # then invokes it. Each middleware's {Base#around_request} wraps the next
+        # link.
+        #
+        # @param provider [Object] the LLM provider
+        # @param request [Hash] the request parameters
+        # @yield the inner block that calls the provider
+        # @return [Object] the provider response
+        def invoke(provider, request)
+          inner = -> { yield }
+
+          chain = inner
+          @entries.reverse_each do |entry|
+            instance = entry[:klass].new(**entry[:options])
+            current = chain
+            chain = -> { instance.around_request(provider, request) { current.call } }
+          end
+
+          chain.call
+        end
+
+        private
+
+        def resolve(middleware)
+          case middleware
+          when Symbol
+            name = KNOWN_MIDDLEWARES[middleware]
+            raise ArgumentError, "Unknown middleware: #{middleware.inspect}" unless name
+
+            name.split("::").reduce(Object) { |mod, k| mod.const_get(k) }
+          when Class
+            unless middleware < Base
+              raise ArgumentError, "#{middleware} is not a Middleware::Base subclass"
+            end
+
+            middleware
+          else
+            raise ArgumentError, "Expected a Symbol or Class, got #{middleware.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/middleware/retry_on_failure.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Middleware
+      # Retries LLM provider calls on transient failures.
+      #
+      # Retries on:
+      # - {Ask::RateLimitError} with exponential backoff + jitter
+      # - {Ask::ServerError} (5xx) with exponential backoff
+      #
+      # Does NOT retry on:
+      # - {Ask::Unauthorized} — credentials are wrong, retrying won't help
+      # - {Ask::InvalidCredential} — same
+      # - {Ask::ModelNotFound} — model doesn't exist
+      # - {Ask::ConfigurationError} — user config issue
+      #
+      # @example
+      #   pipeline.use :retry_on_failure, max_retries: 5
+      class RetryOnFailure < Base
+        DEFAULT_MAX_RETRIES = 3
+
+        def initialize(max_retries: DEFAULT_MAX_RETRIES)
+          @max_retries = max_retries
+        end
+
+        def around_request(provider, request)
+          last_error = nil
+
+          @max_retries.times do |attempt|
+            begin
+              return yield
+            rescue Ask::RateLimitError => e
+              raise if attempt >= @max_retries - 1
+
+              delay = e.retry_after || compute_backoff(attempt)
+              sleep(delay)
+              last_error = e
+            rescue Ask::ServerError, Ask::ServiceUnavailable => e
+              raise if attempt >= @max_retries - 1
+
+              sleep(compute_backoff(attempt))
+              last_error = e
+            rescue Ask::Unauthorized, Ask::InvalidCredential,
+                   Ask::ModelNotFound, Ask::ConfigurationError
+              raise
+            end
+          end
+
+          raise last_error if last_error
+        end
+
+        private
+
+        def compute_backoff(attempt)
+          (2**attempt) + rand(0.0..1.0)
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/stream_transforms/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module StreamTransforms
+      # Base class for stream transforms that process {Ask::Chunk}s.
+      #
+      # Each transform receives every chunk from the LLM stream and can
+      # modify, filter, or buffer it. To emit zero or more transformed chunks,
+      # yield to the provided block.
+      #
+      # @example A simple pass-through transform
+      #   class NoOp < Base
+      #     def call(chunk, &block)
+      #       yield chunk
+      #     end
+      #   end
+      #
+      # @example A transform that drops thinking-only chunks
+      #   class DropThinking < Base
+      #     def call(chunk, &block)
+      #       yield chunk unless chunk.thinking? && chunk.content.to_s.empty?
+      #     end
+      #   end
+      class Base
+        # Process a single chunk from the LLM stream.
+        #
+        # @param chunk [Ask::Chunk] the raw chunk from the LLM provider
+        # @yield [Ask::Chunk] zero or more transformed chunks
+        def call(chunk, &block)
+          yield chunk
+        end
+
+        # Called once when the stream finishes, giving buffering transforms
+        # a chance to flush any remaining state. The default is a no-op.
+        #
+        # @yield [Ask::Chunk] final chunks to emit
+        def finish(&block)
+          # no-op
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/stream_transforms/extract_json.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    module StreamTransforms
+      # Attempts to parse JSON from a streaming LLM text response.
+      #
+      # When the LLM is instructed to return JSON but structured output
+      # (via schema) is not used, the model may emit text that happens
+      # to be valid JSON. This transform buffers the text, attempts a
+      # JSON parse on each addition, and emits a special chunk with
+      # the parsed data when valid JSON is found.
+      #
+      # This is useful for fallback scenarios where you want structured
+      # data without requiring native structured output support from the
+      # provider.
+      #
+      # @example
+      #   pipeline.use :extract_json
+      #
+      #   # The final chunk will have chunk.extracted_json if JSON was parsed.
+      class ExtractJson < Base
+        def initialize
+          @buffer = +""
+          @parsed = nil
+        end
+
+        def call(chunk, &block)
+          if chunk.content.to_s.strip.length > 0
+            @buffer << chunk.content
+
+            # Attempt to parse the accumulated buffer as JSON
+            begin
+              @parsed = JSON.parse(@buffer)
+            rescue JSON::ParserError
+              # Not valid JSON yet — keep buffering
+            end
+          end
+
+          # Pass the original chunk through
+          yield chunk
+        end
+
+        # @return [Hash, nil] the parsed JSON data, if the full response was valid JSON
+        def extracted_json
+          @parsed
+        end
+
+        # @return [Boolean] whether the accumulated response was valid JSON
+        def json?
+          !@parsed.nil?
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/stream_transforms/pipeline.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module StreamTransforms
+      # A composable chain of {Base} transforms applied to LLM stream chunks.
+      #
+      # Transforms are applied in order — the first registered transform sees
+      # each chunk first. Each transform may yield zero, one, or many chunks
+      # downstream.
+      #
+      # @example
+      #   pipeline = Pipeline.new
+      #   pipeline.use :thinking_separator
+      #   pipeline.use :text_buffer, min_size: 100
+      #
+      #   wrapped_block = pipeline.wrap { |chunk| handle_chunk(chunk) }
+      #   stream.each { |chunk| wrapped_block.call(chunk) }
+      #   pipeline.flush { |chunk| handle_chunk(chunk) }
+      class Pipeline
+        KNOWN_TRANSFORMS = {
+          thinking_separator: "Ask::Agent::StreamTransforms::ThinkingSeparator",
+          text_buffer: "Ask::Agent::StreamTransforms::TextBuffer",
+          extract_json: "Ask::Agent::StreamTransforms::ExtractJson"
+        }.freeze
+
+        def initialize
+          @transforms = []
+        end
+
+        # Register a transform in the chain.
+        #
+        # @param transform [Symbol, Class] a symbol from KNOWN_TRANSFORMS or a StreamTransforms::Base subclass
+        # @param options [Hash] keyword arguments passed to the transform's constructor
+        def use(transform, **options)
+          klass = resolve(transform)
+          @transforms << klass.new(**options)
+          self
+        end
+
+        # @return [Boolean] whether any transform has been registered
+        def configured?
+          @transforms.any?
+        end
+
+        # Iterate over the configured transform instances.
+        def each(&block)
+          @transforms.each(&block)
+        end
+
+        # Wrap a chunk-processing block with the transform chain.
+        #
+        # The returned block accepts raw {Ask::Chunk}s, runs them through
+        # each transform in sequence, and yields only to the original block
+        # for chunks that survive the chain.
+        #
+        # @yield [Ask::Chunk] transformed chunks
+        # @return [Proc] a wrapped block that accepts raw chunks
+        def wrap(&block)
+          return block unless configured?
+
+          chain = block
+          @transforms.reverse_each do |transform|
+            current = chain
+            chain = ->(chunk) { transform.call(chunk) { |c| current.call(c) } }
+          end
+          chain
+        end
+
+        # Flush any remaining buffered state from all transforms.
+        #
+        # Call this once when the stream finishes to ensure buffering
+        # transforms (e.g. TextBuffer) emit their final content.
+        #
+        # @yield [Ask::Chunk] final chunks
+        def flush(&block)
+          @transforms.each do |transform|
+            transform.finish { |c| block.call(c) if block }
+          end
+        end
+
+        private
+
+        def resolve(transform)
+          case transform
+          when Symbol
+            name = KNOWN_TRANSFORMS[transform]
+            raise ArgumentError, "Unknown stream transform: #{transform.inspect}" unless name
+
+            name.split("::").reduce(Object) { |mod, k| mod.const_get(k) }
+          when Class
+            unless transform < Base
+              raise ArgumentError, "#{transform} is not a StreamTransforms::Base subclass"
+            end
+
+            transform
+          else
+            raise ArgumentError, "Expected a Symbol or Class, got #{transform.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/stream_transforms/text_buffer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module StreamTransforms
+      # Buffers rapid text deltas into larger contiguous chunks.
+      #
+      # LLM streaming often produces many tiny deltas (1–5 characters each),
+      # especially over high-latency connections. This transform coalesces
+      # them into chunks of at least `min_size` characters, reducing the
+      # number of UI updates, log entries, or event emissions.
+      #
+      # Only text content is buffered. Non-content chunks (tool calls,
+      # finish signals, usage data) pass through immediately.
+      #
+      # @example Buffer until at least 100 characters
+      #   pipeline.use :text_buffer, min_size: 100
+      class TextBuffer < Base
+        def initialize(min_size: 50)
+          @min_size = min_size
+          @buffer = +""
+          @pending_usage = nil
+          @pending_finish = nil
+        end
+
+        def call(chunk, &block)
+          if chunk.content.to_s.strip.length > 0
+            @buffer << chunk.content
+
+            if @buffer.length >= @min_size
+              emit_buffer(&block)
+            end
+          else
+            # Flush buffer before non-content chunks
+            emit_buffer(&block)
+
+            # Track metadata to emit after flush
+            if chunk.finish_reason
+              @pending_finish = chunk.finish_reason
+            end
+            if chunk.usage
+              @pending_usage = chunk.usage
+            end
+
+            # Pass through non-content chunks (tool calls, etc.)
+            yield chunk
+          end
+        end
+
+        def finish(&block)
+          emit_buffer(&block) if @buffer.length > 0
+
+          # Emit pending metadata if any
+          if @pending_finish || @pending_usage
+            yield Ask::Chunk.new(
+              content: nil,
+              tool_calls: nil,
+              finish_reason: @pending_finish,
+              usage: @pending_usage,
+              raw: nil,
+              thinking: nil
+            )
+            @pending_finish = nil
+            @pending_usage = nil
+          end
+        end
+
+        private
+
+        def emit_buffer(&block)
+          return if @buffer.empty?
+
+          yield Ask::Chunk.new(
+            content: @buffer.dup,
+            tool_calls: nil,
+            finish_reason: nil,
+            usage: nil,
+            raw: nil,
+            thinking: nil
+          )
+          @buffer.clear
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/stream_transforms/thinking_separator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module StreamTransforms
+      # Separates thinking/reasoning content from visible text content in the
+      # stream. Useful when you want to handle thinking tokens separately
+      # (e.g., display them in a collapsible UI section or log them for
+      # debugging).
+      #
+      # Some LLM providers (notably Anthropic) send thinking content as
+      # separate chunks with both `content` and `thinking` fields populated.
+      # This transform splits those into two chunks: a thinking-only chunk
+      # (with the thinking content) and a text-only chunk (with the visible
+      # content), so downstream code can handle each independently.
+      #
+      # @example
+      #   pipeline.use :thinking_separator
+      #
+      #   # Now chunks arrive as:
+      #   #   chunk.content? && !chunk.thinking?  → visible text
+      #   #   chunk.thinking? && !chunk.content?  → thinking text
+      class ThinkingSeparator < Base
+        def call(chunk, &block)
+          if chunk.thinking? && chunk.content.to_s.strip.length > 0
+            # Split: emit thinking first, then content
+            yield Ask::Chunk.new(
+              content: nil,
+              tool_calls: nil,
+              finish_reason: nil,
+              usage: nil,
+              raw: nil,
+              thinking: chunk.thinking
+            )
+
+            yield Ask::Chunk.new(
+              content: chunk.content,
+              tool_calls: chunk.tool_calls,
+              finish_reason: chunk.finish_reason,
+              usage: chunk.usage,
+              raw: chunk.raw,
+              thinking: nil
+            )
+          elsif chunk.thinking? && chunk.content.to_s.strip.empty?
+            # Pure thinking chunk — pass through as-is
+            yield chunk
+          else
+            # No thinking — pass through
+            yield chunk
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.4.7"
+    VERSION = "0.5.0"
   end
 end

data/lib/ask/agent.rb

@@ -24,6 +24,22 @@ module Ask
       autoload :AuditLog, "ask/agent/extensions/audit_log"
     end
 
+    module Middleware
+      autoload :Base, "ask/agent/middleware/base"
+      autoload :Pipeline, "ask/agent/middleware/pipeline"
+      autoload :RetryOnFailure, "ask/agent/middleware/retry_on_failure"
+      autoload :LogCalls, "ask/agent/middleware/log_calls"
+      autoload :DefaultSettings, "ask/agent/middleware/default_settings"
+    end
+
+    module StreamTransforms
+      autoload :Base, "ask/agent/stream_transforms/base"
+      autoload :Pipeline, "ask/agent/stream_transforms/pipeline"
+      autoload :ThinkingSeparator, "ask/agent/stream_transforms/thinking_separator"
+      autoload :TextBuffer, "ask/agent/stream_transforms/text_buffer"
+      autoload :ExtractJson, "ask/agent/stream_transforms/extract_json"
+    end
+
     class << self
       def configuration
         @configuration ||= Configuration.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -144,11 +144,21 @@ files:
 - lib/ask/agent/hooks.rb
 - lib/ask/agent/loop.rb
 - lib/ask/agent/meta_agent.rb
+- lib/ask/agent/middleware/base.rb
+- lib/ask/agent/middleware/default_settings.rb
+- lib/ask/agent/middleware/log_calls.rb
+- lib/ask/agent/middleware/pipeline.rb
+- lib/ask/agent/middleware/retry_on_failure.rb
 - lib/ask/agent/persistence/base.rb
 - lib/ask/agent/persistence/in_memory.rb
 - lib/ask/agent/reflector.rb
 - lib/ask/agent/session.rb
 - lib/ask/agent/skills/load_skill_tool.rb
+- lib/ask/agent/stream_transforms/base.rb
+- lib/ask/agent/stream_transforms/extract_json.rb
+- lib/ask/agent/stream_transforms/pipeline.rb
+- lib/ask/agent/stream_transforms/text_buffer.rb
+- lib/ask/agent/stream_transforms/thinking_separator.rb
 - lib/ask/agent/telemetry.rb
 - lib/ask/agent/test.rb
 - lib/ask/agent/tool_abort_controller.rb