protege 0.1.0.alpha.1

data/lib/protege/subscribers/hook_dispatcher.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Protege
+  module Subscribers
+    # The hooks-only event dispatcher — the runtime that activates hooks against the engine's event
+    # stream. Installed once at boot by +Protege::Engine+ (a peer of +Subscribers::Tracing+ and
+    # +Subscribers::IntrospectionBroadcaster+); it subscribes one dispatcher per +Protege::Event.all+
+    # that, when an event fires, runs every registered hook's matching handlers.
+    #
+    # Kept separate from the hook *contract* (+Protege::HookMixin+, the +on+/+stateful+ DSL a hook
+    # declares with): this module only reads that contract off each hook class
+    # (+hook_class.subscriptions+, +hook_class.stateful?+) — a one-way dependency, dispatcher → contract.
+    #
+    # Hooks are pulled live from +Hook.descendants+ (via {registered}) when an event fires, so a Zeitwerk
+    # reload just changes the descendant set; the dispatchers are stable and never need re-subscribing.
+    # Handler blocks run via +instance_exec+ on a hook instance — fresh per event for stateless hooks, or
+    # a shared per-run instance (keyed by +correlation_id+) for +stateful+ ones — inside a +rescue+ that
+    # logs and swallows, so one hook can never break inference or a sibling hook.
+    module HookDispatcher
+      extend self
+
+      # Event classes that end a run; a stateful hook's per-run instance is evicted after these fire.
+      # Includes +InferenceFailedEvent+ so a run that raises before completing never leaves a stale
+      # instance behind.
+      TERMINAL_EVENTS = [
+        InferenceCompletedEvent,
+        InferenceFailedEvent,
+        InferenceMaxTurnsReachedEvent
+      ].freeze
+
+      # Live event-bus dispatcher handles (one per event class), retained so {reset!} can detach them.
+      @handles = []
+
+      # Per-run instances for stateful hooks, keyed by +[hook_class, correlation_id]+.
+      @instances = {}
+
+      # Guards (re)installation of the dispatchers.
+      @install_mutex = Mutex.new
+
+      # Guards the stateful-instance map, mutated from event-dispatch threads.
+      @instances_mutex = Mutex.new
+
+      # Wire the event bus to hook dispatch — the subscriber's +install!+ contract. Called once at boot
+      # by the engine; idempotent, so a repeat call is a no-op until {reset!} runs. Installs one
+      # dispatcher per +Protege::Event.all+ that fans the event out to every registered hook's handlers.
+      #
+      # @return [void]
+      def install!
+        @install_mutex.synchronize do
+          return unless @handles.empty?
+
+          @handles = Protege::Event.all.map do |event_class|
+            event_class.subscribe { |event| dispatch(event_class, event) }
+          end
+        end
+      end
+
+      # Detach every dispatcher and drop all per-run state — the subscriber's +reset!+ contract, for boot
+      # re-wiring and tests.
+      #
+      # @return [void]
+      def reset!
+        @install_mutex.synchronize do
+          @handles.each { |handle| ActiveSupport::Notifications.unsubscribe(handle) }
+          @handles = []
+          @instances_mutex.synchronize { @instances.clear }
+        end
+      end
+
+      private
+
+      # List all concrete hook classes to dispatch to.
+      #
+      # Resolved via +Hook.descendants+ so it survives Zeitwerk reloads without manual bookkeeping.
+      # Anonymous classes (nil name) are excluded.
+      #
+      # @return [Array<Class>] the registered hook classes
+      def registered
+        Hook.descendants.reject { _1.name.nil? }
+      end
+
+      # Fan one fired event out to every registered hook that declared a handler for its class.
+      #
+      # @param event_class [Class] the fired event's class
+      # @param event [Protege::Event] the typed event instance
+      # @return [void]
+      def dispatch(event_class, event)
+        registered.each do |hook_class|
+          # A hook only has a subscriptions key for the events it knew about when its map was seeded.
+          # An event class it has no entry for (an unknown or newly-added event) yields nil — treat that
+          # as "no handlers" and skip, rather than crashing on nil.empty?.
+          blocks = hook_class.subscriptions[event_class]
+          run(hook_class:, event_class:, blocks:, event:) if blocks&.any?
+        end
+      end
+
+      # Run a hook's handlers for one event, isolated and on the right instance.
+      #
+      # @param hook_class [Class] the hook class
+      # @param event_class [Class] the event class being dispatched
+      # @param blocks [Array<Proc>] the handler blocks for this event
+      # @param event [Protege::Event] the typed event
+      # @return [void]
+      def run(hook_class:, event_class:, blocks:, event:)
+        instance = instance_for(hook_class, event)
+
+        blocks.each do |block|
+          instance.instance_exec(event, &block)
+        rescue StandardError => e
+          Protege.configuration.logger.error(
+            "[Protege] hook #{hook_class} on #{event_class} failed: #{e.class}: #{e.message}"
+          )
+        end
+
+        evict(hook_class, event) if hook_class.stateful? && TERMINAL_EVENTS.include?(event_class)
+      end
+
+      # The instance to run handlers on: fresh per event for stateless hooks, or the run's shared
+      # instance (keyed by +correlation_id+) for stateful hooks.
+      #
+      # @param hook_class [Class] the hook class
+      # @param event [Protege::Event] the event being dispatched
+      # @return [Object] the hook instance
+      def instance_for(hook_class, event)
+        return hook_class.new unless hook_class.stateful?
+
+        @instances_mutex.synchronize { @instances[[hook_class, event.correlation_id]] ||= hook_class.new }
+      end
+
+      # Drop a stateful hook's instance for a finished run.
+      #
+      # @param hook_class [Class] the hook class
+      # @param event [Protege::Event] the terminal event
+      # @return [void]
+      def evict(hook_class, event)
+        @instances_mutex.synchronize { @instances.delete([hook_class, event.correlation_id]) }
+      end
+    end
+  end
+end

data/lib/protege/subscribers/tracing.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Protege
+  module Subscribers
+    # The tracing subscriber — the one place that knows the +Protege::Trace+ table exists. Subscribes to
+    # +InferenceGeneratedEvent+ (emitted once per turn by the Harness, only when +config.tracing+ is on)
+    # and snapshots the turn into a durable, self-contained row for later fine-tuning. A peer of
+    # +Subscribers::HookDispatcher+ and +Subscribers::IntrospectionBroadcaster+, installed at boot.
+    #
+    # Kept deliberately decoupled: the Harness gates *whether* the event fires; this module gates nothing
+    # and simply persists what arrives. Delete the +install!+ call and tracing disappears with the
+    # Harness untouched. Writing is **best-effort** — any failure is logged and swallowed, never
+    # propagated, so a tracing hiccup can't abort an inference run (the reply may already have been sent).
+    #
+    # A trace records only what affects training: the wire +request+ and +response+ (each already
+    # serialized by the value object's own +#to_wire+, the same bytes the API exchange uses) and the
+    # inference settings (+model+ + +settings+). No persona/provider identity is stored, and this module
+    # does no serialization of its own — it just persists what the event carries.
+    module Tracing
+      extend self
+
+      # The subscription handle, retained so {reset!} can detach it.
+      @handle = nil
+
+      # Subscribe the tracing recorder to the per-turn event — the subscriber's +install!+ contract.
+      # Idempotent; called once at boot from the engine's +after_initialize+.
+      #
+      # @return [void]
+      def install!
+        return if @handle
+
+        @handle = InferenceGeneratedEvent.subscribe { |event| record(event) }
+      end
+
+      # Detach the subscription — the subscriber's +reset!+ contract, for boot re-wiring and tests.
+      #
+      # @return [void]
+      def reset!
+        return unless @handle
+
+        ActiveSupport::Notifications.unsubscribe(@handle)
+        @handle = nil
+      end
+
+      private
+
+      # Snapshot one generated turn into a +Trace+ row. Best-effort: logs and swallows any error.
+      #
+      # @param event [Protege::InferenceGeneratedEvent] the per-turn event
+      # @return [void]
+      def record(event)
+        Trace.record(
+          correlation_id: event.correlation_id,
+          turn_index:     event.turn,
+          model:          event.model,
+          settings:       event.settings,
+          request:        event.request,
+          response:       event.response
+        )
+      rescue StandardError => e
+        Protege.configuration.logger.error("[Protege] failed to record trace: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/protege/types/document_part.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Protege
+  # One document-typed message part — a sibling of +TextPart+ for multimodal content, used for PDFs.
+  # Carries the filename, MIME type, and Base64-encoded bytes; the provider renders it into the wire
+  # format its API expects (e.g. an OpenAI +file+ block). Document-capable models read the PDF
+  # itself — text and layout — rather than a server-side text extraction.
+  DocumentPart = Data.define(
+    :filename,
+    :media_type,
+    :data
+  )
+end

data/lib/protege/types/image_part.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Protege
+  # One image-typed message part — a sibling of +TextPart+ for multimodal content. Carries the
+  # image's MIME type and its Base64-encoded bytes; the provider renders it into the wire format its
+  # API expects (e.g. an OpenAI +image_url+ data URI). Vision-capable models read it as an image.
+  ImagePart = Data.define(
+    :media_type,
+    :data
+  )
+end

data/lib/protege/types/model_message.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Protege
+  # One normalized message in a chat-completions conversation — a +role+ plus its +content+ (one or more
+  # content parts) and optional tool correlation. This is the pipeline-wide currency the model layer
+  # speaks: providers serialize it to the wire (+Inference::Provider::Request#to_wire+), the harness
+  # threads it through a run, and resolvers build it (via +Resolver#message+) to contribute context. It
+  # lives here at the top level beside the content parts it carries (+TextPart+ / +ImagePart+ /
+  # +DocumentPart+) rather than inside +Inference+, because — like them — it is ownerless currency every
+  # layer constructs and reads, not any one layer's private type. (It cannot be +Protege::Message+: that
+  # name is the stored-email ActiveRecord model.)
+  #
+  # +role+ and +content+ are always required. The tool-correlation fields are optional: +tool_call_id+
+  # is meaningful only when +role+ is +:tool+ (it correlates a tool result back to the call);
+  # +tool_calls+ is meaningful only when +role+ is +:assistant+ and the model is requesting tool
+  # execution.
+  ModelMessage = Data.define(
+    :role,
+    :content,
+    :tool_call_id,
+    :tool_calls
+  ) do
+    # @param role [Symbol] one of +:system+, +:user+, +:assistant+, +:tool+.
+    # @param content [String, Array<TextPart>] message content; String for the text-only case.
+    # @param tool_call_id [String, nil] correlates a +role: :tool+ message to its originating call.
+    # @param tool_calls [Array<ToolCall>, nil] tool calls the model requested (assistant only).
+    def initialize(role:, content:, tool_call_id: nil, tool_calls: nil)
+      super
+    end
+
+    # Return content as a normalized parts array.
+    #
+    # Array content passes through unchanged; String content is wrapped in a single +TextPart+.
+    #
+    # @return [Array<TextPart>] the content normalized to parts.
+    def parts
+      content.is_a?(Array) ? content : [TextPart.new(text: content)]
+    end
+  end
+end

data/lib/protege/types/result.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Protege
+  # Immutable outcome value — the standard return type passed between system parts across the LOGI
+  # pipeline: tools (+Tool#use+), resolvers, and gateway operations all hand back a +Result+. Carrying
+  # success/failure as data (rather than raising across layer boundaries) lets the Orchestrator
+  # serialize a failed tool outcome straight into the LLM's tool message so the model can
+  # self-correct. Frozen on construction; build via +Result.success+ / +Result.failure+.
+  #
+  # @example
+  #   Result.success(id: 42)
+  #   Result.failure(reason: 'bad input', field: :email)
+  #   Result.failure(reason: exception)
+  class Result
+    # Number of backtrace frames retained in the serialized error.
+    #
+    # The serialized result is encoded into the LLM's tool message, where a deep backtrace is just
+    # token-costly noise — the class and message are what the model reasons over. Operators still get
+    # the full backtrace via the engine log (see +ToolMixin.invoke+) and the persisted
+    # +Message#last_processing_error+.
+    SERIALIZED_BACKTRACE_FRAMES = 3
+
+    # @return [Boolean] true when the operation succeeded
+    # @return [Hash] the payload data attached to the outcome
+    # @return [Exception, nil] the captured error on failure, otherwise nil
+    attr_reader :success, :data, :error
+
+    # @return [Boolean] alias of +#success+ — true when the operation succeeded
+    alias success? success
+
+    class << self
+      # Build a successful Result.
+      #
+      # @param data [Hash] arbitrary payload keyed by symbol
+      # @return [Protege::Result] a frozen successful result
+      def success(**data)
+        new success: true, data:
+      end
+
+      # Build a failed Result.
+      #
+      # +reason+ may be a String or an Exception; strings are wrapped in +Protege::GenericError+ so
+      # +#error+ is always an Exception.
+      #
+      # @param reason [String, Exception] the failure cause
+      # @param data [Hash] arbitrary payload keyed by symbol
+      # @return [Protege::Result] a frozen failed result
+      def failure(reason:, **data)
+        new success: false, data:, error: wrap_generic_error(reason)
+      end
+
+      private
+
+      # Coerce a failure reason into an Exception.
+      #
+      # Non-exception reasons become a +Protege::GenericError+ so the result always carries an
+      # error class and message.
+      #
+      # @param reason [String, Exception] the failure cause
+      # @return [Exception] the original exception, or a wrapped generic error
+      def wrap_generic_error(reason)
+        return reason if reason.is_a?(Exception)
+
+        Protege::GenericError.new(reason.to_s)
+      end
+    end
+
+    # Initialize and freeze the result.
+    #
+    # @param success [Boolean] whether the operation succeeded
+    # @param data [Hash] arbitrary payload keyed by symbol
+    # @param error [Exception, nil] the captured error, present only on failure
+    # @return [void]
+    def initialize(success:, data: {}, error: nil)
+      @success = success
+      @data    = data
+      @error   = error
+
+      freeze
+    end
+
+    # @return [Boolean] true when the operation failed
+    def failure?
+      !success
+    end
+
+    # Serialize the result to a plain hash suitable for JSON encoding into a tool message.
+    #
+    # @return [Hash] +{ success:, data:, error: }+ where +error+ is a serialized hash or nil
+    def to_h
+      {
+        success:,
+        data:,
+        error:   serialized_error
+      }
+    end
+
+    private
+
+    # Render +#error+ as a transport-safe hash.
+    #
+    # @return [Hash, nil] +{ message:, class:, backtrace: }+, or nil when there is no error
+    def serialized_error
+      return nil unless error
+
+      {
+        message:   error.message,
+        class:     error.class.name,
+        backtrace: error.backtrace&.first(SERIALIZED_BACKTRACE_FRAMES)
+      }
+    end
+  end
+end

data/lib/protege/types/stored_file.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Protege
+  # Domain wrapper around a stored +ActiveStorage::Blob+ — the single source of truth for how the
+  # engine interprets a file: its kind (image / document / text / viewable), a one-line human summary,
+  # and how it renders into the shapes other layers speak. It renders itself two ways: +#to_part+
+  # produces the provider's multimodal content block (an +ImagePart+ / +DocumentPart+) that inference
+  # feeds a vision model, and +#to_mail_attachment+ produces the transport payload the send path
+  # attaches to outbound mail. +ReadAttachmentTool+ and +ThreadHistoryResolver+ read its kind and
+  # summary. MIME classification (and the parameter-stripping that makes +image/jpeg; name=…+ match)
+  # lives here and nowhere else, so provider and tool authors classify files without re-deriving the
+  # rules.
+  #
+  # A file's durable identity is its *blob* — the per-message +ActiveStorage::Attachment+ is just a
+  # join that is recreated whenever a file rides on a new message. So this wraps the blob directly:
+  # the +#id+ it reports (and the id in +#summary+) is the *blob* id, which is the currency the
+  # +read_attachment+, +send_email+, and +create_file+ tools all speak.
+  class StoredFile
+    extend Forwardable
+
+    # Content types the vision models accept as inline images (jpeg/png/gif/webp). Other image types
+    # (HEIC, BMP, TIFF, SVG) are deliberately excluded — the models can't view them.
+    IMAGE_TYPES = %w[image/png image/jpeg image/jpg image/gif image/webp].freeze
+
+    # Content types sent as a native document block. PDF is the only type the models read as a
+    # document today; listed as a set so a newly-supported type is a one-line addition.
+    DOCUMENT_TYPES = %w[application/pdf].freeze
+
+    # Non-+text/*+ content types whose payloads are safe to return as text.
+    TEXT_TYPES = %w[application/json application/xml application/csv].freeze
+
+    class << self
+      # Look up a stored file by its blob id, or +nil+ when no blob matches. Nil-safe (uses +find_by+,
+      # not +find+), so a tool turns a missing id into a failed +Result+ rather than raising. Single-
+      # argument lookup, so it stays positional by convention.
+      #
+      # @param blob_id [Integer, String] the +ActiveStorage::Blob+ id
+      # @return [StoredFile, nil] the wrapped blob, or nil when the id is unknown
+      def find(blob_id)
+        blob = ActiveStorage::Blob.find_by(id: blob_id)
+        blob && new(blob)
+      end
+    end
+
+    # @return [ActiveStorage::Blob] the wrapped blob
+    attr_reader :blob
+
+    # Read-through to the wrapped blob for the values consumers need verbatim.
+    def_delegators :@blob, :content_type, :byte_size, :id, :download
+
+    # @param blob [ActiveStorage::Blob] the stored blob to wrap
+    def initialize(blob)
+      @blob = blob
+    end
+
+    # @return [String] the original filename as a plain string
+    def filename
+      blob.filename.to_s
+    end
+
+    # Render this file as the provider content part a vision model reads, or +nil+ when its type can't
+    # be viewed (video, Office formats, archives). Images become an +ImagePart+, PDFs a +DocumentPart+;
+    # the bytes are downloaded and Base64-encoded only when there is a part to build.
+    #
+    # @return [ImagePart, DocumentPart, nil] the vision part, or nil when unviewable
+    def to_part
+      if image?
+        ImagePart.new(media_type:, data: encoded_bytes)
+      elsif document?
+        DocumentPart.new(filename:, media_type:, data: encoded_bytes)
+      end
+    end
+
+    # Build the outbound mail payload for this file — the typed attachment the send path attaches to a
+    # message. Downloads the bytes for transport; the blob itself remains the durable identity.
+    #
+    # @return [Gateway::Mail::Attachment] the transport payload
+    def to_mail_attachment
+      Gateway::Mail::Attachment.new(filename:, content_type:, bytes: download)
+    end
+
+    # @return [Boolean] true when the file is an image a vision model can view
+    def image?
+      IMAGE_TYPES.include?(media_type)
+    end
+
+    # @return [Boolean] true when the file is a document a model can read natively (PDF)
+    def document?
+      DOCUMENT_TYPES.include?(media_type)
+    end
+
+    # @return [Boolean] true when the file's content can be returned as plain text
+    def text?
+      media_type.start_with?('text/') || TEXT_TYPES.include?(media_type)
+    end
+
+    # @return [Boolean] true when the file can be shown to the model as a vision part (image or PDF)
+    def viewable?
+      image? || document?
+    end
+
+    # The bare MIME type, lowercased and stripped of header parameters (e.g.
+    # +"image/jpeg; name=p.jpg"+ → +"image/jpeg"+), so classification and part media types match cleanly.
+    #
+    # @return [String] the bare, lowercased media type
+    def media_type
+      content_type.to_s.split(';').first.to_s.strip.downcase
+    end
+
+    # A concise one-line description for the model — filename, type, human size, and the blob id the
+    # tools accept.
+    #
+    # @return [String] e.g. +"invoice.pdf (application/pdf, 42 KB, id: 12)"+
+    def summary
+      "#{filename} (#{content_type}, #{ActiveSupport::NumberHelper.number_to_human_size(byte_size)}, id: #{id})"
+    end
+
+    private
+
+    # @return [String] the file's bytes, Base64-encoded for a provider data block
+    def encoded_bytes
+      Base64.strict_encode64(download)
+    end
+  end
+end

data/lib/protege/types/text_part.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Protege
+  # One text-typed message part — the general multimodal-content currency shared across the pipeline
+  # (providers serialize it, tools and resolvers build it). The text-only common case; its siblings
+  # +ImagePart+ and +DocumentPart+ carry the other content kinds.
+  TextPart = Data.define(:text)
+end

data/lib/protege/types/tool_result.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Protege
+  # Pairs a tool call with its outcome. Built by +ToolMixin.invoke+ and consumed by
+  # +Inference.extend_request+ to build the next turn's messages — +tool_call+ identifies which call this
+  # answers and +result+ carries the +Protege::Result+ the model sees. An immutable +Data+ value object.
+  #
+  # It belongs to no single layer — it bridges an Inference +Provider::ToolCall+, a top-level +Result+,
+  # and Orchestrator's tool dispatch — so it lives here at the top level alongside +Result+ and +Event+.
+  #
+  # @!attribute [r] tool_call
+  #   @return [Object] the originating tool call
+  # @!attribute [r] result
+  #   @return [Protege::Result] the outcome of invoking the tool
+  ToolResult = Data.define(:tool_call, :result)
+end

data/lib/protege/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Protege
+  # Current gem version, following Semantic Versioning.
+  VERSION = '0.1.0.alpha.1'
+end

data/lib/protege.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'protege/version'
+require 'protege/configuration'
+require 'protege/gateway'
+require 'protege/engine'
+
+# Root namespace for the Protege engine — an email-native AI agent toolkit that turns a host
+# Rails application into an agentic workspace.
+#
+# Protege is structured around the LOGI pipeline:
+# - **L**oop — scheduled responsibilities that drive personas on a cron tick.
+# - **O**rchestrator — the +Harness+ multi-turn tool loop that runs inference and dispatches tools.
+# - **G**ateway — Action Mailbox inbound delivery and SMTP outbound delivery.
+# - **I**nference — provider adapters that talk to model APIs.
+#
+# Email is the channel, the host Rails app is the workspace, and personas, tools, providers,
+# resolvers, and hooks all participate as extensions. Requiring this file loads only the engine
+# entry points; runtime constructs are resolved through Rails autoloading once the engine boots.
+#
+# @see https://github.com/sebscholl/protege
+module Protege
+  extend self
+
+  # Yield the configuration object for mutation. Call once in a Rails initializer.
+  #
+  # @yield [config] the configuration to mutate
+  # @yieldparam config [Protege::Configuration] the process-wide configuration
+  # @return [void]
+  def configure
+    yield configuration
+  end
+
+  # Return the process-wide configuration, creating it on first access.
+  #
+  # @return [Protege::Configuration] the memoized configuration instance
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Reset configuration to defaults. Primarily for test isolation between examples.
+  #
+  # @return [Protege::Configuration] the freshly built configuration
+  def reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/tasks/protege_tasks.rake

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+namespace :protege do
+  namespace :css do
+    desc "Build the Protege engine's compiled Tailwind CSS. " \
+         'Run this after changing engine views. Requires tailwindcss-rails in the host app.'
+    task :build do
+      gem_root = File.expand_path('../../..', __dir__)
+      input    = File.join(gem_root, 'app/assets/tailwind/application.css')
+      output   = File.join(gem_root, 'app/assets/builds/protege.css')
+      content  = "#{gem_root}/app/views/**/*.html.erb,#{gem_root}/app/helpers/**/*.rb"
+
+      sh "tailwindcss -i #{input} -o #{output} --content #{content}"
+    end
+  end
+end