Class: Maxim

Defined in: src/lib/maxim.ts:147

Main class for the Maxim SDK that provides access to all platform features.

The Maxim class is the primary entry point for interacting with the Maxim observability platform. It provides methods for prompt management, logging, dataset operations, and test run execution. The class handles authentication, caching, and API communication.

Maxim

Examples

import { Maxim } from '@maximai/maxim-js';

// Basic initialization
const maxim = new Maxim({
  apiKey: 'your-api-key'
});
// Full configuration
const maxim = new Maxim({
  apiKey: 'your-api-key',
  baseUrl: 'https://app.getmaxim.ai',
  promptManagement: true,
  debug: true,
  cache: new CustomCacheImplementation()
});
// Using prompt management
const maxim = new Maxim({
  apiKey: 'your-api-key',
  promptManagement: true
});

// Get a prompt with deployment rules
const rule = new QueryBuilder()
  .deploymentVar('environment', 'production')
  .tag('version', 'v2.0')
  .build();

const prompt = await maxim.getPrompt('prompt-id', rule);
if (prompt) {
  const response = await prompt.run('Hello world');
  console.log(response.choices[0].message.content);
}
// Creating and running test runs
const testResult = await maxim
  .createTestRun('sample-test-run', 'workspace-id')
  .withDataStructure({
    input: 'INPUT',
    expectedOutput: 'EXPECTED_OUTPUT'
  })
  .withData('dataset-id')
  .withEvaluators('bias', 'toxicity')
  .yieldsOutput(async (data) => {
    const response = await callYourModel(data.input);
    return { data: response };
  })
  .run();
// Logging with Maxim
const logger = await maxim.logger({ id: 'my-app' });
const trace = session.trace({ id: 'trace-1', name: 'Query Processing', sessionId: 'session-1' });

// ... Log other operations

trace.end();

// finally, before app shutdown
await maxim.cleanup();

Constructors

Constructor

new Maxim(config): Maxim

Defined in: src/lib/maxim.ts:199

Creates a new Maxim SDK instance.

Parameters

config

Config

Configuration object for the SDK

Returns

Maxim

Throws

When the API key is not provided

Important

CRITICAL: Always call cleanup() before your application exits. Failure to do so may result in memory leaks, unflushed data, or hanging processes. This is especially important in production environments and long-running applications.

Examples

const maxim = new Maxim({
  apiKey: process.env.MAXIM_API_KEY,
  promptManagement: true,
  debug: process.env.NODE_ENV === 'development'
});
// With custom cache
import { RedisCacheImplementation } from './custom-cache';

const maxim = new Maxim({
  apiKey: 'your-api-key',
  cache: new RedisCacheImplementation({
    host: 'localhost',
    port: 6379
  })
});

// Always remember to cleanup before exit
process.on('SIGINT', async () => {
  await maxim.cleanup();
  process.exit(0);
});

Methods

addDatasetEntries()

addDatasetEntries(datasetId, entries): Promise<void>

Defined in: src/lib/maxim.ts:1123

This method is used to add entries to a dataset

Parameters

datasetId

string

Dataset id to add entries to

entries

DatasetEntry[]

Entries to add to the dataset

Returns

Promise<void>

void

Async

Example

await maxim.addDatasetEntries("datasetId", [
	{
		input: {
			type: VariableType.TEXT,
			payload: "cell value",
		},
	},
]);

cleanup()

cleanup(): Promise<void>

Defined in: src/lib/maxim.ts:1260

Cleans up all SDK resources and prepares for application shutdown.

This method performs essential cleanup operations including stopping sync intervals, flushing logger data, clearing caches, and destroying HTTP agents. It ensures proper resource deallocation and prevents memory leaks.

Returns

Promise<void>

Async

Important

CRITICAL: Always call this method before your application exits. Failure to do so may result in memory leaks, unflushed data, or hanging processes. This is especially important in production environments and long-running applications.

Examples

// Basic cleanup on application shutdown
process.on('SIGINT', async () => {
  console.log('Shutting down gracefully...');
  await maxim.cleanup();
  process.exit(0);
});
// Cleanup in Express.js application
process.on('SIGTERM', async () => {
  console.log('SIGTERM received, shutting down...');
  await maxim.cleanup();
  server.close(() => {
    process.exit(0);
  });
});
// Cleanup in test suites
afterAll(async () => {
  await maxim.cleanup();
});

createTestRun()

createTestRun(name, inWorkspaceId): TestRunBuilder<undefined>

Defined in: src/lib/maxim.ts:1220

This method is used to create a test run

Parameters

name

string

Name of the test run

inWorkspaceId

string

Workspace Id to create the test run in

Returns

TestRunBuilder<undefined>

Test run instance

Example

// You can keep chaining methods to
// the created test run to configure it
const testRun = maxim
    .createTestRun(
        "testRunName",
        "workspaceId"
    ); // .with___(...)

getFolderById()

getFolderById(folderId): Promise<undefined | Folder>

Defined in: src/lib/maxim.ts:1041

This method is used to get a folder by id

Parameters

folderId

string

Folder id to fetch

Returns

Promise<undefined | Folder>

a single folder

Async

Throws

If no folder found with id

Example

const folder = await maxim.getFolderById("folderId");

getFolders()

getFolders(rule): Promise<undefined | Folder[]>

Defined in: src/lib/maxim.ts:1081

This method is used to get all folders that match the query rule

Parameters

rule

QueryRule

Query rule to match

Returns

Promise<undefined | Folder[]>

Array of folders

Async

Throws

If no folders found matching the query rule

Example

const folders = await maxim.getFolders(
 new QueryBuilder()
     .and()
     .deploymentVar("Environment", "Production")
     .build()
);

getPrompt()

getPrompt(promptId, rule): Promise<undefined | Prompt>

Defined in: src/lib/maxim.ts:768

Retrieves a specific prompt by ID that matches the given query rule.

This method fetches a prompt from the Maxim platform based on deployment rules and query criteria. It supports versioning and rule-based prompt selection.

Parameters

promptId

string

The unique identifier of the prompt to fetch

rule

QueryRule

Query rule defining deployment variables, tags, and matching criteria

Returns

Promise<undefined | Prompt>

The matching prompt with run capabilities, or undefined if not found

Async

Throws

When prompt management is not enabled

Throws

When no active deployments found for the prompt matching the query rule

Examples

import { QueryBuilder } from '@maximai/maxim-js';

const rule = new QueryBuilder()
  .deploymentVar('environment', 'production')
  .tag('version', 'v2.0')
  .build();

const prompt = await maxim.getPrompt('user-greeting-prompt-id', rule);
if (prompt) {
  const response = await prompt.run('Hello!', {
    variables: { userName: 'John' },
    imageUrls: []
  });
  console.log(response.choices[0].message.content);
}
// Using folder-scoped queries
const rule = new QueryBuilder()
  .folder('customer-service-folder')
  .deploymentVar('language', 'en')
  .build();

const prompt = await maxim.getPrompt('support-template', rule);

getPromptChain()

getPromptChain(promptChainId, rule): Promise<undefined | PromptChain>

Defined in: src/lib/maxim.ts:919

Retrieves a specific prompt chain by ID that matches the given query rule.

This method fetches a prompt chain from the Maxim platform based on deployment rules and query criteria. It supports versioning and rule-based prompt chain selection. Prompt chains allow you to orchestrate multiple prompts in sequence with conditional logic.

Parameters

promptChainId

string

The unique identifier of the prompt chain to fetch

rule

QueryRule

Query rule defining deployment variables, tags, and matching criteria

Returns

Promise<undefined | PromptChain>

The matching prompt chain with run capabilities, or undefined if not found

Async

Throws

When prompt management is not enabled

Throws

When no active deployments found for the prompt chain matching the query rule

Examples

import { QueryBuilder } from '@maximai/maxim-js';

const rule = new QueryBuilder()
  .deploymentVar('environment', 'production')
  .tag('version', 'v2.0')
  .build();

const promptChain = await maxim.getPromptChain('user-onboarding-chain-id', rule);
if (promptChain) {
  const response = await promptChain.run('New user registration', {
    variables: { userName: 'John', userType: 'premium' }
  });
  console.log(response.finalOutput);
}
// Using folder-scoped queries
const rule = new QueryBuilder()
  .folder('customer-onboarding-folder')
  .deploymentVar('language', 'en')
  .build();

const promptChain = await maxim.getPromptChain('welcome-sequence', rule);

getPromptChains()

getPromptChains(rule): Promise<undefined | PromptChain[]>

Defined in: src/lib/maxim.ts:990

Retrieves all prompt chains that match the given query rule.

This method fetches multiple prompt chains from the Maxim platform based on deployment rules and query criteria. Useful for getting all prompt chains within a specific folder or matching certain deployment variables.

Parameters

rule

QueryRule

Query rule defining deployment variables, tags, and matching criteria

Returns

Promise<undefined | PromptChain[]>

Array of matching prompt chains with run capabilities, or undefined if none found

Async

Throws

When prompt management is not enabled

Throws

When no active deployments found for any prompt chain matching the query rule

Examples

import { QueryBuilder } from '@maximai/maxim-js';

// Get all production prompt chains in a specific folder
const rule = new QueryBuilder()
  .folder('customer-support')
  .deploymentVar('environment', 'production')
  .build();

const promptChains = await maxim.getPromptChains(rule);
if (promptChains) {
  for (const promptChain of promptChains) {
    console.log(`Prompt Chain: ${promptChain.promptChainId}, Version: ${promptChain.version}`);
  }
}
// Get all prompt chains with specific tags
const rule = new QueryBuilder()
  .tag('category', 'workflow')
  .tag('complexity', 'advanced')
  .and()
  .build();

const workflowChains = await maxim.getPromptChains(rule);

getPrompts()

getPrompts(rule): Promise<undefined | Prompt[]>

Defined in: src/lib/maxim.ts:839

Retrieves all prompts that match the given query rule.

This method fetches multiple prompts from the Maxim platform based on deployment rules and query criteria. Useful for getting all prompts within a specific folder or matching certain deployment variables.

Parameters

rule

QueryRule

Query rule defining deployment variables, tags, and matching criteria

Returns

Promise<undefined | Prompt[]>

Array of matching prompts with run capabilities, or undefined if none found

Async

Throws

When prompt management is not enabled

Throws

When no active deployments found for any prompt matching the query rule

Examples

import { QueryBuilder } from '@maximai/maxim-js';

// Get all production prompts in a specific folder
const rule = new QueryBuilder()
  .folder('customer-support')
  .deploymentVar('environment', 'production')
  .build();

const prompts = await maxim.getPrompts(rule);
if (prompts) {
  for (const prompt of prompts) {
    console.log(`Prompt: ${prompt.promptId}, Version: ${prompt.version}`);
  }
}
// Get all prompts with specific tags
const rule = new QueryBuilder()
  .tag('category', 'greeting')
  .tag('language', 'english')
  .and()
  .build();

const greetingPrompts = await maxim.getPrompts(rule);

logger()

logger(config): Promise<undefined | MaximLogger>

Defined in: src/lib/maxim.ts:1173

Creates a logger instance for capturing observability data.

The logger provides methods for tracking sessions, traces, generations, and other observability events. It handles buffering, batching, and sending data to the Maxim platform.

Parameters

config

LoggerConfig

Configuration for the logger instance

Returns

Promise<undefined | MaximLogger>

Logger instance for capturing observability data, or undefined if creation fails

Async

Throws

When the specified log repository is not found

Example

// Basic logger creation
const logger = await maxim.logger({
  id: 'my-repository-id',
});

if (logger) {
  // Create a session for user interactions
  const session = logger.session({
    id: 'user-session-123',
    name: 'Customer Support Chat'
  });

  // Create a trace for a specific operation
  const trace = session.trace({
    id: 'query-trace-456',
    name: 'Customer Query Processing'
  });

  // ... Log other operations

  trace.end();

  // finally, before app shutdown
  await maxim.cleanup();
}