@maximai/maxim-js
Version:
Maxim AI JS SDK. Visit https://getmaxim.ai for more info.
900 lines (899 loc) • 33.9 kB
TypeScript
import { MaximCache } from "../cache/cache";
import { ChatCompletionMessage, CompletionRequest } from "../models/prompt";
import { ErrorConfig, Error as MaximError } from "./components";
import { ChatCompletionResult, Generation, GenerationConfig, GenerationError, TextCompletionResult } from "./components/generation";
import { Retrieval, RetrievalConfig } from "./components/retrieval";
import { Session, SessionConfig } from "./components/session";
import { Span, SpanConfig } from "./components/span";
import { ToolCall, ToolCallConfig, ToolCallError } from "./components/toolCall";
import { Trace, TraceConfig } from "./components/trace";
import { Attachment } from "../types";
/**
* Configuration object for initializing a MaximLogger instance.
*/
export type LoggerConfig = {
id: string;
autoFlush?: boolean;
flushIntervalSeconds?: number;
};
/**
* Main logger class for the Maxim SDK providing comprehensive observability capabilities.
*
* Manages the entire lifecycle of capturing, storing, and sending logs to the Maxim
* backend. Supports distributed logging and provides methods for logging sessions,
* traces, generations, tool calls, retrievals, and other observability events.
* Essential for monitoring AI applications and understanding system behavior.
*
* @class MaximLogger
* @example
* import { Maxim } from '@maximai/maxim-js';
*
* // Create logger through Maxim instance
* const maxim = new Maxim({ apiKey: 'your-api-key' });
* const logger = await maxim.logger({ id: 'my-app' });
*/
export declare class MaximLogger {
private _id;
private readonly writer;
private readonly isDebug;
/**
* Creates a new MaximLogger instance.
*
* @param params - Configuration parameters for the logger
* @param params.config - Logger configuration including ID and flush settings
* @param params.apiKey - API key for authenticating with Maxim backend
* @param params.baseUrl - Base URL for the Maxim API
* @param params.isDebug - Enable debug mode for additional logging
* @param params.cache - Cache implementation for distributed logging
* @param params.raiseExceptions - Whether to raise exceptions or log them
* @throws {Error} When logger ID is not provided in the configuration
* @example
* // Usually created through Maxim.logger() method
* const logger = new MaximLogger({
* config: { id: 'my-app', autoFlush: true },
* apiKey: 'your-api-key',
* baseUrl: 'https://app.getmaxim.ai',
* cache: new MaximInMemoryCache(),
* raiseExceptions: false
* });
*/
constructor(params: {
config: LoggerConfig;
apiKey: string;
baseUrl: string;
isDebug?: boolean;
cache: MaximCache;
raiseExceptions: boolean;
});
/**
* Creates a new session.
*
* Sessions represent high-level mutli-turn user interactions,
* containing multiple traces that represent individual turn interaction within
* that session. Useful for tracking user journeys.
*
* @param config - Configuration for the session
* @returns A new session instance for logging activities
* @example
* const session = logger.session({
* id: 'user-session-123',
* name: 'Customer Support Chat',
* });
*
* // Add feedback to the session
* session.feedback({ score: 5, comment: 'Very helpful!' });
* session.end();
*/
session(config: SessionConfig): Session;
/**
* Creates a new trace.
*
* Traces represent individual workflows or processes, containing
* generations, tool calls, retrievals, and other components. They
* provide detailed information about operations in a single conversation turn
* with the user.
*
* @param config - Configuration for the trace
* @returns A new trace instance for logging operations
* @example
* const trace = logger.trace({
* id: 'query-trace-456',
* name: 'Document Analysis',
* });
*
* // Add input and output to the trace
* trace.input('Analyze this contract document');
* // ...Log other operations
* trace.output('Contract analysis complete: 3 issues found');
* trace.end();
*/
trace(config: TraceConfig): Trace;
/**
* Gets the unique identifier for this logger instance.
*
* @returns The logger's unique ID
*/
get id(): string;
/**
* Cleans up resources and ensures all pending logs are flushed.
*
* Should be called before application shutdown to ensure no logs are lost.
* Waits for all pending write operations to complete.
*
* @async
* @returns Promise that resolves when cleanup is complete
* @example
* // Cleanup before app shutdown
* process.on('SIGTERM', async () => {
* await logger.cleanup();
* process.exit(0);
* });
*/
cleanup(): Promise<void>;
/**
* Adds a tag to a session for categorization and filtering.
*
* @param sessionId - The unique identifier of the session
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* logger.sessionTag('session-123', 'environment', 'production');
* logger.sessionTag('session-123', 'user_type', 'premium');
*/
sessionTag(sessionId: string, key: string, value: string): void;
/**
* Ends a session and records the end timestamp.
*
* @param sessionId - The unique identifier of the session
* @returns void
* @example
* logger.sessionEnd('session-123');
*/
sessionEnd(sessionId: string, data?: any): void;
/**
* Adds feedback to a session from users.
*
* @param sessionId - The unique identifier of the session
* @param feedback - Feedback object containing score and optional comment
* @param feedback.score - Numerical score for the session
* @param feedback.comment - Optional textual feedback
* @returns void
* @example
* logger.sessionFeedback('session-123', {
* score: 5,
* comment: 'Excellent customer service!'
* });
*/
sessionFeedback(sessionId: string, feedback: {
score: number;
comment?: string;
}): void;
/**
* Adds a numeric metric to a session.
*
* Records quantitative values such as counts and aggregates across all traces in the
* session under a named metric.
*
* Common examples include: `tool_calls_count`, `traces_count`, `user_messages_count`, `assistant_messages_count`.
*
* @param sessionId - The unique identifier of the session
* @param name - Name of the metric
* @param value - Numeric value of the metric (numeric)
* @returns void
* @example
* logger.sessionAddMetric('session-123', 'traces_count', 4);
*/
sessionAddMetric(sessionId: string, name: string, value: number): void;
/**
* Creates a new trace associated with a session.
*
* @param sessionId - The unique identifier of the session
* @param config - Configuration for the new trace
* @returns A new trace instance associated with the session
* @example
* const trace = logger.sessionTrace('session-123', {
* id: 'query-trace-001',
* name: 'User Query Processing'
* });
*/
sessionTrace(sessionId: string, config: TraceConfig): Trace;
/**
* Gets the evaluation methods for a session.
*
* @param sessionId - The unique identifier of the session
* @returns Evaluation methods for configuring and triggering evaluations on the session
* @example
* logger.sessionEvaluate('session-123')
* .withEvaluators('bias', 'toxicity')
* .withVariables({ context: 'session_context' });
*/
sessionEvaluate(sessionId: string): import("./components").EvaluateContainer;
/**
* Creates a new generation (LLM call) associated with a trace.
*
* @param traceId - The unique identifier of the trace
* @param config - Configuration for the generation
* @returns A new generation instance associated with the trace
* @example
* const generation = logger.traceGeneration('trace-123', {
* id: 'gen-001',
* provider: 'openai',
* model: 'gpt-4',
* messages: [{ role: 'user', content: 'Hello!' }],
* modelParameters: { temperature: 0.7 }
* });
*/
traceGeneration(traceId: string, config: GenerationConfig): Generation;
/**
* Creates a new tool call associated with a trace.
*
* @param traceId - The unique identifier of the trace
* @param config - Configuration for the tool call
* @returns A new tool call instance associated with the trace
* @example
* const toolCall = logger.traceToolCall('trace-123', {
* id: 'tool-001',
* name: 'search_database',
* description: 'Search the product database',
* args: JSON.stringify({ query: 'laptop' })
* });
*/
traceToolCall(traceId: string, config: ToolCallConfig): ToolCall;
/**
* Creates a new retrieval associated with a trace.
*
* @param traceId - The unique identifier of the trace
* @param config - Configuration for the retrieval
* @returns A new retrieval instance associated with the trace
* @example
* const retrieval = logger.traceRetrieval('trace-123', {
* id: 'retrieval-001',
* name: 'Knowledge Base Search'
* });
*/
traceRetrieval(traceId: string, config: RetrievalConfig): Retrieval;
/**
* Sets the output for a trace.
*
* @param traceId - The unique identifier of the trace
* @param output - The final output or result of the trace execution
* @returns void
* @example
* logger.traceOutput('trace-123', 'The analysis is complete: 95% confidence');
*/
traceOutput(traceId: string, output: string): void;
/**
* Creates an error associated with a trace.
*
* @param traceId - The unique identifier of the trace
* @param config - Configuration for the error
* @returns A new error instance associated with the trace
* @example
* const error = logger.traceError('trace-123', {
* id: 'error-001',
* message: 'Failed to process request',
* code: 'PROCESSING_ERROR',
* type: 'ProcessingError'
* });
*/
traceError(traceId: string, config: ErrorConfig): MaximError;
/**
* Sets the input for a trace.
*
* @param traceId - The unique identifier of the trace
* @param input - The input that triggered this trace
* @returns void
* @example
* logger.traceInput('trace-123', 'Analyze customer sentiment from reviews');
*/
traceInput(traceId: string, input: string): void;
/**
* Creates a new span associated with a trace.
*
* @param traceId - The unique identifier of the trace
* @param config - Configuration for the span
* @returns A new span instance associated with the trace
* @example
* const span = logger.traceSpan('trace-123', {
* id: 'span-001',
* name: 'Data Processing Phase'
* });
*/
traceSpan(traceId: string, config: SpanConfig): Span;
/**
* Associates a trace with a session.
*
* @param traceId - The unique identifier of the trace
* @param sessionId - The unique identifier of the session
* @returns void
* @example
* logger.traceAddToSession('trace-123', 'session-456');
*/
traceAddToSession(traceId: string, sessionId: string): void;
/**
* Adds a numeric metric to a trace.
*
* Records quantitative values such as tool call counts, retry attempts, total tokens,
* overall cost, or aggregated evaluation scores under a named metric.
*
* Common examples include: `tool_calls_count`, `retries_count`, `cost_usd`, `tokens_total`,
* `eval_overall_score`, `user_feedback_score`.
*
* @param traceId - The unique identifier of the trace
* @param name - Name of the metric
* @param value - Numeric value of the metric (numeric)
* @returns void
* @example
* logger.traceAddMetric('trace-123', 'tool_calls_count', 5);
* logger.traceAddMetric('trace-123', 'tokens_total', 1500);
*/
traceAddMetric(traceId: string, name: string, value: number): void;
/**
* Adds an attachment to this trace.
*
* @param traceId - The unique identifier of the trace
* @param attachment - The attachment to add (can be of type file, data, or URL)
* @returns void
* @example
* logger.traceAddAttachment('trace-123',{
* id: 'input-document',
* type: 'file',
* path: './uploads/document.pdf',
* tags: { category: 'input' }
* });
*/
traceAddAttachment(traceId: string, attachment: Attachment): void;
/**
* Adds a tag to a trace for categorization and filtering.
*
* @param traceId - The unique identifier of the trace
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* logger.traceTag('trace-123', 'operation', 'analysis');
* logger.traceTag('trace-123', 'priority', 'high');
*/
traceTag(traceId: string, key: string, value: string): void;
/**
* Emits a custom event within a trace.
*
* @param traceId - The unique identifier of the trace
* @param eventId - Unique identifier for the event
* @param eventName - Human-readable name for the event
* @param tags - Optional tags for categorizing the event
* @param metadata - Optional metadata for additional context
* @returns void
* @example
* logger.traceEvent(
* 'trace-123',
* 'checkpoint-1',
* 'Processing Milestone',
* { phase: 'preprocessing', status: 'complete' },
* { itemsProcessed: 1000, timeElapsed: 5.2 }
* );
*/
traceEvent(traceId: string, eventId: string, eventName: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
/** @deprecated Use the method with explicit eventId and eventName instead */
traceEvent(traceId: string, eventName: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
/**
* Adds feedback to a trace from users.
*
* @param traceId - The unique identifier of the trace
* @param feedback - Feedback object containing score and optional comment
* @param feedback.score - Numerical score for the trace
* @param feedback.comment - Optional textual feedback
* @returns void
* @example
* logger.traceFeedback('trace-123', {
* score: 4,
* comment: 'Good results but could be faster'
* });
*/
traceFeedback(traceId: string, feedback: {
score: number;
comment?: string;
}): void;
/**
* Adds metadata to a trace for additional context and debugging.
*
* @param traceId - The unique identifier of the trace
* @param metadata - Key-value pairs of metadata
* @returns void
* @example
* logger.traceMetadata('trace-123', {
* requestId: 'req-456',
* userAgent: 'Mozilla/5.0...',
* processingTime: 1500
* });
*/
traceMetadata(traceId: string, metadata: Record<string, unknown>): void;
/**
* Gets the evaluation methods for a trace.
*
* @param traceId - The unique identifier of the trace
* @returns Evaluation methods for configuring and triggering evaluations on the trace
* @example
* logger.traceEvaluate('trace-123')
* .withEvaluators('bias', 'toxicity')
* .withVariables({ context: 'user_query', expected: 'gold_standard' });
*/
traceEvaluate(traceId: string): import("./components").EvaluateContainer;
/**
* Ends a trace and records the end timestamp.
*
* @param traceId - The unique identifier of the trace
* @returns void
* @example
* logger.traceEnd('trace-123');
*/
traceEnd(traceId: string, data?: any): void;
/**
* Updates the model being used for a generation.
*
* @param generationId - The unique identifier of the generation
* @param model - The new model name or identifier
* @returns void
* @example
* logger.generationSetModel('gen-123', 'gpt-4-turbo');
*/
generationSetModel(generationId: string, model: string): void;
generationSetName(generationId: string, name: string): void;
/**
* Adds a tag to a generation for categorization and filtering.
*
* @param generationId - The unique identifier of the generation
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* logger.generationAddTag('gen-123', 'type', 'chat_completion');
* logger.generationAddTag('gen-123', 'use_case', 'customer_support');
*/
generationAddTag(generationId: string, key: string, value: string): void;
/**
* Adds additional messages to a generation's conversation.
*
* @param generationId - The unique identifier of the generation
* @param messages - Array of messages to add
* @returns void
* @example
* logger.generationAddMessage('gen-123', [
* { role: 'user', content: 'Can you clarify that?' }
* ]);
*/
generationAddMessage(generationId: string, messages: (CompletionRequest | ChatCompletionMessage)[]): void;
/**
* Updates the model parameters for a generation.
*
* @param generationId - The unique identifier of the generation
* @param modelParameters - Object containing model-specific parameters
* @returns void
* @example
* logger.generationSetModelParameters('gen-123', {
* temperature: 0.9,
* max_tokens: 500,
* top_p: 0.95
* });
*/
generationSetModelParameters(generationId: string, modelParameters: Record<string, any>): void;
/**
* Adds a numeric metric to a generation.
*
* Records quantitative values such as generation quality metrics, token accounting,
* and streaming/throughput characteristics under a named metric.
*
* Common examples include: `tokens_in`, `tokens_out`, `output_tokens`, `ttft_ms` (Time To First Token),
* `tps` (tokens per second), `avg_logprob`.
*
* @param generationId - The unique identifier of the generation
* @param name - Name of the metric
* @param value - Numeric value of the metric (numeric)
* @returns void
* @example
* logger.generationAddMetric('gen-123', 'output_tokens', 87);
* logger.generationAddMetric('gen-123', 'ttft_ms', 180.5);
* logger.generationAddMetric('gen-123', 'tps', 15.8);
* logger.generationAddMetric('gen-123', 'avg_logprob', -0.32);
*/
generationAddMetric(generationId: string, name: string, value: number): void;
/**
* Records the successful result of a generation and ends it.
*
* @param generationId - The unique identifier of the generation
* @param result - The completion result from the LLM
* @returns void
* @example
* logger.generationResult('gen-123', {
* id: 'cmpl-456',
* object: 'chat.completion',
* created: Date.now(),
* model: 'gpt-4',
* choices: [{
* index: 0,
* message: { role: 'assistant', content: 'Hello! How can I help?' },
* finish_reason: 'stop',
* logprobs: null
* }],
* usage: { prompt_tokens: 10, completion_tokens: 8, total_tokens: 18 }
* });
*/
generationResult(generationId: string, result: TextCompletionResult | ChatCompletionResult): void;
/**
* Records an error that occurred during a generation.
*
* @param generationId - The unique identifier of the generation
* @param error - Error information including message, code, and type
* @returns void
* @example
* logger.generationError('gen-123', {
* message: 'API request timed out',
* code: 'TIMEOUT_ERROR',
* type: 'NetworkError'
* });
*/
generationError(generationId: string, error: GenerationError): void;
/**
* Adds metadata to a generation for additional context and debugging.
*
* @param generationId - The unique identifier of the generation
* @param metadata - Key-value pairs of metadata
* @returns void
* @example
* logger.generationMetadata('gen-123', {
* requestId: 'req-789',
* latency: 1200,
* tokensPerSecond: 15.5
* });
*/
generationMetadata(generationId: string, metadata: Record<string, unknown>): void;
/**
* Gets the evaluation methods for a generation.
*
* @param generationId - The unique identifier of the generation
* @returns Evaluation methods for configuring and triggering evaluations on the generation
* @example
* logger.generationEvaluate('gen-123')
* .withEvaluators('bias', 'toxicity')
* .withVariables({ expected_output: 'The correct answer' });
*/
generationEvaluate(generationId: string): import("./components").EvaluateContainer;
/**
* Ends a generation and records the end timestamp.
*
* @param generationId - The unique identifier of the generation
* @returns void
* @example
* logger.generationEnd('gen-123');
*/
generationEnd(generationId: string, data?: any): void;
/**
* Adds an attachment to this generation.
*
* @param generationId - The unique identifier of the generation
* @param attachment - The attachment to add (can be of type file, data, or URL)
* @returns void
* @example
* logger.generationAddAttachment('gen-123',{
* id: 'input-document',
* type: 'file',
* path: './uploads/document.pdf',
* tags: { category: 'input' }
* });
*/
generationAddAttachment(generationId: string, attachment: Attachment): void;
/**
* Creates a new generation (LLM call) associated with a span.
*
* @param spanId - The unique identifier of the span
* @param config - Configuration for the generation
* @returns A new generation instance associated with the span
* @example
* const generation = logger.spanGeneration('span-123', {
* id: 'gen-001',
* provider: 'openai',
* model: 'gpt-4',
* messages: [{ role: 'user', content: 'Process this data' }],
* modelParameters: { temperature: 0.1 }
* });
*/
spanGeneration(spanId: string, config: GenerationConfig): Generation;
/**
* Creates a new retrieval associated with a span.
*
* @param spanId - The unique identifier of the span
* @param config - Configuration for the retrieval
* @returns A new retrieval instance associated with the span
* @example
* const retrieval = logger.spanRetrieval('span-123', {
* id: 'retrieval-001',
* name: 'Context Database Lookup'
* });
*/
spanRetrieval(spanId: string, config: RetrievalConfig): Retrieval;
/**
* Creates a new tool call associated with a span.
*
* @param spanId - The unique identifier of the span
* @param config - Configuration for the tool call
* @returns A new tool call instance associated with the span
* @example
* const toolCall = logger.spanToolCall('span-123', {
* id: 'tool-001',
* name: 'api_call',
* description: 'Fetch data from external service',
* args: JSON.stringify({ endpoint: '/users', id: 123 })
* });
*/
spanToolCall(spanId: string, config: ToolCallConfig): ToolCall;
/**
* Creates a nested span within a span for hierarchical organization.
*
* @param spanId - The unique identifier of the parent span
* @param config - Configuration for the nested span
* @returns A new nested span instance
* @example
* const childSpan = logger.spanSpan('span-123', {
* id: 'child-span-001',
* name: 'Data Validation Step'
* });
*/
spanSpan(spanId: string, config: SpanConfig): Span;
/**
* Adds a tag to a span for categorization and filtering.
*
* @param spanId - The unique identifier of the span
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* logger.spanTag('span-123', 'phase', 'preprocessing');
* logger.spanTag('span-123', 'status', 'in_progress');
*/
spanTag(spanId: string, key: string, value: string): void;
/**
* Creates an error associated with a span.
*
* @param spanId - The unique identifier of the span
* @param config - Configuration for the error
* @returns A new error instance associated with the span
* @example
* const error = logger.spanError('span-123', {
* id: 'error-001',
* message: 'Validation failed',
* code: 'VALIDATION_ERROR',
* type: 'ValidationError'
* });
*/
spanError(spanId: string, config: ErrorConfig): MaximError;
/**
* Emits a custom event within a span.
*
* @param spanId - The unique identifier of the span
* @param eventId - Unique identifier for the event
* @param eventName - Human-readable name for the event
* @param tags - Optional tags for categorizing the event
* @param metadata - Optional metadata for additional context
* @returns void
* @example
* logger.spanEvent(
* 'span-123',
* 'validation-complete',
* 'Data Validation Complete',
* { status: 'success', records: '1000' },
* { validationTime: 250, errorsFound: 0 }
* );
*/
spanEvent(spanId: string, eventId: string, eventName: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
/** @deprecated Use the method with explicit eventId and eventName instead */
spanEvent(spanId: string, eventName: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
/**
* Adds metadata to a span for additional context and debugging.
*
* @param spanId - The unique identifier of the span
* @param metadata - Key-value pairs of metadata
* @returns void
* @example
* logger.spanMetadata('span-123', {
* processingTime: 500,
* itemsProcessed: 250,
* memoryUsage: '128MB'
* });
*/
spanMetadata(spanId: string, metadata: Record<string, unknown>): void;
/**
* Gets the evaluation methods for a span.
*
* @param spanId - The unique identifier of the span
* @returns Evaluation methods for configuring and triggering evaluations on the span
* @example
* logger.spanEvaluate('span-123')
* .withEvaluators('performance', 'accuracy')
* .withVariables({ expected_output: 'target_result' });
*/
spanEvaluate(spanId: string): import("./components").EvaluateContainer;
/**
* Ends a span and records the end timestamp.
*
* @param spanId - The unique identifier of the span
* @returns void
* @example
* logger.spanEnd('span-123');
*/
spanEnd(spanId: string, data?: any): void;
/**
* Adds an attachment to this span.
*
* @param spanId - The unique identifier of the span
* @param attachment - The attachment to add (can be of type file, data, or URL)
* @returns void
* @example
* logger.spanAddAttachment('span-123',{
* id: 'input-document',
* type: 'file',
* path: './uploads/document.pdf',
* tags: { category: 'input' }
* });
*/
spanAddAttachment(spanId: string, attachment: Attachment): void;
/**
* Ends a retrieval and records the end timestamp.
*
* @param retrievalId - The unique identifier of the retrieval
* @returns void
* @example
* logger.retrievalEnd('retrieval-123');
*/
retrievalEnd(retrievalId: string): void;
/**
* Adds a tag to a retrieval for categorization and filtering.
*
* @param retrievalId - The unique identifier of the retrieval
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* logger.retrievalAddTag('retrieval-123', 'source', 'knowledge_base');
* logger.retrievalAddTag('retrieval-123', 'query_type', 'semantic');
*/
retrievalAddTag(retrievalId: string, key: string, value: string): void;
/**
* Sets the input query for a retrieval operation.
*
* @param retrievalId - The unique identifier of the retrieval
* @param input - The search query or input text
* @returns void
* @example
* logger.retrievalInput('retrieval-123', 'How do I troubleshoot network issues?');
*/
retrievalInput(retrievalId: string, input: string): void;
/**
* Adds a numeric metric to a retrieval.
*
* Records quantitative values used in information retrieval and RAG evaluation under a
* named metric.
*
* Common examples include: `precision`, `recall`, `f1_score`, `mrr` (Mean Reciprocal Rank),
* `ndcg` (Normalized Discounted Cumulative Gain), `avg_similarity`, `results_count`,
* `unique_sources_count`.
*
* @param retrievalId - The unique identifier of the retrieval
* @param name - Name of the metric
* @param value - Numeric value of the metric (numeric)
* @returns void
* @example
* logger.retrievalAddMetric('retrieval-123', 'precision', 0.86);
* logger.retrievalAddMetric('retrieval-123', 'mrr', 0.58);
*/
retrievalAddMetric(retrievalId: string, name: string, value: number): void;
/**
* Sets the output results for a retrieval operation and ends it.
*
* @param retrievalId - The unique identifier of the retrieval
* @param output - Retrieved documents as a single string or array
* @returns void
* @example
* // Single result
* logger.retrievalOutput('retrieval-123', 'Network troubleshooting guide: First, check cables...');
*
* @example
* // Multiple results
* logger.retrievalOutput('retrieval-123', [
* 'Document 1: Basic troubleshooting steps...',
* 'Document 2: Advanced network diagnostics...'
* ]);
*/
retrievalOutput(retrievalId: string, output: string | string[]): void;
/**
* Adds metadata to a retrieval for additional context and debugging.
*
* @param retrievalId - The unique identifier of the retrieval
* @param metadata - Key-value pairs of metadata
* @returns void
* @example
* logger.retrievalMetadata('retrieval-123', {
* searchTime: 150,
* resultsCount: 5,
* similarityThreshold: 0.85
* });
*/
retrievalMetadata(retrievalId: string, metadata: Record<string, unknown>): void;
/**
* Gets the evaluation methods for a retrieval.
*
* @param retrievalId - The unique identifier of the retrieval
* @returns Evaluation methods for configuring and triggering evaluations on the retrieval
* @example
* logger.retrievalEvaluate('retrieval-123')
* .withEvaluators('relevance', 'recall')
* .withVariables({ context: 'user_query', expected: 'ground_truth' });
*/
retrievalEvaluate(retrievalId: string): import("./components").EvaluateContainer;
/**
* Records the successful result of a tool call and ends it.
*
* @param toolCallId - The unique identifier of the tool call
* @param result - The result returned by the tool as a string
* @returns void
* @example
* logger.toolCallResult('tool-123', JSON.stringify({
* userId: '12345',
* name: 'John Doe',
* email: 'john@example.com'
* }));
*/
toolCallResult(toolCallId: string, result: string): void;
/**
* Records an error that occurred during a tool call and ends it.
*
* @param toolCallId - The unique identifier of the tool call
* @param error - Error information including message, code, and type
* @returns void
* @example
* logger.toolCallError('tool-123', {
* message: 'Database connection failed',
* code: 'DB_CONNECTION_ERROR',
* type: 'DatabaseError'
* });
*/
toolCallError(toolCallId: string, error: ToolCallError): void;
/**
* Adds a tag to a tool call for categorization and filtering.
*
* @param toolCallId - The unique identifier of the tool call
* @param key - The tag key
* @param value - The tag value
* @returns void
* @example
* logger.toolCallAddTag('tool-123', 'category', 'database');
* logger.toolCallAddTag('tool-123', 'priority', 'high');
*/
toolCallAddTag(toolCallId: string, key: string, value: string): void;
/**
* Adds metadata to a tool call for additional context and debugging.
*
* @param toolCallId - The unique identifier of the tool call
* @param metadata - Key-value pairs of metadata
* @returns void
* @example
* logger.toolCallMetadata('tool-123', {
* executionTime: 350,
* apiEndpoint: '/api/v1/users',
* responseSize: 1024
* });
*/
toolCallMetadata(toolCallId: string, metadata: Record<string, unknown>): void;
/**
* Flushes all pending logs to the backend immediately.
*
* Forces the log writer to send all queued logs to the Maxim backend
* without waiting for the automatic flush interval.
*
* @returns void
* @example
* // Force flush before critical operation
* logger.flush();
*/
flush(): Promise<void>;
}