@maximai/maxim-js

import type { Attachment } from "../../types"; import { ILogWriter } from "../types"; import { EventEmittingBaseContainer } from "./base"; import { Error, ErrorConfig } from "./error"; import { Generation, GenerationConfig } from "./generation"; import { Retrieval, RetrievalConfig } from "./retrieval"; import { Span, SpanConfig } from "./span"; import { ToolCall, ToolCallConfig } from "./toolCall"; /** * Configuration object for trace. */ export type TraceConfig = { id: string; name?: string; sessionId?: 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; }; /** * Represents a trace (a single turn interaction). * * Traces capture the complete execution flow of operations, including generations, * tool calls, retrievals, spans, and errors happening within one user interaction * turn. They provide detailed timing and hierarchical organization of activities * within a session or standalone operation. * * @class Trace * @extends EventEmittingBaseContainer * @example * const trace = logger.trace({ * id: 'query-processing-trace', * name: 'User Query Processing', * sessionId: 'chat-session-001', // optional * }); * * // Add input * trace.input('Find information about machine learning'); * * // Adding components to trace * const generation = trace.generation({ * id: 'llm-generation-001', * provider: 'openai', * model: 'gpt-4', * messages: [{ role: 'user', content: 'Explain ML' }], * modelParameters: { temperature: 0.7 } * }); * * const retrieval = trace.retrieval({ * id: 'vector-search-001', * name: 'Knowledge Base Search' * }); * * const toolCall = trace.toolCall({ * id: 'search-tool-001', * name: 'external_search', * description: 'Search external knowledge base', * args: JSON.stringify({ query: 'machine learning' }) * }); * * // Add output * trace.output('Machine learning is a subset of artificial intelligence...'); */ export declare class Trace extends EventEmittingBaseContainer { /** * Creates a new trace log entry. * * @param config - Configuration object defining the trace * @param writer - Log writer instance for persisting trace data * @example * const trace = new Trace({ * id: 'recommendation-trace', * name: 'Product Recommendation Flow', * sessionId: 'shopping-session-456', * }); */ constructor(config: TraceConfig, writer: ILogWriter); /** * Creates a new generation (LLM call) within this trace. * * @param config - Configuration for the generation * @returns A new generation instance associated with this trace * @example * const generation = trace.generation({ * id: 'summary-generation', * provider: 'openai', * model: 'gpt-4', * messages: [ * { role: 'system', content: 'Summarize the following text.' }, * { role: 'user', content: 'Long article content...' } * ], * modelParameters: { temperature: 0.3, max_tokens: 150 } * }); */ generation(config: GenerationConfig): Generation; /** * Static method to create a generation associated with any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param config - Configuration for the generation * @returns A new generation instance */ static generation_(writer: ILogWriter, id: string, config: GenerationConfig): Generation; /** * Associates this trace with a session. * * @param sessionId - The ID of the session to associate with * @returns void * @example * trace.addToSession('user-session-789'); */ addToSession(sessionId: string): void; /** * Static method to associate any trace with a session by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param sessionId - The session ID to associate with * @returns void */ static addToSession_(writer: ILogWriter, id: string, sessionId: string): void; /** * Adds feedback to this trace from users. * * @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 * trace.feedback({ * score: 4, * comment: 'Good results but could be faster' * }); */ feedback(feedback: { score: number; comment?: string; }): void; /** * Static method to add feedback to any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param feedback - Feedback object * @param feedback.score - Numerical score for the trace * @param feedback.comment - Optional textual feedback * @returns void */ static feedback_(writer: ILogWriter, id: string, feedback: { score: number; comment?: string; }): void; /** * Adds a numeric metric to this trace. * * Records quantitative values such as tool call counts, retry attempts, total tokens, * overall cost, or aggregated evaluation scores under a named metric. Each call adds * or updates a single metric entry. * * Common examples include: `tool_calls_count`, `retries_count`, `cost_usd`, `tokens_total`, * `eval_overall_score`, `user_feedback_score`. * * @param name - Name of the metric * @param value - Numeric value of the metric (numeric) * @returns void * @example * trace.addMetric('tool_calls_count', 3); * trace.addMetric('cost_usd', 0.05); * trace.addMetric('tokens_total', 1420); * trace.addMetric('user_feedback_score', 4.7); */ addMetric(name: string, value: number): void; /** * Static method to add a metric to any trace by ID. * * @param writer - The log writer instance * @param id - The trace 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 trace. * * @param attachment - The attachment to add (can be of type file, data, or URL) * @returns void * @example * trace.addAttachment({ * id: 'input-document', * type: 'file', * path: './uploads/document.pdf', * tags: { category: 'input' } * }); */ addAttachment(attachment: Attachment): void; /** * Static method to add an attachment to any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param attachment - The attachment to add * @returns void */ static addAttachment_(writer: ILogWriter, id: string, attachment: Attachment): void; /** * Creates a new span within this trace for hierarchical organization. * * @param config - Configuration for the span * @returns A new span instance associated with this trace * @example * const span = trace.span({ * id: 'data-processing-span', * name: 'Data Processing Pipeline', * }); */ span(config: SpanConfig): Span; /** * Static method to create a span associated with any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param config - Configuration for the span * @returns A new span instance */ static span_(writer: ILogWriter, id: string, config: SpanConfig): Span; /** * Creates an error within this trace. * * @param config - Configuration for the error * @returns A new error instance associated with this trace * @example * const error = trace.error({ * id: 'processing-error', * message: 'Failed to process user input', * code: 'PROCESSING_FAILED', * type: 'ProcessingError' * }); */ error(config: ErrorConfig): Error; /** * Static method to create an error associated with any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param config - Configuration for the error * @returns A new error instance */ static error_(writer: ILogWriter, id: string, config: ErrorConfig): Error; /** * Creates a tool call within this trace. * * @param config - Configuration for the tool call * @returns A new tool call instance associated with this trace * @example * const toolCall = trace.toolCall({ * id: 'calculator-tool', * name: 'calculate', * description: 'Perform mathematical calculations', * args: JSON.stringify({ expression: '2 + 2' }) * }); */ toolCall(config: ToolCallConfig): ToolCall; /** * Static method to create a tool call associated with any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param config - Configuration for the tool call * @returns A new tool call instance */ static toolCall_(writer: ILogWriter, id: string, config: ToolCallConfig): ToolCall; /** * Creates a retrieval within this trace. * * @param config - Configuration for the retrieval * @returns A new retrieval instance associated with this trace * @example * const retrieval = trace.retrieval({ * id: 'knowledge-search', * name: 'Knowledge Base Search' * }); */ retrieval(config: RetrievalConfig): Retrieval; /** * Static method to create a retrieval associated with any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param config - Configuration for the retrieval * @returns A new retrieval instance */ static retrieval_(writer: ILogWriter, id: string, config: RetrievalConfig): Retrieval; /** * Sets the input for this trace. * * @param input - The input that for this trace * @returns This trace instance for method chaining * @example * trace.input('Analyze this customer feedback: "The product is great but shipping was slow"'); */ input(input: string): Trace; /** * Static method to set input for any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param input - The input for the trace * @returns void */ static input_(writer: ILogWriter, id: string, input: string): void; /** * Sets the output for this trace. * * @param output - The final output or result of this trace execution * @returns This trace instance for method chaining * @example * trace.output('Sentiment: Positive (0.7), Issues: Shipping delay, Action: Contact logistics team'); */ output(output: string): Trace; /** * Static method to set output for any trace by ID. * * @param writer - The log writer instance * @param id - The trace ID * @param output - The output for the trace * @returns void */ static output_(writer: ILogWriter, id: string, output: string): void; }