@maximai/maxim-js/src/lib/logger/components/span.d.ts

Maxim AI JS SDK. Visit https://getmaxim.ai for more info.

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 { ToolCall, ToolCallConfig } from "./toolCall";
/**
 * Configuration object for span.
 */
export type SpanConfig = {
    id: 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;
};
/**
 * Represents a hierarchical span within a trace for grouping.
 *
 * Spans provide fine-grained instrumentation within traces, allowing you to
 * organize sections of complex operations. They can contain
 * all kinds of components within them apart from trace or session (nested spans are allowed).
 *
 * @class Span
 * @extends EventEmittingBaseContainer
 * @example
 * const span = container.span({
 *   id: 'authentication-span',
 *   name: 'User Authentication Process',
 * });
 *
 * // Add operations to the span
 * const generation = span.generation({
 *   id: 'token-validation',
 *   provider: 'internal',
 *   model: 'auth-validator',
 *   messages: [{ role: 'system', content: 'Validate token' }],
 *   modelParameters: {}
 * });
 *
 * @example
 * // Nested spans for complex operations
 * const parentSpan = container.span({
 *   id: 'document-processing',
 *   name: 'Document Analysis Pipeline'
 * });
 *
 * const childSpan = parentSpan.span({
 *   id: 'text-extraction',
 *   name: 'Text Extraction Phase'
 * });
 *
 * const retrieval = childSpan.retrieval({
 *   id: 'knowledge-lookup',
 *   name: 'Knowledge Base Lookup'
 * });
 */
export declare class Span extends EventEmittingBaseContainer {
    /**
     * Creates a new span log entry.
     *
     * @param config - Configuration object defining the span
     * @param writer - Log writer instance for persisting span data
     * @example
     * const span = container.span({
     *   id: 'data-validation-span',
     *   name: 'Input Data Validation',
     * });
     */
    constructor(config: SpanConfig, writer: ILogWriter);
    /**
     * Creates a new generation (LLM call) within this span.
     *
     * @param config - Configuration for the generation
     * @returns A new generation instance associated with this span
     * @example
     * const generation = span.generation({
     *   id: 'validation-check',
     *   provider: 'openai',
     *   model: 'gpt-4',
     *   messages: [{ role: 'user', content: 'Validate this input' }],
     *   modelParameters: { temperature: 0.1 }
     * });
     */
    generation(config: GenerationConfig): Generation;
    /**
     * Static method to create a generation associated with any span by ID.
     *
     * @param writer - The log writer instance
     * @param id - The span ID
     * @param config - Configuration for the generation
     * @returns A new generation instance
     */
    static generation_(writer: ILogWriter, id: string, config: GenerationConfig): Generation;
    /**
     * Creates a nested span within this span for hierarchical organization.
     *
     * @param config - Configuration for the nested span
     * @returns A new nested span instance
     * @example
     * const childSpan = parentSpan.span({
     *   id: 'preprocessing-step',
     *   name: 'Data Preprocessing',
     * });
     */
    span(config: SpanConfig): Span;
    /**
     * Static method to create a nested span associated with any span by ID.
     *
     * @param writer - The log writer instance
     * @param id - The parent span ID
     * @param config - Configuration for the nested span
     * @returns A new nested span instance
     */
    static span_(writer: ILogWriter, id: string, config: SpanConfig): Span;
    /**
     * Creates an error within this span.
     *
     * @param config - Configuration for the error
     * @returns A new error instance associated with this span
     * @example
     * const error = span.error({
     *   id: 'validation-error',
     *   message: 'Input validation failed',
     *   code: 'INVALID_INPUT',
     *   type: 'ValidationError'
     * });
     */
    error(config: ErrorConfig): Error;
    /**
     * Static method to create an error associated with any span by ID.
     *
     * @param writer - The log writer instance
     * @param id - The span ID
     * @param config - Configuration for the error
     * @returns A new error instance
     */
    static error_(writer: ILogWriter, id: string, config: ErrorConfig): Error;
    /**
     * Creates a retrieval within this span.
     *
     * @param config - Configuration for the retrieval
     * @returns A new retrieval instance associated with this span
     * @example
     * const retrieval = span.retrieval({
     *   id: 'context-lookup',
     *   name: 'Context Database Lookup',
     * });
     *
     * retrieval.input('user query context');
     * retrieval.output(['relevant context 1', 'relevant context 2']);
     */
    retrieval(config: RetrievalConfig): Retrieval;
    /**
     * Static method to create a retrieval associated with any span by ID.
     *
     * @param writer - The log writer instance
     * @param id - The span ID
     * @param config - Configuration for the retrieval
     * @returns A new retrieval instance
     */
    static retrieval_(writer: ILogWriter, id: string, config: RetrievalConfig): Retrieval;
    /**
     * Creates a tool call within this span.
     *
     * @param config - Configuration for the tool call
     * @returns A new tool call instance associated with this span
     * @example
     * const toolCall = span.toolCall({
     *   id: 'api-call',
     *   name: 'external_api_call',
     *   description: 'Fetch data from external service',
     *   args: JSON.stringify({ endpoint: '/users', id: 123 })
     * });
     *
     * toolCall.result('{"name": "John", "email": "john@example.com"}');
     */
    toolCall(config: ToolCallConfig): ToolCall;
    /**
     * Static method to create a tool call associated with any span by ID.
     *
     * @param writer - The log writer instance
     * @param id - The span ID
     * @param config - Configuration for the tool call
     * @returns A new tool call instance
     */
    static toolCall_(writer: ILogWriter, id: string, config: ToolCallConfig): ToolCall;
    /**
     * Adds an attachment to this span.
     *
     * @param attachment - The attachment to add (file, data, or URL)
     * @returns void
     * @example
     * span.addAttachment({
     *   id: 'processing-result',
     *   type: 'file',
     *   path: './output/processed_data.json',
     *   name: 'Processing Results'
     * });
     */
    addAttachment(attachment: Attachment): void;
    /**
     * Static method to add an attachment to any span by ID.
     *
     * @param writer - The log writer instance
     * @param id - The span ID
     * @param attachment - The attachment to add
     * @returns void
     */
    static addAttachment_(writer: ILogWriter, id: string, attachment: Attachment): void;
}