Package dyntabs.ai.event

Class EasyAIEvent

java.lang.Object
dyntabs.ai.event.EasyAIEvent
public final class EasyAIEvent extends Object
One immutable, transport-agnostic "something happened" notification emitted by any EasyAI capability (chat, assistant, RAG, agent, indexer, extract) while it works.

What this class is for

EasyAI normally does its job silently and hands you a final answer. An EasyAIEvent is the opposite: it lets a capability narrate itself as it runs — "I started", "I'm calling tool X", "tool X returned", "I'm on document 7 of 200", "I finished". You subscribe with an EasyAIListener and receive a stream of these.

Familiar analogy: think of a sports play-by-play commentator. The match (the AI operation) would happen regardless, but the commentator turns it into a live, human-readable stream of moments: "kickoff… pass… shot… goal!". An EasyAIEvent is one such sentence. Equivalently: it is a single structured log line, but pushed to you in real time instead of written to a file.

Why "transport-agnostic" matters

This object knows nothing about HTTP, Server-Sent Events, WebSockets, or any UI's JSON schema. It is a plain value. You decide what to do with it — log it, count it, or (as in the TabForge demo) map it to a UI event and push it over SSE to an Activity panel. That decoupling is deliberate: EasyAI stays a pure library, and the same event stream can feed a log, a metric, or a live dashboard without EasyAI ever depending on any of them.

How the fields are read downstream

source says who emitted it, phase says which moment in the lifecycle it is, status says how it is going, and title/ detail/toolName are the human-readable payload. sequence is the 1-based ordinal within a single operation (handy for ordering a timeline), and timestamp is when it happened.

Instances are created by EventEmitter (which fills in sequence and timestamp for you), or via EasyAIEvent.Builder directly in tests. They are immutable and therefore safe to hand to another thread or queue.

See Also:

  • Method Details

    • source

      public EasyAIEvent.Source source()
      Returns:
      the capability that emitted this event; never null.

    • phase

      public EasyAIEvent.Phase phase()
      Returns:
      the lifecycle moment this event marks; never null.

    • status

      public EasyAIEvent.Status status()
      Returns:
      the visual status, or null if not meaningful for this event.

    • title

      public String title()
      Returns:
      a short human-readable label (e.g. "Indexing documents"), or null.

    • detail

      public String detail()
      Returns:
      a secondary descriptive line (e.g. "document 7 of 200"), or null.

    • toolName

      public String toolName()
      Returns:
      the tool/method name when this event concerns a tool call, else null.

    • sequence

      public long sequence()
      Returns:
      the 1-based ordinal of this event within its operation (0 if unset).

    • timestamp

      public Instant timestamp()
      Returns:
      when the event was created; never null.

    • builder

      public static EasyAIEvent.Builder builder(EasyAIEvent.Source source, EasyAIEvent.Phase phase)
      Start building an event for the given source and phase.

      Most application code never calls this — EventEmitter builds events for you. It is exposed mainly for tests that want to assert on a hand-crafted event.

      Parameters:
      source - the emitting capability (required)
      phase - the lifecycle moment (required)
      Returns:
      a new EasyAIEvent.Builder

    • toString

      public String toString()
      Overrides:
      toString in class Object