@saltcorn/copilot 0.7.5 → 0.8.1

package/builder-gen.js

@@ -4,15 +4,108 @@ const Trigger = require("@saltcorn/data/models/trigger");
 const View = require("@saltcorn/data/models/view");
 const { edit_build_in_actions } = require("@saltcorn/data/viewable_fields");
 const { buildBuilderSchema } = require("./builder-schema");
+const { getLlmConfigurationSafe, canUseResponseFormat } = require("./common");
+const { build_schema_data } = require("@saltcorn/data/plugin-helper");
+const {
+  GET_RELATION_PATHS_FUNCTION,
+  getRelationPaths,
+  getRelationPathsForPairs,
+  pickBestRelation,
+} = require("./relation-paths");
 
 const ACTION_SIZES = ["btn-sm", "btn-lg"];
+
+// ── Edit-mode guidance blocks ─────────────────────────────────────────────────
+
+const EDIT_FIELD_INCLUSION = `\
+Layout is a form for editing a single row. \
+Include ALL non-primary-key, non-calculated fields from the table as inputs — \
+not just fields mentioned in the task description. \
+Never include calculated fields (aggregations, derived values) in an edit form — they are read-only. \
+The only fields that may be omitted are FK fields to the users table that are explicitly \
+designated as ownership fields (set automatically from the logged-in user). \
+All other foreign key fields — including parent-context keys like trip_id — MUST appear as \
+selector inputs; Saltcorn auto-fills them from the URL state when opened in context.`;
+
+const EDIT_FIELDVIEW_SELECTION = `\
+For date fields always prefer fieldview "flatpickr" when available — it provides the best user experience \
+and works for both regular dates and day-only dates. \
+Only use fieldview "edit_day" as a fallback when the field has day_only=true and flatpickr is not installed. \
+For String fields that have an options attribute (a comma-separated list of fixed choices), \
+use fieldview "select" — this renders a dropdown with those options. \
+Do not use "select_by_code" for fields with fixed options.`;
+
+const EDIT_LAYOUT_STRUCTURE = `\
+Every field MUST be preceded by a label. \
+Use a blank segment with the field's label text immediately above each field inside an above array, like: \
+{"above": [{"type":"blank","contents":"Field Label","class":""}, {"type":"field","field_name":"...","fieldview":"edit"}]}. \
+Alternatively wrap groups of fields in a card with a descriptive title.`;
+
+const EDIT_ACTIONS = `\
+Use edit fieldviews, group related inputs, and finish with a row of actions: \
+a Save button (action_name "Save", style "btn btn-primary") and \
+a Cancel button (action_name "GoBack", style "btn btn-outline-secondary"). \
+To add a trigger button, add an extra action segment with action_name set to the trigger's name \
+exactly as it appears in the available actions list (ctx.actions).`;
+
+// ── Show-mode guidance blocks ─────────────────────────────────────────────────
+
+const SHOW_PURPOSE = `\
+Layout displays one record read-only. \
+Use show fieldviews only (e.g. "show", "as_text", "showDay").`;
+
+const SHOW_NO_EDIT_FIELDVIEWS = `\
+A show layout is read-only and must never use edit fieldviews \
+(textarea, edit, input, select) — those are for form inputs, not display.`;
+
+const SHOW_LABELS = `\
+Every field MUST be preceded by a label using a blank segment or \
+grouped in a card with a descriptive title.`;
+
+// ── List-columns guidance blocks ──────────────────────────────────────────────
+
+const LISTCOLUMNS_STRUCTURE = `\
+Layout defines list columns for a list view. \
+Use a list_columns wrapper with besides entries containing list_column segments. \
+Each list_column has a header_label for the column heading — \
+do NOT add any blank or label segment inside a list_column. \
+Typically each list_column contains a single field, action, or view_link.`;
+
+const LISTCOLUMNS_FIELDVIEWS = `\
+Include all meaningful fields as columns, including foreign key fields. \
+For a foreign key field use fieldview "show" so the related record's label is displayed rather than a raw ID. \
+For string/text fields use fieldview "as_text" or "show" by default; \
+only use "show_with_html" when the task explicitly requires rendering HTML content.`;
+
+const LISTCOLUMNS_VIEW_LINK = `\
+A view_link that opens the detail of a row MUST point to a Show-type view (viewtemplate "Show"). \
+Only include such a view_link if a Show view for this table is listed in the available views.`;
+
+// ── Composed MODE_GUIDANCE ────────────────────────────────────────────────────
+
 const MODE_GUIDANCE = {
-  edit: "Layout is a form for editing a single row. Include required inputs with edit fieldviews, group related inputs, and finish with a Save action.",
-  show: "Layout displays one record read-only. Use show fieldviews, blank headings, and optional follow-up actions.",
+  edit: [
+    EDIT_FIELD_INCLUSION,
+    EDIT_ACTIONS,
+    EDIT_FIELDVIEW_SELECTION,
+    EDIT_LAYOUT_STRUCTURE,
+  ].join(" "),
+
+  show: [SHOW_PURPOSE, SHOW_NO_EDIT_FIELDVIEWS, SHOW_LABELS].join(" "),
+
   list: "Layout represents a single row in a list. Highlight key fields, keep actions compact, and support filtering if requested.",
+
+  listcolumns: [
+    LISTCOLUMNS_STRUCTURE,
+    LISTCOLUMNS_FIELDVIEWS,
+    LISTCOLUMNS_VIEW_LINK,
+  ].join(" "),
+
   filter:
     "Layout lets users define filters. Provide appropriate filter inputs plus an action to run or reset filters.",
+
   page: "Layout builds a general app page. Combine hero text, cards, containers, and call-to-action buttons.",
+
   default:
     "Use Saltcorn layout primitives (above, besides, container, card, tabs, blank, field, action, view_link, view). Do not return HTML snippets.",
 };
@@ -188,11 +281,200 @@ const derefSchema = (schema, maxDepth = 3) => {
   return expand(root, []);
 };
 
+const simplifySchemaForLlm = (schema) => {
+  const deref = derefSchema(schema, 2); // Reduced maxDepth
+  const scrub = (node, keyName, depth = 0) => {
+    if (!node || typeof node !== "object" || depth > 4) {
+      // Added depth limit
+      if (
+        keyName === "contents" ||
+        keyName === "besides" ||
+        keyName === "above"
+      )
+        return {
+          type: "string",
+          description: "Simplified content: a string or a basic segment.",
+        };
+      return node;
+    }
+    if (Array.isArray(node))
+      return node.map((item) => scrub(item, undefined, depth + 1));
+    if (keyName === "style") {
+      return {
+        type: "string",
+        description: "CSS style string (e.g. background-color: red;).",
+      };
+    }
+    if (typeof node.$ref === "string") {
+      return {
+        type: "object",
+        description: "Simplified recursive segment.",
+        additionalProperties: false,
+      };
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(node)) {
+      if (key === "$defs" || key === "definitions") continue;
+      out[key] = scrub(val, key, depth + 1);
+    }
+    const nodeType = out.type;
+    const isObjectType =
+      nodeType === "object" ||
+      (Array.isArray(nodeType) && nodeType.includes("object")) ||
+      Object.prototype.hasOwnProperty.call(out, "properties");
+    const isArrayType =
+      nodeType === "array" ||
+      (Array.isArray(nodeType) && nodeType.includes("array")) ||
+      Object.prototype.hasOwnProperty.call(out, "items");
+    const isNumberType =
+      nodeType === "number" ||
+      nodeType === "integer" ||
+      (Array.isArray(nodeType) &&
+        (nodeType.includes("number") || nodeType.includes("integer")));
+    if (isObjectType) {
+      out.additionalProperties = false;
+    }
+    if (isArrayType && typeof out.minItems !== "undefined") {
+      const minItems = Number(out.minItems);
+      if (Number.isFinite(minItems) && minItems > 1) out.minItems = 1;
+    }
+    if (isNumberType) {
+      delete out.minimum;
+      delete out.maximum;
+      delete out.exclusiveMinimum;
+      delete out.exclusiveMaximum;
+      delete out.multipleOf;
+    }
+    return out;
+  };
+  return scrub(deref);
+};
+
+const countOptionalParams = (schema) => {
+  let count = 0;
+  const walk = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    const props = node.properties;
+    if (props && typeof props === "object") {
+      const required = Array.isArray(node.required) ? node.required : [];
+      const optional = Object.keys(props).filter(
+        (key) => !required.includes(key)
+      );
+      count += optional.length;
+      Object.values(props).forEach(walk);
+    }
+    if (node.items) walk(node.items);
+    if (node.anyOf) node.anyOf.forEach(walk);
+    if (node.oneOf) node.oneOf.forEach(walk);
+    if (node.allOf) node.allOf.forEach(walk);
+  };
+  walk(schema);
+  return count;
+};
+
+const trimOptionalProperties = (schema, maxOptional) => {
+  if (!schema || typeof schema !== "object") return schema;
+
+  const clonedSchema = JSON.parse(JSON.stringify(schema));
+  let optionalCount = countOptionalParams(clonedSchema);
+  if (optionalCount <= maxOptional) {
+    return clonedSchema;
+  }
+
+  const optionalPropsByNode = new Map();
+
+  const findOptional = (node, path = []) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      node.forEach((item, i) => findOptional(item, [...path, i]));
+      return;
+    }
+
+    const props = node.properties;
+    if (props && typeof props === "object") {
+      const required = new Set(node.required || []);
+      const optionalKeys = Object.keys(props).filter((k) => !required.has(k));
+      if (optionalKeys.length > 0) {
+        optionalPropsByNode.set(node, optionalKeys);
+      }
+      Object.values(props).forEach((propNode) => findOptional(propNode));
+    }
+
+    if (node.items) findOptional(node.items, [...path, "items"]);
+    if (node.anyOf)
+      node.anyOf.forEach((item, i) =>
+        findOptional(item, [...path, "anyOf", i])
+      );
+    if (node.oneOf)
+      node.oneOf.forEach((item, i) =>
+        findOptional(item, [...path, "oneOf", i])
+      );
+    if (node.allOf)
+      node.allOf.forEach((item, i) =>
+        findOptional(item, [...path, "allOf", i])
+      );
+  };
+
+  findOptional(clonedSchema);
+
+  const nodesWithOptionals = Array.from(optionalPropsByNode.keys());
+  let nodeIndex = 0;
+
+  while (optionalCount > maxOptional && nodeIndex < nodesWithOptionals.length) {
+    const node = nodesWithOptionals[nodeIndex];
+    const optionalKeys = optionalPropsByNode.get(node);
+
+    if (optionalKeys && optionalKeys.length > 0) {
+      const keyToRemove = optionalKeys.pop();
+      delete node.properties[keyToRemove];
+      optionalCount--;
+    } else {
+      nodeIndex++;
+    }
+  }
+
+  return clonedSchema;
+};
+
 const randomId = () =>
   Math.floor(Math.random() * 0xffffff)
     .toString(16)
     .padStart(6, "0");
 
+const toCamelCaseStyle = (key) =>
+  key.replace(/-([a-z])/g, (_m, chr) => chr.toUpperCase());
+
+const parseStyleString = (styleStr) => {
+  if (typeof styleStr !== "string") return styleStr;
+  const trimmed = styleStr.trim();
+  if (!trimmed) return {};
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch (err) {
+      // fall through to CSS parsing
+    }
+  }
+  const out = {};
+  trimmed.split(";").forEach((part) => {
+    const section = part.trim();
+    if (!section) return;
+    const idx = section.indexOf(":");
+    if (idx === -1) return;
+    const rawKey = section.slice(0, idx).trim();
+    const value = section.slice(idx + 1).trim();
+    if (!rawKey || !value) return;
+    if (rawKey.startsWith("--")) out[rawKey] = value;
+    else out[toCamelCaseStyle(rawKey)] = value;
+  });
+  return out;
+};
+
 const ensureArray = (value) =>
   Array.isArray(value) ? value : value == null ? [] : [value];
 
@@ -206,7 +488,10 @@ const prettifyActionName = (name) =>
 // Picks a valid fieldview from the field's available fieldviews only.
 // Never returns a fieldview that doesn't exist in field.fieldviews
 const pickFieldview = (field, mode, requestedFieldview = null) => {
-  const availableViews = field?.fieldviews || [];
+  const isEditMode = mode === "edit" || mode === "filter";
+  const availableViews = isEditMode
+    ? field?.editFieldviews || field?.fieldviews || []
+    : field?.fieldviews || [];
 
   // If no available fieldviews, return the first one or a safe default
   if (!availableViews.length) {
@@ -214,29 +499,60 @@ const pickFieldview = (field, mode, requestedFieldview = null) => {
     return mode === "edit" || mode === "filter" ? "edit" : "show";
   }
 
-  // Helper to validate and return a fieldview only if it exists
+  // Helper to validate and return a fieldview only if it exists (exact match only)
   const validateAndReturn = (candidate) => {
     if (!candidate) return null;
     const lower = String(candidate).toLowerCase();
-    // Exact match
-    const exact = availableViews.find(
-      (fv) => String(fv).toLowerCase() === lower,
+    return (
+      availableViews.find((fv) => String(fv).toLowerCase() === lower) || null
     );
-    if (exact) return exact;
-    // Fuzzy match (contains)
-    const fuzzy = availableViews.find((fv) =>
-      String(fv).toLowerCase().includes(lower),
-    );
-    if (fuzzy) return fuzzy;
-    return null;
   };
 
+  // Edit-only fieldviews must never be used in show/list modes
+  const EDIT_ONLY_FIELDVIEWS = new Set(["textarea", "edit", "input", "select"]);
+  const isShowMode =
+    mode === "show" || mode === "list" || mode === "listcolumns";
+
+  // For date fields in edit mode: flatpickr is always preferred (handles all date types).
+  // Only fall back to edit_day when day_only=true and flatpickr is not installed.
+  const fieldTypeLower = String(field?.type || "").toLowerCase();
+  const isDateField =
+    (mode === "edit" || mode === "filter") &&
+    (fieldTypeLower === "date" || fieldTypeLower.includes("date"));
+  if (isDateField) {
+    const flatpickrMatch = availableViews.find(
+      (fv) => String(fv).toLowerCase() === "flatpickr"
+    );
+    if (flatpickrMatch) return flatpickrMatch;
+    if (field?.attributes?.day_only) {
+      const dayMatch = availableViews.find(
+        (fv) => String(fv).toLowerCase() === "edit_day"
+      );
+      if (dayMatch) return dayMatch;
+    }
+  }
+
+  // Fields with fixed options (options attribute) always use plain select, never select_by_code
+  if ((mode === "edit" || mode === "filter") && field?.attributes?.options) {
+    const selectMatch = availableViews.find(
+      (fv) => String(fv).toLowerCase() === "select"
+    );
+    if (selectMatch) return selectMatch;
+  }
+
   // If a specific fieldview was requested by the user, try to honor it
-  // but ONLY if it actually exists in available views
+  // but ONLY if it actually exists in available views and is appropriate for the mode
   if (requestedFieldview) {
-    const validated = validateAndReturn(requestedFieldview);
-    if (validated) return validated;
-    // Requested fieldview not available for this field - fall through to defaults
+    if (
+      isShowMode &&
+      EDIT_ONLY_FIELDVIEWS.has(String(requestedFieldview).toLowerCase())
+    ) {
+      // Fall through to show-mode defaults — don't use edit fieldviews in show context
+    } else {
+      const validated = validateAndReturn(requestedFieldview);
+      if (validated) return validated;
+      // Requested fieldview not available for this field - fall through to defaults
+    }
   }
 
   // Get the field's configured default fieldview
@@ -249,21 +565,21 @@ const pickFieldview = (field, mode, requestedFieldview = null) => {
   }
 
   // Mode-based selection from available fieldviews
-  if (mode === "show" || mode === "list") {
+  if (mode === "show" || mode === "list" || mode === "listcolumns") {
     // For show mode, prefer simple text-based views, but only from available views
     const showPreferences = ["as_text", "show", "as_string", "text", "showas"];
     for (const pref of showPreferences) {
-      const match = availableViews.find((fv) =>
-        String(fv).toLowerCase().includes(pref),
+      const match = availableViews.find(
+        (fv) => String(fv).toLowerCase() === pref
       );
       if (match) return match;
     }
   } else if (mode === "edit" || mode === "filter") {
-    // For edit mode, prefer edit-capable fieldviews from available views
+    // For edit mode, prefer edit-capable fieldviews from available views (exact match)
     const editPreferences = ["edit", "input", "select", "textarea"];
     for (const pref of editPreferences) {
-      const match = availableViews.find((fv) =>
-        String(fv).toLowerCase().includes(pref),
+      const match = availableViews.find(
+        (fv) => String(fv).toLowerCase() === pref
       );
       if (match) return match;
     }
@@ -343,9 +659,12 @@ const normalizeSegment = (segment, ctx) => {
   if (typeof segment !== "object") return null;
 
   const clone = { ...segment };
+  if (typeof clone.style === "string") {
+    clone.style = parseStyleString(clone.style);
+  }
   if (clone.type === "prompt") return null;
 
-  if (!clone.type && clone.above) {
+  if ((!clone.type || clone.type === "stack") && clone.above) {
     const above = ensureArray(clone.above)
       .map((child) => normalizeSegment(child, ctx))
       .filter(Boolean);
@@ -353,7 +672,7 @@ const normalizeSegment = (segment, ctx) => {
   }
   if (!clone.type && clone.besides) {
     const besides = ensureArray(clone.besides).map((child) =>
-      child == null ? null : normalizeSegment(child, ctx),
+      child == null ? null : normalizeSegment(child, ctx)
     );
     if (!besides.some((child) => child)) return null;
     return {
@@ -362,8 +681,38 @@ const normalizeSegment = (segment, ctx) => {
       widths: normalizeWidths(clone.widths, besides.length),
     };
   }
+  // Handle {columns: {besides: [...], widths: [...]}} wrapper the LLM sometimes emits
+  if (!clone.type && clone.columns?.besides) {
+    const inner = clone.columns;
+    const besides = ensureArray(inner.besides).map((child) =>
+      child == null ? null : normalizeSegment(child, ctx)
+    );
+    if (!besides.some(Boolean)) return null;
+    return {
+      besides,
+      widths: normalizeWidths(inner.widths, besides.length),
+    };
+  }
 
   switch (clone.type) {
+    case "columns":
+    case "row":
+    case "grid": {
+      // LLM uses these as a besides wrapper with widths
+      if (clone.besides) {
+        const besides = ensureArray(clone.besides).map((child) =>
+          child == null ? null : normalizeSegment(child, ctx)
+        );
+        if (!besides.some(Boolean)) return null;
+        return {
+          besides,
+          widths: normalizeWidths(clone.widths, besides.length),
+        };
+      }
+      // fall through to container-like handling if no besides
+      const contents = normalizeChild(clone.contents, ctx);
+      return contents ? { ...clone, contents } : null;
+    }
     case "container": {
       const contents = normalizeChild(clone.contents, ctx);
       return contents
@@ -388,7 +737,10 @@ const normalizeSegment = (segment, ctx) => {
     }
     case "tabs": {
       const tabs = normalizeTabs(clone.tabs, ctx);
-      return tabs.length ? { ...clone, tabs, class: clone.class || "" } : null;
+      if (!tabs.length) return null;
+      const titles = clone.titles ?? tabs.map((t) => t.title || "");
+      const contents = clone.contents ?? tabs.map((t) => t.contents);
+      return { ...clone, tabs, titles, contents, class: clone.class || "" };
     }
     case "blank":
       return {
@@ -428,17 +780,46 @@ const normalizeSegment = (segment, ctx) => {
         state: clone.state || {},
         class: clone.class || "",
       };
-    case "view_link":
+    case "view_link": {
       if (!ctx.viewNames.length) return null;
+      const resolvedView = ctx.viewNames.includes(clone.view)
+        ? clone.view
+        : ctx.viewNames[0];
+      let relation = clone.relation;
+      if (!relation && ctx.table && ctx.schemaData) {
+        try {
+          const relations = getRelationPaths(
+            ctx.table.name,
+            resolvedView,
+            ctx.schemaData
+          );
+          if (relations.length > 0) {
+            const picked = pickBestRelation(relations);
+            if (picked) relation = picked.relationString;
+          }
+        } catch (e) {
+          console.error("view_link relation lookup failed:", e.message);
+        }
+      }
+      // Convert {{ expr }} template syntax to isFormula.label: true with JS expression
+      let viewLabel = clone.view_label || clone.view;
+      let isFormula = clone.isFormula || {};
+      const tmplMatch =
+        typeof viewLabel === "string" && viewLabel.match(/^\{\{\s*(.+?)\s*\}\}$/);
+      if (tmplMatch) {
+        viewLabel = tmplMatch[1];
+        isFormula = { ...isFormula, label: true };
+      }
       return {
         ...clone,
-        view: ctx.viewNames.includes(clone.view)
-          ? clone.view
-          : ctx.viewNames[0],
-        view_label: clone.view_label || clone.view,
+        view: resolvedView,
+        view_label: viewLabel,
         link_style: clone.link_style || "",
         class: clone.class || "",
+        isFormula,
+        ...(relation ? { relation } : {}),
       };
+    }
     case "field": {
       if (!ctx.fields.length) return null;
       const fieldMeta = ctx.fieldMap[clone.field_name] || ctx.fields[0];
@@ -447,7 +828,7 @@ const normalizeSegment = (segment, ctx) => {
       const validFieldview = pickFieldview(
         fieldMeta,
         ctx.mode,
-        clone.fieldview,
+        clone.fieldview
       );
       return {
         ...clone,
@@ -457,6 +838,26 @@ const normalizeSegment = (segment, ctx) => {
         class: clone.class || "",
       };
     }
+    case "list_columns": {
+      const besides = ensureArray(clone.besides).map((child) =>
+        child == null ? null : normalizeSegment(child, ctx)
+      );
+      if (!besides.some(Boolean)) return null;
+      return { ...clone, besides, list_columns: true };
+    }
+    case "list_column": {
+      let raw = clone.contents;
+      // Saltcorn's list renderer handles `above` in a cell (wraps in Container)
+      // but silently drops a typeless `besides`. Convert it so both links render
+      // stacked in one column rather than disappearing.
+      if (raw && !raw.type && Array.isArray(raw.besides)) {
+        raw = { above: raw.besides };
+      }
+      const contents = normalizeChild(raw, ctx);
+      return contents
+        ? { ...clone, contents, header_label: clone.header_label || "" }
+        : null;
+    }
     case "action": {
       if (!ctx.actions.length) return null;
       const actionName = ctx.actions.includes(clone.action_name)
@@ -508,7 +909,7 @@ const collectSegments = (segment, out = []) => {
   if (segment.contents) collectSegments(segment.contents, out);
   if (segment.tabs) {
     ensureArray(segment.tabs).forEach((tab) =>
-      collectSegments(tab.contents, out),
+      collectSegments(tab.contents, out)
     );
   }
   return out;
@@ -559,25 +960,48 @@ const normalizeLayoutCandidate = (candidate, ctx) => {
   if (!normalized) {
     normalized = convertForeignLayout(candidate, ctx);
   }
-  if (!normalized) throw new Error("Empty layout after normalization");
+  if (!normalized) return null;
   const layout = Array.isArray(normalized) ? { above: normalized } : normalized;
   return sanitizeNoHtmlSegments(layout);
 };
 
+const buildFieldMetadata = (fields) => {
+  if (!fields || !fields.length) return null;
+  const lines = fields
+    .filter((f) => !f.primary_key)
+    .map((f) => {
+      const attrs = Object.entries(f.attributes || {})
+        .filter(
+          ([, v]) => v !== null && v !== undefined && v !== "" && v !== false
+        )
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join(", ");
+      return `  ${f.name} (${f.type}${f.calculated ? ", calculated" : ""}${
+        attrs ? ` — attrs: ${attrs}` : ""
+      })`;
+    });
+  return `Table fields available for this layout:\n${lines.join("\n")}`;
+};
+
 const buildPromptText = (userPrompt, ctx, schema) => {
   const parts = [
     `You are an expert Saltcorn layout builder assistant. Your task is to generate a layout for mode "${ctx.mode}" that precisely fulfills the user's request.`,
     'CRITICAL: You must return ONLY a single valid JSON object. Do not include introductory text, explanations, markdown formatting (like ```json), or any pseudo-markup. The output must strictly follow this shape: {"layout": <layout-object>}.',
     'The "layout" object MUST conform entirely to the provided JSON Schema. Do not invent properties, types, or structure not defined in the schema.',
   ];
+  parts.push(ctx.modeGuidance);
+  const fieldMeta = buildFieldMetadata(ctx.fields);
+  if (fieldMeta) parts.push(fieldMeta);
   parts.push(
-    "When a card or container background is requested, set bgType explicitly (None, Color, Image, or Gradient). For Color use bgColor, for Image use bgFileId plus imageLocation (Top, Card, Body) and optionally imageSize (cover, contain, repeat using cover as default) when location is Card or Body, and for Gradient use gradStartColor, gradEndColor, and numeric gradDirection. Use hex color codes when specifying colors.",
+    "When a card or container background is requested, set bgType explicitly (None, Color, Image, or Gradient). For Color use bgColor, for Image use bgFileId plus imageLocation (Top, Card, Body) and optionally imageSize (cover, contain, repeat using cover as default) when location is Card or Body, and for Gradient use gradStartColor, gradEndColor, and numeric gradDirection. Use hex color codes when specifying colors."
   );
   parts.push(
-    `Here is the strict Saltcorn layout JSON schema you MUST follow to construct the layout. Do not deviate from these definitions:\n${JSON.stringify(schema)}`,
+    `Here is the strict Saltcorn layout JSON schema you MUST follow to construct the layout. Do not deviate from these definitions:\n${JSON.stringify(
+      schema
+    )}`
   );
   parts.push(
-    `Based on the schema above, process the following user request and generate the layout JSON. Reminder: ONLY output valid JSON starting with { and ending with }, no markdown fences.\nUser request:\n"${userPrompt}"`,
+    `Based on the schema above, process the following user request and generate the layout JSON. Reminder: ONLY output valid JSON starting with { and ending with }, no markdown fences.\nUser request:\n"${userPrompt}"`
   );
   return parts.join("\n\n");
 };
@@ -796,6 +1220,7 @@ const buildBracketObject = (node) => {
   return obj;
 };
 
+
 const buildContext = async (mode, tableName) => {
   const normalizedMode = (mode || "show").toLowerCase();
   const ctx = {
@@ -806,15 +1231,25 @@ const buildContext = async (mode, tableName) => {
     fieldMap: {},
     actions: [],
     viewNames: [],
+    viewTableMap: {},
+    schemaData: null,
   };
 
   // Global actions and views are useful even when no table is specified (page builder)
   const stateActions = Object.keys(getState().actions || {});
   try {
-    const allViews = await View.find();
-    ctx.viewNames = allViews.map((v) => v.name).filter(Boolean);
+    const schemaData = await build_schema_data();
+    ctx.schemaData = schemaData;
+    ctx.viewNames = schemaData.views.map((v) => v.name).filter(Boolean);
+    for (const v of schemaData.views) {
+      if (v.name && v.table_id) {
+        const vt = Table.findOne({ id: v.table_id });
+        if (vt) ctx.viewTableMap[v.name] = vt.name;
+      }
+    }
   } catch (err) {
     ctx.viewNames = [];
+    ctx.viewTableMap = {};
   }
 
   if (!tableName) {
@@ -823,7 +1258,7 @@ const buildContext = async (mode, tableName) => {
     }).filter((tr) => tr.name && !tr.table_id);
 
     ctx.actions = Array.from(
-      new Set([...stateActions, ...triggers.map((tr) => tr.name)]),
+      new Set([...stateActions, ...triggers.map((tr) => tr.name)])
     ).filter(Boolean);
     return ctx;
   }
@@ -843,7 +1278,19 @@ const buildContext = async (mode, tableName) => {
   }
   if (rawFields?.then) rawFields = await rawFields;
   const fields = (rawFields || []).map((field) => {
-    const fieldviews = Object.keys(field.type?.fieldviews || {});
+    const fvDefs = field.type?.fieldviews || {};
+    let fieldviews = Object.keys(fvDefs);
+    // FK fields have type "Key" (a string) so field.type?.fieldviews is empty;
+    // ensure select and show are always available for them
+    const typeName = field.type?.name || field.type || "";
+    if (!fieldviews.length && String(typeName).startsWith("Key")) {
+      fieldviews = ["select", "show"];
+    }
+    // editFieldviews: only fieldviews where isEdit is not explicitly false
+    const editFieldviews = fieldviews.filter(
+      (fv) => fvDefs[fv]?.isEdit !== false
+    );
+
     const isPkName =
       table.pk_name &&
       typeof field.name === "string" &&
@@ -868,6 +1315,8 @@ const buildContext = async (mode, tableName) => {
       is_pk_name: !!isPkName,
       default_fieldview: defaultFieldview,
       fieldviews: fieldviews.length ? fieldviews : ["show"],
+      editFieldviews: editFieldviews.length ? editFieldviews : fieldviews,
+      attributes: field.attributes || {},
     };
   });
 
@@ -888,7 +1337,7 @@ const buildContext = async (mode, tableName) => {
       ? edit_build_in_actions || []
       : ["Delete", "GoBack"];
   const actions = Array.from(
-    new Set([...builtIns, ...stateActions, ...triggers.map((tr) => tr.name)]),
+    new Set([...builtIns, ...stateActions, ...triggers.map((tr) => tr.name)])
   ).filter(Boolean);
 
   ctx.table = table;
@@ -951,9 +1400,60 @@ const buildErrorLayout = ({ message, mode, table }) => {
   };
 };
 
+const GET_RELATION_PATHS_TOOL = { type: "function", function: GET_RELATION_PATHS_FUNCTION };
+
+/**
+ * Run the LLM giving it one opportunity to call get_relation_paths before
+ * producing the final layout JSON. Returns the final text response.
+ */
+const runWithRelationTools = async (llm, mainPrompt, opts) => {
+  const llm_add_message = getState().functions.llm_add_message;
+
+  // Local chat copy with the main prompt pre-loaded so all iterations see it.
+  const runChat = Array.isArray(opts.chat) ? [...opts.chat] : [];
+  runChat.push({ role: "user", content: mainPrompt });
+
+  // Drop response_format during tool phase; repair chain handles JSON after.
+  const toolOpts = { ...opts, tools: [GET_RELATION_PATHS_TOOL] };
+  delete toolOpts.response_format;
+  delete toolOpts.chat;
+
+  // Call 1: model either returns JSON directly or calls get_relation_paths.
+  const raw = await llm.run(null, { ...toolOpts, chat: runChat });
+  if (!raw?.hasToolCalls) {
+    return typeof raw === "string" ? raw : raw?.content ?? "";
+  }
+
+  // Append the assistant message so call 2 has full context.
+  if (raw.ai_sdk && Array.isArray(raw.messages)) {
+    raw.messages.filter((m) => m.role === "assistant").forEach((m) => runChat.push(m));
+  } else if (raw.tool_calls) {
+    runChat.push({ role: "assistant", content: raw.content || null, tool_calls: raw.tool_calls });
+  }
+
+  // Resolve the tool call(s) and push results.
+  const schemaData = await build_schema_data();
+  for (const tc of raw.getToolCalls()) {
+    let resultText;
+    if (tc.tool_name === "get_relation_paths") {
+      const sections = getRelationPathsForPairs(tc.input.pairs || [], schemaData);
+      resultText =
+        sections.join("\n\n") +
+        `\n\nSet the "relation" property to one of the strings listed above for each view_link.`;
+    } else {
+      resultText = `Unknown tool: ${tc.tool_name}`;
+    }
+    await llm_add_message.run("tool_response", resultText, { chat: runChat, tool_call: tc });
+  }
+
+  // Call 2: model has relation paths, now generates the layout JSON.
+  const final = await llm.run(null, { ...opts, chat: runChat });
+  return typeof final === "string" ? final : final?.content ?? "";
+};
+
 module.exports = {
-  run: async (prompt, mode, table, chat) => {
-    // Remove any leading "container:" or similar so as to remain with only the user prompt.
+  normalizeLayoutCandidate,
+  run: async (prompt, mode, table, existing_layout, chat) => {
     prompt = prompt.trim().replace(/^\[\w+\]:\s*/, "");
 
     const ctx = await buildContext(mode, table);
@@ -961,28 +1461,46 @@ module.exports = {
     const llm = getState().functions.llm_generate;
     if (!llm?.run) throw new Error("LLM generator not configured");
 
-    const llmPrompt = buildPromptText(prompt, ctx, schema);
-    console.log({ schema });
-    console.log({ llmPrompt: llmPrompt.slice(0, 1000) });
+    const llmConfig = await getLlmConfigurationSafe();
+    const allowResponseFormat = canUseResponseFormat(llmConfig);
+
+    let llmPrompt = buildPromptText(prompt, ctx, schema);
+    if (existing_layout !== undefined && existing_layout !== null) {
+      const layoutJson =
+        typeof existing_layout === "string"
+          ? existing_layout
+          : JSON.stringify(existing_layout);
+      llmPrompt = `${llmPrompt}\n\nExisting layout (reproduce this with the requested changes applied):\n${layoutJson}`;
+    }
+
     let responseFormat;
     try {
       if (!schema || !schema.schema) {
         throw new Error("Builder schema unavailable");
       }
-      validateSchemaRefs(schema.schema);
-      const deref = derefSchema(schema.schema);
-      if (schemaHasRef(deref)) {
-        console.warn(
-          "Builder response schema still contains $ref; skipping response_format",
-        );
+      if (!allowResponseFormat) {
+        console.warn("LLM backend does not support response_format; skipping");
       } else {
-        responseFormat = {
-          type: "json_schema",
-          json_schema: {
-            name: "saltcorn_layout",
-            schema: deref,
-          },
-        };
+        validateSchemaRefs(schema.schema);
+        let simplified = simplifySchemaForLlm(schema.schema);
+        const optionalCount = countOptionalParams(simplified);
+        console.log({ optionalCount });
+        if (optionalCount > 24) {
+          simplified = trimOptionalProperties(simplified, 24);
+        }
+        if (simplified && schemaHasRef(simplified)) {
+          console.warn(
+            "Builder response schema still contains $ref; skipping response_format"
+          );
+        } else if (simplified) {
+          responseFormat = {
+            type: "json_schema",
+            json_schema: {
+              name: "saltcorn_layout",
+              schema: simplified,
+            },
+          };
+        }
       }
     } catch (err) {
       console.warn("Builder response schema validation failed", err);
@@ -1003,13 +1521,12 @@ module.exports = {
       if (!schema || !schema.schema) {
         throw new Error("Builder schema unavailable");
       }
-      console.log("¢¢¢¢", { options });
-      rawResponse = await llm.run(llmPrompt, options);
-      console.log(JSON.stringify(rawResponse, null, 2));
+      rawResponse = await runWithRelationTools(llm, llmPrompt, options);
       payload = parseJsonPayload(rawResponse);
-      console.log(JSON.stringify({ payload }, null, 2));
       const candidate = payload.layout ?? payload;
-      return normalizeLayoutCandidate(candidate, ctx);
+      const result = normalizeLayoutCandidate(candidate, ctx);
+      if (!result) throw new Error("Empty layout after normalization");
+      return result;
     } catch (err) {
       let lastError = err;
       try {
@@ -1017,7 +1534,9 @@ module.exports = {
         rawResponse = await llm.run(repairPrompt, options);
         payload = parseJsonPayload(rawResponse);
         const candidate = payload.layout ?? payload;
-        return normalizeLayoutCandidate(candidate, ctx);
+        const result = normalizeLayoutCandidate(candidate, ctx);
+        if (!result) throw new Error("Empty layout after normalization");
+        return result;
       } catch (repairErr) {
         lastError = repairErr;
       }
@@ -1027,7 +1546,9 @@ module.exports = {
         rawResponse = await llm.run(reducedPrompt, options);
         payload = parseJsonPayload(rawResponse);
         const candidate = payload.layout ?? payload;
-        return normalizeLayoutCandidate(candidate, ctx);
+        const result = normalizeLayoutCandidate(candidate, ctx);
+        if (!result) throw new Error("Empty layout after normalization");
+        return result;
       } catch (reducedErr) {
         lastError = reducedErr;
       }
@@ -1047,6 +1568,7 @@ module.exports = {
     { name: "prompt", type: "String" },
     { name: "mode", type: "String" },
     { name: "table", type: "String" },
+    { name: "existing_layout", type: "JSON" },
     { name: "chat", type: "JSON" },
   ],
 };