Package com.inductiveautomation.ignition.common.ai


@NullMarked package com.inductiveautomation.ignition.common.ai
Scope-independent SPI for driving conversations with a language model. Everything here is interface-and-record only: the AI module supplies the implementations, and the gateway and Designer each expose a scope-specific facade (GatewayAiContext, DesignerAiContext) that extends AiContext. Code that only needs to ask a model a question should depend on this package and nothing else.

The three roles

Agent is configuration — a system prompt, a set of CallableTools, and optional supplemental context. Agents are stateless recipes, built fresh per harness through an Agent.AgentFactory.

AgenticHarness is one conversation. It pairs an agent with a specific model, accumulates message history across send calls, and runs the tool-calling loop. Two harnesses built from the same agent share no memory.

AiContext is the factory and registry. It resolves provider/model names against the scope's catalog, mints harnesses through AiContext.HarnessBuilder, and tracks every harness it minted.

Harness lifecycle and ownership

A harness has exactly one owner: whoever called build(). Ownership carries a close obligation, and it is not advisory. The context holds each harness it mints by strong reference so that its registry of live harnesses can be authoritative — an entry there is a live harness, not a guess. The only thing that removes an entry is AgenticHarness.close().

The consequence is direct: a harness that is never closed is never collected, and neither is anything it reaches. That is more than the conversation buffer. A harness's event consumer and per-host tools typically capture the UI or component that built it, so a missed close on a hosted harness pins a Perspective component model and its session, or a Swing panel and its whole hierarchy.

Two shapes cover every case:

  • One-shot — a route, a script call, a single send. Use try-with-resources.
  • Long-lived — a harness parked in a field for the life of a component, panel, or session. Close it in the teardown hook that matches the construction site, and close the outgoing harness before assigning a replacement. Rebuild-on-config-change is the most common leak: the owner survives, so nothing else will ever close the harness it just discarded.

close() is idempotent and does not interrupt an in-flight send; cancel your own work first if you need the turn to stop. A send after close throws IllegalStateException.

Transcripts

Every harness writes a JSONL transcript of its conversation, and the harness owns that file: it opens one when it is built and closes it as part of close(). The owning AiContext decides where transcripts land and how many are kept — on the gateway, under the logs directory; in the Designer, under the user's home. A caller's only say in the matter is AiContext.HarnessBuilder.transcript(com.inductiveautomation.ignition.common.ai.TranscriptPolicy), which opts one harness out. There is no writer to hold, pass, or close, and a transcript that cannot be written never fails a turn.

Observing a running conversation

Two channels, aimed at different consumers. HarnessEvent is a push stream delivered synchronously on the thread driving the turn — turn boundaries, tool calls, reasoning traces, token spend. UI consumers attach one via HarnessBuilder.events(...) and marshal to their own event thread. HarnessInfo is the pull side: an immutable snapshot with identity, model, timestamps, and cumulative counters, read from the owning context's harness registry — a scope-internal surface, not part of this SPI, whose gateway consumer is the AI sessions page. Snapshots deliberately carry no handle on the harness, so a status page can enumerate AI activity without being able to drive a conversation it does not own.

Errors

Provider-side failures — auth, rate limits, timeouts, unreachable endpoints — arrive as UpstreamModelProviderException, a checked exception with a reason() that keeps the provider's own failure as its cause. Anything else propagating out of send came from a tool or from the caller's own code.

Extension guidance

Types here must be usable from gateway, Designer, and client scopes, which rules out any dependency on scope-specific context objects or on the AI module's own classes. Scope-specific capability belongs on the facade interface for that scope; implementation belongs in the AI module. This SPI is implemented outside the platform, so treat additions to AiContext and AgenticHarness as breaking changes.