protege 0.1.0.alpha.7 → 0.1.0.alpha.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d413f57504bbdb848d33fd0afd7fdc616a409de2b5d3107c38a2d169bd1e1c6f
-  data.tar.gz: a80f880c36d5b1add111ca5176abfb27416fcb18ae63d2bf4504fd97d61e0912
+  metadata.gz: 435fd074ac0f41e0e1e5bf859d394ac23b6e3d46dae7e079ec0080650a54d505
+  data.tar.gz: b7cbd48b85e705c1da2d935dcbbb7ce167535e9485b657439d53587d231e790b
 SHA512:
-  metadata.gz: 0f9ebf231169742d602abad8f806793599636a6e15ec196d19672128e9ac123fb9db72ba4738e33cc86fd1bcf546dfb9f69ae0aebc9f935400a4a24347b584a0
-  data.tar.gz: 211573228c71e00cd37ea479419fe13cf7260bcc303443ed3720a7c991f9c2634e6fb1628958c3cb23f9e77121055e2d81a479a44d33eebf3ff7444964a6ff65
+  metadata.gz: e9d4bf8c6d7c28383f4584cd28bba77e3ba940e470cac6dce21fbc6f171ce87db5b7cae2a62623c7074406d1d074af3d6e260e6ed4982decd63f6ae6792298e6
+  data.tar.gz: 686d8e8842a41b551a0d47509f48768f00d07b18edb96512453f9c5bd6a165d43779d28fed12c0f4dc27b659a58b4e6d0e5ca042e03199f3741b67d162e40981

data/app/services/protege/dev_setup.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Protege
+  # One-command development bootstrap — the service behind `bin/rails protege:setup:dev`. Provisions
+  # everything a fresh host app needs to start chatting locally, except the provider API key:
+  #
+  # * the system toolkits (via +SystemToolkits.sync!+, run first so Default Tools exists to auto-attach),
+  # * the +protege.local+ email domain (DKIM keypair minted on create),
+  # * the +ExecutiveAgent+ class itself when the host doesn't have one — generated through the same
+  #   +protege:agent+ generator the installer uses, never guessed at or resolved from configuration,
+  # * **Phoenix**, an +ExecutiveAgent+ record at +phoenix@protege.local+ with starter instructions,
+  # * a proactive, open-gated All Tools grant, so every registered tool is exercisable in development.
+  #
+  # Idempotent throughout — records are found-or-created, so re-running never duplicates or clobbers.
+  # Environment gating (this seeds play data) is the rake task's concern, not this service's.
+  class DevSetup
+    # The development email domain. Registering it is what routes inbound mail; sharing a domain with the
+    # default +console_address+ (+console@protege.local+) is safe — console-local delivery is decided by
+    # address match, not domain registration.
+    DOMAIN = 'protege.local'
+
+    # The development agent's identity.
+    AGENT_NAME  = 'Phoenix'
+    AGENT_EMAIL = "phoenix@#{DOMAIN}".freeze
+
+    # The starter system prompt — enough personality to be pleasant and enough direction to exercise
+    # tools, while staying generic (Phoenix knows nothing about any particular host app).
+    INSTRUCTIONS = <<~TEXT.strip
+      You are Phoenix, a general-purpose agent running in a development environment. You communicate by
+      email: read what you receive, use your tools whenever they help you act or answer accurately, and
+      reply with send_email. Keep replies short, concrete, and friendly. When asked to demonstrate a
+      capability, actually exercise the tool and report what happened.
+    TEXT
+
+    class << self
+      # Provision the full development setup.
+      #
+      # @return [Protege::Agent] the Phoenix agent record
+      def run!
+        new.run!
+      end
+    end
+
+    # Provision the full development setup.
+    #
+    # @return [Protege::Agent] the Phoenix agent record
+    def run!
+      SystemToolkits.sync!
+      ensure_domain
+
+      agent = ensure_phoenix
+      ensure_all_tools_grant(agent:)
+
+      agent
+    end
+
+    private
+
+    # Register the development email domain (a no-op when it already exists).
+    #
+    # @return [void]
+    def ensure_domain
+      EmailDomain.find_or_create_by!(domain: DOMAIN)
+    end
+
+    # Find or create Phoenix. Creation auto-attaches the Default Tools toolkit (see +Toolable+), which
+    # is why the toolkit sync runs first.
+    #
+    # @return [Protege::Agent] the Phoenix record
+    def ensure_phoenix
+      agent_class.find_or_create_by!(name: AGENT_NAME) do |agent|
+        agent.email_address = AGENT_EMAIL
+        agent.instructions  = INSTRUCTIONS
+      end
+    end
+
+    # The host's +ExecutiveAgent+ class — generated on the spot when absent, through the same
+    # +protege:agent+ generator the installer invokes, then loaded so the constant is live in this
+    # process. Deterministic by design: no constant guessing, no environment-variable overrides.
+    #
+    # @return [Class] the ExecutiveAgent class
+    def agent_class
+      return ::ExecutiveAgent if defined?(::ExecutiveAgent)
+
+      generate_executive_agent
+      load Rails.root.join(Protege.configuration.agents_path, 'executive_agent.rb')
+      ::ExecutiveAgent
+    end
+
+    # Scaffold +app/agents/executive_agent.rb+ into the host app.
+    #
+    # @return [void]
+    def generate_executive_agent
+      Rails::Generators.invoke('protege:agent', ['Executive'], destination_root: Rails.root.to_s)
+    end
+
+    # Attach the All Tools system toolkit to the agent — open gate (no rules), proactive use enabled —
+    # so the whole catalogue, host tools included, is exercisable in development, reactively and on
+    # scheduled runs alike.
+    #
+    # @param agent [Protege::Agent] the agent to equip
+    # @return [void]
+    def ensure_all_tools_grant(agent:)
+      grant = AgentToolkit.find_or_initialize_by(agent:, toolkit: Toolkit.all_tools)
+      grant.update!(allow_proactive: true)
+    end
+  end
+end

data/app/services/protege/system_toolkits.rb

@@ -8,8 +8,9 @@ module Protege
   #   each sync rewrites it to the live tool manifest, so a tool added in code shows up automatically and
   #   an operator's edits don't stick.
   # * **Default Tools** (+default_tools+) — auto-attached to every new agent (see +Toolable+). The engine
-  #   only *seeds* it (with +send_email+, so a fresh agent can at least reply) on first creation;
-  #   thereafter its membership is the operator's to curate, so later syncs leave it alone.
+  #   only *seeds* it on first creation — with every engine built-in tool, so a fresh agent starts with
+  #   the full generic baseline (reply, search, web, files) — and thereafter its membership is the
+  #   operator's to curate, so later syncs leave it alone.
   #
   # Sync is idempotent and safe to run repeatedly. It runs like any other seed data — not at boot (writing
   # to the DB from an initializer is an anti-pattern): the +protege:toolkits:sync+ rake task on deploy and
@@ -49,8 +50,10 @@ module Protege
       toolkit.save!
     end
 
-    # Ensure the Default Tools toolkit exists. On first creation it is seeded with +send_email+ so a new
-    # agent is immediately able to reply; on later syncs its membership is left untouched (operator-owned).
+    # Ensure the Default Tools toolkit exists. On first creation it is seeded with every engine built-in
+    # tool — the generic baseline (reply, search, web, files) that makes a new agent immediately useful,
+    # deliberately overlapping All Tools — while host-defined tools stay out of the seed (granting your
+    # own tools is an explicit act). On later syncs its membership is left untouched (operator-owned).
     #
     # @return [void]
     def ensure_default_tools
@@ -60,8 +63,18 @@ module Protege
       toolkit.name            = 'Default Tools'
       toolkit.description     = 'Attached to every new agent automatically. Curate its members to set the ' \
                                 'baseline tools an agent starts with.'
-      toolkit.member_tool_ids = ['send_email']
+      toolkit.member_tool_ids = engine_tool_ids
       toolkit.save!
     end
+
+    # The ids of the tools the engine itself ships — manifest entries whose class lives under the
+    # +Protege::+ namespace, distinguishing built-ins from host-defined tools.
+    #
+    # @return [Array<String>] the engine built-in tool ids
+    def engine_tool_ids
+      Manifest.registered(:tool)
+              .select { |entry| entry.klass.module_parent == Protege }
+              .map { |entry| entry.id.to_s }
+    end
   end
 end

data/lib/generators/protege/install/install_generator.rb

@@ -114,6 +114,9 @@ module Protege
 
             6. Create your first agent + email domain (dashboard, or a db/seeds.rb bootstrap) so
                inbound mail has somewhere to route. Then boot and open /protege.
+
+               Or, for a ready-to-chat development setup in one command (covers steps 2 and 6):
+                 bin/rails protege:setup:dev
         STEPS
       end
 

data/lib/protege/version.rb

@@ -2,5 +2,5 @@
 
 module Protege
   # Current gem version, following Semantic Versioning.
-  VERSION = '0.1.0.alpha.7'
+  VERSION = '0.1.0.alpha.8'
 end

data/lib/tasks/protege_tasks.rake

@@ -13,6 +13,34 @@ namespace :protege do
     end
   end
 
+  namespace :setup do
+    desc 'Provision a ready-to-chat development environment: the protege.local domain, the Phoenix ' \
+         'agent (generating ExecutiveAgent if absent), and the system toolkits. Idempotent; dev only.'
+    task dev: :environment do
+      abort 'protege:setup:dev seeds development play data — refusing to run outside development.' unless
+        Rails.env.development?
+
+      # Rake tasks don't eager-load by default, so the tool manifest would be incomplete; force it so
+      # the toolkits capture every registered tool.
+      Rails.application.eager_load!
+
+      agent = Protege::DevSetup.run!
+
+      puts <<~DONE
+        Development environment ready.
+
+          Domain   #{Protege::DevSetup::DOMAIN}  (DKIM keypair minted; DNS only matters in production)
+          Agent    #{agent.name} <#{agent.email_address}>  — #{agent.class.name}
+          Toolkits Default Tools (auto-attached, all engine built-ins) + All Tools (open gate, proactive)
+
+        To start chatting:
+          1. export OPENROUTER_API_KEY=sk-...   (the one thing this task can't do for you)
+          2. bin/dev
+          3. open http://localhost:3000/protege — Inbox -> Compose -> #{agent.name}
+      DONE
+    end
+  end
+
   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.'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protege
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.7
+  version: 0.1.0.alpha.8
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -205,7 +205,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: 'Protege gives your Rails app AI teammates: inbound mail via Action Mailbox,
+description: 'Protege gives your Rails app AI agents: inbound mail via Action Mailbox,
   replies over SMTP, tools that act on your own models, cron-scheduled responsibilities
   dispatched through Active Job, and a built-in dashboard to manage and observe it
   all — in process, no separate service.'
@@ -308,6 +308,7 @@ files:
 - app/resolvers/protege/load_record_resolver.rb
 - app/resolvers/protege/load_text_resolver.rb
 - app/resolvers/protege/thread_history_resolver.rb
+- app/services/protege/dev_setup.rb
 - app/services/protege/introspection_tool_call_presentation.rb
 - app/services/protege/message_search.rb
 - app/services/protege/system_toolkits.rb