Class AiToolKernel

java.lang.Object
com.kingsrook.qqq.backend.core.actions.ai.AiToolKernel
public class AiToolKernel extends Object
The AI tool kernel: the one permission-checked path through which an AI model (the in-app assistant, an MCP server, ...) reads QQQ data. The tool set is generic and stable (list_tables, describe_table, query_records, count_records, get_record, search_records, get_record_history, render_widget, search_help, navigate), plus any READ or NAVIGATION tools that qbits contribute through AiToolRegistry: the same definitions for every user, so they cache well. Permissions are applied when a tool runs, as the requesting user - never a system session: 1. QContext is set up for the user's session (and the caller's context is restored afterwards - so execute is re-entrant). 2. Metadata visibility (DENY_HIDE objects are invisible) and the exposure policy (AiExposure, AiTableMetaData, AiFieldMetaData). 3. PermissionsHelper checks for the specific operation (READ on the table, joined tables, the widget, READ on the audit table for history) - always made by the kernel itself, as defense in depth, even when core actions enforce permissions too. 4. The QQQ action, with input source USER, hidden fields omitted and passwords masked - so record security locks apply. 5. A post-filter (only exposed field values; MASKED values masked; METADATA_ONLY never), truncation (maxRowsToModel, maxCellChars) and redaction of secrets and PII. 6. The data envelope around everything sent back to the model. execute never throws: permission and validation problems are outcomes (DENIED, NOT_FOUND, INVALID_INPUT) with a polite message, and unexpected errors are an ERROR outcome with a generic message (details are logged).

  • Field Details

  • Constructor Details

  • Method Details

    • getBuiltInToolNames

      public static Set<String> getBuiltInToolNames()
      The names of the built-in tools (sorted). Contributed tools (AiToolRegistry) may not use them.

    • getToolDefinitions

      public List<AiToolDefinition> getToolDefinitions()
      The tool definitions - sorted by name, identical for every user and every call (no timestamps or per-user content), so they are cache-friendly. Each call returns new objects, so a caller can't change another's.

    • execute

      public AiToolResult execute(QSession session, AiToolCall call)
      Run one tool call as the given (user's) session. Never throws.

    • buildAppDigest

      public String buildAppDigest()
      A digest of the application for a (cached, shared) system prompt: the apps, tables, processes and widgets - names, labels, aiDescriptions and help summaries - that EVERY user may see. So it only includes objects whose permission rules can't deny anyone (level NOT_PROTECTED, no custom permission checker - and nothing at all if the instance has a meta-data action customizer, which may hide objects per user); permission-restricted objects are described per user, in buildUserDigest. Hidden objects, tables with exposure NONE and widgets not allowed for the assistant are excluded. The same for every user and deterministic (sorted by name), so it can sit in a cached prompt prefix. Contains no data.

    • buildUserDigest

      public String buildUserDigest(QSession session)
      A digest of the user for a (per-user) prompt section: name, timezone, the tables the user can read through the assistant (with their insert / edit / delete permissions) - and descriptions of the permission-restricted tables, apps, processes and widgets this user may use (which the shared app digest leaves out). Objects the user can't see (DENY_HIDE) or use are never named. Sorted by name.

    • describeAccess

      public AiAccessReport describeAccess(QSession session, String tableName, Serializable primaryKey)
      What the assistant may do with a table (and optionally one record) for a user - for the record Developer screen. Permission-scoped: a table that is missing, invisible (DENY_HIDE) or not readable by the user - or a record the user can't read - is reported as "not available", with nothing more about it. Hidden and password fields are omitted. Never throws.

    • getSettings

      public AiToolKernelSettings getSettings()
      Getter for settings