Package com.tnsai.spi

Interface Healthcheckable

public interface Healthcheckable
Opt-in marker for components whose backing service can be reached over the network or another out-of-process boundary, and that can answer a lightweight reachability probe in bounded time.

The framework's pre-flight validation pipeline (issue #85) uses this SPI to surface unreachable dependencies at AgentBuilder.build() time — when the user has explicitly opted in via .withReachabilityChecks(true) — instead of letting the failure surface at first chat or first tool call, often minutes into production.

Implementing

Any component implementation can implement this interface to declare itself probeable. Typical implementers:

  • LLMClient subclasses — a single-token chat / list-models call
  • MemoryStore subclasses — a probe write/read of a synthetic key
  • McpClient subclasses — the MCP initialize handshake

The probe MUST:

  • Be cheap — no large requests, no long-lived state
  • Be idempotent — repeated calls do not change observable state
  • Honour the supplied timeout — a slow remote service must not block the caller longer than the budget
  • Never throw — return Healthcheckable.HealthStatus.unreachable(String, Duration) on any failure so callers don't need try/catch around the probe

Why a marker, not a base-interface default method

LLMClient, MemoryStore, and McpClient are protected APIs — adding a default method to each would impose a probe contract on every implementor. Marker SPI keeps the choice explicit: a provider that hasn't decided what a meaningful probe looks like stays silent, and validators degrade gracefully via an instanceof Healthcheckable guard.

Since:
0.8.4 (issue #85 phase 2a)