ask-rails 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 805ea4f5713b8cfacc7f25c54b6229b788199ddba9ab1dc5a50c4719a834f256
-  data.tar.gz: da2648a6027373d0c65f37786c347e6fda211d6f43a38378042acb8dae1a7ca8
+  metadata.gz: 8c73b254e032db5c313a0eeca47499a4b30152fcf725ed410e575b0ea0a9460f
+  data.tar.gz: bfe5f9b1769e4ea4b864b7dee0c6ca3d1a6587186ccac7820a71f65999f8e0f5
 SHA512:
-  metadata.gz: 02e6b7d1dca1617b4070e9068cb6be162040756119ef1dbdab793ec27b1cb1aaa33a46eb88d7dcc9c9734e3b3c570172f816290f2629be0a09c8cdef041a88e9
-  data.tar.gz: bedabfd712c7397baf254aecaf8c2c2316dfb47964303d4b91437e9ef53dcf187a31fccdc406e8b5434de5029d657179845d31044de8e2ee148abff0baef8063
+  metadata.gz: 9c02cc27c98ea141900339703160ecfad56ed70979292a654b8b1f6c7e6562f02307abc7c02a88e319cc3f8e78b66677cfa37bee8a9fc84430f07ef3b3188ba4
+  data.tar.gz: d8f235e67a77dba643184f1f81d71f40c70be04725d24e26f6a4778b41bb6cf658f7e1a73067b9ebd88bb1552e25862dce57fe21b52653cfceb7d1db066fc32a

data/CHANGELOG.md

@@ -1,26 +1,42 @@
-## [0.7.0] — 2026-07-31
+## [0.9.0] — 2026-07-30
 
-### Added
+### Fixed
+
+- **Agent generator + templates now follow the ask-agent directory convention.**
+  `rails generate ask:agent support_bot` creates `app/agents/support_bot/agent.rb`
+  + `instructions.md` + `tools/` (the discovery layout), not a flat
+  `app/agents/support_bot.rb`. Templates no longer reference the removed
+  `system_prompt`/`tool` Definition DSL — they use `model`, `provider`,
+  `max_turns`, and `tools` (plural), with instructions auto-loaded from
+  the sibling `instructions.md`.
 
-- **`ask:workflow NAME` generator** — scaffolds a workflow module under `app/workflows/<name>/` with `workflow.rb` and `steps/` directory. Requires ask-graph; aborts with a helpful message if it's not installed.
+## [0.8.0] — 2026-07-31
 
-- **`ask:agent NAME` generator** — scaffolds an individual agent under `app/agents/`.
+### Added
 
-- **ask-graph support in install generator** — `ask:install` now creates `app/workflows/application_workflow.rb` and the workflows directory when ask-graph is installed. Pass `--skip-graph` to skip. The initializer's graph configuration block is only generated when ask-graph is present:
+- **`Ask::Actions` — action convention** — user-facing operations callable from any channel (web, Slack, voice) by name:
 
   ```ruby
-  if defined?(Ask::Graph)
-    Ask::Graph.storage = ASK_STATE
-  end
+  Ask::Actions.dispatch(action: "chats.create", context: context, params: {})
   ```
 
-### Changed
+  - `Ask::Actions::Result` — uniform response shape (`ok`/`error`, `message`, `data`, `code`)
+  - `Ask::Actions::Context` — per-request context bag; attributes become accessors
+  - `Ask::Actions::Backend` — dispatcher with explicit registration (`Ask::Actions.register`) and convention resolution (`"chats.create"` → `Chats::Create` via Zeitwerk). Unknown actions raise `Ask::Actions::Backend::UnknownAction` with guidance.
+
+- **`ask:action NAME [NAMESPACE]` generator** — scaffolds actions:
+
+  ```bash
+  rails generate ask:action create_workspace   # app/actions/create_workspace.rb
+  rails generate ask:action chats create       # app/actions/chats/create.rb → "chats.create"
+  ```
 
-- Shared `ask_state` table is explicitly documented as serving both agent sessions and workflow checkpoints.
+- **Actions in install generator** — `ask:install` now creates `app/actions/` and `app/actions/application_action.rb` (base class with `call(context:, params:)` → `#call`). The initializer documents the actions block with a registration example.
 
 ### Tested
 
-- 11 generator tests, 51 assertions, 0 failures.
+- 25 new tests (Result, Context, Backend, generators) — 48 runs, 141 assertions, 0 failures.
+- End-to-end smoke test in a fresh Rails 8.1 app: `ask:install` + `ask:action` (namespaced and top-level) run; `Ask::Actions.dispatch` resolves both via convention; unknown actions raise with a helpful message.
 
 ## [0.7.0] — 2026-07-31
 

data/README.md

@@ -24,6 +24,7 @@ This creates:
 |---|---|
 | `config/initializers/ask.rb` | Agent + workflow configuration (graph block only generated when ask-graph is installed) |
 | `app/agents/application_agent.rb` | Base class for your agents |
+| `app/actions/application_action.rb` | Base class for your actions |
 | `app/workflows/application_workflow.rb` | Base class for your workflows (only with ask-graph) |
 | `db/migrate/*_create_ask_state.rb` | Shared key-value state table — workflow checkpoints and agent session indexes |
 | `db/migrate/*_create_ask_audit_logs.rb` | Agent session audit log |
@@ -40,16 +41,28 @@ Scaffolds a new agent:
 rails generate ask:agent support_bot
 ```
 
-Creates `app/agents/support_bot.rb`:
+Creates the agent directory convention used by ask-agent discovery:
+
+```
+app/agents/support_bot/
+├── agent.rb           # class Agents::SupportBot < ApplicationAgent
+├── instructions.md    # auto-loaded as the system prompt
+└── tools/             # per-agent tools (referenced with `tools :tool_name`)
+```
 
 ```ruby
+# app/agents/support_bot/agent.rb
 module Agents
   class SupportBot < ApplicationAgent
-    system_prompt "You are a helpful assistant."
+    model "gpt-4o"
+    # tools :search_knowledge_base
   end
 end
 ```
 
+Run it with `Ask::Agent.new("support_bot")`. The directory name is the
+agent name — keep the file named `agent.rb`.
+
 ### `ask:workflow NAME`
 
 Scaffolds a new workflow (requires ask-graph):
@@ -68,6 +81,27 @@ module NotifyCustomer
 end
 ```
 
+### `ask:action NAME [NAMESPACE]`
+
+Scaffolds a new action — a user-facing operation callable from any channel (web, Slack, voice) by name:
+
+```bash
+rails generate ask:action create_workspace   # app/actions/create_workspace.rb
+rails generate ask:action chats create       # app/actions/chats/create.rb
+```
+
+Creates `app/actions/chats/create.rb`:
+
+```ruby
+module Chats
+  class Create < ApplicationAction
+    def call
+      Ask::Actions::Result.ok(message: "Chat created", data: { id: record.id })
+    end
+  end
+end
+```
+
 ### Skipping workflow scaffolding
 
 If you don't use ask-graph, install with:
@@ -132,6 +166,40 @@ result.payment
 
 Checkpoints are saved to the shared `ask_state` table, so workflows resume after crashes.
 
+### Actions
+
+Actions are the operations your users trigger — booking an appointment, creating a chat, upgrading a plan. They live in `app/actions/` and are dispatched **by name**, so any channel (web controller, Slack handler, voice agent) calls the same operation:
+
+```ruby
+# app/actions/chats/create.rb
+module Chats
+  class Create < ApplicationAction
+    def call
+      chat = context.channel.start_new_chat!
+      Ask::Actions::Result.ok(message: "Chat created", data: { chat: chat })
+    end
+  end
+end
+```
+
+```ruby
+# From any channel:
+context = Ask::Actions::Context.new(user: current_user, session: session)
+result = Ask::Actions.dispatch(action: "chats.create", context: context, params: { name: "general" })
+result.ok?      # => true
+result.message  # => "Chat created"
+result.data     # => { chat: ... }
+```
+
+By convention, `"chats.create"` resolves to `Chats::Create` — no registration needed (Zeitwerk autoloads `app/actions/`). Register explicitly to override the convention or to list actions in `Ask::Actions.available`:
+
+```ruby
+# config/initializers/ask.rb
+Ask::Actions.register "chats.create", Chats::Create
+```
+
+Unknown action names raise `Ask::Actions::Backend::UnknownAction` with a helpful message.
+
 ## Configuration
 
 API keys are resolved automatically by `Ask::Auth`:

data/lib/ask/actions/backend.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ask
+  module Actions
+    # Dispatches named actions to their classes.
+    #
+    # Resolution order:
+    #   1. Explicitly registered actions (Ask::Actions.register)
+    #   2. Convention: "chats.create" resolves to Chats::Create
+    #
+    # Convention resolution works with Zeitwerk — app/actions/chats/create.rb
+    # is autoloaded as Chats::Create with no configuration.
+    class Backend
+      class UnknownAction < StandardError
+        def initialize(action)
+          super(<<~MSG.strip)
+            Unknown action #{action.inspect}. Define it at app/actions/ \
+            (e.g. app/actions/chats/create.rb for "chats.create") or register \
+            it with Ask::Actions.register.
+          MSG
+        end
+      end
+
+      CONVENTION = /\A[a-z0-9_.]+\z/
+
+      class << self
+        def register(action, klass)
+          registered[action.to_s] = klass
+        end
+
+        def registered
+          @registered ||= {}
+        end
+
+        def reset!
+          @registered = {}
+        end
+
+        def available
+          registered.keys
+        end
+
+        def dispatch(action:, context:, params: {})
+          resolve(action).call(context: context, params: params)
+        end
+
+        def resolve(action)
+          name = action.to_s
+          registered[name] || resolve_by_convention(name) || unknown_action!(name)
+        end
+
+        private
+
+        def resolve_by_convention(name)
+          return nil unless name.match?(CONVENTION)
+
+          name.split(".").map { |part| part.split("_").map(&:capitalize).join }.join("::").safe_constantize
+        end
+
+        def unknown_action!(name)
+          raise UnknownAction, name
+        end
+      end
+    end
+  end
+end

data/lib/ask/actions/context.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ask
+  module Actions
+    # A per-request bag of context. Channel adapters construct it with
+    # whatever the app needs — user, session, workspace, channel, voice call —
+    # and actions read from it. Attributes become accessors on the instance.
+    #
+    # @example
+    #   context = Ask::Actions::Context.new(user: user, session: session, workspace: workspace)
+    #   context.user      # => user
+    #   context.workspace # => workspace
+    class Context
+      def initialize(**attributes)
+        attributes.each { |name, value| define_attribute(name, value) }
+      end
+
+      private
+
+      def define_attribute(name, value)
+        singleton_class.attr_accessor(name)
+        public_send("#{name}=", value)
+      end
+    end
+  end
+end

data/lib/ask/actions/result.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ask
+  module Actions
+    # The uniform response shape every action returns. Channel adapters
+    # (web controllers, Slack handlers, voice agents) consume the same
+    # contract regardless of which surface a request came from.
+    #
+    # @example
+    #   Ask::Actions::Result.ok(message: "Booking confirmed", data: { booking: booking })
+    #   Ask::Actions::Result.error(message: "Slot unavailable", code: :slot_taken)
+    class Result
+      attr_reader :ok, :message, :data, :code
+
+      def initialize(ok:, message:, data: {}, code: nil)
+        @ok = ok
+        @message = message
+        @data = data
+        @code = code
+      end
+
+      def ok?
+        ok
+      end
+
+      def error?
+        !ok
+      end
+
+      def to_h
+        { ok: ok, message: message, data: data, code: code }
+      end
+
+      def self.ok(message: "", data: {}, code: nil)
+        new(ok: true, message: message, data: data, code: code)
+      end
+
+      def self.error(message: "", data: {}, code: nil)
+        new(ok: false, message: message, data: data, code: code)
+      end
+    end
+  end
+end

data/lib/ask/actions.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "actions/result"
+require_relative "actions/context"
+require_relative "actions/backend"
+
+module Ask
+  # Actions — a convention for user-facing operations callable from any channel.
+  #
+  # Every action lives in app/actions/, responds to .call(context:, params:),
+  # and returns an Ask::Actions::Result. Dispatch them by name so any channel —
+  # web, Slack, voice — can invoke the same operation:
+  #
+  #   Ask::Actions.dispatch(action: "chats.create", context: context, params: {})
+  #
+  # By convention, "chats.create" resolves to Chats::Create (app/actions/chats/create.rb).
+  # Register explicitly to override the convention or to list actions in
+  # Ask::Actions.available:
+  #
+  #   Ask::Actions.register "chats.create", Chats::Create
+  module Actions
+    class << self
+      def register(action, klass)
+        Backend.register(action, klass)
+      end
+
+      def dispatch(action:, context:, params: {})
+        Backend.dispatch(action: action, context: context, params: params)
+      end
+
+      def resolve(action)
+        Backend.resolve(action)
+      end
+
+      def available
+        Backend.available
+      end
+
+      def reset!
+        Backend.reset!
+      end
+    end
+  end
+end

data/lib/ask/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Rails
-    VERSION = "0.7.0"
+    VERSION = "0.9.0"
   end
 end

data/lib/ask/rails.rb

@@ -9,4 +9,5 @@ end
 
 require_relative "rails/version"
 require_relative "rails/state"
+require_relative "actions"
 require_relative "rails/railtie" if defined?(::Rails::Railtie)

data/lib/generators/ask/action/templates/action.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# <%= dispatch_name %> action.
+#
+# Dispatch it from any channel — web, Slack, voice:
+#   Ask::Actions.dispatch(action: "<%= dispatch_name %>", context: context, params: {})
+#
+# Return an Ask::Actions::Result:
+#   Ask::Actions::Result.ok(message: "Done", data: { id: record.id })
+<% if namespaced? -%>
+module <%= namespace_class_name %>
+  class <%= action_class_name %> < ApplicationAction
+    # def call
+    #   Ask::Actions::Result.ok(message: "Done")
+    # end
+  end
+end
+<% else -%>
+class <%= action_class_name %> < ApplicationAction
+  # def call
+  #   Ask::Actions::Result.ok(message: "Done")
+  # end
+end
+<% end -%>

data/lib/generators/ask/action_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Ask
+  module Generators
+    # Creates an action under app/actions. Actions are operations callable
+    # from any channel by name — dispatch them with Ask::Actions.dispatch.
+    #
+    #   rails generate ask:action create_workspace
+    #   # => app/actions/create_workspace.rb  (dispatch name: "create_workspace")
+    #
+    #   rails generate ask:action chats create
+    #   # => app/actions/chats/create.rb      (dispatch name: "chats.create")
+    class ActionGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("action/templates", __dir__)
+
+      desc "Creates an action under app/actions — a user-facing operation callable from any channel"
+
+      def create_action
+        template "action.rb", action_path
+      end
+
+      private
+
+      def action_path
+        if namespaced?
+          "app/actions/#{namespace_name}/#{action_name}.rb"
+        else
+          "app/actions/#{action_name}.rb"
+        end
+      end
+
+      def namespaced?
+        args.any?
+      end
+
+      def namespace_name
+        file_name
+      end
+
+      def action_name
+        namespaced? ? args.first.underscore : file_name
+      end
+
+      def namespace_class_name
+        namespace_name.camelize
+      end
+
+      def action_class_name
+        action_name.camelize
+      end
+
+      def dispatch_name
+        namespaced? ? "#{namespace_name}.#{action_name}" : action_name
+      end
+    end
+  end
+end

data/lib/generators/ask/agent/templates/agent.rb

@@ -6,13 +6,17 @@
 #   agent = Ask::Agent.new("<%= file_name %>")
 #   response = agent.run("Hello")
 #
+# Instructions load automatically from instructions.md next to this file.
+# Per-agent tools live in tools/ — reference them with `tools :tool_name`.
+#
 module Agents
   class <%= class_name %> < ApplicationAgent
     # model "gpt-4o"
-    system_prompt "You are a helpful assistant."
+    # provider :openai
+    # max_turns 25
 
-    # tool :bash
-    # tool :read
-    # tool :grep
+    # tools :bash
+    # tools :read
+    # tools :grep
   end
 end

data/lib/generators/ask/agent/templates/instructions.md

@@ -0,0 +1,9 @@
+# <%= class_name %>
+
+You are a helpful assistant. Describe what this agent does and how it
+should behave. This file is auto-loaded as the system prompt.
+
+## Guidelines
+
+- Be concise and direct.
+- Use the tools available to you when you need information.

data/lib/generators/ask/agent_generator.rb

@@ -7,10 +7,12 @@ module Ask
     class AgentGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("agent/templates", __dir__)
 
-      desc "Creates an agent under app/agents — subclass ApplicationAgent with a model and system prompt"
+      desc "Creates an agent under app/agents/<name>/ — the ask-agent directory convention with agent.rb, instructions.md, and tools/"
 
       def create_agent
-        template "agent.rb", "app/agents/#{file_name}.rb"
+        template "agent.rb", "app/agents/#{file_name}/agent.rb"
+        template "instructions.md", "app/agents/#{file_name}/instructions.md"
+        empty_directory "app/agents/#{file_name}/tools"
       end
     end
   end

data/lib/generators/ask/install/templates/application_action.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Base class for your application's actions.
+#
+# Subclass this to define actions — operations callable from any channel
+# (web, Slack, voice) by name:
+#
+#   module Chats
+#     class Create < ApplicationAction
+#       def call
+#         chat = context.channel.start_new_chat!
+#         Ask::Actions::Result.ok(message: "Chat created", data: { chat: chat })
+#       end
+#     end
+#   end
+#
+# Then dispatch from anywhere:
+#   Ask::Actions.dispatch(action: "chats.create", context: context, params: {})
+#
+class ApplicationAction
+  def self.call(context:, params: {})
+    new(context: context, params: params).call
+  end
+
+  def initialize(context:, params: {})
+    @context = context
+    @params = params
+  end
+
+  private
+
+  attr_reader :context, :params
+end

data/lib/generators/ask/install/templates/application_agent.rb

@@ -4,23 +4,20 @@
 #
 # Subclass this to define agents:
 #
-#   class Agents::SupportBot < ApplicationAgent
+#   # app/agents/support_bot/agent.rb
+#   class SupportBotAgent < ApplicationAgent
 #     model "gpt-4o"
-#     system_prompt "You help users with support questions."
-#
-#     tool :search_knowledge_base
+#     tools :search_knowledge_base
 #   end
 #
+#   # app/agents/support_bot/instructions.md — auto-loaded as the system prompt
+#   # app/agents/support_bot/tools/search_knowledge_base.rb — per-agent tools
+#
 # Then run:
 #   agent = Ask::Agent.new("support_bot")
 #   agent.run("How do I reset my password?")
 #
 class ApplicationAgent < Ask::Agent::Definition
-  # Default instructions — override in subclasses
-  system_prompt "You are a helpful assistant."
-
-  # Uncomment to add built-in tools:
-  # tool :bash
-  # tool :read
-  # tool :grep
+  # Default instructions — override by adding an instructions.md file
+  # in the agent directory, or with option :system_prompt, "..."
 end

data/lib/generators/ask/install/templates/initializer.rb

@@ -31,3 +31,13 @@ if defined?(Ask::Graph)
   # Ask::Graph.default_step_timeout 30
   # Ask::Graph.default_workflow_timeout 60
 end
+
+# Actions
+#
+# Actions live in app/actions/ and are dispatched by name from any channel:
+#   Ask::Actions.dispatch(action: "chats.create", context: context, params: {})
+#
+# By convention, "chats.create" resolves to Chats::Create
+# (app/actions/chats/create.rb). Register explicitly to override the
+# convention or to list the action in Ask::Actions.available:
+# Ask::Actions.register "chats.create", Chats::Create

data/lib/generators/ask/install_generator.rb

@@ -27,6 +27,14 @@ module Ask
         template "application_agent.rb", "app/agents/application_agent.rb"
       end
 
+      def create_actions_directory
+        empty_directory "app/actions"
+      end
+
+      def create_application_action
+        template "application_action.rb", "app/actions/application_action.rb"
+      end
+
       def create_workflows_directory
         return if skip_graph?
         empty_directory "app/workflows"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-rails
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -105,12 +105,20 @@ files:
 - LICENSE
 - README.md
 - lib/ask-rails.rb
+- lib/ask/actions.rb
+- lib/ask/actions/backend.rb
+- lib/ask/actions/context.rb
+- lib/ask/actions/result.rb
 - lib/ask/rails.rb
 - lib/ask/rails/railtie.rb
 - lib/ask/rails/state.rb
 - lib/ask/rails/version.rb
+- lib/generators/ask/action/templates/action.rb
+- lib/generators/ask/action_generator.rb
 - lib/generators/ask/agent/templates/agent.rb
+- lib/generators/ask/agent/templates/instructions.md
 - lib/generators/ask/agent_generator.rb
+- lib/generators/ask/install/templates/application_action.rb
 - lib/generators/ask/install/templates/application_agent.rb
 - lib/generators/ask/install/templates/application_workflow.rb
 - lib/generators/ask/install/templates/audit_log_migration.rb