A platform for community discussion. Free, open, simple.
FEATURE: Let AI agents read and write workflow data tables
Régis Hanol7e8e23cbeadf
diff --git a/plugins/discourse-workflows/config/locales/server.en.yml b/plugins/discourse-workflows/config/locales/server.en.ymlindex d3b14acbb90..64ceb2159e1 100644--- a/plugins/discourse-workflows/config/locales/server.en.yml+++ b/plugins/discourse-workflows/config/locales/server.en.yml@@ -267,6 +267,9 @@ en:search_chat_channels: "Searches chat channel names and IDs for workflow parameters"search_chat_integration_channels: "Searches external chat integration channel labels and IDs for workflow parameters"workflow_validate_script: "Runs workflow Code node JavaScript with test data"+ data_table_schema: "Lists workflow data tables with their columns"+ data_table_query: "Reads rows from a workflow data table"+ data_table_write: "Inserts, updates, upserts or deletes workflow data table rows"tool_summary:workflow_node_catalog: "Reading workflow node catalog"workflow_ai_agent_catalog: "Reading AI agent catalog"@@ -278,6 +281,9 @@ en:search_chat_channels: "Searching chat channels"search_chat_integration_channels: "Searching external chat integration channels"workflow_validate_script: "Testing script"+ data_table_schema: "Reading data table schema"+ data_table_query: "Querying data table"+ data_table_write: "Writing to data table"tool_description:workflow_node_catalog: "Read workflow node catalog"workflow_ai_agent_catalog: "Read AI agent catalog"@@ -289,6 +295,22 @@ en:search_chat_channels: "Searched chat channels"search_chat_integration_channels: "Searched external chat integration channels"workflow_validate_script: "Tested script"+ data_table_schema: "Read data table schema"+ data_table_query: "Queried data table"+ data_table_write: "Wrote to data table"+ tool_options:+ data_table_schema:+ allowed_tables:+ name: "Allowed tables"+ description: "Comma-separated data table names or ids this agent may use. Leave empty to allow all tables."+ data_table_query:+ allowed_tables:+ name: "Allowed tables"+ description: "Comma-separated data table names or ids this agent may use. Leave empty to allow all tables."+ data_table_write:+ allowed_tables:+ name: "Allowed tables"+ description: "Comma-separated data table names or ids this agent may use. Leave empty to allow all tables."reviewables:reasons:workflow_flagged_user: "A workflow added this user to the review queue."diff --git a/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/base.rb b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/base.rbindex 552495d10ed..be402a5c8c6 100644--- a/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/base.rb+++ b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/base.rb@@ -7,13 +7,11 @@ module DiscourseWorkflowsprivatedef ensure_can_manage_workflows!- return true if context.user&.guardian&.can_manage_workflows?-- false+ !!context.user&.guardian&.can_manage_workflows?enddef not_allowed_response- error_response(I18n.t("discourse.errors.disallowed"))+ error_response(I18n.t("invalid_access"))enddef json_safe(value)diff --git a/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_base.rb b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_base.rbnew file mode 100644index 00000000000..a1c7df7ae35--- /dev/null+++ b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_base.rb@@ -0,0 +1,90 @@+# frozen_string_literal: true++module DiscourseWorkflows+ module Ai+ module Tools+ class DataTableBase < Base+ NUMERIC_ID = /\A\d+\z/++ TABLE_SCHEMA = { type: "string", description: "Data table name or id" }.freeze++ FILTER_SCHEMA = {+ type: "object",+ description: "Row filter. Omit to match every row.",+ additionalProperties: false,+ properties: {+ type: {+ type: "string",+ enum: DiscourseWorkflows::NormalizedFilter::VALID_TYPES,+ },+ filters: {+ type: "array",+ items: {+ type: "object",+ additionalProperties: false,+ required: %w[columnName condition],+ properties: {+ columnName: {+ type: "string",+ },+ condition: {+ type: "string",+ enum: DiscourseWorkflows::NormalizedFilter::VALID_CONDITIONS,+ description:+ "like, ilike and not_ilike match a substring; wildcards are not supported.",+ },+ value: {+ type: "string",+ description:+ "Compared after conversion to the column type. Omit with eq/neq to match empty cells.",+ },+ },+ },+ },+ },+ }.freeze++ def self.accepted_options+ [option(:allowed_tables, type: :string)]+ end++ private++ def authorized+ return not_allowed_response if !ensure_can_manage_workflows!++ yield+ rescue DataTables::InvalidInput,+ DiscourseWorkflows::DataTables::Facade::StatementTimeout => e+ error_response(e.message)+ end++ def with_data_table+ authorized do+ reference = parameters[:table].to_s.strip+ data_table =+ (reference.match?(NUMERIC_ID) && allowed_data_tables.find_by(id: reference)) ||+ allowed_data_tables.named(reference).first+ next error_response("Unknown data table '#{reference}'") if data_table.nil?++ yield data_table+ end+ end++ def allowed_data_tables+ scope = DiscourseWorkflows::DataTable.all+ references = options[:allowed_tables].to_s.split(",").map(&:strip).compact_blank+ return scope if references.empty?++ scope.where(id: references.grep(NUMERIC_ID)).or(scope.named(references))+ end++ def node_proxy(data_table)+ DiscourseWorkflows::DataTables::NodeProxy.new(+ DiscourseWorkflows::DataTables::Facade.new(data_table),+ )+ end+ end+ end+ end+enddiff --git a/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_query.rb b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_query.rbnew file mode 100644index 00000000000..022d9de0214--- /dev/null+++ b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_query.rb@@ -0,0 +1,68 @@+# frozen_string_literal: true++module DiscourseWorkflows+ module Ai+ module Tools+ class DataTableQuery < DataTableBase+ def self.signature+ {+ name: name,+ description:+ "Reads rows from a workflow data table. Returns at most #{DiscourseWorkflows::Pagination::MAX_LIMIT} rows per call; use offset to page.",+ json_schema: {+ type: "object",+ additionalProperties: false,+ required: %w[table],+ properties: {+ table: TABLE_SCHEMA,+ filter: FILTER_SCHEMA,+ sort_by: {+ type: "string",+ description: "Column name to sort by",+ },+ sort_direction: {+ type: "string",+ enum: DiscourseWorkflows::DataTables::Facade::SORT_DIRECTIONS.keys,+ },+ limit: {+ type: "integer",+ description:+ "Rows to return, default #{DiscourseWorkflows::Pagination::DEFAULT_LIMIT}, max #{DiscourseWorkflows::Pagination::MAX_LIMIT}",+ },+ offset: {+ type: "integer",+ },+ },+ },+ }+ end++ def self.name+ "data_table_query"+ end++ def invoke+ with_data_table do |data_table|+ result =+ node_proxy(data_table).get_many_rows_and_count(+ filter: parameters[:filter],+ take:+ DiscourseWorkflows::Pagination.normalize_limit(+ Integer(parameters[:limit], exception: false),+ ),+ skip: parameters[:offset],+ sort_by: [parameters[:sort_by], parameters[:sort_direction]],+ )++ {+ status: "success",+ table: data_table.name,+ count: result[:count],+ rows: json_safe(result[:data]),+ }+ end+ end+ end+ end+ end+enddiff --git a/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_schema.rb b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_schema.rbnew file mode 100644index 00000000000..1c436fee13f--- /dev/null+++ b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_schema.rb@@ -0,0 +1,64 @@+# frozen_string_literal: true++module DiscourseWorkflows+ module Ai+ module Tools+ class DataTableSchema < DataTableBase+ def self.signature+ {+ name: name,+ description:+ "Lists the workflow data tables this agent can use, with their columns, column types and row counts. Call this before querying or writing to a data table.",+ parameters: [+ {+ name: "query",+ description: "Optional partial table name to narrow the list",+ type: "string",+ },+ ],+ }+ end++ def self.name+ "data_table_schema"+ end++ def invoke+ authorized do+ scope = allowed_data_tables.order(:name)+ query = parameters[:query].to_s.strip+ if query.present?+ scope =+ scope.where(+ "name ILIKE ?",+ "%#{DiscourseWorkflows::DataTable.sanitize_sql_like(query)}%",+ )+ end++ data_tables = scope.to_a+ stats = DiscourseWorkflows::DataTables::Facade.batch_stats(data_tables.map(&:id))++ {+ status: "success",+ data_tables:+ data_tables.map do |data_table|+ {+ id: data_table.id,+ name: data_table.name,+ columns:+ data_table.user_columns.map do |column|+ {+ name: DiscourseWorkflows::DataTable.column_name(column),+ type: DiscourseWorkflows::DataTable.column_type(column),+ }+ end,+ row_count: stats.dig(data_table.id, :row_count).to_i,+ }+ end,+ }+ end+ end+ end+ end+ end+enddiff --git a/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_write.rb b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_write.rbnew file mode 100644index 00000000000..9cc8154e738--- /dev/null+++ b/plugins/discourse-workflows/lib/discourse_workflows/ai/tools/data_table_write.rb@@ -0,0 +1,99 @@+# frozen_string_literal: true++module DiscourseWorkflows+ module Ai+ module Tools+ class DataTableWrite < DataTableBase+ MUTATIONS = {+ "insert" => :insert_row,+ "update" => :update_rows,+ "upsert" => :upsert_row,+ "delete" => :delete_rows,+ }.freeze+ OPERATIONS = MUTATIONS.keys.freeze++ def self.signature+ {+ name: name,+ description:+ "Inserts, updates, upserts or deletes rows in a workflow data table. upsert inserts one row when the filter matches nothing. count is the number of affected rows; rows holds at most #{DiscourseWorkflows::Pagination::MAX_LIMIT} of them.",+ json_schema: {+ type: "object",+ additionalProperties: false,+ required: %w[table operation],+ properties: {+ table: TABLE_SCHEMA,+ operation: {+ type: "string",+ enum: OPERATIONS,+ },+ data: {+ type: "object",+ description: "Column name to value pairs to write",+ additionalProperties: true,+ },+ filter: FILTER_SCHEMA,+ },+ },+ }+ end++ def self.name+ "data_table_write"+ end++ def self.requires_approval?+ true+ end++ def self.attribute_to_approver?+ true+ end++ def validation_error+ with_data_table do |data_table|+ if OPERATIONS.exclude?(operation)+ next error_response("Unsupported operation '#{operation}'")+ end+ next error_response("data is required") if data.blank? && operation != "delete"++ mutate(data_table, dry_run: true, take: 1)+ nil+ end+ end++ def invoke+ validation_error ||+ with_data_table do |data_table|+ result = mutate(data_table, take: DiscourseWorkflows::Pagination::MAX_LIMIT)++ {+ status: "success",+ table: data_table.name,+ operation:,+ count: result[:count],+ rows: json_safe(result[:data]),+ }+ end+ end++ private++ def mutate(data_table, **options)+ node_proxy(data_table).public_send(+ MUTATIONS.fetch(operation),+ { filter: parameters[:filter], data: }.merge(options),+ )+ end++ def operation+ parameters[:operation].to_s+ end++ def data+ parameters[:data]+ end+ end+ end+ end+enddiff --git a/plugins/discourse-workflows/lib/discourse_workflows/data_tables/node_proxy.rb b/plugins/discourse-workflows/lib/discourse_workflows/data_tables/node_proxy.rbindex 39c97309012..c573e504206 100644--- a/plugins/discourse-workflows/lib/discourse_workflows/data_tables/node_proxy.rb+++ b/plugins/discourse-workflows/lib/discourse_workflows/data_tables/node_proxy.rb@@ -85,9 +85,12 @@ module DiscourseWorkflowsresult = update_matching_rows(query, row_input, options)return result if result[:count] > 0- ensure_insertable!(row_input)- row = options["dry_run"] ? dry_run_insert_row(row_input) : @facade.insert(row_input)- { data: [row], count: 1 }+ insert_row_input(row_input, options)+ end++ def insert_row(options)+ options = normalize_options(options)+ insert_row_input(build_row_input(options["data"]), options)enddef delete_rows(options)@@ -194,6 +197,12 @@ module DiscourseWorkflowswith_count(result.merge(rows: pairs))end+ def insert_row_input(row_input, options)+ ensure_insertable!(row_input)+ row = options["dry_run"] ? dry_run_insert_row(row_input) : @facade.insert(row_input)+ { data: [row], count: 1 }+ end+def dry_run_insert_row(row_input){ "id" => nil, "created_at" => nil, "updated_at" => nil, "dryRunState" => "after" }.merge(row_input.columns,diff --git a/plugins/discourse-workflows/plugin.rb b/plugins/discourse-workflows/plugin.rbindex e5911b46bfc..26ae611c974 100644--- a/plugins/discourse-workflows/plugin.rb+++ b/plugins/discourse-workflows/plugin.rb@@ -220,6 +220,10 @@ after_initialize dorequire_relative "lib/discourse_workflows/ai/tools/search_chat_channels"require_relative "lib/discourse_workflows/ai/tools/search_chat_integration_channels"require_relative "lib/discourse_workflows/ai/tools/workflow_validate_script"+ require_relative "lib/discourse_workflows/ai/tools/data_table_base"+ require_relative "lib/discourse_workflows/ai/tools/data_table_schema"+ require_relative "lib/discourse_workflows/ai/tools/data_table_query"+ require_relative "lib/discourse_workflows/ai/tools/data_table_write"require_relative "lib/discourse_workflows/ai_workflow_author"DiscourseAi.register_feature(@@ -234,6 +238,9 @@ after_initialize do[DiscourseWorkflows::Ai::Tools::SearchChatChannels,DiscourseWorkflows::Ai::Tools::SearchChatIntegrationChannels,+ DiscourseWorkflows::Ai::Tools::DataTableSchema,+ DiscourseWorkflows::Ai::Tools::DataTableQuery,+ DiscourseWorkflows::Ai::Tools::DataTableWrite,],plugin: self,)diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_query_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_query_spec.rbnew file mode 100644index 00000000000..00c62dd1260--- /dev/null+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_query_spec.rb@@ -0,0 +1,67 @@+# frozen_string_literal: true++RSpec.describe DiscourseWorkflows::Ai::Tools::DataTableQuery do+ fab!(:admin)+ fab!(:data_table) do+ Fabricate(+ :discourse_workflows_data_table,+ name: "Contacts",+ columns: [{ name: "email", type: "string" }, { name: "score", type: "number" }],+ ).tap do |data_table|+ [["[email protected]", 1], ["[email protected]", 5], ["[email protected]", 10]].each do |email, score|+ insert_data_table_row(data_table, "email" => email, "score" => score)+ end+ end+ end++ def invoke(agent_options: {}, **params)+ invoke_ai_tool(described_class, params, user: admin, agent_options:)+ end++ it "filters, sorts and pages rows" do+ result =+ invoke(+ table: "Contacts",+ filter: {+ filters: [{ columnName: "score", condition: "gte", value: "5" }],+ },+ sort_by: "score",+ sort_direction: "desc",+ limit: 1,+ offset: 1,+ )++ expect(result).to include(status: "success", table: "Contacts", count: 2)+ expect(result[:rows].map { |row| row["email"] }).to eq(%w[[email protected]])+ end++ it "resolves the table by id or case-insensitive name and clamps a zero limit to one row" do+ result = invoke(table: data_table.id.to_s, limit: 0)++ expect(result).to include(status: "success", count: 3)+ expect(result[:rows].size).to eq(1)+ expect(invoke(table: "contacts", agent_options: { allowed_tables: "CONTACTS" })).to include(+ status: "success",+ count: 3,+ )+ end++ it "returns errors for unknown tables, tables outside allowed_tables and bad offsets" do+ expect(invoke(table: "people")).to eq(status: "error", error: "Unknown data table 'people'")+ expect(invoke(table: "Contacts", offset: true)).to eq(+ status: "error",+ error: "offset must be an integer",+ )+ expect(invoke(table: "Contacts", agent_options: { allowed_tables: "other" })).to eq(+ status: "error",+ error: "Unknown data table 'Contacts'",+ )+ end++ it "lets programming errors propagate instead of reporting them to the model" do+ tool = build_ai_tool(described_class, { table: "Contacts" }, user: admin)+ tool.stubs(:node_proxy).raises(ArgumentError, "unknown keyword: :foo")++ expect { tool.invoke }.to raise_error(ArgumentError, "unknown keyword: :foo")+ end+enddiff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_schema_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_schema_spec.rbnew file mode 100644index 00000000000..b41c947672e--- /dev/null+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_schema_spec.rb@@ -0,0 +1,55 @@+# frozen_string_literal: true++RSpec.describe DiscourseWorkflows::Ai::Tools::DataTableSchema do+ fab!(:admin)+ fab!(:contacts) do+ Fabricate(+ :discourse_workflows_data_table,+ name: "contacts",+ columns: [{ name: "email", type: "string" }, { name: "score", type: "number" }],+ ).tap { |data_table| insert_data_table_row(data_table, "email" => "[email protected]") }+ end+ fab!(:orders) { Fabricate(:discourse_workflows_data_table, name: "orders") }++ def invoke(agent_options: {}, **params)+ invoke_ai_tool(described_class, params, user: admin, agent_options:)+ end++ def names(result)+ result[:data_tables].map { |data_table| data_table[:name] }+ end++ it "is registered as an external tool alongside the query and write tools" do+ expect(DiscourseAi::Agents::Agent.external_tools).to include(+ described_class,+ DiscourseWorkflows::Ai::Tools::DataTableQuery,+ DiscourseWorkflows::Ai::Tools::DataTableWrite,+ )+ end++ it "lists tables with columns and row counts" do+ expect(invoke).to eq(+ status: "success",+ data_tables: [+ {+ id: contacts.id,+ name: "contacts",+ columns: [{ name: "email", type: "string" }, { name: "score", type: "number" }],+ row_count: 1,+ },+ {+ id: orders.id,+ name: "orders",+ columns: [{ name: "value", type: "string" }],+ row_count: 0,+ },+ ],+ )+ end++ it "narrows by query and by the allowed_tables option" do+ expect(names(invoke(query: "ord"))).to eq(%w[orders])+ expect(names(invoke(agent_options: { allowed_tables: "contacts" }))).to eq(%w[contacts])+ expect(names(invoke(agent_options: { allowed_tables: orders.id.to_s }))).to eq(%w[orders])+ end+enddiff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_write_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_write_spec.rbnew file mode 100644index 00000000000..ea51c9b9253--- /dev/null+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/ai/tools/data_table_write_spec.rb@@ -0,0 +1,101 @@+# frozen_string_literal: true++RSpec.describe DiscourseWorkflows::Ai::Tools::DataTableWrite do+ fab!(:admin)+ fab!(:user)+ fab!(:data_table) do+ Fabricate(+ :discourse_workflows_data_table,+ name: "contacts",+ columns: [{ name: "email", type: "string" }, { name: "score", type: "number" }],+ )+ end++ def email_filter(email = "[email protected]")+ { filters: [{ columnName: "email", condition: "eq", value: email }] }+ end++ def invoke(user: admin, **params)+ invoke_ai_tool(described_class, params, user:)+ end++ def emails+ list_data_table_rows(data_table)[:rows].map { |row| row["email"] }+ end++ it "inserts, updates, upserts and deletes rows" do+ inserted = invoke(table: "contacts", operation: "insert", data: { email: "[email protected]" })+ expect(inserted).to include(status: "success", operation: "insert", count: 1)+ expect(emails).to eq(%w[[email protected]])++ updated =+ invoke(table: "contacts", operation: "update", filter: email_filter, data: { score: 7 })+ expect(updated).to include(operation: "update", count: 1)++ upserted =+ invoke(+ table: "contacts",+ operation: "upsert",+ filter: email_filter("[email protected]"),+ data: {+ email: "[email protected]",+ },+ )+ expect(upserted).to include(operation: "upsert", count: 1)++ deleted = invoke(table: "contacts", operation: "delete", filter: email_filter)+ expect(deleted).to include(operation: "delete", count: 1)+ expect(emails).to eq(%w[[email protected]])+ end++ it "rejects unsupported operations, unknown tables and missing data before approval" do+ expect(+ build_ai_tool(+ described_class,+ { table: "nope", operation: "truncate" },+ user: admin,+ ).validation_error,+ ).to eq(status: "error", error: "Unknown data table 'nope'")+ expect(invoke(table: "contacts", operation: "truncate")).to eq(+ status: "error",+ error: "Unsupported operation 'truncate'",+ )+ expect(invoke(table: "contacts", operation: "update", filter: email_filter)).to eq(+ status: "error",+ error: "data is required",+ )+ expect(+ build_ai_tool(+ described_class,+ { table: "contacts", operation: "delete" },+ user: admin,+ ).validation_error,+ ).to match(status: "error", error: /Filter must not be empty/)+ end++ it "rejects invalid insert data before approval without writing" do+ expect(+ build_ai_tool(+ described_class,+ { table: "contacts", operation: "insert", data: { score: "not a number" } },+ user: admin,+ ).validation_error,+ ).to include(status: "error")+ expect(+ build_ai_tool(+ described_class,+ { table: "contacts", operation: "insert", data: { nope: "x" } },+ user: admin,+ ).validation_error,+ ).to include(status: "error")+ expect(emails).to be_empty+ end++ it "denies users who cannot manage workflows without writing" do+ expect(invoke(table: "contacts", operation: "insert", data: { email: "x" }, user: user)).to eq(+ status: "error",+ error: I18n.t("invalid_access"),+ )+ expect(emails).to be_empty+ end+enddiff --git a/plugins/discourse-workflows/spec/support/discourse_workflows_ai_tool_helpers.rb b/plugins/discourse-workflows/spec/support/discourse_workflows_ai_tool_helpers.rbnew file mode 100644index 00000000000..c1e98cc4cc6--- /dev/null+++ b/plugins/discourse-workflows/spec/support/discourse_workflows_ai_tool_helpers.rb@@ -0,0 +1,19 @@+# frozen_string_literal: true++module DiscourseWorkflowsAiToolHelpers+ def build_ai_tool(tool_class, params, user:, agent_options: {})+ tool_class.new(+ params,+ agent_options:,+ bot_user: Discourse.system_user,+ llm: nil,+ context: DiscourseAi::Agents::BotContext.new(messages: [], user:),+ )+ end++ def invoke_ai_tool(tool_class, params, user:, agent_options: {})+ build_ai_tool(tool_class, params, user:, agent_options:).invoke+ end+end++RSpec.configure { |config| config.include(DiscourseWorkflowsAiToolHelpers) }