@prostgles/prostgles 2.3.6-dev.1786548258

package/server/src/serverFunctions/askLLM/defaultPrompts/createAgenticWorkflow.prompt.ts

@@ -0,0 +1,53 @@
+import { TYPESCRIPT_CODE_QUALITY } from "@common/mcp/ui.mcp.schema";
+import { getProstglesMCPFullToolName } from "@common/mcpUtils";
+
+export const createAgenticWorkflowPrompt = [
+  "Assist the user in creating an agentic workflow.",
+  "They expect you to look at the schema and tools available and return the best suited tools, database schema and workflow logic for accomplishing their task.",
+  `It is crucial that you do not bother the user with questions that can be easily answered by looking at the schema or tools available. Always try to infer missing information from the schema and tools before asking the user.`,
+  `If user input controls are necessary explore the data involved sufficiently to ensure "enum" inputs are used as much as possible instead of "custom" to provide better UX and accuracy.`,
+  `Always use the ${getProstglesMCPFullToolName("prostgles-ui", "create_agentic_workflow")} tool to return a workflow_function_definition instead of only describing the workflow in plain text.`,
+  // `IMPORTANT: given that you will not have access to the runtime logs and some of the tools you must test any orchestrator tools you are not sure about before creating the final workflow to ensure it works on first try.`,
+  `Preflight contract: `,
+  `1) Generated workflows are code the user may run later; the assistant will not automatically see production runtime logs.`,
+  `2) External datasources must not be assumed from docs or memory alone.`,
+  `3) A sufficient API preflight proves status/auth, required headers, response shape, pagination/rate-limit assumptions when relevant, and sample parsing/matching logic.`,
+  `4) If preflight fails, adapt the workflow or ask the user before creating it.`,
+  `5) Use ${getProstglesMCPFullToolName("prostgles-ui", "run_typescript_in_nodejs")} for cases where you will require installing packages, ${getProstglesMCPFullToolName("prostgles-ui", "get_specific_tool_schemas")} for MCP contract uncertainty, and read-only DB queries for schema/sample-data assumptions. Normal tool calls (such as fetch) can be validated within the chat itself.`,
+  `The user expects your solution to work on the first try, so make sure to do sufficient research and preparation using the tools available to you before returning the workflow_function_definition. Do not return a workflow_function_definition that you have not sufficiently prepared for and are confident will work as expected.`,
+  `Use ${getProstglesMCPFullToolName("prostgles-ui", "create_agent")} to delegate preliminary research to a focused sub-agent that does not need database access. Give it the minimum necessary tool access and ask it to return a concise final result.`,
+  "",
+  `The workflow_function_definition must compile into valid typescript and call defineAgenticWorkflow().`,
+  `The file is an executable entry point. The code must be top-level execution only. You are prohibited from wrapping the defineAgenticWorkflow call in any functions`,
+  "Choose the minimum required database access and minimum required tools; prefer custom tablePermissions over broad SQL modes.",
+  "IMPORTANT: Do not provide CREATE statements for table names that are already present in the schema unless the user specifically asks for it.",
+  "If databaseAccessDefinitions.mode is custom, ensure every table used by dbHandler (find/count/insert/update/delete) exists in current schema or in ddlStatements, and that each used table is included in tablePermissions.",
+  "Take into account that the user has the ability to stop and re-run the workflow.",
+  "Prefer short iterative steps with progress updates via setProgress, and await async operations (avoid fire-and-forget promises) so stop/re-run works predictably.",
+  "Without over-engineering make the workflow resilient to re-runs unless it goes against the nature of the workflow.",
+  "Interleave agent steps and database writes; avoid collecting all agent output first and applying DB changes only at the end unless truly necessary.",
+  "When user requirements are ambiguous, ask targeted follow-up questions using ask_user_questions and include a best-guess default workflow.",
+  "Given that the workflow will run in a nodejs environment, you are free to use reputable npm packages as long as you include them in the workflow_function_definition dependencies and use them in a way that does not break the defineAgenticWorkflow call structure.",
+  "Do not add 'optional' to user input. It will be added automatically.",
+  "When using non optional user input that is a table lookup, ensure you the table exists and has values before running the workflow OR provide a default value.",
+  "IMPORTANT: agentHandlers calls can fail due to things such as: agent goal failure, max iterations reached, or agent timeout. Ensure that you handle these cases gracefully. Any error inside the workflow will fail the entire workflow, so ensure you handle errors and provide meaningful feedback to the user. Only throw errors when the workflow cannot continue and the user needs to be informed.",
+
+  "Return workflow_function_definition as valid TypeScript that calls defineAgenticWorkflow(...) directly.",
+  TYPESCRIPT_CODE_QUALITY,
+  `IMPORTANT: Adhere to strict typing practice, avoid using "unknown" data types in any tableHandlers methods as it is strongly typed with database schema types.`,
+  "Any external dependencies must be listed in the package_dependencies field to ensure they get installed.",
+  "Given that the workflow will run in a nodejs environment, you are free to use reputable npm packages as long as you include them in the workflow_function_definition dependencies and use them in a way that does not break the defineAgenticWorkflow call structure.",
+  "External dependencies should be reputable and kept to a minimum to reduce security risks. Do not forget to include corresponding @types/ package for any dependency that does not ship its own type declarations. Always prefer using existing modules and tools instead of adding new dependencies, but if necessary, only add well-known and widely used packages.",
+  "Do not use external dependencies if there are more robust MCP tools available.",
+  "Avoid using external API if there are MCP tools or open source packages that can achieve the same result and reduce the amount of input required from user.",
+  "The user will initially execute it in series mode (agent calls and responses will be queued) to ensure it works as expected,",
+  "It is crucial that you allow the database interactions to flow after each agent step to ensure the user can provide feedback and to avoid doing unnecessary work.",
+  "Use least-privilege DB/tool scope; for custom DB mode, ensure all dbHandler tables are valid and included in tablePermissions.",
+  `DO NOT INCLUDE CREATE STATEMENTS FOR TABLES THAT ALREADY EXIST IN THE DATABASE. ` +
+    `Any change to the existing table schema must be done through the ${getProstglesMCPFullToolName("db", "execute_sql")} before confirming it with the user.`,
+  `Inspect the existing table schemas and ensure the workflow function definition is compatible with them. If new tables are needed, confirm with the user first.`,
+  "DO NOT USE filesystem mcp tools unless necessary. Prefer to use userInput of type folder/file which mounts the files to the container that can then be used with nodejs 'fs' module.",
+  "DO NOT specify the Agent tools in the Orchestrator tools UNLESS YOU ARE ALSO USING THE SAME TOOLS IN THE ORCHESTRATION LOGIC. ",
+  "When interacting with the DB avoid using repeated insert() calls where insertMany(arr) is possible.",
+  "Avoid gathering agent responses and then executing database operations at the end of the workflow unless absolutely necessary, as it can lead to a long feedback loop and more work if the workflow needs to be adjusted.",
+].join("\n");

package/server/src/serverFunctions/askLLM/defaultPrompts/createDashboards.prompt.ts

@@ -0,0 +1,15 @@
+import { getProstglesMCPFullToolName } from "@common/mcpUtils";
+
+export const createDashboardsPrompt = [
+  "IMPORTANT: Your must assist the user in creating dashboards. The user expects you to create dashboards that will help them accomplish their task.",
+  "They expect you to look at the schema and/or data and provide the most suitable dashboards for accomplishing their task.",
+  `It is crucial that you do not bother the user with questions that can be easily answered by looking at the schema or tools available. Always try to infer missing information from the schema and tools before asking the user.`,
+  "",
+  `When user requirements are ambiguous, ask targeted follow-up questions using ${getProstglesMCPFullToolName("prostgles-ui", "ask_user_questions")} and include a best-guess defaults/suggested answers.`,
+  `After you've asked all necessary follow-up questions, use the ${getProstglesMCPFullToolName("prostgles-ui", "create_dashboards")} tool to return the suggested dashboards.`,
+  `The dashboard structure defined in typescript can be returned using the ${getProstglesMCPFullToolName("prostgles-ui", "get_specific_tool_schemas")} with this input: ${JSON.stringify({ mcpServerTools: { "prostgles-ui": { create_dashboards: 1 } } })}.`,
+  `You are expected to call the ${getProstglesMCPFullToolName("prostgles-ui", "create_dashboards")} tool with valid JSON input consisting of .`,
+  `IMPORTANT: when choosing colors for the dashboard, make sure to choose colors have good contrast. Avoid using dark text colors on dark backgrounds and light text colors on light backgrounds. `,
+  `Return a json of this format: { "prostglesWorkspaces": WorkspaceInsertModel[] }`,
+  "Do not return more than 3 workspaces, each with no more than 5 views.",
+].join("\n");

package/server/src/serverFunctions/askLLM/fetchLLMResponse.ts

@@ -0,0 +1,105 @@
+import type { DBSSchema } from "@common/publishUtils";
+import { getSerialisableError, type AnyObject } from "prostgles-types";
+import { getLLMRequestBody } from "./getLLMRequestBody";
+import type { MCPToolSchema } from "./getLLMToolsAllowedInThisChat";
+import {
+  parseLLMResponseObject,
+  type LLMParsedResponse,
+} from "./parseLLMResponseObject";
+import { readFetchStream } from "./readFetchStream";
+export type LLMMessageWithRole = {
+  role: "system" | "user" | "assistant" | "model";
+  content: DBSSchema["llm_messages"]["message"];
+};
+export type FetchLLMResponseArgs = {
+  llm_chat: Pick<
+    DBSSchema["llm_chats"],
+    "extra_body" | "extra_headers" | "options"
+  >;
+  llm_model: DBSSchema["llm_models"];
+  llm_provider: DBSSchema["llm_providers"];
+  llm_credential: DBSSchema["llm_credentials"];
+  tools: undefined | (MCPToolSchema & { auto_approve: boolean })[];
+  messages: LLMMessageWithRole[];
+  aborter: AbortController;
+};
+
+export const fetchLLMResponse = async (
+  args: FetchLLMResponseArgs,
+): Promise<LLMParsedResponse> => {
+  const { llm_provider, llm_credential, llm_model, aborter } = args;
+
+  const model = llm_model.name;
+  const provider = llm_provider.id;
+  const { api_key } = llm_credential;
+  const { body, headers } = getLLMRequestBody(args);
+  const api_url = llm_provider.api_url
+    .replace("$KEY", api_key)
+    .replace("$MODEL", model);
+  if (api_url === "http://localhost:3004/mocked-llm") {
+    return {
+      responseData: { mocked: true },
+      content: [{ type: "text", text: "Mocked response" }],
+      cost: 0,
+      total_tokens: 0,
+    };
+  }
+
+  const res = await fetch(api_url, {
+    method: "POST",
+    headers,
+    body,
+    signal: aborter.signal,
+  }).catch((err) => {
+    const serialisableError = getSerialisableError(err);
+    return Promise.reject(serialisableError);
+  });
+  if (!res.ok) {
+    const contentType = res.headers.get("content-type");
+    const errorData = {
+      statusText: res.statusText,
+      statusCode: res.status,
+      error: "" as unknown,
+    };
+    if (contentType?.includes("application/json")) {
+      errorData.error = await res.json();
+    } else {
+      errorData.error = await res.text();
+    }
+
+    throw new Error(
+      `Failed to fetch LLM response: ${res.statusText} ${JSON.stringify(errorData)}`,
+    );
+  }
+  const responseClone = res.clone();
+
+  const responseData = (await readFetchStream(res)) as AnyObject | undefined;
+  if (!responseData) {
+    throw new Error(
+      "No response data from LLM. statusText:" + responseClone.statusText,
+    );
+  }
+
+  if ("error" in responseData) {
+    throw new Error(
+      `Error response from LLM: ${JSON.stringify(responseData)} statusText:${responseClone.statusText}`,
+    );
+  }
+
+  try {
+    return parseLLMResponseObject({
+      provider,
+      responseData,
+      model: llm_model,
+    });
+  } catch (e) {
+    console.error(
+      `Error parsing LLM response from ${provider} for model ${model}`,
+      getSerialisableError(e),
+      responseData,
+    );
+    throw new Error(
+      `Error parsing LLM response from ${provider} for model ${model}: ${JSON.stringify(getSerialisableError(e))} statusText:${responseClone.statusText}`,
+    );
+  }
+};

package/server/src/serverFunctions/askLLM/getCompactedMessages.ts

@@ -0,0 +1,101 @@
+import { filterArr } from "@common/llmUtils";
+import { type PROSTGLES_MCP_SERVERS_AND_TOOLS } from "@common/prostglesMcp";
+import type { JSONBTypeIfDefined } from "@src/McpHub/ProstglesMcpHub/ProstglesMCPServerTypes";
+import { isDefined } from "prostgles-types";
+import type { LLMMessageWithRole } from "./fetchLLMResponse";
+import { getProstglesMCPFullToolName } from "@common/mcpUtils";
+
+type CompactionInput = JSONBTypeIfDefined<
+  (typeof PROSTGLES_MCP_SERVERS_AND_TOOLS)["prostgles-ui"]["compact_context"]["schema"]
+>;
+export const getCompactedMessages = ({
+  nonEmptyMessages,
+}: {
+  nonEmptyMessages: LLMMessageWithRole[];
+}) => {
+  const compactionToolName = getProstglesMCPFullToolName(
+    "prostgles-ui",
+    "compact_context",
+  );
+
+  const getCompactionToolUse = (
+    message: (typeof nonEmptyMessages)[number],
+    type: "conversation" | "previous-message",
+  ) =>
+    filterArr(message.content, { type: "tool_use" as const }).find(
+      (c) =>
+        c.name === compactionToolName &&
+        (c.input as CompactionInput).type === type,
+    );
+
+  const lastConversationCompactionIndex = nonEmptyMessages.findLastIndex((m) =>
+    getCompactionToolUse(m, "conversation"),
+  );
+  const lastConversationCompactionMessage =
+    nonEmptyMessages[lastConversationCompactionIndex];
+
+  const messagesAfterCompaction: LLMMessageWithRole[] = nonEmptyMessages
+    .map((message, index) => {
+      if (message.role === "system" || index === 0) {
+        return message;
+      }
+
+      if (
+        lastConversationCompactionMessage &&
+        lastConversationCompactionIndex !== -1
+      ) {
+        if (
+          index < lastConversationCompactionIndex ||
+          /** Remove the compaction tool_result */
+          index === lastConversationCompactionIndex + 1
+        ) {
+          return undefined;
+        }
+        if (index === lastConversationCompactionIndex) {
+          const conversationSummary = getCompactionToolUse(
+            lastConversationCompactionMessage,
+            "conversation",
+          );
+          return {
+            ...message,
+            content: [
+              {
+                type: "text",
+                text: `Previous messages have been compacted to reduce context length. Summary: ${conversationSummary?.input!.summary}`,
+              },
+            ],
+          } satisfies LLMMessageWithRole;
+        }
+      }
+
+      const nextMessage = nonEmptyMessages[index + 1];
+      const hasCompactionToolUse =
+        !nextMessage ? undefined : (
+          getCompactionToolUse(nextMessage, "previous-message")
+        );
+      if (hasCompactionToolUse) {
+        const summary = hasCompactionToolUse.input!.summary;
+        return {
+          ...message,
+          content: message.content.map((c) => {
+            const text = `This message has been compacted to reduce context length. Summary: ${summary}`;
+            if (c.type === "tool_result") {
+              return {
+                ...c,
+                content: text,
+              };
+            }
+            return {
+              type: "text",
+              text,
+            };
+          }),
+        } satisfies LLMMessageWithRole;
+      }
+
+      return message;
+    })
+    .filter(isDefined);
+
+  return { messagesAfterCompaction };
+};

package/server/src/serverFunctions/askLLM/getFullPrompt.ts

@@ -0,0 +1,86 @@
+import { LLM_PROMPT_VARIABLES, wrapCode } from "@common/llmUtils";
+import { getProstglesMCPFullToolName } from "@common/mcpUtils";
+import { prostglesApiTypes } from "@common/prostglesApiTypes";
+import { getElectronConfig } from "@src/electronConfig";
+import { connectionManager } from "@src/index";
+import { statePrgl } from "@src/init/startProstgles";
+
+export const getFullPrompt = async ({
+  prompt,
+  schema,
+  connectionId,
+}: {
+  prompt: string;
+  schema: string;
+  connectionId: string;
+}) => {
+  const connInfo = await connectionManager.getConnectionData(connectionId);
+  const activeConnection =
+    connectionManager.getActiveConnectionSilentFail(connectionId);
+  const fileTableName = activeConnection?.dbConf.file_table_config?.fileTable;
+  const schemaWithInfo =
+    !schema ?
+      "Schema is empty: there are no tables or views in the database"
+    : [
+        "Below (in the next sql code block) is the schema of database they're currently working with expressed as create statements so you have a better idea of relationships and constraints.",
+        "\n\nIMPORTANT: Wrapped in an sql code block below is the schema of EXISTING TABLES AND VIEWS from the database. Tables can be accessed through the database tools. The schema is expressed as create statements to give you a better idea of relationships and constraints.",
+        wrapCode("sql", schema),
+        `\n`,
+        `When interacting with the tables through non raw SQL tools, it is important that you include double quotes for table names that need escaping. `,
+        `For example: db.find(${JSON.stringify("my users")}); db.insert("tools");`,
+        ...(!fileTableName ?
+          []
+        : [
+            `The database has file storage enabled. The table named "${fileTableName}" stores only the necessary metadata and is used to facilitate file access:`,
+            `- Files can be inserted only through ${getProstglesMCPFullToolName("db", "insert")} or ${getProstglesMCPFullToolName("db", "insertMany")} and only these properties can be inserted: "data", "original_name", "original_last_modified", "content_type"`,
+            `- Files can be updated only through ${getProstglesMCPFullToolName("db", "update")} and only these properties can be updated: "data", "original_name", "original_last_modified", "content_type"`,
+            `- Files can be deleted only through ${getProstglesMCPFullToolName("db", "delete")}`,
+            `- Actual file data can be accessed by fetching the "url". The "data" column in the database is just a dummy placeholder.`,
+            `- The "text_content" and "docling_metadata" columns can be used for text searching. They are populated by the document (docling) service which extracts text data from applicable file types.`,
+          ]),
+        `\n`,
+        `When you need to reference records from the database use an anchor to ensure the user can quickly preview them.`,
+        `The tag must be of this format for a single record: `,
+        wrapCode(
+          "html",
+          `<a href="#record" data-table-name="{the name of the table}" data-column-name="{the name of the column to filter by (should ideally have a pkey constraint)}" data-column-value="{the value of the column/pkey}">{pkey and/or name and/or other data}</a>`,
+        ),
+        `And this format for multiple records: `,
+        wrapCode(
+          "html",
+          `<a href="#records" data-table-name="{the name of the table}" data-filter="{valid DetailedTableFilter[] filter expressed as json. E.g.: [{ "fieldName": "temperature", "type": "$gt", "value": 22 }]">{some relevant text}</a>`,
+        ),
+      ].join("\n");
+  const promptWithContext = prompt
+    .replaceAll(
+      LLM_PROMPT_VARIABLES.PROSTGLES_SOFTWARE_NAME,
+      getElectronConfig()?.isElectron ? "Prostgles Desktop" : "Prostgles UI",
+    )
+    .replace(
+      LLM_PROMPT_VARIABLES.TODAY,
+      new Date().toISOString().split("T")[0]!,
+    )
+    .replace(LLM_PROMPT_VARIABLES.SCHEMA, schemaWithInfo)
+    .replace(
+      LLM_PROMPT_VARIABLES.DB_TYPESCRIPT_SCHEMA,
+      wrapCode(
+        "typescript",
+        (() => {
+          if (connInfo.is_state_db)
+            return statePrgl?.getTSSchema().tsSchema ?? "";
+          const prglConn = connectionManager.prglConnections.get(connectionId);
+          if (!prglConn || prglConn.state !== "started") return "";
+          return prglConn.prgl.getTSSchema().tsSchema;
+        })(),
+      ),
+    )
+    .replace(
+      LLM_PROMPT_VARIABLES.DB_HANDLER_SCHEMA,
+      wrapCode("typescript", prostglesApiTypes),
+    );
+  // .replace(
+  //   LLM_PROMPT_VARIABLES.DASHBOARD_TYPES,
+  //   wrapCode("typescript", dashboardTypesContent),
+  // );
+  return promptWithContext;
+};