@maximai/maxim-js
Version:
Maxim AI JS SDK. Visit https://getmaxim.ai for more info.
285 lines • 9.25 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.Span = void 0;
const base_1 = require("./base");
const error_1 = require("./error");
const generation_1 = require("./generation");
const retrieval_1 = require("./retrieval");
const toolCall_1 = require("./toolCall");
const types_1 = require("./types");
/**
* 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'
* });
*/
class Span extends base_1.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, writer) {
super(types_1.Entity.SPAN, config, writer);
this.commit("create");
}
/**
* 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) {
const generation = new generation_1.Generation(config, this.writer);
this.commit("add-generation", {
id: config.id,
messages: JSON.parse(JSON.stringify(config.messages)),
...generation.data(),
});
return 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, id, config) {
const generation = new generation_1.Generation(config, writer);
base_1.EventEmittingBaseContainer.commit_(writer, types_1.Entity.SPAN, id, "add-generation", {
id: config.id,
messages: JSON.parse(JSON.stringify(config.messages)),
...generation.data(),
});
return 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) {
const span = new Span(config, this.writer);
this.commit("add-span", {
id: config.id,
...span.data(),
});
return 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, id, config) {
const span = new Span(config, writer);
base_1.EventEmittingBaseContainer.commit_(writer, types_1.Entity.SPAN, id, "add-span", {
id: config.id,
...span.data(),
});
return 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) {
const error = new error_1.Error(config, this.writer);
this.commit("add-error", {
id: config.id,
...error.data(),
});
return 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, id, config) {
const error = new error_1.Error(config, writer);
base_1.EventEmittingBaseContainer.commit_(writer, types_1.Entity.SPAN, id, "add-error", {
id: config.id,
...error.data(),
});
return 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) {
const retrieval = new retrieval_1.Retrieval(config, this.writer);
this.commit("add-retrieval", {
id: config.id,
...retrieval.data(),
});
return 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, id, config) {
const retrieval = new retrieval_1.Retrieval(config, writer);
base_1.EventEmittingBaseContainer.commit_(writer, types_1.Entity.SPAN, id, "add-retrieval", {
id: config.id,
...retrieval.data(),
});
return 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) {
const toolCall = new toolCall_1.ToolCall(config, this.writer);
this.commit("add-tool-call", {
id: config.id,
...toolCall.data(),
});
return 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, id, config) {
const toolCall = new toolCall_1.ToolCall(config, writer);
base_1.EventEmittingBaseContainer.commit_(writer, types_1.Entity.SPAN, id, "add-tool-call", {
id: config.id,
...toolCall.data(),
});
return 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) {
this.commit("upload-attachment", attachment);
}
/**
* 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, id, attachment) {
base_1.EventEmittingBaseContainer.commit_(writer, types_1.Entity.SPAN, id, "upload-attachment", attachment);
}
}
exports.Span = Span;
//# sourceMappingURL=span.js.map