This document defines the current reviewed Java API surface for ModelMatrix4J. It is a repository-level compatibility and review boundary used by documentation and standalone consumer verification.
Only public top-level types explicitly listed in this document are part of the supported Java API. Package membership alone does not create a compatibility promise. A newly added public helper is therefore not automatically supported API; it must be reviewed and deliberately added to this baseline.
A listed supported top-level type includes its current public API surface: public constructors, methods, fields/constants, record components, and public nested types together with their public members. For example, ModelMatrix includes ModelMatrix.Builder; ToolCallComparison includes ToolCallComparison.Status; and StructuredOutputResult includes its public nested status/observation types. These nested types do not need separate allowlist entries because they are already part of the listed top-level type's public surface.
Adding, removing, renaming, or incompatibly changing a public member or public nested type of a listed supported top-level type still requires compatibility review. A future nested type is not exempt from review merely because its enclosing top-level type is already listed.
Package-private implementation types, public framework wiring types not listed below, test fixtures, integration-test infrastructure, Maven profiles, and internal execution helpers are not supported Java API.
The supported surface is grouped into four categories:
- Core domain and execution API — stable provider-neutral contracts used directly by applications and tests.
- Capability API — provider-neutral structured-output, tool, retrieval, and MCP contracts used when that capability is enabled.
- Adapter API — Spring AI integration types whose signatures necessarily track the supported Spring AI line.
- Report API — the Java projection/writer API. The durable report schema has its own compatibility contract in
REPORT_SCHEMA.mdand is not versioned implicitly by Java API changes.
Supported consumer API:
com.modelmatrix4j.core.execution.ModelMatrixcom.modelmatrix4j.core.scenario.Scenariocom.modelmatrix4j.core.model.ModelAdaptercom.modelmatrix4j.core.model.ModelDescriptorcom.modelmatrix4j.core.model.ModelUnderTestcom.modelmatrix4j.core.model.ModelUnavailableExceptioncom.modelmatrix4j.core.result.CompatibilityResultcom.modelmatrix4j.core.result.CompatibilityStatuscom.modelmatrix4j.core.result.RunResultcom.modelmatrix4j.core.result.RunStatus
ModelMatrix and its public builder API are the execution facade. Core remains JDK-only. No Spring, provider, capability, report, MCP, or persistence type may enter a supported core signature.
Package-private orchestration types such as executors, invocation runners, execution settings/outcomes, evaluators, and result mappers are implementation details.
Supported consumer API:
com.modelmatrix4j.junit.ModelMatrixTestcom.modelmatrix4j.junit.ModelMatrixSource
ModelMatrixExtension is public because JUnit's composed annotation wiring must be able to reference and instantiate it, but it is framework wiring, not direct consumer API. Its constructor and direct BeforeEachCallback / ParameterResolver usage are not part of the compatibility baseline. Consumers should use ModelMatrixTest plus ModelMatrixSource.
If a future use case requires direct extension registration, that must be reviewed explicitly before ModelMatrixExtension is added to the supported type list.
Supported consumer API:
com.modelmatrix4j.structured.JsonObjectSchemacom.modelmatrix4j.structured.JsonValueComparatorcom.modelmatrix4j.structured.StructuredOutputEvaluatorcom.modelmatrix4j.structured.StructuredOutputExecutioncom.modelmatrix4j.structured.StructuredOutputObservationcom.modelmatrix4j.structured.StructuredOutputResult
These types own semantic JSON comparison, schema validation, structured observations/results, and composition with the core lifecycle. Public nested result/status vocabulary exposed by these listed types is included in the compatibility baseline under the rule above.
Supported consumer API:
com.modelmatrix4j.tool.ToolAdaptercom.modelmatrix4j.tool.ToolArgumentValidatorcom.modelmatrix4j.tool.ToolCallComparatorcom.modelmatrix4j.tool.ToolCallComparisoncom.modelmatrix4j.tool.ToolCallObservationcom.modelmatrix4j.tool.ToolExecutioncom.modelmatrix4j.tool.ToolInvocationcom.modelmatrix4j.tool.ToolModelcom.modelmatrix4j.tool.ToolObservation
These types own Java tool-call capture/composition, JSON argument validation, and comparison semantics. Public nested status vocabulary such as ToolCallComparison.Status is included in the listed top-level type's supported surface.
Supported consumer API:
com.modelmatrix4j.rag.RetrievalAdaptercom.modelmatrix4j.rag.RetrievalComparatorcom.modelmatrix4j.rag.RetrievalEvaluatorcom.modelmatrix4j.rag.RetrievalExecutioncom.modelmatrix4j.rag.RetrievalInvocationcom.modelmatrix4j.rag.RetrievalModelcom.modelmatrix4j.rag.RetrievalObservationcom.modelmatrix4j.rag.RetrievalResultcom.modelmatrix4j.rag.RetrievedDocument
These types own provider-neutral retrieval observations, stable logical document identity, evaluation, comparison, and core-lifecycle composition.
Supported consumer API:
com.modelmatrix4j.mcp.McpAdaptercom.modelmatrix4j.mcp.McpComparatorcom.modelmatrix4j.mcp.McpEvaluatorcom.modelmatrix4j.mcp.McpExecutioncom.modelmatrix4j.mcp.McpInvocationcom.modelmatrix4j.mcp.McpModelcom.modelmatrix4j.mcp.McpObservationcom.modelmatrix4j.mcp.McpResultcom.modelmatrix4j.mcp.McpToolInteraction
These types own application-visible MCP tool-interaction observations and comparison. MCP transport/session/resource internals are not part of this baseline.
Capability-local evidence remains outside RunResult. Capability execution APIs compose with the core lifecycle and must not create a second model invocation merely for evaluation.
Supported adapter API:
com.modelmatrix4j.springai.SpringAiModelAdaptercom.modelmatrix4j.springai.SpringAiToolCallAdaptercom.modelmatrix4j.springai.SpringAiRetrievalAdaptercom.modelmatrix4j.springai.SpringAiMcpToolAdapter
These types translate supported Spring AI APIs into core/capability contracts. Spring AI types are allowed here and nowhere in provider-neutral modules.
Package-private callback decorators such as SpringAiMcpToolObserver are not API. Changes forced by a supported Spring AI major/minor line are adapter compatibility concerns; they must not silently widen or break core contracts.
Supported consumer API:
com.modelmatrix4j.report.CompatibilityReportcom.modelmatrix4j.report.JsonReportWritercom.modelmatrix4j.report.ReportCompatibilityStatuscom.modelmatrix4j.report.ReportProjectorcom.modelmatrix4j.report.ReportRunStatuscom.modelmatrix4j.report.RunReportcom.modelmatrix4j.report.TextReportWriter
ReportProjector is the boundary from core results into the report model. The Java report API and the durable schema are deliberately separate contracts. Schema compatibility is defined in REPORT_SCHEMA.md; core enum evolution must be mapped explicitly rather than leaking into an existing schema version.
A Java type is not part of the compatibility baseline merely because it is declared public. In particular, the following are implementation/framework details unless they are explicitly added to the supported type list above:
ModelMatrixExtensiondirect construction or direct extension-callback behavior;- matrix executors, invocation runners, execution outcome carriers, result mappers, evidence stores, correlation keys, callback decorators, and similar implementation helpers;
- deterministic fixtures used only from tests;
- Ollama, pgvector, and MCP integration-test lifecycle code;
- Maven profile names as a Java compatibility promise;
- incidental
toString()formats unless a document explicitly defines them as durable output; - JSON produced by serializing arbitrary Java records directly. Only the documented report schema is durable serialized output.
No internal helper should be made public merely to simplify tests. When framework mechanics require a public type that consumers are not expected to use directly, this baseline must explicitly classify it as framework wiring rather than relying on package-level assumptions.
Public constructors, record canonical constructors/components, methods, constants, and public nested types of supported top-level types are API. Each must have a consumer-facing reason to exist. Validation performed by supported constructors is part of the observable contract and should be covered by tests.
A constructor or public nested type on an unlisted framework-wiring or implementation top-level type does not become supported API merely because Java visibility makes it callable.
New public members should be preferred only when they represent a stable consumer path. Internal correlation/state objects should remain package-private instead of exposing types or constructors that consumers are not expected to call.
This document is a reviewed repository boundary and may be tightened deliberately as the project evolves.
Adding a new supported top-level type requires an explicit edit to this baseline. Simply adding a new top-level public declaration does not create a compatibility guarantee. Adding a public member or nested type to an already listed supported type is additive API, but still requires compatibility review because it expands the supported surface.
Additive APIs should still be justified by a concrete consumer. ModelMatrix4J does not use public generic extension frameworks such as Evidence<T> as placeholders for possible future capabilities.
The durable report schema follows its independent schema-version policy even when the corresponding Java change would otherwise be source/binary compatible.
Before adding or changing a supported public API:
- Is the top-level type explicitly listed in this baseline, or is the member/nested type part of a listed top-level type?
- Is there a concrete external consumer path?
- Can the type/member remain package-private or framework-only?
- Does the signature leak Spring/provider/capability types across the wrong module boundary?
- Does the change alter timeout, cancellation, repetition, ordering, failure, or evidence semantics?
- Does a public record/constructor expose data that should remain capability-local or persistence-restricted?
- Does a report change require a report schema-version decision?
- Is the API documented sufficiently for generated Javadocs without reading implementation code?
- Is the behavior covered through the public entry point?
Standalone external-consumer verification uses this baseline to guard the reviewed API surface.