Class PerspectiveScriptGrounding

java.lang.Object
com.inductiveautomation.perspective.designer.ai.PerspectiveScriptGrounding

public final class PerspectiveScriptGrounding extends Object

Produces the AI grounding for one Perspective script-editing surface: the framing string that describes where the body lives, the read tools the agent can call for anything the framing does not carry, and the @-reference sources the prompt offers.

Construct one per editor and hand it to PerspectiveScriptAssistMounter.attach(ExtensionFunctionPanel, PerspectiveScriptGrounding, Supplier), which mounts the "Ask AI" button. This class decides what the agent knows; the mounter decides how that reaches it.

The component the body is written against is fixed when its editor window opens: its name, type and target count all describe that component, never whatever is selected when the prompt is sent. The editor windows are non-modal, so the Designer's selection can move while one is open; reading the type off the live selection would name one component with another's type. The message type code and the checked listen scopes, by contrast, are live widget state, re-read on the Event Dispatch Thread at prompt time. Nothing here blocks — the component registry is held locally in the Designer, so the reads are cheap enough to sit inside the framework's synchronous context assembly. Anything that would cost a Gateway round trip belongs in PerspectivePropertyTools instead, which the agent calls from its own thread when it needs it.

Facts that cannot be read degrade to unstated rather than to an error, so an assistant opened on a multi-selection, on a component whose type is not in the registry, or before a message type has been typed still answers.

  • Constructor Details

    • PerspectiveScriptGrounding

      public PerspectiveScriptGrounding(DesignAdapter adapter, Supplier<Optional<ComponentPath>> primaryComponentPath, PerspectiveScriptGrounding.TargetSnapshot targetSnapshot)
      Parameters:
      adapter - the Perspective design adapter for the workspace the editor belongs to; the source of the view path and of the read tools' view of the component graph.
      primaryComponentPath - the anchor component's path as the editor window recorded it when it opened. Typically context::getPrimaryComponentPath or the editor frame's own accessor.
      targetSnapshot - the anchor component's type and the target count, captured when the editor window opened alongside primaryComponentPath.
  • Method Details

    • callerContextFor

      public Supplier<String> callerContextFor(PerspectiveScriptSurface surface)
      The framing for a surface that needs no facts beyond the component it is defined on — custom methods and extension functions. Message handlers and property change scripts must use messageHandlerCallerContext(Supplier, Supplier) and propertyChangeCallerContext(Supplier) instead: without their live configuration, a message handler would be framed as having no type code and no listen scope, telling the agent that nothing can ever reach it.
      Parameters:
      surface - the surface being framed; PerspectiveScriptSurface.CUSTOM_METHOD or PerspectiveScriptSurface.EXTENSION_FUNCTION.
      Returns:
      a supplier building the framing on each prompt.
      Throws:
      IllegalArgumentException - if surface is one that has a variant of its own.
    • messageHandlerCallerContext

      public Supplier<String> messageHandlerCallerContext(Supplier<@Nullable String> messageType, Supplier<List<String>> listenScopes)
      The framing for a component message handler, adding the routing that decides whether the body ever runs.
      Parameters:
      messageType - the message type code as currently typed; blank until the user fills it in.
      listenScopes - the currently checked listen scopes, as "session" / "page" / "view". An empty list is a meaningful state — nothing reaches the handler — and is framed as such.
      Returns:
      a supplier re-reading the handler's form on each prompt.
    • propertyChangeCallerContext

      public Supplier<String> propertyChangeCallerContext(Supplier<@Nullable String> propertyDescription)
      The framing for a property change script, adding the property whose change runs the body.
      Parameters:
      propertyDescription - a human description of the triggering property, e.g. Button1.props.text.
      Returns:
      a supplier re-reading the property on each prompt.
    • componentCallerContext

      public Supplier<String> componentCallerContext(Supplier<String> surfaceFraming)
      The framing for a component script surface Perspective does not define — one a module adds to the scripts editor through a ScriptCategoryProvider, such as an AI Chat's Agent Tools. The module describes its own surface; this adds what self is, its members, and the view it is on, exactly as the built-in surfaces state them.
      Parameters:
      surfaceFraming - the module's description of the surface: who calls the body, what it receives and what it must return. Re-read on each prompt, so it may read live form state.
      Returns:
      a supplier building the combined framing on each prompt.
    • tools

      public ToolBundle tools()
      Returns:
      the read-only Perspective tools every scripting surface offers — the selection, the view structure, and the component graph with its bindings, scripts and property values.
    • promptAssists

      public List<PromptAssist> promptAssists(DesignerAiContext ai)
      The @-reference sources every scripting surface offers: tags, the components of the current view, and Perspective property paths. The tag browser is the platform's own, taken default-configured off ai.promptAssists() the way the binding and property editors take theirs; only the two Perspective-specific assists are constructed here.
      Parameters:
      ai - the Designer AI context the button will be mounted against, the owner of the shared platform assists.
      Returns:
      the assists, in the order the @-popup should present them.