@maximai/maxim-js
Version:
Maxim AI JS SDK. Visit https://getmaxim.ai for more info.
353 lines (352 loc) • 11.2 kB
TypeScript
import type OpenAI from "openai";
import { ChatCompletionMessage, CompletionRequest } from "../../models/prompt";
import type { Attachment } from "../../types";
import { ILogWriter } from "../types";
import { EvaluatableBaseContainer } from "./base";
/**
* Represents an error that occurred during LLM generation.
*/
export interface GenerationError {
message: string;
code?: string;
type?: string;
}
/**
* Represents the result of an LLM chat completion.
*/
export interface ChatCompletionResult {
id: string;
object: string;
created: number;
model: string;
choices: Array<ChatCompletionChoice>;
usage: Usage;
cost?: Cost;
error?: GenerationError;
}
/**
* Represents the result of an LLM text completion.
*/
export interface TextCompletionResult {
id: string;
object: string;
created: number;
model: string;
choices: Array<TextCompletionChoice>;
usage: Usage;
cost?: Cost;
error?: GenerationError;
}
export interface Logprobs {
text_offset?: Array<number>;
token_logprobs?: Array<number>;
tokens?: Array<string>;
top_logprobs?: Array<Record<string, number>>;
}
export interface ChatCompletionChoice {
index: number;
message: ChatCompletionMessage;
logprobs: Logprobs | null;
finish_reason: string;
}
export interface TextCompletionChoice {
index: number;
text: string;
logprobs: Logprobs | null;
finish_reason: string;
}
/**
* Token usage statistics for a generation request.
*/
export interface Usage {
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
}
/**
* Cost statistics for a generation request.
*/
export interface Cost {
input: number;
output: number;
total: number;
}
/**
* Configuration object for generation.
*/
export type GenerationConfig = {
id: string;
name?: string;
provider: "openai" | "bedrock" | "anthropic" | "huggingface" | "azure" | "together" | "groq" | "google" | "elevenlabs";
model: string;
maximPromptId?: string;
maximPromptVersionId?: string;
messages: (CompletionRequest | ChatCompletionMessage)[];
modelParameters: Record<string, any>;
tags?: Record<string, string>;
/**
* Optional explicit start timestamp. If not provided, defaults to current time.
*/
startTimestamp?: Date;
/**
* Optional explicit end timestamp. Can be set during creation for completed operations.
*/
endTimestamp?: Date;
};
/**
* Represents an LLM generation or completion.
*
* The Generation class tracks the complete lifecycle of LLM requests,
* including input messages, model parameters, results, and any errors.
* It supports both chat and text completion formats.
*
* @class Generation
* @extends EvaluatableBaseContainer
* @example
* const generation = container.generation({
* id: 'gen-001',
* name: 'User Query Response',
* provider: 'openai',
* model: 'gpt-4',
* messages: [
* { role: 'system', content: 'You are a helpful assistant.' },
* { role: 'user', content: 'What is the capital of France?' }
* ],
* modelParameters: { temperature: 0.7, max_tokens: 150 }
* });
*
* // Record the result
* generation.result({
* id: 'cmpl-123',
* object: 'chat.completion',
* created: Date.now(),
* model: 'gpt-4',
* choices: [{
* index: 0,
* message: { role: 'assistant', content: 'The capital of France is Paris.' },
* finish_reason: 'stop',
* logprobs: null
* }],
* usage: { prompt_tokens: 25, completion_tokens: 8, total_tokens: 33 }
* });
*/
export declare class Generation extends EvaluatableBaseContainer {
private model?;
private provider?;
private maximPromptId?;
private maximPromptVersionId?;
private modelParameters?;
/**
* Creates a new generation log entry.
*
* @param config - Configuration object defining the generation
* @param writer - Log writer instance for persisting generation data
* @example
* const generation = container.generation({
* id: 'response-gen-001',
* name: 'Customer Query Response',
* provider: 'openai',
* model: 'gpt-4',
* messages: [
* { role: 'system', content: 'You are a helpful assistant.' },
* { role: 'user', content: 'How do I reset my password?' }
* ],
* modelParameters: { temperature: 0.7, max_tokens: 200 }
* });
*/
constructor(config: GenerationConfig, writer: ILogWriter);
/**
* Updates the model being used for this generation.
*
* @param model - The new model name or identifier
* @returns void
* @example
* generation.setModel('gpt-4-turbo');
*/
setModel(model: string): void;
/**
* Static method to update the model for any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param model - The new model name
* @returns void
*/
static setModel_(writer: ILogWriter, id: string, model: string): void;
/**
* Updates the name being used for this generation.
*
* @param name - The new name
* @returns void
* @example
* generation.setName('Customer Query Response');
*/
setName(name: string): void;
/**
* Static method to update the name for any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param name - The new name
* @returns void
*/
static setName_(writer: ILogWriter, id: string, name: string): void;
/**
* Adds additional messages to this generation's conversation.
*
* @param messages - Array of messages to add
* @returns void
* @example
* generation.addMessages([
* { role: 'user', content: 'Can you clarify that?' },
* ]);
*/
addMessages(messages: (CompletionRequest | ChatCompletionMessage)[]): void;
/**
* Static method to add messages to any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param messages - Array of messages to add
* @returns void
*/
static addMessages_(writer: ILogWriter, id: string, messages: (CompletionRequest | ChatCompletionMessage)[]): void;
/**
* Updates the model parameters for this generation.
*
* @param modelParameters - Object containing model-specific parameters
* @returns void
* @example
* generation.setModelParameters({
* temperature: 0.9,
* max_tokens: 500,
* top_p: 0.95,
* frequency_penalty: 0.2
* });
*/
setModelParameters(modelParameters: Record<string, any>): void;
/**
* Static method to update model parameters for any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param modelParameters - Model parameters to update
* @returns void
*/
static setModelParameters_(writer: ILogWriter, id: string, modelParameters: Record<string, any>): void;
/**
* Records the successful result of this generation and ends it.
*
* @param result - The completion result from the LLM
* @returns void
* @example
* generation.result({
* id: 'cmpl-123',
* object: 'chat.completion',
* created: Date.now(),
* model: 'gpt-4',
* choices: [{
* index: 0,
* message: { role: 'assistant', content: 'Here is the answer...' },
* finish_reason: 'stop',
* logprobs: null
* }],
* usage: { prompt_tokens: 50, completion_tokens: 25, total_tokens: 75 }
* });
*/
result(result: TextCompletionResult | ChatCompletionResult | OpenAI.Responses.Response): void;
/**
* Static method to record a result for any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param result - The completion result
* @returns void
*/
static result_(writer: ILogWriter, id: string, result: TextCompletionResult | ChatCompletionResult | OpenAI.Responses.Response): void;
/**
* Records an error that occurred during this generation.
*
* @param error - Error information including message, code, and type
* @returns void
* @example
* generation.error({
* message: 'API request timed out',
* code: 'TIMEOUT_ERROR',
* type: 'NetworkError'
* });
*/
error(error: GenerationError): void;
/**
* Static method to record an error for any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param error - Error information
* @returns void
*/
static error_(writer: ILogWriter, id: string, error: GenerationError): void;
/**
* Adds a numeric metric to this generation.
*
* Records quantitative values such as generation quality metrics, token accounting,
* and streaming/throughput characteristics under a named metric. Each call adds
* or updates a single metric entry.
*
* Common examples include: `tokens_in`, `tokens_out`, `output_tokens`, `ttft_ms` (Time To First Token),
* `tps` (tokens per second), `avg_logprob`.
*
* @param name - Name of the metric
* @param value - Numeric value of the metric (numeric)
* @returns void
* @example
* generation.addMetric('tokens_in', 312);
* generation.addMetric('tokens_out', 87);
* generation.addMetric('output_tokens', 87);
* generation.addMetric('ttft_ms', 180.5);
* generation.addMetric('tps', 15.8);
* generation.addMetric('avg_logprob', -0.32);
*/
addMetric(name: string, value: number): void;
/**
* Static method to add a metric to any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param name - Name of the metric
* @param value - Numeric value of the metric (float/number)
* @returns void
*/
static addMetric_(writer: ILogWriter, id: string, name: string, value: number): void;
/**
* Adds an attachment to this generation (can be of type `file`, `data`, or `url`).
*
* @param attachment - The attachment to add (file, data, or URL)
* @returns void
* @example
* generation.addAttachment({
* id: 'input-document',
* type: 'file',
* path: './uploads/user_document.pdf',
* name: 'User Document'
* });
*/
addAttachment(attachment: Attachment): void;
/**
* Static method to add an attachment to any generation by ID.
*
* @param writer - The log writer instance
* @param id - The generation ID
* @param attachment - The attachment to add
* @returns void
*/
static addAttachment_(writer: ILogWriter, id: string, attachment: Attachment): void;
/**
* Returns the complete data representation of this generation.
*
* @returns Generation data.
* @example
* const genData = generation.data();
*/
data(): any;
}