SPI reference

Register an implementation

1. Implement the interface in a public class with a public no-argument constructor.
2. Create src/main/resources/META-INF/services/<interface binary name>. For a nested interface, the binary name puts $ before the nested name, so the file for PlannerHandle.Factory is named ...PlannerHandle$Factory.
3. Put the fully qualified class name of your implementation on its own line in that file.

For example, an audit store that writes to your own database:

# src/main/resources/META-INF/services/com.tnsai.security.audit.AuditStore
com.example.audit.JdbcAuditStore

On the module path, declare the implementation with provides ... with ... in module-info.java instead.

Service interfaces

These are the interfaces the framework loads with ServiceLoader. "Built in" lists the implementations that TnsAI's own modules register.

Agents and runtime

LLM providers

Knowledge and RAG

Optional-module handles

tnsai-core reaches the intelligence, quality and coordination modules through a nested Factory interface on each handle. Factory.discover() returns the first registered factory, or null when the module is absent, and the caller then uses the handle's no-op.

Security, quality and evaluation

Observability, channels and MCP

How lookups are cached

Most lookups go through com.tnsai.spi.SpiLoader, which keeps one immutable snapshot of the providers per service type and class loader:

The cache holds its keys and snapshots weakly, so it does not keep an application class loader alive after a redeploy. Three lookups call ServiceLoader directly instead:

• MemoryStoreFactory creates fresh providers on every call, because each memory store holds one agent's state.
• EmbeddingFunctionRegistry reads the provider descriptors first, so two installed embedding functions fail before either one is constructed.
• ContentExtractorRegistry sorts extractors by class name, so load order never decides which one handles a format. A built-in extractor gives way to yours for the same format, and two of your own that claim one format fail.

Checkpointers

CheckpointerFactory.getInstance() collects every CheckpointerProvider and adds two of its own: memory (priority -100) and file (priority -50, JSON files). When two providers share a name, the one with the higher priority wins.

CheckpointerFactory factory = CheckpointerFactory.getInstance();

List<String> available = factory.availableProviders();
Checkpointer files = factory.create("file", Map.of("path", "./data"));
Checkpointer best = factory.createBest(Map.of("path", "./data"));   // highest-priority available provider
Checkpointer memory = factory.createInMemory();

A provider implements name(), isAvailable() and create(config), and can override description(), priority() and validateSpec(config). TnsAI ships no database provider. This example shows the shape of one you would write yourself and register under META-INF/services/com.tnsai.spi.CheckpointerProvider:

public class PostgresCheckpointerProvider implements CheckpointerProvider {
    @Override
    public String name() { return "postgres"; }

    @Override
    public boolean isAvailable() {
        try {
            Class.forName("org.postgresql.Driver");
            return true;
        } catch (ClassNotFoundException e) {
            return false;
        }
    }

    @Override
    public Checkpointer create(Map<String, Object> config) {
        return new MyPostgresCheckpointer((String) config.get("url"));   // your Checkpointer implementation
    }
}

Types you create in code

These types are not loaded with ServiceLoader. You create them with their factories or implement them on your own components.

CognitiveModel

CognitiveModel holds beliefs, goals and intentions, and reason(context) returns the next Action, if there is one. CognitiveModel.bdi() returns a builder with withBelief, withGoal and build(). CognitiveModel.reactive() returns a reactive model. snapshot() and restore(state) save and reload the model's state. AgentBuilder does not wire a cognitive model; you keep and call it yourself.

Two other extension points are registered in code as well:

• Agent tools: AgentBuilder.builtInTools(...), toolPojos(...) and dynamicTool(...). See Register tools.
• LLMConfigurationSource, for per-agent LLM overrides on the SCOP bridge: SCOPBridge.llmConfigurationSource(...). See LLM configuration.

Related

• Register tools
• Actions
• Resilience
• Payments