Package com.inductiveautomation.eventstream.designer.ai.tools


@NullMarked package com.inductiveautomation.eventstream.designer.ai.tools

The expensive half of the Event Stream AI grounding: the on-demand tools an agent calls when it wants a real captured event rather than a description of one.

The split this package sits on is described in the parent package. The short version: the embed framework assembles a caller context synchronously on the Event Dispatch Thread and forbids that assembly from blocking, so a sample — which costs a blocking Gateway RPC — cannot be embedded inline. It rides a tool instead, invoked from the agent's tool loop on a background thread, which also makes it lazy and always current.

SampleTools is the only public type here. Callers hand it the RPC, the resource's coordinates, and an EDT-only read of the live configuration, and ask it for the tool a EventStreamSurface should install. Everything else is package-private.

Inside

A fetch is a three-step hand-off, and each step is a type:

  1. SamplePlan is the decision — which encoder describes a surface's events and which stages a sample must pass through to reach it. It is the only place the pipeline's stage layout is known, and its one entry point is keyed by EventStreamSurface. It is a pure function of the configuration it is handed, so it carries no threading contract of its own.
  2. SampleFetcher is the hand-off — where the two threads meet. It reads the configuration and decides the plan on the Event Dispatch Thread, then runs the resulting fetch on the tool thread, with the plan as the value that crosses between them, carrying everything the run needs, already read.
  3. EventStreamPreviewClient is the run — the only class here that reaches the Gateway. It touches no Swing state, so it states one flat rule (never call it on the Event Dispatch Thread) rather than carrying the fetcher's two-threaded contract.

What comes back is a SampleEvent: the captured event, or a failure saying why there is none, worded for the model to read — PreviewStageFailures is what turns the Gateway's bare "no output" facts into that wording, and is also what recognizes the one failure that is an answer rather than a fault, a Filter that rejected the event.

Splitting decision from run is what lets a sample fetch straddle the two threads at all, and it leaves the branching that decides a sample — filter applied or bypassed, transform output or source-encoded — testable without a Gateway or a Designer.

The two tools

The Filter surface installs EventStreamSampleTool, which takes no arguments: it is the one surface upstream of the Filter, so its sample is simply the source-encoded event with nothing that could stop it from arriving. Every surface downstream of the Filter — the transform, the error handler, the handlers — installs EventStreamFilterableSampleTool, whose applyFilter argument exists because those bodies only ever see events an enabled Filter forwarded. A Filter that rejects everything means there is no sample, not a different one.

  • Classes
    Class
    Description
    The package's one public face: hands out the on-demand sample tools an Event Stream script-assist agent installs, keyed by the surface being edited.