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