saltcorn-ai-embed 0.1.0

package/README.md

@@ -0,0 +1,233 @@
+# saltcorn-ai-embed
+
+Vector embedding and semantic search for [Saltcorn](https://github.com/saltcorn/saltcorn) — embed any text field using OpenAI and search your table by meaning, not just keywords.
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [How it works](#how-it-works)
+- [Plugin configuration](#plugin-configuration)
+- [Action: ai_embed](#action-ai_embed)
+- [View: SemanticSearch](#view-semanticsearch)
+- [Testing locally](#testing-locally)
+- [License](#license)
+
+---
+
+## Requirements
+
+- **Saltcorn** v1.0.0 or later
+- An **OpenAI API key** (for generating embeddings via `text-embedding-3-small` or similar)
+
+No pgvector or special database extension required — similarity is computed in JavaScript and works with any Saltcorn database including SQLite.
+
+---
+
+## Installation
+
+### From the plugin store
+
+1. Go to **Settings → Plugins → Plugin Store**
+2. Search for `saltcorn-ai-embed`
+3. Click **Install**
+4. Go to **Settings → Plugins → Configure → saltcorn-ai-embed** and enter your OpenAI API key
+
+### From npm
+
+```bash
+npm install saltcorn-ai-embed
+```
+
+Then in Saltcorn: **Settings → Plugins → Install from npm** → enter `saltcorn-ai-embed`.
+
+---
+
+## How it works
+
+1. **Embed your rows** — use the `ai_embed` action to call the OpenAI embeddings API for each row's text field. The resulting vector (an array of ~1500 floats) is stored as JSON in a dedicated field.
+2. **Search by meaning** — add a `SemanticSearch` view to any page. When the user types a query, it is embedded the same way, then compared against every stored vector using cosine similarity. The top-N most similar rows are returned.
+
+This works well for up to ~50,000 rows. Beyond that, consider offloading similarity search to pgvector.
+
+---
+
+## Plugin configuration
+
+Go to **Settings → Plugins → Installed → saltcorn-ai-embed → Configure**.
+
+| Field | Required | Description |
+|---|---|---|
+| OpenAI API key | ✅ | Your `sk-...` key from [platform.openai.com](https://platform.openai.com) |
+| Embedding model | — | Model used for all embeddings (default: `text-embedding-3-small`) |
+
+**Supported models:**
+
+| Model | Dimensions | Best for |
+|---|---|---|
+| `text-embedding-3-small` | 1536 | Fast, cheap, accurate enough for most use cases |
+| `text-embedding-3-large` | 3072 | Higher accuracy, higher cost |
+| `text-embedding-ada-002` | 1536 | Legacy — prefer `3-small` for new projects |
+
+> All rows must be embedded with the **same model**. If you change the model, re-run `ai_embed` on all rows.
+
+---
+
+## Action: `ai_embed`
+
+Generates a vector embedding for a text field and stores it as a JSON array in another field. Use this to prepare rows for semantic search.
+
+| Config field | Required | Description |
+|---|---|---|
+| Source field | ✅ | Text field to embed (the content that will be searched) |
+| Embedding field | ✅ | Field where the vector JSON will be stored — use a **Text** field or a String field with no max length |
+
+### Usage patterns
+
+**As a trigger (recommended)** — embed automatically on every insert or update:
+
+1. Go to **Settings → Triggers → Add trigger**
+2. When: `Insert`, Table: your table, Action: `ai_embed`
+3. Source field: your text field, Embedding field: your vector field
+4. Save — every new row is embedded automatically
+
+**As a row action in a List view** — bulk-embed existing rows by clicking a button per row.
+
+**As a button in an Edit view** — embed on demand before saving.
+
+### Embedding field setup
+
+Add a field to your table:
+
+| Setting | Value |
+|---|---|
+| Name | `embedding` (or any name) |
+| Type | **Text** |
+| Required | No |
+
+Text fields have no length limit in Saltcorn's SQLite and PostgreSQL backends, which is needed because a `text-embedding-3-small` vector serialises to ~9 KB of JSON.
+
+---
+
+## View: `SemanticSearch`
+
+Renders a search input. On submit, embeds the query and returns the most similar rows ranked by cosine similarity.
+
+### Configuration
+
+| Field | Required | Description |
+|---|---|---|
+| Embedding field | ✅ | Field that stores the pre-computed JSON vectors |
+| Result fields | ✅ | Comma-separated list of fields to display, e.g. `title,body,category` |
+| Max results | — | Maximum number of rows to return (default: 5) |
+| Minimum similarity | — | Cosine similarity threshold 0–1 — rows below this are hidden (default: 0.5) |
+| Search placeholder | — | Placeholder text in the search input |
+
+### Adding to a page
+
+1. Go to **Views → Add view**
+2. Select your table, template: **SemanticSearch**, give it a name (e.g. `article-search`)
+3. Set **Embedding field** to the field that holds your vectors
+4. Set **Result fields** to the fields you want displayed, e.g. `title,summary,category`
+5. Save
+6. Go to **Pages**, open any page in the builder, drag a **View** element, select `article-search`
+
+### Results
+
+Each result row shows the configured fields plus a **Score** badge (percentage cosine similarity). Results are sorted highest-to-lowest.
+
+---
+
+## Testing locally
+
+### Prerequisites
+
+- Node.js 18+
+- Saltcorn installed globally: `npm install -g @saltcorn/cli`
+- An OpenAI API key
+
+### Step 1 — Clone and register
+
+```bash
+git clone https://github.com/satwikjambula/saltcorn-ai-embed
+cd saltcorn-ai-embed
+
+sqlite3 ~/Library/Application\ Support/saltcorn/scdb.sqlite \
+  "INSERT OR REPLACE INTO _sc_plugins (name, source, location) \
+   VALUES ('saltcorn-ai-embed', 'local', '$(pwd)');"
+```
+
+### Step 2 — Start the server
+
+```bash
+saltcorn serve
+```
+
+### Step 3 — Configure the plugin
+
+1. Go to **Settings → Plugins → Installed → saltcorn-ai-embed → Configure**
+2. Enter your OpenAI API key
+3. Leave model as `text-embedding-3-small`
+4. Save
+
+### Step 4 — Create a test table
+
+Go to **Tables → Add table**, name it `articles`. Add fields:
+
+| Field | Type |
+|---|---|
+| `title` | String |
+| `body` | Text |
+| `embedding` | Text |
+
+### Step 5 — Insert test rows
+
+Insert a few rows via **Views → Add view → Edit** or directly in the table view. Example body texts to try:
+
+- `"The Eiffel Tower is a wrought-iron lattice tower in Paris, France."`
+- `"Python is a high-level programming language known for its readability."`
+- `"Photosynthesis allows plants to convert sunlight into glucose."`
+- `"The French Revolution began in 1789 and transformed European politics."`
+
+### Step 6 — Embed the rows
+
+1. Go to **Settings → Triggers → Add trigger**
+2. When: `Insert`, Table: `articles`, Action: `ai_embed`
+3. Source field: `body`, Embedding field: `embedding`
+4. Save
+
+Re-insert (or update) each row — the trigger will call the OpenAI API and populate the `embedding` field.
+
+Alternatively, add a row action button to a List view with the `ai_embed` action and click it for each row.
+
+### Step 7 — Create the SemanticSearch view
+
+1. **Views → Add view**, Table: `articles`, Template: **SemanticSearch**, Name: `article-search`
+2. Embedding field: `embedding`, Result fields: `title,body`, Max results: `5`, Min similarity: `0.4`
+3. Save
+
+### Step 8 — Search
+
+Open the view. Try queries like:
+
+- `"Paris architecture"` → should surface the Eiffel Tower row
+- `"biology and nature"` → should surface the photosynthesis row
+- `"coding and software"` → should surface the Python row
+
+### Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `No OpenAI API key configured` | Go to **Settings → Plugins → Configure → saltcorn-ai-embed** |
+| `OpenAI embeddings error 401` | API key is invalid or expired |
+| `embedding_field not configured` | Re-open the SemanticSearch view config and set the embedding field |
+| All scores are 0 or no results | Rows may not have embeddings yet — run `ai_embed` on them first |
+| Results seem irrelevant | Lower the Min similarity threshold; try `text-embedding-3-large` for better accuracy |
+
+---
+
+## License
+
+MIT

package/actions.js

@@ -0,0 +1,65 @@
+const { embed, getPluginCfg } = require("./embed-util");
+
+function fieldOptions(fields) {
+  return fields.filter((f) => !f.primary_key).map((f) => f.name);
+}
+
+function textFieldOptions(fields) {
+  return fields
+    .filter(
+      (f) =>
+        !f.primary_key &&
+        (f.type?.name === "String" || f.type?.name === "Text")
+    )
+    .map((f) => f.name);
+}
+
+// ─── ai_embed ─────────────────────────────────────────────────────────────────
+
+const ai_embed = {
+  name: "ai_embed",
+  description:
+    "Generate a vector embedding for a text field and store it as JSON in another field. " +
+    "Use this to prepare rows for semantic search.",
+  configFields: async ({ table }) => {
+    const fields = table ? table.getFields() : [];
+    return [
+      {
+        name: "source_field",
+        label: "Source field",
+        sublabel: "Text field to embed",
+        type: "String",
+        required: true,
+        attributes: { options: textFieldOptions(fields) },
+      },
+      {
+        name: "target_field",
+        label: "Embedding field",
+        sublabel:
+          "Field where the vector will be stored as a JSON array. " +
+          "Use a String field with a large max length, or a Text field.",
+        type: "String",
+        required: true,
+        attributes: { options: fieldOptions(fields) },
+      },
+    ];
+  },
+  run: async ({ row, table, user, configuration: { source_field, target_field } }) => {
+    if (!source_field || !target_field)
+      return { error: "source_field and target_field are required" };
+
+    const text = row?.[source_field];
+    if (!text) return { notify: "Source field is empty — nothing to embed" };
+
+    const cfg = getPluginCfg();
+    const vector = await embed(text, cfg);
+    const value = JSON.stringify(vector);
+
+    if (row?.id) {
+      await table.updateRow({ [target_field]: value }, row.id, user);
+    }
+    return { set_fields: { [target_field]: value } };
+  },
+};
+
+module.exports = { ai_embed };

package/embed-util.js

@@ -0,0 +1,76 @@
+// Shared utilities: module-cache lookup, OpenAI call, cosine similarity
+
+// ─── Saltcorn state ───────────────────────────────────────────────────────────
+
+function getState() {
+  const key = Object.keys(require.cache).find((k) =>
+    /\/@saltcorn\/data\/db\/state(\.[cm]?js)?$/.test(k)
+  );
+  return key ? require.cache[key].exports.getState?.() : null;
+}
+
+function getPluginCfg() {
+  return getState()?.plugin_cfg?.["saltcorn-ai-embed"] ?? {};
+}
+
+// ─── OpenAI embeddings ────────────────────────────────────────────────────────
+
+async function embed(text, cfg) {
+  const { openai_api_key, embedding_model = "text-embedding-3-small" } =
+    cfg || getPluginCfg();
+
+  if (!openai_api_key) {
+    throw new Error(
+      "No OpenAI API key configured. Go to Settings → Plugins → Configure → saltcorn-ai-embed."
+    );
+  }
+
+  // Use Node's built-in fetch (Node 18+) — no extra dependencies
+  const res = await fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${openai_api_key}`,
+    },
+    body: JSON.stringify({ input: String(text), model: embedding_model }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(
+      `OpenAI embeddings error ${res.status}: ${err?.error?.message ?? res.statusText}`
+    );
+  }
+
+  const data = await res.json();
+  return data.data[0].embedding; // float[]
+}
+
+// ─── Cosine similarity ────────────────────────────────────────────────────────
+
+function cosine(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+// ─── Helper: safe JSON parse for stored embeddings ────────────────────────────
+
+function parseEmbedding(raw) {
+  if (!raw) return null;
+  if (Array.isArray(raw)) return raw;
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { getState, getPluginCfg, embed, cosine, parseEmbedding };

package/index.js

@@ -0,0 +1,45 @@
+const { ai_embed } = require("./actions");
+
+module.exports = {
+  sc_plugin_api_version: 1,
+  plugin_name: "saltcorn-ai-embed",
+
+  configuration_workflow: () => ({
+    steps: [
+      {
+        name: "OpenAI settings",
+        form: async () => ({
+          fields: [
+            {
+              name: "openai_api_key",
+              label: "OpenAI API key",
+              sublabel:
+                "Required for generating embeddings. Get one at platform.openai.com.",
+              type: "String",
+              required: true,
+              input_type: "password",
+            },
+            {
+              name: "embedding_model",
+              label: "Embedding model",
+              sublabel:
+                "text-embedding-3-small is fast and cheap. text-embedding-3-large is more accurate.",
+              type: "String",
+              required: false,
+              attributes: {
+                options: [
+                  "text-embedding-3-small",
+                  "text-embedding-3-large",
+                  "text-embedding-ada-002",
+                ],
+              },
+            },
+          ],
+        }),
+      },
+    ],
+  }),
+
+  actions: { ai_embed },
+  viewtemplates: [require("./semantic-search")],
+};

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "saltcorn-ai-embed",
+  "version": "0.1.0",
+  "description": "Vector embedding and semantic search for Saltcorn — embed any text field and search by meaning",
+  "main": "index.js",
+  "keywords": ["saltcorn", "plugin", "ai", "embeddings", "vector", "semantic-search", "openai"],
+  "license": "MIT",
+  "peerDependencies": {
+    "@saltcorn/data": ">=1.0.0"
+  }
+}

package/semantic-search.js

@@ -0,0 +1,268 @@
+// SemanticSearch view template
+const { embed, cosine, parseEmbedding, getPluginCfg } = require("./embed-util");
+
+function escHtml(str) {
+  return String(str ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function getTable(table_name) {
+  const key = Object.keys(require.cache).find((k) =>
+    /\/@saltcorn\/data\/models\/table(\.[cm]?js)?$/.test(k)
+  );
+  if (!key) throw new Error("Cannot find @saltcorn/data Table model");
+  const Table = require.cache[key].exports;
+  return Table.findOne ? Table.findOne({ name: table_name }) : null;
+}
+
+// ─── view template ────────────────────────────────────────────────────────────
+
+const SemanticSearch = {
+  name: "SemanticSearch",
+  description:
+    "Semantic search widget — type a query, find the most similar rows by meaning using vector embeddings.",
+
+  get_state_fields: async () => [],
+
+  configuration_workflow: () => ({
+    steps: [
+      {
+        name: "Configure semantic search",
+        form: async (context) => {
+          // Get fields of the table this view is attached to
+          let fieldOpts = [];
+          if (context?.table_id) {
+            const key = Object.keys(require.cache).find((k) =>
+              /\/@saltcorn\/data\/models\/table(\.[cm]?js)?$/.test(k)
+            );
+            if (key) {
+              const Table = require.cache[key].exports;
+              const tbl = await Table.findOne({ id: context.table_id });
+              if (tbl) {
+                const fields = tbl.getFields();
+                fieldOpts = fields.filter((f) => !f.primary_key).map((f) => f.name);
+              }
+            }
+          }
+          return {
+            fields: [
+              {
+                name: "embedding_field",
+                label: "Embedding field",
+                sublabel:
+                  "Field that stores the pre-computed JSON embedding vectors (populated by the ai_embed action)",
+                type: "String",
+                required: true,
+                attributes: { options: fieldOpts },
+              },
+              {
+                name: "display_fields",
+                label: "Result fields",
+                sublabel:
+                  "Comma-separated list of fields to show in each result row, e.g. title,body,category",
+                type: "String",
+                required: true,
+              },
+              {
+                name: "top_n",
+                label: "Max results",
+                sublabel: "Maximum number of results to return (default: 5)",
+                type: "Integer",
+                required: false,
+                attributes: { default: 5 },
+              },
+              {
+                name: "min_score",
+                label: "Minimum similarity (0–1)",
+                sublabel:
+                  "Only show results above this cosine similarity threshold (default: 0.5)",
+                type: "Float",
+                required: false,
+                attributes: { default: 0.5 },
+              },
+              {
+                name: "placeholder",
+                label: "Search placeholder",
+                type: "String",
+                required: false,
+                attributes: { placeholder: "Search by meaning…" },
+              },
+            ],
+          };
+        },
+      },
+    ],
+  }),
+
+  // ── render ────────────────────────────────────────────────────────────────
+  run: async (table_name, viewname, cfg, state, extra) => {
+    const {
+      placeholder = "Search by meaning…",
+      display_fields = "",
+      top_n = 5,
+      min_score = 0.5,
+    } = cfg || {};
+
+    const id = "sc_sem_" + Math.random().toString(36).slice(2, 8);
+
+    return `
+<div class="sc-semsearch-wrap" id="${id}">
+  <div class="input-group mb-3">
+    <input
+      type="text"
+      class="form-control"
+      id="${id}_q"
+      placeholder="${escHtml(placeholder)}"
+    />
+    <button class="btn btn-primary" id="${id}_btn" type="button">
+      <i class="fas fa-search me-1"></i>Search
+    </button>
+  </div>
+  <div id="${id}_status" class="text-muted small mb-2" style="display:none"></div>
+  <div id="${id}_results"></div>
+</div>
+
+<script>
+(function() {
+  var q   = document.getElementById(${JSON.stringify(id + "_q")});
+  var btn = document.getElementById(${JSON.stringify(id + "_btn")});
+  var statusEl  = document.getElementById(${JSON.stringify(id + "_status")});
+  var resultsEl = document.getElementById(${JSON.stringify(id + "_results")});
+  var viewname  = ${JSON.stringify(viewname)};
+  var displayFields = ${JSON.stringify(
+    display_fields.split(",").map((s) => s.trim()).filter(Boolean)
+  )};
+
+  function setStatus(msg) {
+    statusEl.textContent = msg;
+    statusEl.style.display = msg ? "" : "none";
+  }
+
+  function renderResults(rows) {
+    if (!rows.length) {
+      resultsEl.innerHTML = '<p class="text-muted">No results found.</p>';
+      return;
+    }
+    var headers = displayFields.length
+      ? displayFields
+      : Object.keys(rows[0]).filter(function(k) { return k !== "_score" && k !== "_embedding"; });
+
+    var html = '<table class="table table-hover table-sm sc-semsearch-table"><thead><tr>';
+    headers.forEach(function(h) {
+      html += "<th>" + h + "</th>";
+    });
+    html += "<th>Score</th></tr></thead><tbody>";
+
+    rows.forEach(function(row) {
+      html += "<tr>";
+      headers.forEach(function(h) {
+        var val = row[h] != null ? String(row[h]) : "";
+        html += "<td>" + val.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;") + "</td>";
+      });
+      html += "<td><span class='badge bg-secondary'>" + (row._score * 100).toFixed(1) + "%</span></td>";
+      html += "</tr>";
+    });
+
+    html += "</tbody></table>";
+    resultsEl.innerHTML = html;
+  }
+
+  async function search() {
+    var query = q.value.trim();
+    if (!query) return;
+
+    btn.disabled = true;
+    setStatus("Searching…");
+    resultsEl.innerHTML = "";
+
+    try {
+      var resp = await fetch("/view/" + viewname + "/search", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Requested-With": "XMLHttpRequest" },
+        body: JSON.stringify({ query: query }),
+      });
+      var data = await resp.json();
+      if (data.error) { setStatus("Error: " + data.error); return; }
+      setStatus(data.results.length + " result" + (data.results.length === 1 ? "" : "s"));
+      renderResults(data.results);
+    } catch(e) {
+      setStatus("Network error: " + e.message);
+    } finally {
+      btn.disabled = false;
+    }
+  }
+
+  btn.addEventListener("click", search);
+  q.addEventListener("keydown", function(e) {
+    if (e.key === "Enter") search();
+  });
+})();
+</script>`;
+  },
+
+  // ── route: POST /view/{viewname}/search ───────────────────────────────────
+  routes: {
+    search: {
+      post: async (table_name, viewname, cfg, { query }, { req }) => {
+        if (!query) return { json: { error: "query is required" } };
+
+        const {
+          embedding_field,
+          display_fields = "",
+          top_n = 5,
+          min_score = 0.5,
+        } = cfg || {};
+
+        if (!embedding_field)
+          return { json: { error: "embedding_field not configured" } };
+
+        // Embed the query
+        let queryVec;
+        try {
+          queryVec = await embed(query, getPluginCfg());
+        } catch (err) {
+          return { json: { error: err.message } };
+        }
+
+        // Load all rows that have an embedding
+        const table = await getTable(table_name);
+        if (!table) return { json: { error: `Table ${table_name} not found` } };
+
+        const rows = await table.getRows({});
+        const displayCols = display_fields
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+
+        // Score each row
+        const scored = rows
+          .map((row) => {
+            const vec = parseEmbedding(row[embedding_field]);
+            if (!vec) return null;
+            const score = cosine(queryVec, vec);
+            return { row, score };
+          })
+          .filter((r) => r !== null && r.score >= Number(min_score))
+          .sort((a, b) => b.score - a.score)
+          .slice(0, Number(top_n));
+
+        const results = scored.map(({ row, score }) => {
+          const out = displayCols.length
+            ? Object.fromEntries(displayCols.map((f) => [f, row[f]]))
+            : { ...row };
+          // remove the raw embedding from output
+          delete out[embedding_field];
+          out._score = Math.round(score * 1000) / 1000;
+          return out;
+        });
+
+        return { json: { results } };
+      },
+    },
+  },
+};
+
+module.exports = SemanticSearch;