SAP RPT

The @sap-ai-sdk/rpt package provides a client to interact with SAP RPT, SAP's Relational Pretrained Transformer model for tabular AI.

Installation

To add the package to your project, run the following command in your terminal:

npm install @sap-ai-sdk/rpt

Usage

SAP RPT is a relational pretrained transformer model that delivers accurate predictive insights from structured business data. The following shows the different ways to use the RPT client to interact with the model.

Client Initialization

Initialize a client using the RptClient constructor with a model name.

import { RptClient } from '@sap-ai-sdk/rpt';

const client = new RptClient('sap-rpt-1.6');

To use the large model:

const client = new RptClient('sap-rpt-1.6-large');

The large model supports context_mode: 'deep' for high-accuracy predictions on large datasets. See Context Mode for details.

Follow the instructions in the Foundation Models documentation to specify a model version, use a model with an explicit deployment ID, select a specific resource group, or target a custom AI Core instance.

tip

When you use SAP RPT models, follow the best practices to improve performance and prediction accuracy.

Predict With Schema

Use the predictWithSchema() method to make predictions with a schema explicitly defined. Pass the data schema, and the prediction data including the prediction configuration and input data to the method. Prefer providing the data schema if it is known instead of relying on the auto-inference solely based on the input data.

For information about custom request options such as compression, custom headers, or timeout, refer to the Advanced Usage section.

const prediction = await client.predictWithSchema(
  // Data schema
  [
    { name: 'PRODUCT', dtype: 'string' },
    { name: 'PRICE', dtype: 'numeric' },
    { name: 'PRODUCTION_DATE', dtype: 'date' },
    { name: 'ID', dtype: 'string' },
    { name: 'SALESGROUP', dtype: 'string' }
  ],
  // Prediction data
  {
    prediction_config: {
      target_columns: [
        {
          name: 'SALESGROUP',
          prediction_placeholder: '[PREDICT]',
          task_type: 'classification'
        }
      ]
    },
    index_column: 'ID',
    rows: [
      {
        PRODUCT: 'Laptop',
        PRICE: 999.99,
        PRODUCTION_DATE: '2025-01-15',
        ID: '35',
        SALESGROUP: '[PREDICT]'
      },
      {
        PRODUCT: 'Desktop Computer',
        PRICE: 750.5,
        PRODUCTION_DATE: '2024-12-02',
        ID: '42',
        SALESGROUP: 'Hardware'
      }
      // Additional rows...
    ]
  }
);

The data schema is a list of column definitions, each containing a name and a dtype property. Supported dtype values, grouped by category:

Category	Types
Text	`string`, `largestring`, `uuid`
Numeric	`numeric`, `integer`, `int16`, `int32`, `int64`, `uint8`, `decimal`, `double`
Boolean	`boolean`
Date and time	`date`, `time`, `datetime`, `timestamp`

The prediction data contains the following properties:

prediction_config: A mandatory configuration to specify the columns to predict, including their names, prediction placeholders, and task types. The task type can be either classification or regression. If not specified, the model infers the task type based on the column data type. Optionally, set context_mode to control how context rows are used — see Context Mode. Optionally, set explanations to receive feature importance scores — see Explainability.
index_column: The name of the column that serves as the unique identifier for each row. The index column is returned in the prediction results to allow mapping predictions back to the input data.
rows or columns: The input data to make predictions on. Use rows for row-based format or columns for column-based format. Exactly one of rows or columns must be provided.
parse_data_types: Optional boolean to control data type parsing. When set to true, numeric columns are parsed to float or integer, and dates (YYYY-MM-DD) are parsed automatically. Defaults to false.

important

When you store the schema and prediction data in variables, declare the schema with as const and use the PredictionData<typeof schema> type. This enables type inference and accurate IDE autocompletion. If you pass the data directly to predictWithSchema(), you do not need additional annotations.

Example:

const schema = [
  // ...
] as const;
const data: PredictionData<typeof schema> = {
  // ...
};

client.predictWithSchema(schema, data);

Predict Without Schema

tip

If the data schema is known, it is recommended to use the predictWithSchema() method instead.

To make predictions without providing a schema, use the predictWithoutSchema() method. Pass only the prediction data as a parameter. The data schema will be inferred from the input data.

For information about custom request options such as compression, custom headers, or timeout, refer to the Advanced Usage section.

const prediction = await client.predictWithoutSchema(
  // Prediction data
  {
    prediction_config: {
      target_columns: [
        {
          name: 'SALESGROUP',
          prediction_placeholder: '[PREDICT]',
          task_type: 'classification'
        }
      ]
    },
    index_column: 'ID',
    rows: [
      {
        PRODUCT: 'Laptop',
        PRICE: 999.99,
        PRODUCTION_DATE: '2025-01-15',
        ID: '35',
        SALESGROUP: '[PREDICT]'
      },
      {
        PRODUCT: 'Desktop Computer',
        PRICE: 750.5,
        PRODUCTION_DATE: '2024-12-02',
        ID: '42',
        SALESGROUP: 'Hardware'
      }
      // Additional rows...
    ]
  }
);

Best Practices

Follow these best practices to improve performance and prediction accuracy when using SAP RPT models:

Provide appropriate level of context: Use the recommended context length from the SAP Help Portal when preparing input data.
Follow service best practices: Refer to the SAP AI Core best practices documentation for general guidance on optimizing SAP RPT usage.
Provide a schema when possible: Use predictWithSchema() for better performance and more accurate predictions. Explicitly defining the schema helps the model understand your data structure more precisely than auto-inference.
Use string types for numerical identifiers and category columns: In the provided schema, set identifier columns, category codes, and postal codes to dtype: 'string', even when the values look numeric. This prevents the model from treating them as a continuous scale and interpolating them with numerical methods.
String predictions are limited to values seen in context: For columns with dtype: 'string', the model treats values as discrete categories and can only predict values present in the context rows.

Advanced Usage

The RPT client supports advanced features for specialized use cases.

Context Mode

The context_mode field on prediction_config controls how the model uses the provided context rows. This feature is currently only available on sap-rpt-1.6-large.

Value	Description
`'default'`	Standard prediction mode (default).
`'deep'`	Higher accuracy for datasets with more than 8,000 context rows. Higher cost. Only supported on `sap-rpt-1.6-large`.

const client = new RptClient('sap-rpt-1.6-large');
const prediction = await client.predictWithSchema(
  [
    { name: 'PRODUCT', dtype: 'string' },
    { name: 'PRICE', dtype: 'numeric' },
    { name: 'PRODUCTION_DATE', dtype: 'date' },
    { name: 'ID', dtype: 'string' },
    { name: 'SALESGROUP', dtype: 'string' }
  ],
  {
    prediction_config: {
      target_columns: [
        {
          name: 'SALESGROUP',
          prediction_placeholder: '[PREDICT]',
          task_type: 'classification'
        }
      ],
      context_mode: 'deep'
    },
    index_column: 'ID',
    rows: [
      // More than 8,000 context rows...
    ]
  }
);

Explainability

This feature is available with RPT 1.5 or higher. To understand which columns and context rows influenced a prediction, set explanations on prediction_config. The response includes an explanations field with per-query-row scores and indices.

top_column_scores: Number of top-contributing columns to return per query row (maximum 20). The response contains an array of objects mapping column names to importance scores, one entry per query row.
top_relevant_context_rows: Number of most relevant context row indices to return per query row (maximum 20). The response contains a 2D array of context row indices, one subarray per query row.

const response = await client.predictWithSchema(
  [
    { name: 'PRODUCT', dtype: 'string' },
    { name: 'PRICE', dtype: 'numeric' },
    { name: 'PRODUCTION_DATE', dtype: 'date' },
    { name: 'ID', dtype: 'string' },
    { name: 'SALESGROUP', dtype: 'string' }
  ],
  {
    prediction_config: {
      target_columns: [
        {
          name: 'SALESGROUP',
          prediction_placeholder: '[PREDICT]',
          task_type: 'classification'
        }
      ],
      explanations: {
        top_column_scores: 3,
        top_relevant_context_rows: 3
      }
    },
    index_column: 'ID',
    rows: [
      {
        PRODUCT: 'Laptop',
        PRICE: 999.99,
        PRODUCTION_DATE: '2025-01-15',
        ID: '35',
        SALESGROUP: '[PREDICT]'
      }
    ]
  }
);

const columnScores = response.explanations?.top_column_scores;
// [{ PRODUCT: 0.8, PRICE: 0.15, PRODUCTION_DATE: 0.05 }, ...]

const relevantRows = response.explanations?.top_relevant_context_rows;
// [[0, 5, 12], ...]

Predict with Parquet

Parquet is a tabular file format optimized for data-science workloads. To make predictions on Parquet files, use the predictParquet() method. Pass a ParquetPayload object containing the Parquet file, prediction configuration, and optional arguments such as index_column and parse_data_types.

note

parse_data_types controls whether the server parses numeric columns to float or integer and date strings automatically. It defaults to false — set it to true if you rely on automatic type parsing.

import { RptClient } from '@sap-ai-sdk/rpt';
import { openAsBlob } from 'node:fs';

const parquetBlob = await openAsBlob('path/to/input-data.parquet', {
  type: 'application/vnd.apache.parquet'
});
const client = new RptClient('sap-rpt-1.6');

const prediction = await client.predictParquet({
  file: parquetBlob,
  prediction_config: {
    target_columns: [
      {
        name: 'SALESGROUP',
        prediction_placeholder: '[PREDICT]',
        task_type: 'classification'
      }
    ]
  },
  index_column: 'ID',
  parse_data_types: false
});

Request Compression

The RPT client automatically compresses prediction requests to improve performance for large datasets. By default, requests with a body of 1024 bytes or larger are automatically compressed using the gzip algorithm.

To customize compression settings, pass a customRequest parameter with a compress configuration to the predictWithSchema() or predictWithoutSchema() methods:

const prediction = await client.predictWithSchema(schema, predictionData, {
  compress: {
    mode: 'always', // Force compression regardless of payload size (default 'auto')
    autoCompressMinSize: 2048, // Only compress payloads >= 2048 bytes in 'auto' mode (default 1024)
    compressOptions: {
      level: zlib.constants.Z_BEST_SPEED // Custom compression level
    }
  }
});

Custom Request Options

The customRequest parameter also supports additional HTTP request configuration options from the SAP Cloud SDK for JavaScript, such as:

headers: Custom HTTP headers.
timeout: Request timeout in milliseconds.
middleware: Custom HTTP middleware functions.

warning

The compression middleware is automatically prepended to the middleware chain, unless disabled by setting mode: 'never'.

The following example demonstrates how to include custom HTTP headers in your request configuration:

const prediction = await client.predictWithSchema(schema, predictionData, {
  headers: {
    'x-custom-header': 'value'
  },
  timeout: 30000, // 30 seconds
  compress: {
    mode: 'always'
  }
});

Resilience

Use the resilience() function from @sap-cloud-sdk/resilience to add resilience to requests. By default, it enables a circuit breaker and a 10-second timeout.

import { resilience } from '@sap-cloud-sdk/resilience';

const prediction = await client.predictWithSchema(schema, predictionData, {
  middleware: resilience()
});

tip

resilience() returns an array of middleware. You can pass it directly to middleware or combine it with other middleware: [...resilience(), myMiddleware].

Customize the behavior by passing options:

import { resilience } from '@sap-cloud-sdk/resilience';

const prediction = await client.predictWithSchema(schema, predictionData, {
  middleware: resilience({
    timeout: 5000, // 5 seconds; true for default 10s, false to disable
    circuitBreaker: true, // true by default, false to disable
    retry: 3 // false by default; true for 3 retries, or pass a number
  })
});

For advanced resilience patterns, refer to the SAP Cloud SDK documentation on resilience.

Custom Middleware Order

When you need precise control over middleware ordering — for example, placing the compression middleware at a specific position relative to resilience — disable automatic compression and manage the full middleware chain yourself:

import { compress } from '@sap-cloud-sdk/http-client';
import { resilience } from '@sap-cloud-sdk/resilience';
import type { HttpMiddleware } from '@sap-cloud-sdk/http-client';

const prediction = await client.predictWithSchema(schema, predictionData, {
  middleware: [
    ...(resilience() as HttpMiddleware[]),
    compress({ mode: 'always' }) // Explicit position in the middleware chain
  ],
  compress: {
    mode: 'never' // Disable automatic compression prepending
  }
});

Installation​

Usage​

Client Initialization​

Predict With Schema​

Predict Without Schema​

Best Practices​

Advanced Usage​

Context Mode​

Explainability​

Predict with Parquet​

Request Compression​

Custom Request Options​

Resilience​

Custom Middleware Order​