Skip to main content

SAP RPT-1 (Beta)

important

This package is experimental and subject to change. Do not use in production.

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

Installation​

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

npm install @sap-ai-sdk/rpt

Usage​

SAP-RPT-1 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 RptClient constructor with optional parameters. By default, the 'sap-rpt-1-small' model is chosen as the prediction model.

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

const client = new RptClient();

To use the 'sap-rpt-1-large' model, specify the model name in the constructor:

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

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.

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: '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 properties. The prediction data contains the following properties:

  • prediction_config: A mandatory configuration to specify the columns to predict, including their names, placeholder values, 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.
  • 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.
  • parse_data_types: Optional boolean to control data type parsing. When set to true (default), numeric columns are parsed to float or integer, and dates (YYYY-MM-DD) are parsed automatically.
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...
    ]
  }
);

Advanced Usage​

The RPT client supports advanced features for specialized use cases.

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 the Parquet file as a Blob along with the prediction configuration. Optional arguments such as index_column and parse_data_types can be specified in the third parameter.

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();

const prediction = await client.predictParquet(
  parquetBlob,
  {
    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:

import * as zlib from 'zlib';

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:

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';

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