protege 0.1.0.alpha.1

data/app/models/protege/responsibility.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Protege
+  # A persona's standing, cron-scheduled duty — the record behind the Loop layer (the "L" of LOGI).
+  #
+  # Where an inbound email drives the reactive path, a responsibility drives the *proactive* one: on
+  # its +schedule+ (a 5-field cron string) the Loop scheduler runs the owning persona's
+  # +responsibility_resolvers+ chain, seeded with this responsibility's +instructions+ as the opening user
+  # turn. The persona decides what to do from there (typically sending mail via +send_email+).
+  #
+  # Responsibilities are lean, dashboard-managed records — not a developer subclass; the per-persona
+  # resolver chain lives on the +Persona+, so a responsibility is just "which persona, what task, how
+  # often." Each execution is tracked by a +ResponsibilityRun+.
+  class Responsibility < ApplicationRecord
+    self.table_name = 'protege_responsibilities'
+
+    # ── Concerns ──────────────────────────────────────────────────────────────
+
+    # Keep the persona's Responsibilities sidebar live (append/replace/remove).
+    include BroadcastableResponsibility
+
+    # ── Associations ──────────────────────────────────────────────────────────
+
+    # The persona that carries out this duty; its +responsibility_resolvers+ chain assembles context
+    # and its identity is the enforced +From+ on any mail the run sends.
+    belongs_to :persona, class_name: 'Protege::Persona'
+
+    # Every execution of this responsibility, newest interesting for the dashboard; destroyed with it.
+    has_many :responsibility_runs,
+             class_name: 'Protege::ResponsibilityRun',
+             dependent:  :destroy,
+             inverse_of: :responsibility
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    with_options presence: true do
+      validates :name
+      validates :instructions
+      validates :schedule
+    end
+
+    validate :schedule_must_be_valid_cron
+
+    # ── Scopes ────────────────────────────────────────────────────────────────
+
+    default_scope { order(:name) }
+
+    # Only responsibilities currently enabled to fire.
+    scope :active, -> { where(active: true) }
+
+    # Only responsibilities whose persona is active (not archived) — archiving a persona stops its
+    # scheduled runs. The scheduler intersects this with {.active}.
+    scope :with_active_persona, -> { joins(:persona).merge(Protege::Persona.active) }
+
+    # ── Instance methods ────────────────────────────────────────────────────
+
+    # Whether this responsibility should fire at +time+ — active and its cron matches that minute.
+    # The scheduler calls this each tick (over the {.with_active_persona} set, so an archived persona's
+    # duties are already excluded); there is no precomputed next-run, only minute matching.
+    #
+    # @param time [Time] the moment to test (the tick's +Time.current+)
+    # @return [Boolean] true when due
+    def due?(time)
+      active? && Loop.schedule_due?(schedule, at: time)
+    end
+
+    # Enqueue a run of this responsibility. Records a +pending+ +ResponsibilityRun+ now — its
+    # +created_at+ marks enqueue time, so the later gap to the run's +started_at+ surfaces a backed-up
+    # queue — then hands off to +ResponsibilityJob+, which advances it to running and on to
+    # completed/failed. No timestamp is taken here: nothing has run yet (the job stamps +last_run_at+).
+    #
+    # The run's +correlation_id+ is minted here, at birth, and the worker adopts it — so the whole
+    # lifecycle (+loop_run_enqueued+ → +started+ → +completed+/+failed+) and the run row share one trace
+    # id. +Protege::Current+ is set so the enqueued event carries it.
+    #
+    # @return [Protege::ResponsibilityRun] the pending run that was enqueued
+    def dispatch!
+      run                             = responsibility_runs.create!(status: :pending, correlation_id: SecureRandom.uuid)
+      Protege::Current.correlation_id = run.correlation_id
+
+      LoopRunEnqueuedEvent.emit(name:, persona_name: persona.name)
+      ResponsibilityJob.perform_later(run_id: run.id)
+      run
+    end
+
+    private
+
+    # Reject a schedule that is not a parseable cron expression (presence is validated separately, so
+    # a blank value is left to that rule).
+    #
+    # @return [void]
+    def schedule_must_be_valid_cron
+      return if schedule.blank?
+
+      errors.add(:schedule, 'is not a valid cron expression') unless Loop.schedule_valid?(schedule)
+    end
+  end
+end

data/app/models/protege/responsibility_run.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Protege
+  # One execution of a +Responsibility+ — the Loop layer's run-state record and audit trail.
+  #
+  # The scheduler creates a run +pending+ and enqueues a +ResponsibilityJob+; the job marks it
+  # +running+ (stamping +started_at+) and then +completed+ or +failed+ (stamping +finished_at+ and, on
+  # failure, the error class and message). The dashboard reads these rows to show a responsibility's
+  # recent history.
+  class ResponsibilityRun < ApplicationRecord
+    self.table_name = 'protege_responsibility_runs'
+
+    # ── Associations ──────────────────────────────────────────────────────────
+
+    belongs_to :responsibility,
+               class_name: 'Protege::Responsibility',
+               inverse_of: :responsibility_runs
+
+    # Tool calls+results the agent recorded during this scheduled run — an audit trail beside the run's
+    # own status; destroyed with the run.
+    has_many :tool_uses, as: :source, class_name: 'Protege::ToolUse', dependent: :destroy
+
+    # ── Status ────────────────────────────────────────────────────────────────
+
+    # Lifecycle of a run. String-backed (matching +AccessRule+'s enum convention) so the stored value
+    # reads plainly in the database and dashboard.
+    enum :status, {
+      pending:   'pending',
+      running:   'running',
+      completed: 'completed',
+      failed:    'failed'
+    }
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    # Mark this run as running now: stamp +started_at+, snapshot the current correlation id (minted by
+    # the job, so the run row links to the events it emits), and keep the responsibility's denormalised
+    # +last_run_at+ fresh (it is running, so the responsibility has just run) — mirroring how +Message+
+    # keeps its thread's counters current.
+    #
+    # @return [void]
+    def start!
+      now = Time.current
+      update!(status: :running, started_at: now, correlation_id: Protege::Current.correlation_id)
+      responsibility.update!(last_run_at: now)
+    end
+
+    # Mark this run completed, stamping +finished_at+.
+    #
+    # @return [void]
+    def mark_completed!
+      update!(status: :completed, finished_at: Time.current)
+    end
+
+    # Mark this run failed, recording the error class and message and stamping +finished_at+.
+    #
+    # @param error [Exception] the failure to record
+    # @return [void]
+    def mark_failed!(error)
+      update!(
+        status:        :failed,
+        finished_at:   Time.current,
+        error_class:   error.class.name,
+        error_message: error.message
+      )
+    end
+  end
+end

data/app/models/protege/tool_use.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Protege
+  # One tool call the agent made and the result it got back, recorded during a run so a run's tool
+  # activity is durable. During a single run the calls/results live only in the in-memory
+  # +Provider::Request+; persisting them here gives two things: a reply run's tool use can be replayed by
+  # +ThreadHistoryResolver+ on later turns (as real +:assistant+/+:tool+ messages, so the agent remembers
+  # what it searched, fetched, or read), and a scheduled run's tool use is captured for audit beside the
+  # +ResponsibilityRun+ status trail.
+  #
+  # The owning record is polymorphic +source+: a +Protege::Message+ for a reply run (the triggering
+  # inbound message) or a +Protege::ResponsibilityRun+ for a scheduled run. A row pairs a call with its
+  # result (the tool loop produces them 1:1). +run_id+ groups one harness run, +turn_index+ the
+  # tool-calling round within it, and +position+ the order within a round (an assistant turn may request
+  # several calls at once). +tool_call_id+ correlates the call to its result when history is replayed.
+  # +persona_id+ is denormalized for per-persona queries.
+  class ToolUse < ApplicationRecord
+    # Upper bound on a stored +arguments+/+result+ JSON payload, so a huge tool result (e.g. a large
+    # +web_fetch+ body) can't bloat the row. Replay truncates further still (see +#replay_result+).
+    STORED_PAYLOAD_LIMIT = 16_000
+
+    # Marker appended to any payload clipped for length.
+    TRUNCATION_MARKER = '…[truncated]'
+
+    # ── Associations ────────────────────────────────────────────────────────
+
+    belongs_to :source,  polymorphic: true
+    belongs_to :persona, class_name: 'Protege::Persona'
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    with_options presence: true do
+      validates :tool_name
+      validates :turn_index
+      validates :position
+    end
+
+    # ── Scopes ────────────────────────────────────────────────────────────────
+
+    # Replay order: by run, then round, then call position within the round.
+    scope :in_replay_order, -> { order(:run_id, :turn_index, :position) }
+
+    # ── Instance methods ──────────────────────────────────────────────────────
+
+    # Rebuild the provider tool call for structured replay.
+    #
+    # @return [Protege::Inference::Provider::ToolCall] the call as the model originally emitted it
+    def to_provider_tool_call
+      Protege::Inference::Provider::ToolCall.new(
+        id:    tool_call_id,
+        name:  tool_name,
+        input: arguments.present? ? JSON.parse(arguments) : {}
+      )
+    end
+
+    # The stored result, truncated for replay so past results never dominate the context window.
+    #
+    # @param limit [Integer] maximum characters of result to replay
+    # @return [String] the (possibly truncated) result JSON text
+    def replay_result(limit:)
+      self.class.clip(result.to_s, limit:)
+    end
+
+    # ── Class methods ───────────────────────────────────────────────────────
+
+    class << self
+      # Record one tool-calling round: one row per call, paired index-for-index with its result (the
+      # tool loop builds +tool_calls+ and +tool_results+ in the same order).
+      #
+      # **Atomic:** the whole round is written in a single transaction, so a serialization or validation
+      # failure on one call rolls the whole round back rather than leaving a half-written round (which
+      # would replay as an +:assistant+ with unmatched +tool_calls+ and break the next provider request).
+      # The transaction wraps **only these inserts** — it is entered after the tools have run and exits
+      # before the next inference call, so no provider request is ever made inside an open transaction.
+      #
+      # **Idempotent:** rows are keyed by +[source, run_id, turn_index, position]+, so re-recording a
+      # round (e.g. when the job retries after a transient provider error, replaying the same +run_id+)
+      # finds the existing rows instead of duplicating them.
+      #
+      # @param source [Protege::Message, Protege::ResponsibilityRun] the run's owning record
+      # @param persona [Protege::Persona] the persona handling the run
+      # @param run_id [String, nil] id grouping this harness run
+      # @param turn_index [Integer] the tool-calling round within the run (0-based)
+      # @param tool_calls [Array<Protege::Inference::Provider::ToolCall>] the calls the model requested
+      # @param tool_results [Array<Protege::ToolResult>] the paired results
+      # @return [Array<Protege::ToolUse>] the recorded rows
+      def record_round(source:, persona:, run_id:, turn_index:, tool_calls:, tool_results:)
+        transaction do
+          tool_calls.each_with_index.map do |call, position|
+            result = tool_results[position]
+            find_or_create_by!(source:, run_id:, turn_index:, position:) do |use|
+              use.persona      = persona
+              use.tool_call_id = call.id
+              use.tool_name    = call.name
+              use.arguments    = clip(call.input.to_json, limit: STORED_PAYLOAD_LIMIT)
+              use.result       = clip(result.result.to_h.to_json, limit: STORED_PAYLOAD_LIMIT)
+              use.succeeded    = result.result.success?
+            end
+          end
+        end
+      end
+
+      # Clip a string to +limit+ characters, appending {TRUNCATION_MARKER} when it had to be cut.
+      #
+      # @param text [String] the text to clip
+      # @param limit [Integer] the maximum length before truncation
+      # @return [String] the original text, or a truncated copy with the marker
+      def clip(text, limit:)
+        return text if text.length <= limit
+
+        "#{text[0, limit - TRUNCATION_MARKER.length]}#{TRUNCATION_MARKER}"
+      end
+    end
+  end
+end

data/app/models/protege/trace.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Protege
+  # A durable, self-contained snapshot of one inference turn (one provider API call), captured for later
+  # fine-tuning when tracing is enabled. Each row is a training example in the making: the exact
+  # +request+ as sent (the wire conversation — resolved system prompt, history, user turn, tool catalog,
+  # attachment bytes inline) paired with the +response+ it produced and the inference settings
+  # (+model+ + +settings+) that shaped it, frozen at that instant — unlike +ToolUse+, which stores only
+  # enough to *replay* against the *current* prompts.
+  #
+  # Deliberately **isolated and minimal**: no associations, no foreign keys, and no identity columns
+  # (persona/provider) — a trace records only what affects training, plus a human review verdict. The
+  # table can be truncated or dropped without touching anything else. +correlation_id+ + +turn_index+
+  # group the turns of one run for retry-safe dedup. Written only by the tracing subscriber
+  # (+Protege::Subscribers::Tracing+); reviewed and labeled in the dashboard.
+  class Trace < ApplicationRecord
+    # The request/response/settings snapshots are stored as JSON text (SQLite has no native JSON type),
+    # the same coder convention +Message+ uses for its address lists.
+    with_options coder: JSON do
+      serialize :request
+      serialize :response
+      serialize :settings
+    end
+
+    # Human review verdict on the turn's quality — the label a fine-tuning corpus is filtered by. Backed
+    # by strings (matching the engine's enum convention), defaulting to +unlabeled+ until a reviewer acts.
+    enum :label, { unlabeled: 'unlabeled', good: 'good', bad: 'bad', neutral: 'neutral' }, default: 'unlabeled'
+
+    # ── Scopes ────────────────────────────────────────────────────────────────
+    #
+    # The label enum supplies the per-verdict scopes (+unlabeled+/+good+/+bad+/+neutral+) the review
+    # filter selects from; these add ordering and the "any verdict applied" queue.
+
+    # Newest first — the review view's default order.
+    scope :recent, -> { order(created_at: :desc) }
+
+    # Turns a human has judged, whatever the verdict (the complement of the enum's +unlabeled+ scope).
+    scope :reviewed, -> { where.not(label: 'unlabeled') }
+
+    # ── Instance methods ──────────────────────────────────────────────────────
+
+    # Apply a human review verdict — the label plus an optional free-text note — stamping the review time
+    # so the turn leaves the {unlabeled} queue.
+    #
+    # @param label [String, Symbol] one of the {label} values
+    # @param annotation [String, nil] a free-text reviewer note
+    # @return [void]
+    def apply_label(label:, annotation: nil)
+      update!(label:, annotation:, reviewed_at: Time.current)
+    end
+
+    class << self
+      # Record one turn's snapshot. Idempotent on +[correlation_id, turn_index]+ so a retried job (which
+      # replays the same run from turn 0) re-snapshots each turn in place rather than duplicating training
+      # rows — the same retry-safety +ToolUse.record_round+ provides. When no correlation id is present
+      # (a run kind that carries none), rows can't be keyed for dedup, so each call simply inserts.
+      #
+      # @param correlation_id [String, nil] the id grouping this run's turns
+      # @param turn_index [Integer] this generation's turn index within the run
+      # @param attributes [Hash] the snapshot columns (model, settings, request, response)
+      # @return [Protege::Trace] the recorded row
+      def record(correlation_id:, turn_index:, **attributes)
+        return create!(correlation_id:, turn_index:, **attributes) if correlation_id.blank?
+
+        find_or_create_by!(correlation_id:, turn_index:) do |trace|
+          trace.assign_attributes(attributes)
+        end
+      end
+    end
+  end
+end

data/app/providers/protege/open_router_provider.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'net/http'
+require 'uri'
+
+module Protege
+  # Built-in OpenRouter provider. Hits OpenRouter's OpenAI-compatible /chat/completions endpoint.
+  # Model selection lives in the Request model field so one configured OpenRouter instance
+  # dispatches across every model OpenRouter routes to.
+  #
+  # Plugs into Protege by subclassing +Protege::Provider+ and registering under
+  # +protege_id :openrouter+, so it satisfies the +Protege::Inference::Provider+ contract
+  # (+generate+ and +generate_stream+) that the harness drives. Activated when
+  # +config.provider_id = :openrouter+.
+  #
+  # Auth and endpoint come from this provider's slice of +config.providers+ — +:api_key+ and
+  # +:base_url+ under the +:openrouter+ key — resolved lazily on first request, so construction never
+  # touches them and the built-in is harmless when unused. The host sets both in the Protege
+  # initializer (typically defaulted to ENV vars there; the provider itself does not read ENV).
+  class OpenRouterProvider < Protege::Provider
+    protege_id :openrouter
+
+    # Run a blocking, non-streaming completion.
+    #
+    # @param request [Hash] the request hash (messages + tools; see the providers doc)
+    # @return [Hash] the response hash (content + tool_calls + finish_reason)
+    # @raise [Protege::Error] on a non-2xx HTTP status
+    def generate(request)
+      response = http_client.post('chat/completions') do |req|
+        req.body = build_payload(request).to_json
+      end
+
+      raise_for_status(response)
+      parse_response(JSON.parse(response.body))
+    end
+
+    # Run a streaming completion over SSE.
+    #
+    # Streams tokens as they arrive: text deltas are yielded to +block+ as
+    # +{ type: :text, content: ... }+ hashes, tool-call deltas are accumulated, and the final
+    # assembled response hash is returned once the stream closes.
+    #
+    # @param request [Hash] the request hash (messages + tools; see the providers doc)
+    # @yieldparam chunk [Hash] a +{ type: :text, content: String }+ token chunk
+    # @return [Hash] the response hash (content + tool_calls + finish_reason)
+    def generate_stream(request, &block)
+      payload     = build_payload(request).merge(stream: true)
+      accumulator = { text_parts: [], tool_calls: {}, finish_reason: nil }
+
+      stream_chat_completion(payload) do |line|
+        process_stream_line(line, accumulator, &block)
+      end
+
+      build_stream_response(accumulator)
+    end
+
+    # The sampling settings this provider applies beyond the model — the same knobs merged into the
+    # wire payload — surfaced for tracing. Overrides the mixin default so a trace records the
+    # generation settings that shaped the output.
+    #
+    # @return [Hash] the temperature/max-tokens settings in effect (nils dropped)
+    def settings
+      { temperature:, max_tokens: max_output_tokens }.compact
+    end
+
+    private
+
+    # The configured API key, resolved lazily here (never at construction, so the unused built-in
+    # is harmless). The host sets it in the initializer — typically defaulted to an ENV var.
+    #
+    # @return [String] the bearer token
+    # @raise [Protege::UnauthorizedError] when no key is configured
+    def api_key
+      options[:api_key] ||
+        raise(Protege::UnauthorizedError,
+              'OpenRouter api_key is not configured — set ' \
+              'config.providers[:openrouter][:api_key] in the Protege initializer')
+    end
+
+    # The configured base URL (set in the initializer, typically defaulted to an ENV var).
+    #
+    # @return [String] the API base URL
+    # @raise [Protege::UnauthorizedError] when no base URL is configured
+    def base_url
+      options[:base_url] ||
+        raise(Protege::UnauthorizedError,
+              'OpenRouter base_url is not configured — set ' \
+              'config.providers[:openrouter][:base_url] in the Protege initializer')
+    end
+
+    # The configured sampling temperature, or +nil+ to defer to the model's own default.
+    #
+    # @return [Float, nil] the temperature
+    def temperature
+      options[:temperature]
+    end
+
+    # The configured output-token cap, or +nil+ to defer to the model's own default.
+    #
+    # @return [Integer, nil] the max output tokens
+    def max_output_tokens
+      options[:max_output_tokens]
+    end
+
+    # This provider's options Hash from the Protege config, keyed by its own +protege_id+
+    # (+:openrouter+). Empty when the host hasn't configured this provider.
+    #
+    # @return [Hash] the +:openrouter+ slice of +config.providers+ (or +{}+)
+    def options
+      Protege.configuration.provider_options(self.class.id)
+    end
+
+    # Open the SSE connection and yield each complete response line as it arrives.
+    #
+    # Owns the Net::HTTP lifecycle and the chunk-to-line buffering so the caller only sees whole,
+    # stripped lines.
+    #
+    # @param payload [Hash] the request body (already merged with +stream: true+)
+    # @yieldparam line [String] one stripped line of the SSE response body
+    # @return [void]
+    def stream_chat_completion(payload)
+      uri  = URI.join("#{base_url}/", 'chat/completions')
+      http = build_stream_http(uri)
+      post = build_stream_post(uri, payload)
+
+      http.request(post) do |response|
+        buffer = ''
+
+        response.read_body do |chunk|
+          buffer += chunk
+
+          while (line_end = buffer.index("\n"))
+            yield buffer.slice!(0..line_end).strip
+          end
+        end
+      end
+    end
+
+    # Construct the Net::HTTP transport for an SSE request.
+    #
+    # @param uri [URI] the fully resolved chat-completions endpoint
+    # @return [Net::HTTP] the configured (TLS-aware) transport
+    def build_stream_http(uri)
+      http         = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http
+    end
+
+    # Construct the SSE POST request with auth and streaming headers.
+    #
+    # @param uri [URI] the endpoint whose path the POST targets
+    # @param payload [Hash] the JSON-serializable request body
+    # @return [Net::HTTP::Post] the prepared POST request
+    def build_stream_post(uri, payload)
+      post                  = Net::HTTP::Post.new(uri.path)
+      post['Authorization'] = "Bearer #{api_key}"
+      post['Content-Type']  = 'application/json'
+      post['Accept']        = 'text/event-stream'
+      post.body             = payload.to_json
+      post
+    end
+
+    # Parse one SSE line and fold its delta into the streaming accumulator.
+    #
+    # Skips keep-alive blanks, the terminal +[DONE]+ sentinel, and non-+data:+ lines. For a valid
+    # delta it records the finish reason (first wins), streams text to +block+, and merges any
+    # tool-call fragments.
+    #
+    # @param line [String] one stripped SSE line
+    # @param accumulator [Hash] mutable state with +:text_parts+, +:tool_calls+, +:finish_reason+
+    # @yieldparam chunk [Hash] a +{ type: :text, content: String }+ token chunk
+    # @return [void]
+    def process_stream_line(line, accumulator, &)
+      return if line.empty? || line == 'data: [DONE]'
+      return unless line.start_with?('data: ')
+
+      data  = JSON.parse(line.delete_prefix('data: '))
+      delta = data.dig('choices', 0, 'delta')
+      return unless delta
+
+      accumulator[:finish_reason] ||= data.dig('choices', 0, 'finish_reason')
+
+      accumulate_text(delta, accumulator, &)
+      accumulate_tool_calls(delta, accumulator)
+    end
+
+    # Append a text delta to the accumulator and stream it to the caller.
+    #
+    # @param delta [Hash] the choice delta from one SSE event
+    # @param accumulator [Hash] mutable state whose +:text_parts+ is appended to
+    # @yieldparam chunk [Hash] a +{ type: :text, content: String }+ token chunk
+    # @return [void]
+    def accumulate_text(delta, accumulator)
+      return unless delta['content']
+
+      accumulator[:text_parts] << delta['content']
+      yield({ type: :text, content: delta['content'] })
+    end
+
+    # Merge tool-call fragments from a delta into the accumulator by index.
+    #
+    # Tool calls stream incrementally: name and argument strings arrive in pieces across events
+    # and are concatenated per +index+; the id is set once seen.
+    #
+    # @param delta [Hash] the choice delta from one SSE event
+    # @param accumulator [Hash] mutable state whose +:tool_calls+ map is updated
+    # @return [void]
+    def accumulate_tool_calls(delta, accumulator)
+      return unless delta['tool_calls']
+
+      tool_calls = accumulator[:tool_calls]
+
+      delta['tool_calls'].each do |tc|
+        idx                                       = tc['index']
+        tool_calls[idx]                         ||= { 'id' => nil,
+                                                      'function' => { 'name' => '', 'arguments' => '' } }
+        tool_calls[idx]['id']                     = tc['id'] if tc['id']
+        tool_calls[idx]['function']['name']      += tc.dig('function', 'name').to_s
+        tool_calls[idx]['function']['arguments'] += tc.dig('function', 'arguments').to_s
+      end
+    end
+
+    # Assemble the final +Response+ from accumulated streaming state.
+    #
+    # @param accumulator [Hash] state with +:text_parts+, +:tool_calls+, +:finish_reason+
+    # @return [Hash] the response hash with joined text, the accumulated tool calls, and finish reason
+    def build_stream_response(accumulator)
+      {
+        content:       accumulator[:text_parts].join.presence,
+        tool_calls:    wire_tool_calls(accumulator[:tool_calls].values),
+        finish_reason: accumulator[:finish_reason]
+      }
+    end
+
+    # Build (and memoize) the Faraday client for non-streaming requests.
+    #
+    # @return [Faraday::Connection] the configured HTTP client
+    def http_client
+      @http_client ||= Faraday.new(url: base_url) do |c|
+        c.headers['Authorization'] = "Bearer #{api_key}"
+        c.headers['Content-Type']  = 'application/json'
+      end
+    end
+
+    # Build the OpenRouter chat-completions body: the standard request hash Protege hands in (messages
+    # + tools) plus this provider's model and sampling. Nil fields are dropped. Enforces model presence
+    # here — a missing model is a misconfiguration that surfaces on first use, not at construction (the
+    # mixin's +#model+ reader is intentionally soft).
+    #
+    # @param request [Hash] the request hash (messages + tools)
+    # @return [Hash] the compacted request payload
+    # @raise [Protege::ContractViolationError] when no model is configured
+    def build_payload(request)
+      model.presence ||
+        raise(Protege::ContractViolationError,
+              'OpenRouter model is not configured — set ' \
+              'config.providers[:openrouter][:model] in the Protege initializer')
+
+      request.merge(
+        model:,
+        temperature:,
+        max_tokens:  max_output_tokens
+      ).compact
+    end
+
+    # Map a non-2xx HTTP status onto the matching +Protege::Error+.
+    #
+    # @param response [Faraday::Response] the HTTP response to inspect
+    # @return [nil] when the status is 2xx
+    # @raise [Protege::Error] the error class matching the status code
+    def raise_for_status(response)
+      case response.status
+      when 200..299 then nil
+      when 400      then raise Protege::BadRequestError,   response.body
+      when 401      then raise Protege::UnauthorizedError, response.body
+      when 429      then raise Protege::RateLimitedError,  response.body
+      when 500..599 then raise Protege::UnavailableError,  response.body
+      else               raise Protege::InternalError,
+                               "HTTP #{response.status}: #{response.body}"
+      end
+    end
+
+    # Parse a non-streaming response body into the response hash Protege expects
+    # (+{ content:, tool_calls:, finish_reason: }+ — the OpenAI assistant message + finish reason,
+    # symbol-keyed with tool-call arguments left as JSON strings).
+    #
+    # @param body [Hash] the decoded JSON response body
+    # @return [Hash] the response hash
+    # @raise [Protege::ResponseParseFailedError] when no choice is present
+    def parse_response(body)
+      choice  = body.dig('choices', 0) || raise(Protege::ResponseParseFailedError, body.to_s)
+      message = choice.fetch('message')
+
+      {
+        content:       message['content'],
+        tool_calls:    wire_tool_calls(message['tool_calls']),
+        finish_reason: choice['finish_reason']
+      }
+    end
+
+    # Normalize the API's (string-keyed) tool_calls into the function-call wire shape Protege parses:
+    # +{ id:, type: 'function', function: { name:, arguments: <JSON string> } }+.
+    #
+    # @param raw [Array<Hash>, nil] the message's +tool_calls+ from the API
+    # @return [Array<Hash>] the wire tool calls (empty when none)
+    def wire_tool_calls(raw)
+      Array(raw).map do |tc|
+        {
+          id:       tc['id'],
+          type:     'function',
+          function: { name: tc.dig('function', 'name'), arguments: tc.dig('function', 'arguments') }
+        }
+      end
+    end
+  end
+end