​
Deployments

You can create prompts with versions and create their deployments that can be used via the SDK.

​
Initializing the SDK

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

const maxim = new Maxim({ apiKey: "", promptManagement: true });

​
For a prompt with specific deployment variables

For building query to get prompt with specific deployment variables, you can use QueryBuilder.

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const prompt = await maxim.getPrompt("prompt-id",
  				new QueryBuilder()
  					.and()
  					.deploymentVar("Environment", "prod")
  					.build());

Adding multiple queries

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const prompt = await maxim.getPrompt(
  "prompt-id",
  new QueryBuilder().and().deploymentVar("Environment", "prod").deploymentVar("CustomerId", "123").build(),
);

Adding filters based on Tags

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true});

const prompt = await maxim.getPrompt(
  "prompt-id",
  new QueryBuilder().and().deploymentVar("Environment", "prod").tag("TenantId", "3000").build(),
);

​
Querying Prompts

Sometimes you have usescases where you need to fetch multiple deployed prompts at once using a single query. For example, you might want to fetch all prompts for a specific customer or specific workflow. You can use getPrompts function for this purpose.

​
Query deployed prompts using tags

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const prompts = await maxim.getPrompts(new QueryBuilder().and().deploymentVar("Environment", "prod").tag("CustomerId", "123").build());

​
Query deployed prompts using folder

To get all prompts from a folder, you can use getPrompts function with folderId as a query parameter.

​
First capture folder id

There are multiple ways to capture folder id. You can use Maxim dashboard to get folder id.

  1. Right click/click on three dots on the folder you want to get id for.
  2. Select Edit Folder option.
  3. You will see folder id in the form.

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

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const folder = await maxim.getFolderById("folder-id");

To get folders using tags attached to the folder.

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const folders = await maxim.getFolders(new QueryBuilder().and().tag("CustomerId", "123").build());

​
Get all deployed prompts from a folder

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const folder = maxim.getFolderById("folder-id")
const prompts = await maxim.getPrompts(
  new QueryBuilder()
  .and()
  .folder(folder.id)
  .deploymentVar("Environment", "prod")
  .build(),
);

You can filter prompts based on deploymentVars or tags attached to the prompt.

import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const folder = await maxim.getFolderById("folder-id");
const prompts = await maxim.getPrompts(
  	new QueryBuilder()
  	.and()
  	.folder(folder.id)
  	.deploymentVar("Environment", "prod")
  	.tag("CustomerId","123")
  	.build());

​
Prompt Structure

export type Prompt = {
  promptId: string;
  version: number;
  versionId: string;
  messages: { role: string; content: string }[];
  modelParameters: { [key: string]: string };
  provider: string;
  model: string;
  tags: { [key: string]: string };
};

​
Folder Structure

export type Folder = {
  id: string;
  name: string;
  parentFolderId?: string;
  tags: { [key: string]: string };
};

​
Using your own cache for prompts

Maxim SDK uses in-memory caching by default. You can use your own caching implementation by passing a custom cache object to the SDK. This allows you to remove complete dependency on our backend.

​
Interface for custom cache

export interface MaximCache {
  getAllKeys(): Promise<string[]>;
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  delete(key: string): Promise<void>;
}

You will have to pass this custom cache object to the SDK while initializing it.

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

const maxim = new Maxim({ apiKey: "api-key", promptManagement: true, cache: new CustomCache() });

​
Example

Here is the default in-memory cache implementation used by the SDK.

export class MaximInMemoryCache implements MaximCache {
  private cache: Map<string, string> = new Map();

  getAllKeys(): Promise<string[]> {
  	return Promise.resolve(Array.from(this.cache.keys()));
  }

  get(key: string): Promise<string | null> {
  	return Promise.resolve(this.cache.get(key) || null);
  }
  set(key: string, value: string): Promise<void> {
  	this.cache.set(key, value);
  	return Promise.resolve();
  }
}

​
Matching algorithm

Before going into the details of how to use the SDK, let’s understand how the matching algorithm works. Maxim SDK uses best matching entity algorithm.

  1. Let’s assume that, you have asked for a prompt with deployment var env as prod, customerId as "123" and a tag, tenantId as 456 for promptId - "abc".
  2. SDK will first try to find a prompt matching all conditions.
  3. If we don’t find any matching entity, we enforce only deploymentVar conditions (you can override this behaviour, as explained in the next section) and match as many tags as possible.
  4. If we still don’t find any prompt, we check for a prompt version marked as fallback.
  5. If we still don’t find any prompt, we return null.

​
Overriding fallback algorithm

  1. You can override fallback algorithm by calling .exactMatch() on QueryBuilder object. That will enforce all conditions to be matched.
import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const prompt = await maxim.getPrompt(
  "prompt-id",
  new QueryBuilder().and().deploymentVar("Environment", "prod").tag("CustomerId", "123").exactMatch().build(),
);
  1. You can override fallback algorithm at each variable level. The third optional parameter in deploymentVar & tag function is enforce. If you pass true to this parameter, it will enforce exact match for that variable.
import { Maxim, QueryBuilder } from "@maximai/maxim-js;

const maxim = new Maxim({ apiKey: "", promptManagement: true });

const prompt = await maxim.getPrompt(
  "prompt-id",
  new QueryBuilder().and().deploymentVar("Environment", "prod").tag("CustomerId", "123", true).build(),
);