TensorAPI.comContracts before compute
Tensor API contracts that preserve meaning
A Tensor API connects an application to numerical operations through an agreed input and output format. Its most important design work happens before inference: naming the data, defining its dimensions, and deciding what a consumer can rely on. This guide helps you write a compact contract for your own workflow. Begin with one task, such as classifying a record or producing an embedding, and make each accepted request interpretable without depending on hidden knowledge about the model implementation.
Name the contract before the payload
Write down the task, the input units, and the output meaning before choosing an encoding. A rectangular array does not identify its own feature order. A shape such as [batch, features] needs a feature definition that explains every column, including its units and missing-value policy.
Keep a small contract record with a schema revision, axis names, accepted numerical types, and limits. Treat preprocessing as part of that record whenever it changes interpretation. The same number can represent a raw measurement, a standardized feature, or a category identifier.
For outputs, identify both the numerical layout and the associated vocabulary or representation. A classifier needs a label map; an embedding needs a model and dimension contract. Consumers should be able to detect a changed meaning before using a structurally compatible response.
Validate requests at the boundary
Use validation to turn ambiguous requests into actionable errors before allocating expensive execution resources. Start with the fields and schema revision, then check dimensions, value counts, and numerical constraints. Apply the same policy to single examples and batches so that the boundary does not change unexpectedly with request size.
- Require an explicit axis order and supported feature revision.
- Confirm that dimensions agree with the supplied values.
- Reject unsupported types and disallowed nonfinite values.
- Set a documented maximum payload and batch size.
- Preserve item identifiers in every response.
An error should identify the failed rule and relevant field. Keep transport failure, invalid input, and unsuccessful model execution as distinct states. This separation gives clients a reasonable basis for deciding whether to correct the request, retry later, or request review.
Evolve the interface deliberately
A model replacement can change outputs while leaving the JSON layout untouched. Track the model revision alongside feature and output-schema revisions, and compare a representative set of requests before introducing that replacement. Include boundary cases whose mistakes would be expensive to discover downstream.
| Change | Contract question |
|---|---|
| New feature order | Can an old client detect the incompatibility? |
| New label definition | Will existing routing rules still mean the same thing? |
| New encoding | Are value order and numerical precision preserved? |
Optimize transport or batching after this agreement is stable. Keep performance measurements tied to useful completed outputs, since a faster response that violates the contract creates work elsewhere. The result should remain understandable to a client developer who has never inspected your execution code.
Use the official reference for the documented interface; the workflow recommendations above are Tensor API Lab guidance.