ask-rails 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87296c9e940bcd34d48e640c3a13c3e3d634b57abf253c434d0919b1dc3388bc
-  data.tar.gz: b8edd3def1dfa96b41d6af0dd842bebb724ac9909c8728d5c8a193a3956e83be
+  metadata.gz: 2abe315f91db647a828734bbb14a557ba8feac60a35e99185f83545704e721cc
+  data.tar.gz: be8595aaa795abec9f74d8bee89e44cdfbb0da792b11e944eb7294529e7bede1
 SHA512:
-  metadata.gz: 4533e9675014317d48c973bcfa23dd30a996d24f9f5e734060c37250735cdf0569df6b38ed2bb60c3a6c6d0dfdb8cf814869d5b628a9f0e37a8f5f91616f8347
-  data.tar.gz: 13fc4f80420ad209ab5e531d254883858acb6e8ac28d7806bac514afcc58c278df79a3c7026dfa69a49f20fbd70fa7ef0ac5ecada3255afedb3d23c338dcff2d
+  metadata.gz: ccc55bc26de71c3382af0dc38ab825e1886ddfcfaf030715bf4dc3ff5c0016fe50dcaa3eb0c0f7dd630cbfeb3f35880cc0d4a28c9f1291ab4822872aa9501336
+  data.tar.gz: 0bab3d0dab2a293485984deb1acf767c14e63cc9cc8995fab0f2a0e70e276d6e847a2573d41cd535632033f1d151dfbe6cb3118a9c0763ac5c08eacf0593bef7

data/CHANGELOG.md

@@ -1,3 +1,72 @@
+## [0.8.0] — 2026-07-31
+
+### Added
+
+- **`Ask::Actions` — action convention** — user-facing operations callable from any channel (web, Slack, voice) by name:
+
+  ```ruby
+  Ask::Actions.dispatch(action: "chats.create", context: context, params: {})
+  ```
+
+  - `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"
+  ```
+
+- **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
+
+- 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
+
+### Added
+
+- **`ask:agent NAME` generator** — scaffolds an individual agent under `app/agents/`:
+
+  ```bash
+  rails generate ask:agent support_bot
+  ```
+
+- **`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:
+
+  ```bash
+  rails generate ask:workflow notify_customer
+  ```
+
+- **`Ask::Rails::State`** — ActiveRecord-backed state adapter for the `ask_state` table. Used by ask-graph for workflow checkpoints. Works with any database adapter (PostgreSQL, MySQL, SQLite). Implements key-value storage plus ordered lists (for agent session indexes).
+
+- **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 block is only generated when ask-graph is present:
+
+  ```ruby
+  if defined?(Ask::Graph)
+    Ask::Graph.storage = Ask::Rails::State.new
+  end
+  ```
+
+### Changed
+
+- **Generators consolidated under `lib/generators/ask/`** — all three generators (`ask:install`, `ask:agent`, `ask:workflow`) now live at the standard Rails discovery path. The old railtie-registered `ask:rails:*` names and the duplicate `lib/generators/ask/install_generator.rb` were removed. No duplicated work between generators: `ask:install` owns one-time setup, `ask:agent`/`ask:workflow` own per-component scaffolding.
+
+- **Initializer fixed to use real APIs** — removed references to non-existent `Ask::State::PostgreSQL` and `config.state`. The agent block now only configures what ask-agent supports (audit log, default model).
+
+- **State migration uses `t.json` instead of `t.jsonb`** — works on PostgreSQL, MySQL, and SQLite.
+
+- **`migration_version` fix** — generated migrations now produce `ActiveRecord::Migration[8.1]` instead of the broken `Migration[[8.1]]`.
+
+### Tested
+
+- 24 tests, 67 assertions, 0 failures — including 13 tests for `Ask::Rails::State` against an in-memory SQLite database.
+- End-to-end smoke test in a fresh Rails app: `ask:install`, `ask:agent`, `ask:workflow` all run; migrations execute; a workflow checkpoint survives a second run via `Ask::Rails::State`.
+
 ## [0.6.0] — 2026-07-29
 
 ### Added

data/README.md

@@ -1,36 +1,121 @@
 # ask-rails
 
-Rails integration for the [ask-rb](https://github.com/ask-rb) ecosystem. Provides generators, file conventions, and railtie for using AI agents in your Rails app.
+Rails integration for the [ask-rb](https://github.com/ask-rb) ecosystem. Provides generators, file conventions, and a railtie for building agents and workflows in your Rails app.
 
 ## Installation
 
+Add to your Gemfile:
+
+```ruby
+gem "ask-rails"
+gem "ask-graph"   # optional — add only if you use workflows
+```
+
+Run the installer:
+
 ```bash
-bundle add ask-rails
+bundle install
 rails generate ask:install
 ```
 
 This creates:
-- `config/initializers/ask.rb` — agent configuration
-- `app/agents/application_agent.rb` — base class for your agents
-- `app/agents/` — directory for agent definitions
 
-## Usage
+| File | Purpose |
+|---|---|
+| `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 |
+
+The `ask_state` table is backed by `Ask::Rails::State` — an ActiveRecord adapter that works with any database (PostgreSQL, MySQL, SQLite). Workflow checkpoints and agent session persistence share the same table, keyed by convention.
+
+## Generators
+
+### `ask:agent NAME`
 
-Define an agent:
+Scaffolds a new agent:
+
+```bash
+rails generate ask:agent support_bot
+```
+
+Creates `app/agents/support_bot.rb`:
 
 ```ruby
-# app/agents/support_bot.rb
-class Agents::SupportBot < ApplicationAgent
-  model "gpt-4o"
-  system_prompt "You help users with support questions."
+module Agents
+  class SupportBot < ApplicationAgent
+    system_prompt "You are a helpful assistant."
+  end
+end
+```
+
+### `ask:workflow NAME`
+
+Scaffolds a new workflow (requires ask-graph):
 
-  tool :bash
-  tool :read
-  tool :grep
+```bash
+rails generate ask:workflow notify_customer
+```
+
+Creates `app/workflows/notify_customer/workflow.rb` and `app/workflows/notify_customer/steps/`:
+
+```ruby
+module NotifyCustomer
+  class Workflow < ApplicationWorkflow
+    # step SomeStep
+  end
 end
 ```
 
-Run it:
+### `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:
+
+```bash
+rails generate ask:install --skip-graph
+```
+
+The initializer still works — the graph block is omitted when ask-graph isn't installed.
+
+## Usage
+
+### Agents
+
+```ruby
+# app/agents/support_bot.rb
+module Agents
+  class SupportBot < ApplicationAgent
+    model "gpt-4o"
+    system_prompt "You help users with support questions."
+
+    tool :bash
+    tool :read
+  end
+end
+```
 
 ```ruby
 agent = Ask::Agent.new("support_bot")
@@ -38,12 +123,71 @@ response = agent.run("Find all open issues in the codebase")
 puts response
 ```
 
-Or use `Ask.chat` for one-off conversations:
+### Workflows
+
+```ruby
+# app/workflows/order_fulfillment/workflow.rb
+module OrderFulfillment
+  class Workflow < ApplicationWorkflow
+    step ValidatePayment
+    step NotifyCustomer
+    step ShipOrder
+  end
+end
+```
+
+```ruby
+# app/workflows/order_fulfillment/steps/validate_payment.rb
+module OrderFulfillment
+  class ValidatePayment
+    def call(context)
+      context.payment = PaymentService.charge(context.input[:order])
+    end
+  end
+end
+```
+
+```ruby
+result = OrderFulfillment::Workflow.call(order: order)
+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
-Ask.chat("Summarize this article: #{text}")
+# 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/railtie.rb

@@ -3,9 +3,6 @@
 module Ask
   module Rails
     class Railtie < ::Rails::Railtie
-      generators do
-        require_relative "generators/install/install_generator"
-      end
     end
   end
 end

data/lib/ask/rails/state.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Ask
+  module Rails
+    # ActiveRecord-backed state adapter for the ask_state table.
+    #
+    # Used by ask-graph (workflow checkpoints) and any other ask component
+    # that needs durable key-value storage in the Rails database. Works with
+    # any Rails database adapter — PostgreSQL, MySQL, SQLite — because the
+    # +value+ column is a portable JSON type.
+    #
+    # @example
+    #   store = Ask::Rails::State.new
+    #   store.set("checkpoint:1", { completed: true })
+    #   store.get("checkpoint:1")  # => { "completed" => true }
+    class State < ::Ask::State::Adapter
+      class Record < ::ActiveRecord::Base
+        self.table_name = "ask_state"
+      end
+
+      def get(key)
+        record = Record.find_by(key: key)
+        return nil unless record
+        return nil if record.expires_at && record.expires_at <= Time.current
+
+        record.value
+      end
+
+      def set(key, value, ttl: nil)
+        record = Record.find_or_initialize_by(key: key)
+        record.value = value
+        record.expires_at = ttl ? Time.current + ttl : nil
+        record.save!
+        value
+      end
+
+      def delete(key)
+        Record.where(key: key).delete_all
+      end
+
+      def clear
+        Record.delete_all
+      end
+
+      def keys(pattern: nil)
+        scope = Record.all
+        if pattern
+          like = self.class.glob_to_like(pattern)
+          scope = scope.where("key LIKE ?", like)
+        end
+        scope.pluck(:key)
+      end
+
+      def set_if_not_exists(key, value, ttl: nil)
+        return false if exists?(key)
+
+        set(key, value, ttl: ttl)
+        true
+      end
+
+      # Ordered lists — stored as an array in the value column.
+      # Required by Ask::Agent::Persistence::Base for session indexes.
+
+      def list_append(key, value, max_length: nil)
+        entries = list_range(key)
+        entries << value
+        entries = entries.last(max_length) if max_length
+        set(key, entries)
+      end
+
+      def list_range(key, start = 0, stop = -1)
+        entries = get(key)
+        return [] unless entries.is_a?(Array)
+
+        entries[start..stop] || []
+      end
+
+      def list_remove(key, value)
+        entries = get(key)
+        return 0 unless entries.is_a?(Array)
+
+        before = entries.size
+        entries.delete(value)
+        set(key, entries)
+        before - entries.size
+      end
+    end
+  end
+end

data/lib/ask/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Rails
-    VERSION = "0.6.0"
+    VERSION = "0.8.0"
   end
 end

data/lib/ask/rails.rb

@@ -8,4 +8,6 @@ module Ask
 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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# <%= class_name %> agent.
+#
+# Run it:
+#   agent = Ask::Agent.new("<%= file_name %>")
+#   response = agent.run("Hello")
+#
+module Agents
+  class <%= class_name %> < ApplicationAgent
+    # model "gpt-4o"
+    system_prompt "You are a helpful assistant."
+
+    # tool :bash
+    # tool :read
+    # tool :grep
+  end
+end

data/lib/generators/ask/agent_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Ask
+  module Generators
+    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"
+
+      def create_agent
+        template "agent.rb", "app/agents/#{file_name}.rb"
+      end
+    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_workflow.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Base class for your application's workflows.
+#
+# Subclass this to define workflows:
+#
+#   module OrderFulfillment
+#     class Workflow < ApplicationWorkflow
+#       step ValidatePayment
+#       step NotifyCustomer
+#       step ShipOrder
+#     end
+#   end
+#
+# Then run:
+#   result = OrderFulfillment::Workflow.call({ order: order })
+#
+class ApplicationWorkflow < Ask::Graph
+  # Shared defaults — uncomment as needed:
+  # step_timeout 30
+  # workflow_timeout 60
+  # storage PostgresStore.new
+end

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

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-class CreateAskAuditLogs < ActiveRecord::Migration[8.1]
+# Migration for ask-agent's audit log table.
+# This table records session events (tool calls, errors, token usage, etc.)
+# from every agent that has audit_log configured.
+class CreateAskAuditLogs < ActiveRecord::Migration[<%= migration_version %>]
   def change
     create_table :ask_audit_logs, if_not_exists: true do |t|
       t.string :session_id, null: false

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Ask Agent Configuration
-# ========================
+# Ask Configuration
+# =================
 #
 # API keys are resolved automatically by Ask::Auth:
 #   - Environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
@@ -10,10 +10,34 @@
 #
 # See https://github.com/ask-rb/ask-auth for details.
 
+# Agents
 Ask::Agent.configure do |config|
-  # Enable audit logging to the ask_audit_logs table
+  # Audit log for session events (ask_audit_logs table)
   # config.audit_log = { adapter: :active_record }
 
-  # Optional: set a default model
   # config.default_model = "gpt-4o"
 end
+
+# Workflows (ask-graph)
+#
+# The graph block is only generated when ask-graph is installed.
+# Run `bundle add ask-graph` then `rails generate ask:install` to add it.
+if defined?(Ask::Graph)
+  # Checkpoint storage for workflow crash recovery — backed by the
+  # ask_state table (created by the migration) in your Rails database.
+  # Works with any database adapter: PostgreSQL, MySQL, SQLite.
+  Ask::Graph.storage = Ask::Rails::State.new
+
+  # 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/templates/state_migration.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
-class CreateAskState < ActiveRecord::Migration[8.1]
+# Migration for ask-rb's shared key-value state table.
+# Used by ask-agent (session persistence) and ask-graph (workflow checkpoints).
+# This single table serves both components — keys are namespaced by convention.
+# The json column type works on PostgreSQL, MySQL, and SQLite.
+class CreateAskState < ActiveRecord::Migration[<%= migration_version %>]
   def change
     create_table :ask_state do |t|
       t.string :key, null: false
-      t.jsonb :value, null: false, default: {}
+      t.json :value, null: false, default: {}
       t.datetime :expires_at
       t.timestamps
 

data/lib/generators/ask/install_generator.rb

@@ -6,34 +6,62 @@ require "rails/generators/active_record"
 module Ask
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
-      include ::Rails::Generators::Migration
+      include ::ActiveRecord::Generators::Migration
 
       source_root File.expand_path("install/templates", __dir__)
 
-      desc "Sets up ask-rb for Rails — creates initializer, state and audit log migrations"
+      desc "Sets up ask-rb for Rails — creates initializer, agents and workflows directories, and shared state migrations"
+
+      class_option :skip_graph, type: :boolean, default: false,
+                                desc: "Skip workflow scaffolding even if ask-graph is installed"
 
       def create_initializer
         template "initializer.rb", "config/initializers/ask.rb"
       end
 
+      def create_agents_directory
+        empty_directory "app/agents"
+      end
+
+      def create_application_agent
+        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"
+      end
+
+      def create_application_workflow
+        return if skip_graph?
+        template "application_workflow.rb", "app/workflows/application_workflow.rb"
+      end
+
       def create_state_migration
-        template "state_migration.rb", "db/migrate/#{next_migration_number}_create_ask_state.rb"
+        migration_template "state_migration.rb", "db/migrate/create_ask_state.rb"
       end
 
       def create_audit_log_migration
-        template "audit_log_migration.rb", "db/migrate/#{next_migration_number}_create_ask_audit_logs.rb"
+        migration_template "audit_log_migration.rb", "db/migrate/create_ask_audit_logs.rb"
       end
 
       private
 
-      def next_migration_number
-        # Rails requires exactly YYYYMMDDHHMMSS format
-        @migration_suffix ||= 0
-        now = Time.now.utc.strftime("%Y%m%d%H%M")
-        "#{now}#{format('%02d', @migration_suffix)}"
-      ensure
-        @migration_suffix = (@migration_suffix || 0) + 1
+      def skip_graph?
+        options[:skip_graph] || !defined?(Ask::Graph)
       end
+
+        def migration_version
+          ActiveRecord::Migration.current_version
+        end
     end
   end
 end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# <%= class_name %> workflow.
+#
+# Define steps as plain Ruby classes in steps/ — each responds to call(context).
+# Compose other workflows via Workflow.call(context) inside a step.
+#
+#   module <%= class_name %>
+#     class Workflow < ApplicationWorkflow
+#       step SomeStep
+#       step OtherStep, if: :condition?
+#
+#       private
+#
+#       def condition?
+#         context.some_flag
+#       end
+#     end
+#   end
+#
+# Run it:
+#   result = <%= class_name %>::Workflow.call({ input: value })
+#
+module <%= class_name %>
+  class Workflow < ApplicationWorkflow
+    # step SomeStep
+  end
+end

data/lib/generators/ask/workflow_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Ask
+  module Generators
+    class WorkflowGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("workflow/templates", __dir__)
+
+      desc "Creates a workflow under app/workflows — module directory, Workflow class, and steps directory"
+
+      def verify_ask_graph
+        return if defined?(Ask::Graph)
+
+        raise ::Thor::Error, <<~MSG.strip
+          ask-graph is not installed. Add it to your Gemfile and run `bundle install` first:
+
+            gem "ask-graph"
+        MSG
+      end
+
+      def create_workflow_directory
+        empty_directory "app/workflows/#{file_name}"
+      end
+
+      def create_workflow
+        template "workflow.rb", "app/workflows/#{file_name}/workflow.rb"
+      end
+
+      def create_steps_directory
+        empty_directory "app/workflows/#{file_name}/steps"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-rails
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
 description: Rails generators, file conventions, and railtie for using ask-agent in
   Rails apps.
 email:
@@ -91,18 +105,27 @@ 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/generators/install/install_generator.rb
-- lib/ask/rails/generators/install/templates/application_agent.rb
-- lib/ask/rails/generators/install/templates/audit_log_migration.rb
-- lib/ask/rails/generators/install/templates/initializer.rb
-- lib/ask/rails/generators/install/templates/state_migration.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_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
 - lib/generators/ask/install/templates/initializer.rb
 - lib/generators/ask/install/templates/state_migration.rb
 - lib/generators/ask/install_generator.rb
+- lib/generators/ask/workflow/templates/workflow.rb
+- lib/generators/ask/workflow_generator.rb
 homepage: https://github.com/ask-rb/ask-rails
 licenses:
 - MIT

data/lib/ask/rails/generators/install/install_generator.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require "rails/generators"
-require "rails/generators/active_record"
-
-module Ask
-  module Rails
-    module Generators
-      class InstallGenerator < ::Rails::Generators::Base
-        include ::Rails::Generators::Migration
-
-        source_root File.expand_path("templates", __dir__)
-
-        desc "Sets up ask-rb for Rails — creates initializer, agents directory, state and audit log migrations"
-
-        def create_initializer
-          template "initializer.rb", "config/initializers/ask.rb"
-        end
-
-        def create_application_agent
-          template "application_agent.rb", "app/agents/application_agent.rb"
-        end
-
-        def create_agents_directory
-          empty_directory "app/agents"
-          create_file "app/agents/.keep", "" unless options[:skip_keep]
-        end
-
-        def create_state_migration
-          migration_template "state_migration.rb", "db/migrate/create_ask_state.rb"
-        end
-
-        def create_audit_log_migration
-          migration_template "audit_log_migration.rb", "db/migrate/create_ask_audit_logs.rb"
-        end
-
-        private
-
-        def migration_version
-          "[#{ActiveRecord::Migration.current_version}]"
-        end
-      end
-    end
-  end
-end

data/lib/ask/rails/generators/install/templates/audit_log_migration.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-# Migration for ask-agent's audit log table.
-# This table records session events (tool calls, errors, token usage, etc.)
-# from every agent that has audit_log configured.
-class CreateAskAuditLogs < ActiveRecord::Migration[<%= migration_version %>]
-  def change
-    create_table :ask_audit_logs, if_not_exists: true do |t|
-      t.string :session_id, null: false
-      t.string :event_type, null: false
-      t.jsonb :data, default: {}
-      t.datetime :timestamp, null: false
-      t.timestamps
-
-      t.index [:session_id, :event_type]
-      t.index :timestamp
-    end
-  end
-end

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

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-# Ask Agent Configuration
-# ========================
-#
-# API keys are resolved automatically by Ask::Auth:
-#   - Environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
-#   - Rails credentials: rails credentials:edit → ask.openai, ask.anthropic
-#   - ~/.ask/credentials.yml
-#
-# See https://github.com/ask-rb/ask-auth for details.
-
-# Shared key-value state store for agent sessions and graph checkpoints.
-# Uses the ask_state table created by the migration.
-ASK_STATE = Ask::State::PostgreSQL.new(
-  table_name: :ask_state
-)
-
-Ask::Agent.configure do |config|
-  # State persistence for agent sessions
-  config.state = ASK_STATE
-
-  # Audit log for session events
-  config.audit_log = { adapter: :active_record }
-
-  # config.default_model = "gpt-4o"
-end

data/lib/ask/rails/generators/install/templates/state_migration.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-# Migration for ask-rb's shared key-value state table.
-# Used by ask-agent (session persistence) and ask-graph (workflow checkpoints).
-# This single table serves both components — keys are namespaced by convention.
-class CreateAskState < ActiveRecord::Migration[<%= migration_version %>]
-  def change
-    create_table :ask_state do |t|
-      t.string :key, null: false
-      t.jsonb :value, null: false, default: {}
-      t.datetime :expires_at
-      t.timestamps
-
-      t.index :key, unique: true
-      t.index :expires_at
-    end
-  end
-end