saltcorn-ai-fields 0.1.1

package/README.md

@@ -0,0 +1,307 @@
+# saltcorn-ai-fields
+
+AI-powered field actions for [Saltcorn](https://github.com/saltcorn/saltcorn) — fill, summarize, classify, translate, and extract using any LLM configured in the copilot plugin.
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Actions](#actions)
+  - [ai\_fill\_field](#ai_fill_field)
+  - [ai\_summarize](#ai_summarize)
+  - [ai\_classify](#ai_classify)
+  - [ai\_translate](#ai_translate)
+  - [ai\_extract](#ai_extract)
+- [How to use actions in Saltcorn](#how-to-use-actions-in-saltcorn)
+  - [As a button in an Edit view](#as-a-button-in-an-edit-view)
+  - [As a row action in a List view](#as-a-row-action-in-a-list-view)
+  - [As a trigger (on insert / on update)](#as-a-trigger-on-insert--on-update)
+- [Testing locally](#testing-locally)
+- [License](#license)
+
+---
+
+## Requirements
+
+- **Saltcorn** v1.0.0 or later
+- **[saltcorn/copilot](https://github.com/saltcorn/copilot)** plugin — must be installed and configured with an OpenAI or compatible API key. This plugin registers the `llm_generate` function that `saltcorn-ai-fields` uses for all LLM calls.
+
+---
+
+## Installation
+
+### From the plugin store
+
+1. Go to **Settings → Plugins → Plugin Store**
+2. Search for `saltcorn-ai-fields`
+3. Click **Install**
+
+### From npm
+
+```bash
+npm install saltcorn-ai-fields
+```
+
+Then in Saltcorn: **Settings → Plugins → Install from npm** → enter `saltcorn-ai-fields`.
+
+---
+
+## Actions
+
+### `ai_fill_field`
+
+Fill any field using a custom prompt. Reference any other field's value with `{{field_name}}`.
+
+| Config field | Required | Description |
+|---|---|---|
+| Target field | ✅ | The field whose value will be set by the AI |
+| Prompt | ✅ | Describe what to generate. Use `{{field_name}}` to inject row values |
+| Response instruction | — | Extra instruction appended to prompt, e.g. `Be concise. Under 50 words.` |
+
+**Example prompts:**
+
+```
+Write a product description for {{name}} priced at ${{price}}.
+```
+```
+Generate 5 SEO keywords for an article titled "{{title}}" in the {{category}} category.
+```
+```
+Write a professional bio for {{first_name}} {{last_name}}, who works as {{job_title}} at {{company}}.
+```
+
+---
+
+### `ai_summarize`
+
+Summarize a long text field and write the result to another field.
+
+| Config field | Required | Description |
+|---|---|---|
+| Source field | ✅ | Text field to summarize |
+| Target field | ✅ | Field where the summary will be written |
+| Max words | — | Approximate word limit (default: 50) |
+| Style | — | `Concise`, `Bullet points`, `One sentence`, `Formal`, `Casual` |
+
+**Example use cases:**
+- Summarize a long customer review into a one-sentence highlight
+- Condense meeting notes into bullet points
+- Create a short description from a long article body
+
+---
+
+### `ai_classify`
+
+Classify a text field into one of your defined categories.
+
+| Config field | Required | Description |
+|---|---|---|
+| Source field | ✅ | Text field to classify |
+| Target field | ✅ | Field where the category will be written |
+| Categories | ✅ | Comma-separated list, e.g. `Bug,Feature,Question,Other` |
+| Context hint | — | Describe what the text is about to improve accuracy |
+
+**Example use cases:**
+- Classify support tickets: `Bug,Feature Request,Billing,General`
+- Tag blog posts by topic: `Technology,Health,Finance,Travel,Food`
+- Prioritise leads: `Hot,Warm,Cold`
+
+> The AI response is validated against your category list. If the model returns an exact match (case-insensitive), the correctly-cased category is stored.
+
+---
+
+### `ai_translate`
+
+Translate a text field to another language.
+
+| Config field | Required | Description |
+|---|---|---|
+| Source field | ✅ | Text field to translate |
+| Target field | ✅ | Field where the translation will be written |
+| Target language | ✅ | One of 18 supported languages |
+| Formality | — | `Default`, `Formal`, or `Informal` |
+
+**Supported languages:**
+Spanish, French, German, Italian, Portuguese, Dutch, Russian, Japanese, Chinese (Simplified), Chinese (Traditional), Korean, Arabic, Hindi, Turkish, Polish, Swedish, Norwegian, Danish.
+
+---
+
+### `ai_extract`
+
+Extract specific information from a text field — dates, prices, email addresses, names, phone numbers, etc.
+
+| Config field | Required | Description |
+|---|---|---|
+| Source field | ✅ | Text field to extract from |
+| Target field | ✅ | Field where the extracted value will be written |
+| What to extract | ✅ | Plain-English description of what to extract |
+| Fallback value | — | Value to write if the information is not found |
+
+**Example extraction prompts:**
+
+```
+the total price including tax
+```
+```
+the customer's email address
+```
+```
+the delivery date in YYYY-MM-DD format
+```
+```
+the company name mentioned in the first paragraph
+```
+
+> If the information is not found and no fallback is set, the target field is left unchanged and a notification is shown.
+
+---
+
+## How to use actions in Saltcorn
+
+### As a button in an Edit view
+
+This is the most common use case. The button calls the AI when clicked, fills in the field on the form, and the user can review the result before saving.
+
+1. Open a table and go to **Views**
+2. Create or open an **Edit** view
+3. In the view builder, drag a **Button** element into the layout
+4. Click the button element to configure it:
+   - **Label:** e.g. `Generate with AI`
+   - **Action:** select one of the `ai_*` actions
+   - Configure the action fields (source field, target field, prompt, etc.)
+5. Save the view
+6. Open the Edit view on a row, fill in the source fields, and click the button
+
+The AI-generated value appears in the target field immediately. You can edit it before saving.
+
+---
+
+### As a row action in a List view
+
+Row actions run on an already-saved row and update the database directly.
+
+1. Open a **List** view in the builder
+2. Add an **Action** column
+3. Set the action to one of the `ai_*` actions and configure it
+4. Save the view
+5. In the list, click the action button on any row — the target field is updated immediately in the database
+
+---
+
+### As a trigger (on insert / on update)
+
+Triggers let you run AI actions automatically whenever a row is created or updated — no button required.
+
+1. Go to **Settings → Triggers → Add trigger**
+2. Set **When:** `Insert` or `Update`
+3. Set **Table:** your table
+4. Set **Action:** one of the `ai_*` actions
+5. Configure the action fields
+6. Save
+
+Now every time a row is inserted (or updated), the AI action runs automatically. Useful for:
+- Auto-summarising a description when a product is added
+- Auto-classifying a support ticket on creation
+- Auto-translating content into a second language field on save
+
+---
+
+## Testing locally
+
+Use these steps to test the plugin against a local Saltcorn development server before publishing.
+
+### Prerequisites
+
+- Node.js 18+
+- Saltcorn installed globally: `npm install -g @saltcorn/cli`
+- The `saltcorn/copilot` plugin installed and configured with an OpenAI API key
+
+### Step 1 — Clone and install dependencies
+
+```bash
+git clone https://github.com/satwikjambula/saltcorn-ai-fields
+cd saltcorn-ai-fields
+npm install
+```
+
+### Step 2 — Install the plugin into your local Saltcorn instance
+
+```bash
+saltcorn install-plugin -d /absolute/path/to/saltcorn-ai-fields
+```
+
+> Replace `/absolute/path/to/saltcorn-ai-fields` with the actual path, e.g. `/Users/you/Documents/saltcorn-ai-fields`.
+
+This registers the plugin in Saltcorn's SQLite database using `source: local`. Saltcorn loads it directly from the directory — no publish step needed.
+
+### Step 3 — Start the Saltcorn server
+
+```bash
+saltcorn serve
+```
+
+Open [http://localhost:3000](http://localhost:3000) and log in as admin.
+
+### Step 4 — Verify plugin is loaded
+
+Go to **Settings → Plugins** — you should see `saltcorn-ai-fields` listed.
+
+### Step 5 — Create a test table
+
+Go to **Tables → Add table** → name it `test_ai`.
+
+Add these fields:
+
+| Field name | Type | Notes |
+|---|---|---|
+| `body` | String | Long text input field |
+| `summary` | String | Will be filled by AI |
+| `category` | String | Will be filled by AI |
+| `translated` | String | Will be filled by AI |
+
+### Step 6 — Test `ai_summarize`
+
+1. Go to **Views → Add view** → pick `test_ai` table → template: **Edit** → name it `Edit test_ai`
+2. In the builder, drag a **Button** into the layout
+3. Label: `Summarize`, Action: `ai_summarize`
+   - Source field: `body`
+   - Target field: `summary`
+   - Max words: `30`
+   - Style: `One sentence`
+4. Save the view
+5. Go to **Views → Edit test_ai** → enter a long paragraph in `body` → click **Summarize**
+6. The `summary` field should populate with a one-sentence summary
+
+### Step 7 — Test `ai_classify`
+
+1. In the same Edit view, add another button: Label `Classify`, Action: `ai_classify`
+   - Source field: `body`
+   - Target field: `category`
+   - Categories: `Technology,Health,Finance,General`
+2. Save, open the view, enter text, click **Classify**
+3. The `category` field should contain one of the four categories
+
+### Step 8 — Test as a trigger
+
+1. Go to **Settings → Triggers → Add trigger**
+2. When: `Insert`, Table: `test_ai`, Action: `ai_summarize`
+   - Source field: `body`, Target field: `summary`, Max words: `20`
+3. Save
+4. Insert a new row via the Edit view — the `summary` field should be populated automatically on save
+
+### Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `No LLM available` error | Install and configure `saltcorn/copilot` with an API key |
+| Button appears but does nothing | Check the browser console for errors; ensure the action is fully configured |
+| Target field not updating in form | Confirm the target field name matches exactly (case-sensitive) |
+| Trigger not firing | Check **Settings → Event log** for errors |
+
+---
+
+## License
+
+MIT

package/actions.js

@@ -0,0 +1,380 @@
+// ─── LLM helper ───────────────────────────────────────────────────────────────
+
+// Saltcorn copies the plugin to a temp dir without node_modules, so we cannot
+// use require('@saltcorn/data/...') at module load time. Instead we read the
+// already-loaded modules straight from Node's module cache — they are always
+// present because Saltcorn loaded them before our plugin.
+function _saltcornState() {
+  const key = Object.keys(require.cache).find((k) =>
+    /\/@saltcorn\/data\/db\/state(\.[cm]?js)?$/.test(k)
+  );
+  return key ? require.cache[key].exports : null;
+}
+
+function getLLM() {
+  return _saltcornState()?.getState?.()?.functions?.llm_generate ?? null;
+}
+
+async function callLLM(prompt) {
+  const llm = getLLM();
+  if (!llm)
+    throw new Error(
+      "No LLM available. Install the saltcorn/copilot plugin and configure an API key."
+    );
+  const result = await llm.run(prompt, {});
+  return typeof result === "string" ? result.trim() : String(result ?? "").trim();
+}
+
+// interpolate {{field_name}} placeholders with row values
+function interpolate(template, row) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) =>
+    row[key] !== undefined && row[key] !== null ? String(row[key]) : ""
+  );
+}
+
+// persist to DB if row already saved, always return set_fields for form context
+async function applyResult(table, row, user, target_field, value) {
+  if (row && row.id) {
+    await table.updateRow({ [target_field]: value }, row.id, user);
+  }
+  return { set_fields: { [target_field]: value } };
+}
+
+function fieldOptions(fields) {
+  return fields.filter((f) => !f.primary_key).map((f) => f.name);
+}
+
+// ─── actions ──────────────────────────────────────────────────────────────────
+
+const ai_fill_field = {
+  name: "ai_fill_field",
+  description:
+    "Fill a field using a custom AI prompt. Reference any row field with {{field_name}}.",
+  configFields: async ({ table }) => {
+    const fields = table ? table.getFields() : [];
+    return [
+      {
+        name: "target_field",
+        label: "Target field",
+        sublabel: "Field whose value will be set by the AI response",
+        type: "String",
+        required: true,
+        attributes: { options: fieldOptions(fields) },
+      },
+      {
+        name: "prompt_template",
+        label: "Prompt",
+        sublabel:
+          "Describe what to generate. Use {{field_name}} to inject row values. " +
+          "Example: Write a product description for {{name}} priced at {{price}}.",
+        input_type: "textarea",
+        required: true,
+      },
+      {
+        name: "instruction",
+        label: "Response instruction",
+        sublabel:
+          "Optional extra instruction appended to the prompt, e.g. 'Be concise. Under 50 words.'",
+        type: "String",
+        required: false,
+      },
+    ];
+  },
+  run: async ({ row, table, user, configuration: { target_field, prompt_template, instruction } }) => {
+    if (!target_field || !prompt_template)
+      return { error: "target_field and prompt_template are required" };
+
+    const prompt =
+      interpolate(prompt_template, row || {}) +
+      (instruction ? `\n\n${instruction}` : "") +
+      "\n\nRespond with only the generated value, nothing else.";
+
+    const value = await callLLM(prompt);
+    return applyResult(table, row, user, target_field, value);
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ai_summarize = {
+  name: "ai_summarize",
+  description: "Summarize a text field and write the result to another field.",
+  configFields: async ({ table }) => {
+    const fields = table ? table.getFields() : [];
+    const textFields = fields.filter(
+      (f) => !f.primary_key && (f.type?.name === "String" || f.type?.name === "Text")
+    );
+    return [
+      {
+        name: "source_field",
+        label: "Source field",
+        sublabel: "Text field to summarize",
+        type: "String",
+        required: true,
+        attributes: { options: textFields.map((f) => f.name) },
+      },
+      {
+        name: "target_field",
+        label: "Target field",
+        sublabel: "Field where the summary will be written",
+        type: "String",
+        required: true,
+        attributes: { options: fieldOptions(fields) },
+      },
+      {
+        name: "max_words",
+        label: "Max words",
+        sublabel: "Approximate maximum length of the summary",
+        type: "Integer",
+        required: false,
+        attributes: { default: 50 },
+      },
+      {
+        name: "style",
+        label: "Summary style",
+        type: "String",
+        required: false,
+        attributes: {
+          options: ["Concise", "Bullet points", "One sentence", "Formal", "Casual"],
+        },
+      },
+    ];
+  },
+  run: async ({ row, table, user, configuration: { source_field, target_field, max_words, style } }) => {
+    if (!source_field || !target_field)
+      return { error: "source_field and target_field are required" };
+
+    const sourceText = row?.[source_field];
+    if (!sourceText) return { notify: "Source field is empty — nothing to summarize" };
+
+    const wordLimit = max_words || 50;
+    const styleHint = style ? ` Style: ${style}.` : "";
+    const prompt =
+      `Summarize the following text in ${wordLimit} words or fewer.${styleHint} ` +
+      `Respond with only the summary, nothing else.\n\n${sourceText}`;
+
+    const value = await callLLM(prompt);
+    return applyResult(table, row, user, target_field, value);
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ai_classify = {
+  name: "ai_classify",
+  description:
+    "Classify a text field into one of your defined categories and write the result to another field.",
+  configFields: async ({ table }) => {
+    const fields = table ? table.getFields() : [];
+    const textFields = fields.filter(
+      (f) => !f.primary_key && (f.type?.name === "String" || f.type?.name === "Text")
+    );
+    return [
+      {
+        name: "source_field",
+        label: "Source field",
+        sublabel: "Text field to classify",
+        type: "String",
+        required: true,
+        attributes: { options: textFields.map((f) => f.name) },
+      },
+      {
+        name: "target_field",
+        label: "Target field",
+        sublabel: "Field where the category will be written",
+        type: "String",
+        required: true,
+        attributes: { options: fieldOptions(fields) },
+      },
+      {
+        name: "categories",
+        label: "Categories",
+        sublabel: "Comma-separated list of valid categories, e.g. Bug,Feature,Question,Other",
+        type: "String",
+        required: true,
+      },
+      {
+        name: "context_prompt",
+        label: "Context hint",
+        sublabel:
+          "Optional: describe what the text is about to improve accuracy, e.g. 'This is a customer support ticket.'",
+        type: "String",
+        required: false,
+      },
+    ];
+  },
+  run: async ({ row, table, user, configuration: { source_field, target_field, categories, context_prompt } }) => {
+    if (!source_field || !target_field || !categories)
+      return { error: "source_field, target_field, and categories are required" };
+
+    const sourceText = row?.[source_field];
+    if (!sourceText) return { notify: "Source field is empty — nothing to classify" };
+
+    const context = context_prompt ? `${context_prompt}\n\n` : "";
+    const prompt =
+      `${context}Classify the following text into exactly one of these categories: ${categories}.\n\n` +
+      `Text: ${sourceText}\n\n` +
+      `Respond with only the category name, exactly as written above. No explanation.`;
+
+    const value = await callLLM(prompt);
+
+    // validate response is one of the configured categories
+    const validCats = categories.split(",").map((c) => c.trim());
+    const matched = validCats.find(
+      (c) => c.toLowerCase() === value.toLowerCase()
+    );
+    const finalValue = matched || value;
+
+    return applyResult(table, row, user, target_field, finalValue);
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ai_translate = {
+  name: "ai_translate",
+  description: "Translate a text field to another language and write the result to a field.",
+  configFields: async ({ table }) => {
+    const fields = table ? table.getFields() : [];
+    const textFields = fields.filter(
+      (f) => !f.primary_key && (f.type?.name === "String" || f.type?.name === "Text")
+    );
+    return [
+      {
+        name: "source_field",
+        label: "Source field",
+        sublabel: "Text field to translate",
+        type: "String",
+        required: true,
+        attributes: { options: textFields.map((f) => f.name) },
+      },
+      {
+        name: "target_field",
+        label: "Target field",
+        sublabel: "Field where the translation will be written",
+        type: "String",
+        required: true,
+        attributes: { options: fieldOptions(fields) },
+      },
+      {
+        name: "target_language",
+        label: "Target language",
+        sublabel: "Language to translate into",
+        type: "String",
+        required: true,
+        attributes: {
+          options: [
+            "Spanish", "French", "German", "Italian", "Portuguese",
+            "Dutch", "Russian", "Japanese", "Chinese (Simplified)",
+            "Chinese (Traditional)", "Korean", "Arabic", "Hindi",
+            "Turkish", "Polish", "Swedish", "Norwegian", "Danish",
+          ],
+        },
+      },
+      {
+        name: "formality",
+        label: "Formality",
+        type: "String",
+        required: false,
+        attributes: { options: ["Default", "Formal", "Informal"] },
+      },
+    ];
+  },
+  run: async ({ row, table, user, configuration: { source_field, target_field, target_language, formality } }) => {
+    if (!source_field || !target_field || !target_language)
+      return { error: "source_field, target_field, and target_language are required" };
+
+    const sourceText = row?.[source_field];
+    if (!sourceText) return { notify: "Source field is empty — nothing to translate" };
+
+    const formalityHint =
+      formality && formality !== "Default" ? ` Use a ${formality.toLowerCase()} tone.` : "";
+    const prompt =
+      `Translate the following text to ${target_language}.${formalityHint} ` +
+      `Respond with only the translation, nothing else.\n\n${sourceText}`;
+
+    const value = await callLLM(prompt);
+    return applyResult(table, row, user, target_field, value);
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ai_extract = {
+  name: "ai_extract",
+  description:
+    "Extract specific information from a text field (dates, names, numbers, etc.) and write it to another field.",
+  configFields: async ({ table }) => {
+    const fields = table ? table.getFields() : [];
+    const textFields = fields.filter(
+      (f) => !f.primary_key && (f.type?.name === "String" || f.type?.name === "Text")
+    );
+    return [
+      {
+        name: "source_field",
+        label: "Source field",
+        sublabel: "Text field to extract information from",
+        type: "String",
+        required: true,
+        attributes: { options: textFields.map((f) => f.name) },
+      },
+      {
+        name: "target_field",
+        label: "Target field",
+        sublabel: "Field where the extracted value will be written",
+        type: "String",
+        required: true,
+        attributes: { options: fieldOptions(fields) },
+      },
+      {
+        name: "extract_prompt",
+        label: "What to extract",
+        sublabel:
+          "Describe what to extract, e.g. 'the total price', 'the customer email address', 'the delivery date in YYYY-MM-DD format'",
+        type: "String",
+        required: true,
+      },
+      {
+        name: "fallback_value",
+        label: "Fallback value",
+        sublabel: "Value to write if nothing is found (leave blank to leave field unchanged)",
+        type: "String",
+        required: false,
+      },
+    ];
+  },
+  run: async ({ row, table, user, configuration: { source_field, target_field, extract_prompt, fallback_value } }) => {
+    if (!source_field || !target_field || !extract_prompt)
+      return { error: "source_field, target_field, and extract_prompt are required" };
+
+    const sourceText = row?.[source_field];
+    if (!sourceText) return { notify: "Source field is empty — nothing to extract from" };
+
+    const prompt =
+      `From the following text, extract ${extract_prompt}.\n\n` +
+      `Text: ${sourceText}\n\n` +
+      `Respond with only the extracted value, nothing else. ` +
+      `If the information is not present, respond with exactly: NOT_FOUND`;
+
+    const raw = await callLLM(prompt);
+
+    if (raw === "NOT_FOUND") {
+      if (!fallback_value) return { notify: "Could not extract the requested information" };
+      return applyResult(table, row, user, target_field, fallback_value);
+    }
+
+    return applyResult(table, row, user, target_field, raw);
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Saltcorn reads plugin.actions directly as an object (keyed by action name).
+// The function form only applies when the plugin has a configuration_workflow.
+module.exports = {
+  ai_fill_field,
+  ai_summarize,
+  ai_classify,
+  ai_translate,
+  ai_extract,
+};

package/index.js

@@ -0,0 +1,7 @@
+const actions = require("./actions");
+
+module.exports = {
+  sc_plugin_api_version: 1,
+  plugin_name: "saltcorn-ai-fields",
+  actions,
+};

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "saltcorn-ai-fields",
+  "version": "0.1.1",
+  "description": "AI-powered field actions for Saltcorn — fill, summarize, classify, translate, and extract using LLMs",
+  "main": "index.js",
+  "keywords": [
+    "saltcorn",
+    "plugin",
+    "ai",
+    "llm",
+    "openai",
+    "fields",
+    "actions"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@saltcorn/data": ">=0.5.0"
+  }
+}