@maximai/maxim-js
Version:
Maxim AI JS SDK. Visit https://getmaxim.ai for more info.
310 lines (309 loc) • 11.3 kB
TypeScript
import { ILogWriter } from "../types";
import { Entity } from "./types";
/**
* Configuration object for base container initialization.
*/
export type BaseConfig = {
id: string;
spanId?: string;
name?: string;
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;
};
/**
* Abstract base class for all logging containers in the Maxim SDK.
*
* Provides common functionality for managing container lifecycle, metadata, tags,
* and communication with the log writer. All specific container types extend this class.
*
* @abstract
* @class BaseContainer
* @example
* // BaseContainer is not instantiated directly, but through subclasses
* const session = new Session({ id: 'session-1', name: 'User Chat' }, writer);
* session.addTag('user_id', '12345');
* session.addMetadata({ context: 'support_chat' });
*/
export declare abstract class BaseContainer {
protected readonly entity: Entity;
protected _id: string;
protected _name?: string;
protected spanId?: string;
protected readonly startTimestamp: Date;
protected endTimestamp?: Date;
protected tags: Record<string, string>;
protected readonly writer: ILogWriter;
/**
* Creates a new base container instance.
*
* @param entity - The entity type this container represents
* @param config - Configuration for the container
* @param writer - Log writer instance for committing changes
* @throws {Error} When the provided ID contains invalid characters (only alphanumeric, hyphens, and underscores allowed; only throws if you have `raiseExceptions` config set to true)
*/
constructor(entity: Entity, config: BaseConfig, writer: ILogWriter);
/**
* Gets the unique identifier for this container.
*
* @returns The container's unique ID
*/
get id(): string;
/**
* Adds a tag to this container for categorization and filtering.
*
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* container.addTag('environment', 'production');
* container.addTag('user_type', 'premium');
*/
addTag(key: string, value: string): void;
/**
* Static method to add a tag to any container by ID.
*
* @param writer - The log writer instance
* @param entity - The entity type
* @param id - The container ID
* @param key - The tag key
* @param value - The tag value
* @returns void
*/
static addTag_(writer: ILogWriter, entity: Entity, id: string, key: string, value: string): void;
/**
* Adds metadata to this container for additional context and debugging. Any data type could be added as the value in the metadata record.
*
* @param metadata - Key-value pairs of metadata
* @returns void
* @example
* container.addMetadata({
* requestId: 'req-123',
* userAgent: 'Mozilla/5.0...',
* processingTime: 1500
* });
*/
addMetadata(metadata: Record<string, unknown>): void;
/**
* Static method to add metadata to any container by ID.
*
* @param writer - The log writer instance
* @param entity - The entity type
* @param id - The container ID
* @param metadata - The metadata to add
* @returns void
*/
static addMetadata_(writer: ILogWriter, entity: Entity, id: string, metadata: Record<string, unknown>): void;
/**
* Marks this container as ended and records the end timestamp.
*
* @param endTimestamp - Optional explicit end timestamp. If not provided, defaults to current time.
* @returns void
* @example
* // End a container when processing is complete
* container.end();
*
* @example
* // End with explicit timestamp
* container.end(new Date('2024-01-15T10:30:00Z'));
*/
end(endTimestamp?: Date): void;
/**
* Static method to end any container by ID.
*
* @param writer - The log writer instance
* @param entity - The entity type
* @param id - The container ID
* @param data - Optional additional data to include with the end event
* @returns void
*/
static end_(writer: ILogWriter, entity: Entity, id: string, data?: any): void;
/**
* Returns the current data state of this container.
*
* @returns The container's data.
*/
data(): any;
/**
* Commits a change to this container via the log writer.
*
* @protected
* @param action - The action being performed
* @param data - Data associated with the action
* @returns void
*/
protected commit(action: string, data?: any): void;
/**
* Static method to commit changes to any container by ID.
*
* @protected
* @param writer - The log writer instance
* @param entity - The entity type
* @param id - The container ID
* @param action - The action being performed
* @param data - Data associated with the action
* @returns void
*/
protected static commit_(writer: ILogWriter, entity: Entity, id: string, action: string, data?: any): void;
}
/**
* Extended base container that supports evaluation functionality.
*
* Provides additional capabilities for containers that can be evaluated,
* such as sessions, traces, generations, and retrievals. Includes methods
* for triggering evaluations.
*
* @abstract
* @class EvaluatableBaseContainer
* @extends BaseContainer
*/
export declare abstract class EvaluatableBaseContainer extends BaseContainer {
/**
* Gets the evaluation methods for this container.
*
* @returns Evaluation methods for configuring and triggering evaluations
* @example
* container.evaluate.withEvaluators('bias', 'toxicity');
*/
get evaluate(): EvaluateContainer;
/**
* Static method to get evaluation methods for any evaluatable container by ID.
*
* @param writer - The log writer instance
* @param entity - The entity type
* @param id - The container ID
* @returns Evaluation methods for configuring and triggering evaluations
*/
static evaluate_(writer: ILogWriter, entity: Entity, id: string): EvaluateContainer;
}
/**
* Extended evaluatable container that supports event emission.
*
* Provides capabilities for containers that can emit events. Used by traces and spans.
*
* @abstract
* @class EventEmittingBaseContainer
* @extends EvaluatableBaseContainer
*/
export declare abstract class EventEmittingBaseContainer extends EvaluatableBaseContainer {
/**
* Emits a custom event within this container.
*
* @param id - Unique identifier for the event
* @param name - Human-readable name for the event
* @param tags - Optional tags for categorizing the event
* @param metadata - Optional metadata for additional context
* @returns void
* @example
* container.event(
* 'checkpoint-1',
* 'Processing Milestone',
* { phase: 'preprocessing', status: 'complete' },
* { itemsProcessed: 1000, timeElapsed: 5.2 }
* );
*/
event(id: string, name: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
/**
* Static method to emit an event for any event-emitting container by ID.
*
* @param writer - The log writer instance
* @param entity - The entity type
* @param id - The container ID
* @param eventId - Unique identifier for the event
* @param name - Human-readable name for the event
* @param tags - Optional tags for categorizing the event
* @param metadata - Optional metadata for additional context
* @returns void
*/
static event_(writer: ILogWriter, entity: Entity, id: string, eventId: string, name: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
}
/**
* Container for configuring and triggering evaluations on containers.
*
* Provides an interface for setting up evaluations with variables.
* Used to assess the quality and performance of different operations
* for your application.
*
* @class EvaluateContainer
* @example
// Attaching evaluators to a container
* container.evaluate
* .withEvaluators('bias', 'toxicity')
* // Optionally, directly chain variables for the evaluators mentioned above
* .withVariables({ context: 'user_query', expected: 'gold_standard' });
*
* @example
* // Attaching variables at a later stage to specific evaluators
* container.evaluate
* .withVariables({ context: 'user_query', expected: 'gold_standard' }, ['bias']);
*/
export declare class EvaluateContainer {
private _writer;
private _entity;
private _id;
/**
* Creates a new evaluation container instance.
*
* @param writer - The log writer instance for committing evaluations
* @param entity - The entity type being evaluated
* @param id - The unique identifier of the entity being evaluated
* @example
* // Usually created through container.evaluate getter
* const evaluator = new EvaluateContainer(writer, Entity.GENERATION, 'gen-123');
*/
constructor(writer: ILogWriter, entity: Entity, id: string);
/**
* Configures variables for specific evaluators in the evaluation.
*
* Variables provide the values needed by the evaluators to
* execute; such as expected outputs, retrieved contexts, or input queries.
*
* @template T - String literal type for variable names
* @param variables - Key-value pairs mapping variables to their values
* @param forEvaluators - Array of evaluator names that should receive these variables
* @example
* // Provide expected output for `accuracy` evaluator
* container.evaluate
* .withVariables(
* { expected_output: 'The correct answer is 42' },
* ['bias']
* )
*
* @example
* // Multiple variables for different evaluators
* container.evaluate
* .withVariables(
* { context: 'Retrieved documents...', user_query: 'What is AI?' },
* ['bias', 'toxicity']
* );
*/
withVariables<T extends string = string>(variables: Record<T, string>, forEvaluators: string[]): void;
/**
* Specifies which evaluators should be attached for evaluation to this container.
*
* @template T - String literal type for evaluator names
* @param evaluators - Names of evaluators to be used for evaluation once all variables are available to them
* @example
* // Use built-in evaluators
* container.evaluate
* .withEvaluators('bias', 'toxicity');
*
* @example
* // Mix of built-in and custom evaluators
* container.evaluate
* .withEvaluators(
* 'bias',
* 'custom_domain_knowledge',
* 'brand_compliance'
* );
*/
withEvaluators<T extends string = string>(...evaluators: string[]): {
withVariables: <U extends string = T>(variables: Record<U, string>) => void;
};
}