protege 0.1.0.alpha.1

data/lib/protege/inference/provider/request.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Protege
+  module Inference
+    module Provider
+      # One normalized generation request handed to a provider's +#generate+ method — the conversation
+      # only: the ordered messages plus the tool schemas to expose. Model, sampling, and credentials are
+      # not carried here; each provider reads those from its own +config.providers+ slice.
+      #
+      # +messages+ is the complete ordered message array for this
+      # generation call — resolver context messages (role: :system,
+      # :user, :assistant) prepended by the harness, followed by the
+      # current inbound as a +:user+ message. Providers handle
+      # role: :system messages according to their API requirements
+      # (OpenRouter normalises for all underlying models; a direct
+      # Anthropic provider would extract system messages into its
+      # top-level +system:+ parameter).
+      #
+      # == Wire serialization
+      #
+      # +#to_wire+ renders the request into the standard (OpenAI-compatible) +{ messages:, tools: }+
+      # body. This lives here — not on each provider — because it is the *same* serialization the API
+      # call needs and a trace needs: +OpenRouterProvider#generate+ builds its payload by merging
+      # model/sampling onto +to_wire+, and the tracing subscriber snapshots +to_wire+ directly. Keeping
+      # it in one place means a trace records the exact conversation that was sent, never a re-derivation.
+      Request = Data.define(
+        :messages,
+        :tools
+      ) do
+        # @param messages [Array<Protege::ModelMessage>] the ordered message array for this generation call
+        # @param tools [Array<Protege::Inference::Tool>] the tools available to the model (default empty)
+        def initialize(messages:, tools: [])
+          super
+        end
+
+        # Render this request as the standard chat-completions body: the serialized message array and the
+        # function-tool schemas. Model, sampling, and credentials are the provider's to add.
+        #
+        # @return [Hash] +{ messages: Array<Hash>, tools: Array<Hash> }+ (tools omitted when none)
+        def to_wire
+          {
+            messages: messages.map { |message| wire_message(message) },
+            tools:    tools.presence&.map { |tool| wire_tool(tool) }
+          }.compact
+        end
+
+        private
+
+        # Serialize one message: role, content (a joined string when all-text, else typed blocks), and
+        # any tool linkage (an assistant turn's +tool_calls+, a tool result's +tool_call_id+).
+        #
+        # @param message [Protege::ModelMessage] the message to serialize
+        # @return [Hash] the wire message
+        def wire_message(message)
+          body                = { role: message.role.to_s, content: wire_content(message.parts) }
+          body[:tool_call_id] = message.tool_call_id if message.tool_call_id
+          body[:tool_calls]   = message.tool_calls.map(&:to_wire) if message.tool_calls
+          body
+        end
+
+        # Render message parts as content: a plain joined string when every part is text (the common
+        # case), otherwise an array of typed content blocks for a multimodal message.
+        #
+        # @param parts [Array<Object>] the normalized message parts
+        # @return [String, Array<Hash>] joined text, or an array of content blocks
+        def wire_content(parts)
+          return parts.map(&:text).join if parts.all?(TextPart)
+
+          parts.map { |part| wire_part(part) }
+        end
+
+        # Serialize one content part into a typed content block, with attachment bytes inline as a data
+        # URI (so the request — and any trace of it — is self-contained).
+        #
+        # @param part [Object] a TextPart, ImagePart, or DocumentPart
+        # @return [Hash] the typed content block (+text+, +image_url+, or +file+)
+        def wire_part(part)
+          case part
+          when TextPart
+            { type: 'text', text: part.text }
+          when ImagePart
+            { type: 'image_url', image_url: { url: data_uri(part.media_type, part.data) } }
+          when DocumentPart
+            { type: 'file', file: { filename: part.filename, file_data: data_uri(part.media_type, part.data) } }
+          end
+        end
+
+        # Build a base64 data URI for an inline content block.
+        #
+        # @param media_type [String] the MIME type
+        # @param data [String] the Base64-encoded bytes
+        # @return [String] the +data:+ URI
+        def data_uri(media_type, data)
+          "data:#{media_type};base64,#{data}"
+        end
+
+        # Serialize a tool definition into the function-tool schema advertised to the model.
+        #
+        # @param tool [Protege::Tool] the tool to advertise
+        # @return [Hash] the function-typed tool descriptor
+        def wire_tool(tool)
+          {
+            type:     'function',
+            function: { name: tool.id.to_s, description: tool.description, parameters: tool.input_schema }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/protege/inference/provider/response.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Protege
+  module Inference
+    module Provider
+      # One normalized generation result — Protege's **internal** representation of a model turn.
+      #
+      # Providers never construct this: they return the wire **response hash** (an OpenAI assistant
+      # message + finish reason — see the providers doc), and Protege wraps it here via {from_wire} at
+      # the Inference↔Provider seam. The harness and tracing read this object.
+      #
+      # +text+: assistant text (nil when the turn is tool calls only).
+      # +tool_calls+: +Array<ToolCall>+ (empty when none were requested).
+      # +finish_reason+: provider-reported reason (e.g. +'stop'+, +'tool_calls'+, +'length'+).
+      Response = Data.define(
+        :text,
+        :tool_calls,
+        :finish_reason
+      ) do
+        # Build a Response from a provider's wire response hash:
+        # +{ content:, tool_calls: [ {id:, function: {name:, arguments: <JSON string>}} ], finish_reason: }+.
+        #
+        # @param hash [Hash] the provider's response hash (symbol keys)
+        # @return [Response] the wrapped response
+        def self.from_wire(hash)
+          new(
+            text:          hash[:content],
+            tool_calls:    Array(hash[:tool_calls]).map { |call| ToolCall.from_wire(call) },
+            finish_reason: hash[:finish_reason]
+          )
+        end
+
+        # Render the model's output as a compact wire snapshot — the completion a trace trains toward:
+        # assistant text, any tool calls (in the shared function-call shape), and the finish reason.
+        # Mirrors +Request#to_wire+; the tracing subscriber stores this verbatim. Nil/empty fields drop.
+        #
+        # @return [Hash] the response snapshot
+        def to_wire
+          {
+            text:,
+            tool_calls:    tool_calls.presence&.map(&:to_wire),
+            finish_reason:
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/protege/inference/provider/tool_call.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Protege
+  module Inference
+    module Provider
+      # One tool call emitted by the model in a +Response+ (Protege's internal representation).
+      #
+      # +id+: provider-assigned identifier used to correlate the eventual tool-result message back to
+      # this call.
+      # +name+: snake_case tool name to invoke.
+      # +input+: parsed input hash matching the tool's input schema.
+      ToolCall = Data.define(
+        :id,
+        :name,
+        :input
+      ) do
+        # Build a ToolCall from a function-call wire hash:
+        # +{ id:, type: "function", function: { name:, arguments: <JSON string> } }+ — the shape the
+        # model emits in the response hash. +arguments+ is JSON-decoded into +input+.
+        #
+        # @param hash [Hash] the function-call wire hash (symbol keys)
+        # @return [ToolCall] the parsed call
+        def self.from_wire(hash)
+          function = hash[:function] || {}
+          new(id: hash[:id], name: function[:name], input: parse_arguments(function[:arguments]))
+        end
+
+        # Decode the JSON +arguments+ string into an input hash (empty when blank).
+        #
+        # @param raw [String, nil] the JSON-encoded arguments
+        # @return [Hash] the parsed input
+        def self.parse_arguments(raw)
+          raw.present? ? JSON.parse(raw) : {}
+        end
+
+        # Render this call in the standard function-call wire shape, with JSON-encoded arguments — the
+        # same serialization a request's assistant turn and a trace's response snapshot both use.
+        #
+        # @return [Hash] +{ id:, type: 'function', function: { name:, arguments: } }+
+        def to_wire
+          {
+            id:,
+            type:     'function',
+            function: { name:, arguments: input.to_json }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/protege/inference.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Protege
+  # Namespace for all inference concerns — providers, requests,
+  # responses, and the value objects they exchange.
+  #
+  # Module methods here are the cross-namespace entry points. Other namespaces (Orchestrator, Gateway)
+  # and the Rails layer call these rather than reaching into +Provider::*+ internals directly.
+  module Inference
+    extend self
+
+    # Build a +Provider::Request+ for the first turn of a generation.
+    #
+    # The message list is the resolver-supplied +context_messages+. When +user_content+ is given, it
+    # is appended as a trailing +role: :user+ message — used by the reply path to inject the live
+    # inbound email body (a stripped string, or multimodal parts when it has attachments). When
+    # +user_content+ is +nil+ the request is exactly the resolver messages: a scheduled run assembles
+    # its whole turn — instructions included — through its resolver chain, so the harness injects
+    # nothing. The request carries only the conversation and the tool classes; the active provider reads
+    # its own model / sampling / credentials from +config.providers+.
+    #
+    # @param user_content [String, Array<Object>, nil] the trailing user turn, or nil to add none.
+    # @param tools [Array<Class>] tool classes to expose for this generation.
+    # @param context_messages [Array<ModelMessage>] the resolver-assembled message list.
+    # @return [Provider::Request] the assembled first-turn request.
+    def build_request(user_content: nil, tools: [], context_messages: [])
+      messages  = Array(context_messages)
+      messages += [ModelMessage.new(role: :user, content: user_content)] unless user_content.nil?
+
+      Provider::Request.new(messages:, tools:)
+    end
+
+    # Build the next-turn +Provider::Request+ by appending the assistant turn and tool results.
+    #
+    # Used by the Orchestrator tool loop after the model requested tools: it appends the assistant
+    # +ModelMessage+ (carrying its +tool_calls+) followed by one +role: :tool+ message per
+    # result, then re-issues the request with the same tools as +previous+ (model and sampling come
+    # from the provider's config on each turn). Each tool result's payload is correlated back via
+    # +tool_call.id+ and serialized as JSON.
+    #
+    # When +review_parts+ are given (a tool asked to show the model an image/PDF it can't return in a
+    # text-only tool result), a final +role: :user+ message carrying those vision parts is appended
+    # after the tool messages — the only place the OpenAI schema lets visual content reach the model.
+    #
+    # @param previous [Provider::Request] the request that produced +response+.
+    # @param response [Provider::Response] the assistant response containing the requested tool
+    #   calls.
+    # @param tool_results [Array<Protege::ToolResult>] one result per executed tool call.
+    # @param review_parts [Array<Object>] vision parts to show the model on a trailing user turn.
+    # @return [Provider::Request] the request for the next tool-loop turn.
+    def extend_request(previous:, response:, tool_results:, review_parts: [])
+      assistant_msg = ModelMessage.new(
+        role:       :assistant,
+        content:    response.text || '',
+        tool_calls: response.tool_calls
+      )
+
+      tool_messages = tool_results.map do |tr|
+        ModelMessage.new(
+          role:         :tool,
+          tool_call_id: tr.tool_call.id,
+          content:      tr.result.to_h.to_json
+        )
+      end
+
+      messages  = previous.messages + [assistant_msg] + tool_messages
+      messages += [review_message(review_parts)] if review_parts.any?
+
+      Provider::Request.new(messages:, tools: previous.tools)
+    end
+
+    # Instantiate the provider class matching the configured +provider_id+.
+    #
+    # Resolves against +ProviderMixin.registered+ (every +Provider+ descendant) by symbolic
+    # id, so the lookup stays correct across Zeitwerk reloads.
+    #
+    # @return [ProviderMixin] a fresh provider instance for the configured id.
+    # @raise [Protege::ContractViolationError] when no registered provider declares the configured id.
+    def provider
+      id    = Protege.configuration.provider_id
+      klass = ProviderMixin.registered.find { |k| k.id == id }
+
+      raise Protege::ContractViolationError, "no provider registered for #{id.inspect}" unless klass
+
+      klass.new
+    end
+
+    # Generate against the configured provider — the seam that keeps the provider contract hash-based.
+    # Hands the provider the wire request hash (+Request#to_wire+) and wraps its returned response hash
+    # back into a +Provider::Response+, so providers never touch Protege's internal value types.
+    #
+    # @param request [Provider::Request] the request to generate against
+    # @return [Provider::Response] the wrapped response
+    def generate(request)
+      Provider::Response.from_wire(provider.generate(request.to_wire))
+    end
+
+    # Stream a generation against the configured provider, wrapping the final response hash as {generate}
+    # does. Yielded chunks pass through untouched.
+    #
+    # @param request [Provider::Request] the request to generate against
+    # @yieldparam chunk [Hash] a +{ type:, content: }+ token chunk
+    # @return [Provider::Response] the wrapped final response
+    def generate_stream(request, &)
+      Provider::Response.from_wire(provider.generate_stream(request.to_wire, &))
+    end
+
+    private
+
+    # Build the trailing +role: :user+ message that shows the model the attachments it asked to review.
+    #
+    # @param parts [Array<Object>] the vision parts to show
+    # @return [ModelMessage] the review user message
+    def review_message(parts)
+      ModelMessage.new(
+        role:    :user,
+        content: [TextPart.new(text: 'Here are the attachments you asked to review:'), *parts]
+      )
+    end
+  end
+end

data/lib/protege/loop/schedule.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'fugit'
+
+module Protege
+  module Loop
+    # Domain wrapper over a standard 5-field cron expression — the only knob a responsibility's
+    # schedule exposes. Backed by +Fugit::Cron+ so raw cron parsing never scatters through the engine
+    # (the gateway/wrapper convention), and deliberately answers just one question: does a given
+    # minute match? The Loop scheduler ticks every minute, so there is no "next occurrence" maths to do.
+    #
+    # The expression is interpreted in the **application timezone** (+Time.zone+) by pinning Fugit to
+    # that zone's IANA name, so "0 9 * * *" means 9am app-time regardless of the host's system clock.
+    class Schedule
+      class << self
+        # Whether +expression+ parses as a valid cron string. Never raises — safe for validations.
+        #
+        # @param expression [String, nil] the cron expression to check
+        # @return [Boolean] true when parseable
+        def valid?(expression)
+          new(expression).valid?
+        end
+      end
+
+      # @return [String] the raw cron expression as given
+      attr_reader :expression
+
+      # @param expression [String, nil] a standard 5-field cron expression (e.g. "0 9 * * 1-5")
+      # @return [void]
+      def initialize(expression)
+        @expression = expression.to_s.strip
+        @cron       = Fugit::Cron.parse(zoned(@expression))
+      end
+
+      # @return [Boolean] true when the expression parsed as valid cron
+      def valid?
+        !@cron.nil?
+      end
+
+      # Whether +time+ falls on this schedule, at minute granularity. Seconds are zeroed before the
+      # match because a 5-field cron fires at second zero, while the tick runs a few seconds into the
+      # minute.
+      #
+      # @param time [Time] the moment to test (typically +Time.current+)
+      # @return [Boolean] true when this minute is a scheduled minute
+      def due?(time)
+        return false unless valid?
+
+        @cron.match?(time.change(sec: 0, usec: 0))
+      end
+
+      private
+
+      # Append the application timezone's IANA name so the cron is interpreted in app-time. Blank input
+      # is passed through unchanged so it parses to +nil+ (and reads as invalid).
+      #
+      # @param expr [String] the raw cron expression
+      # @return [String] the expression pinned to the application timezone
+      def zoned(expr)
+        return expr if expr.empty?
+
+        "#{expr} #{(Time.zone || ActiveSupport::TimeZone['UTC']).tzinfo.name}"
+      end
+    end
+  end
+end

data/lib/protege/loop/scheduler.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Protege
+  module Loop
+    # The dispatch coordinator behind the Loop layer's every-minute clock. Each tick it finds the
+    # responsibilities due this minute and tells each to dispatch itself; it owns *which* responsibilities
+    # fire, while +Responsibility#dispatch!+ owns *how* (recording a run, enqueuing the job).
+    #
+    # Intentionally minimal: no overlap guard, no concurrency cap, no stale recovery, no minute-dedup.
+    # The recurring tick fires once per minute and the queue adapter bounds parallelism; a failed run is
+    # recorded and simply waits for its next scheduled minute.
+    class Scheduler
+      class << self
+        # Dispatch every responsibility due now.
+        #
+        # @return [void]
+        def dispatch
+          new.dispatch
+        end
+      end
+
+      # Tell each active, due responsibility to dispatch itself.
+      #
+      # @return [void]
+      def dispatch
+        Protege::Responsibility.active.with_active_persona.find_each do |responsibility|
+          responsibility.dispatch! if responsibility.due?(now)
+        end
+      end
+
+      private
+
+      # The single moment every responsibility this tick is evaluated against, captured once so a tick
+      # spanning a minute boundary still tests everyone against the same minute.
+      #
+      # @return [Time]
+      def now
+        @now ||= Time.current
+      end
+    end
+  end
+end

data/lib/protege/loop.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Protege
+  # LOGI "L" — the loop layer. Owns scheduled, proactive work: deciding which responsibilities are due
+  # on each clock tick and dispatching their runs. The +Scheduler+ drives dispatch and +Schedule+ parses
+  # and evaluates cron expressions.
+  #
+  # Class methods on this module are the cross-namespace entry points. Callers (the recurring tick job,
+  # the +Responsibility+ model) use these rather than reaching into +Scheduler+ / +Schedule+ directly.
+  module Loop
+    extend self
+
+    # Dispatch a run for every responsibility due right now. Called once per clock tick.
+    #
+    # @return [void]
+    def dispatch
+      Scheduler.dispatch
+    end
+
+    # Report whether a cron expression is well-formed — for model validation.
+    #
+    # @param expression [String] the cron expression
+    # @return [Boolean] true when parseable
+    def schedule_valid?(expression)
+      Schedule.valid?(expression)
+    end
+
+    # Report whether a cron expression is due at a given time.
+    #
+    # @param expression [String] the cron expression
+    # @param at [Time] the moment to test
+    # @return [Boolean] true when due at +at+
+    def schedule_due?(expression, at:)
+      Schedule.new(expression).due?(at)
+    end
+  end
+end

data/lib/protege/orchestrator/context.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Protege
+  module Orchestrator
+    # Base context shared by both kinds of run. Carries the per-run runtime data every tool and
+    # resolver needs — persona, a frozen config snapshot, logger, correlation id — plus the
+    # +#deliver+ affordance for sending mail through the Gateway, without exposing mutable framework
+    # state. Frozen after construction so one instance is safely shared across every tool/resolver
+    # invocation in a run.
+    #
+    # The thing that *drove* the run differs by kind, so it is exposed through two accessors that both
+    # default to +nil+ here and are each overridden by exactly one subclass: +ReplyContext+ sets
+    # +#message+ (reactive, an inbound email) and +ResponsibilityContext+ sets +#responsibility+
+    # (proactive, a scheduled Loop run). Tools and resolvers branch on whichever is present.
+    class Context
+      # @return [Protege::Persona] the persona handling this run
+      # @return [Protege::Configuration] the frozen process configuration snapshot
+      # @return [Logger] the engine logger
+      # @return [String, nil] the correlation id threaded through this run's events
+      attr_reader :persona, :config, :logger, :correlation_id
+
+      # Capture the shared runtime data and freeze. Subclasses set their own subject ivar *before*
+      # calling +super+, since this constructor freezes the instance.
+      #
+      # @param persona [Protege::Persona] the persona handling this run
+      # @return [void]
+      def initialize(persona:)
+        @persona        = persona
+        @logger         = Protege.configuration.logger
+        # Snapshot a frozen *copy* so the context is immutable without freezing the process-wide
+        # configuration (which boot-time code and tests still mutate).
+        @config         = Protege.configuration.dup.freeze
+        @correlation_id = Protege::Current.correlation_id
+
+        freeze
+      end
+
+      # The inbound message that drove this run, or nil when none did (overridden by +ReplyContext+).
+      #
+      # @return [Object, nil]
+      def message
+        nil
+      end
+
+      # The responsibility that drove this run, or nil when none did (overridden by
+      # +ResponsibilityContext+).
+      #
+      # @return [Protege::Responsibility, nil]
+      def responsibility
+        nil
+      end
+
+      # Deliver an outbound mail via the Gateway, handling transport, thread resolution, and message
+      # persistence under the current persona. Any +attachments+ (blobs already in storage) are attached
+      # to the persisted outbound message by reference, so a file is never re-uploaded on send.
+      #
+      # @param mail [Object] the outbound mail to deliver
+      # @param attachments [Array<ActiveStorage::Blob>] blobs to attach to the outbound message
+      # @return [Object] the Gateway delivery outcome
+      def deliver(mail:, attachments: [])
+        Gateway.deliver(mail:, persona:, attachments:)
+      end
+    end
+  end
+end