Package com.tnsai.agents.validation.validators

Class LLMHealthcheckValidator

java.lang.Object
com.tnsai.agents.validation.validators.LLMHealthcheckValidator
All Implemented Interfaces:
ReachabilityValidator, Validator
public final class LLMHealthcheckValidator extends Object implements ReachabilityValidator
AGENT-V005 — opt-in reachability probe for the configured LLMClient.

Runs only when AgentBuilder.withReachabilityChecks(true) is set. Surfaces the all-too-common situation where the agent builds fine but the very first chat call hits an unreachable provider / wrong API key / rate-limited account — symptoms that today only appear minutes into production.

Behaviour matrix

Probe outcomes
StateOutcome
No LLM configured Silent (V002 owns the missing-LLM signal)
LLM does not implement Healthcheckable Silent — the provider has not opted into probeability and the framework can't synthesise a meaningful probe (a chat call costs money / a list-models call returns empty by default)
Probe returns reachable=true Silent
Probe returns reachable=false WARNING with provider-supplied error message + observed latency in the structured context
Probe throws (contract violation — implementations must convert failures to unreachable) WARNING with the throwable's message; never propagates the exception out of validation

Severity is WARNING, not ERROR — networks are transient and the user has explicitly asked for the probe; failing the build outright on a momentary blip would be hostile. Suppress with .relaxValidation("AGENT-V005") for environments where the probe-time provider is genuinely different from the runtime provider.

Since:
0.8.4 (issue #85 phase 2a)

  • Constructor Details

    • LLMHealthcheckValidator

      public LLMHealthcheckValidator()

  • Method Details

    • id

      public String id()
      Description copied from interface: Validator
      Short, stable id for logging and test assertions (e.g. "llm-presence").
      Specified by:
      id in interface Validator

    • validate

      public List<ValidationIssue> validate(ValidationContext ctx)
      Description copied from interface: Validator
      Inspect the agent configuration and return any issues detected. Returning an empty list means "no problems found by this validator".
      Specified by:
      validate in interface Validator
      Parameters:
      ctx - frozen view of the agent under construction
      Returns:
      zero-or-more issues; never null