ask-rails 0.15.3 → 0.15.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e259cec23b1c2cc2ffcf28aa4e88631c6b8324f06faf54796bfe3dd25811c7b8
-  data.tar.gz: 77f68fbcc68972b2f2e7ee25b4c191f3323ef7ac7fe67b87e28c34c133d76888
+  metadata.gz: dcbbe5b90ea4ca26543e8ff114cf09eece8d4bb86870a901e0c01410bb5cd8be
+  data.tar.gz: 1c0f1b2a39714a48432c2486d853803fa300eb1f170703508f09dd5db3f61b7b
 SHA512:
-  metadata.gz: 57ac3ea96821f89d216ef96f6ef903c07c054f8fbced39df03753531a5034edfe5eee0edf4cd6895ca7f187509fec6a17805893ae5958b7262f7e5311c734c9d
-  data.tar.gz: 91b579013d926feb5e5d4991ed65f50478e7d537f272c9113e2e504f3763c36b8f815e4d4974032ce5ea51213b81abf117c5633403b9be4bbe4d9e5d5934fb37
+  metadata.gz: 29a0091cf06a3960bdaf7251f1a2cd3ce38a4cd9f4004d322445e33da7b93373a5db8eb4c859b0e3d1dcaf49cb8933f8ea592be71fed0387cafeda825eb87979
+  data.tar.gz: b12f575ef3851ecd03dc223ca406edf2081dfc177df72af5cff712ceaeedf189b050bc7e67260afb1dfd5065ea9138a3f8338bb4e61e23915c607c2648ac1758

data/README.md

@@ -1,6 +1,8 @@
 # ask-rails
 
-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.
+[![Gem Version](https://badge.fury.io/rb/ask-rails.svg)](https://badge.fury.io/rb/ask-rails)
+
+Rails integration for the [ask-rb](https://github.com/ask-rb) ecosystem. Provides generators, file conventions, and a railtie for building user-facing AI features (agents, workflows, actions) inside a Rails app. Requires Rails 7.1+.
 
 ## Installation
 
@@ -8,7 +10,7 @@ Add to your Gemfile:
 
 ```ruby
 gem "ask-rails"
-gem "ask-graph"   # optional — add only if you use workflows
+gem "ask-graph"   # optional, add only if you use workflows
 ```
 
 Run the installer:
@@ -22,193 +24,75 @@ This creates:
 
 | File | Purpose |
 |---|---|
-| `config/initializers/ask.rb` | Agent + workflow configuration (graph block only generated when ask-graph is installed) |
+| `config/initializers/ask.rb` | Agent, workflow, and action configuration |
 | `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_state.rb` | Shared key-value state table |
 | `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.
+No controllers, views, or routes are generated. The admin chat UI ships in [ask-rails-harness](https://github.com/ask-rb/ask-rails-harness).
 
 ## Generators
 
-### `ask:agent NAME`
-
-Scaffolds a new agent:
-
-```bash
-rails generate ask:agent support_bot
-```
+- `rails generate ask:agent NAME`: creates `app/agents/<name>/` with `agent.rb`, `instructions.md`, and `tools/`.
+- `rails generate ask:action NAME [NAMESPACE]`: creates an action under `app/actions/` (e.g. `ask:action chats create` → `app/actions/chats/create.rb`).
+- `rails generate ask:workflow NAME`: creates `app/workflows/<name>/workflow.rb` and `steps/` (requires ask-graph).
+- `rails generate ask:install --skip-graph`: skips workflow scaffolding when you don't use ask-graph.
 
-Creates the agent directory convention used by ask-agent discovery:
-
-```
-app/agents/support_bot/
-├── agent.rb           # module SupportBot; class Agent < ApplicationAgent
-├── instructions.md    # auto-loaded as the system prompt
-└── tools/             # per-agent tools (referenced with `tools :tool_name`)
-```
+## Quick Start
 
 ```ruby
 # app/agents/support_bot/agent.rb
 module SupportBot
   class Agent < ApplicationAgent
     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):
-
-```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
-```
-
-### `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")
-response = agent.run("Find all open issues in the codebase")
+response = agent.run("How do I reset my password?")
 puts response
 ```
 
-### Workflows
+The directory name is the agent name. `instructions.md` next to `agent.rb` is auto-loaded as the system prompt.
 
-```ruby
-# app/workflows/order_fulfillment/workflow.rb
-module OrderFulfillment
-  class Workflow < ApplicationWorkflow
-    step ValidatePayment
-    step NotifyCustomer
-    step ShipOrder
-  end
-end
-```
+## Essential API
 
-```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
-```
+### Ask::Actions: dispatch operations by name from any channel
 
 ```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
-# 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: ... }
+result.ok?       # => true
+result.message   # => "Chat created"
 ```
 
-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`:
+`"chats.create"` resolves to `Chats::Create` (Zeitwerk autoloads `app/actions/`). Register explicitly to override the convention or list actions:
 
 ```ruby
-# config/initializers/ask.rb
 Ask::Actions.register "chats.create", Chats::Create
+Ask::Actions.available   # => ["chats.create"]
 ```
 
-Unknown action names raise `Ask::Actions::Backend::UnknownAction` with a helpful message.
+Actions return an `Ask::Actions::Result` (`Result.ok` / `Result.error`). Unknown action names raise `Ask::Actions::Backend::UnknownAction`.
+
+### Ask::Rails::State: ActiveRecord-backed state
 
-## Configuration
+`Ask::Rails::State` backs the `ask_state` table and works with any database (PostgreSQL, MySQL, SQLite). ask-graph stores workflow checkpoints there; ask-agent session persistence uses the same table, keyed by convention.
 
-API keys are resolved automatically by `Ask::Auth`:
+## Full documentation
 
-- **Environment variables:** `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.
-- **Rails credentials:** `rails credentials:edit` → add `ask.openai`, `ask.anthropic`
-- **File:** `~/.ask/credentials.yml`
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [Rails app integration](https://ask-rb.github.io/ask-docs/getting-started/rails-app) covers ask-rails in depth. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
-No manual credential setup is required.
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
 
 ## License
 

data/lib/ask/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Rails
-    VERSION = "0.15.3"
+    VERSION = "0.15.4"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-rails
 version: !ruby/object:Gem::Version
-  version: 0.15.3
+  version: 0.15.4
 platform: ruby
 authors:
 - Kaka Ruto
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.40.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.40.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -148,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Rails integration for the ask-rb ecosystem
 test_files: []