@gaiaverse/semantic-turning-point-detector
Version:
Detects key semantic turning points in conversations using recursive semantic distance analysis. Ideal for conversation analysis, dialogue segmentation, insight detection, and AI-assisted reasoning tasks.
172 lines (171 loc) • 8.48 kB
TypeScript
import type { TurningPoint } from './types';
/**
* Message span identifies a range of messages
* Used for tracking dimensional representations across recursion levels
*/
export interface MessageSpan {
/** Start message ID */
startId: string;
/** End message ID */
endId: string;
/** Start index in the original message array */
startIndex: number;
/** End index in the original message array */
endIndex: number;
/** Original message span if this is a meta-message span */
originalSpan?: MessageSpan;
}
/**
* BaseMessage interface - foundation for all message types
*/
export interface Message {
/** Unique identifier for this message */
id: string;
/** The sender of the message */
author: string;
/** The message content */
message: string;
/** Optional span data for dimensional tracking */
spanData?: MessageSpan;
/** Get index method - implementations must handle both cases */
getIndex?(originalMessages?: any[], isStart?: boolean): number;
/** Get turning points */
getTurningPoints?(): TurningPoint[];
/** Get getMessagesContentContextualAid */
getMessagesContentContextualAid?(props: {
dimension?: number;
contextualType?: 'before-and-after' | 'within';
messagesToUse?: number;
maxContentLengthChar?: number;
}): string;
getMessagesInTurningPointSpan?(): Map<string, Message[]>;
getMessagesInTurningPointSpanToMessagesArray?(): Message[];
}
/**
* MetaMessage class provides structured representation of higher dimensional messages
* with guaranteed span information and proper indexing
*/
export declare class MetaMessage implements Message {
readonly id: string;
readonly author: string;
readonly message: string;
readonly spanData: MessageSpan;
private readonly representedTurningPoints?;
private readonly messagesByTurningPoint;
readonly dimension: number;
constructor(id: string, content: string, spanData: MessageSpan, representedTurningPoints: TurningPoint[], originalMessages: Message[], dimension?: number);
/**
* Reliably returns the index of this meta-message in the original conversation
* - Meta-messages always include spanData with reliable indices, making originalMessages unnecessary. Originally, originalMessages was used in a format that managed containing messages within a single interface. It relied on creating regex IDs to extract indices and determine if a message was a meta-message. However, this approach failed due to design flaws, as more complex origin message string IDs could not reliably be converted into a meta ID. As a result, this new class was developed to encapsulate a meta-message, which can encompass a group of turning points. This is distinct from a baseMessage, which represents a single turning point between two actual messages.
*/
getIndex(originalMessages?: any[], isStart?: boolean): number;
getMessagesInTurningPointSpan(): Map<string, Message[]>;
getMessagesInTurningPointSpanToMessagesArray(): Message[];
/**
* Creates a string representation with embedded span information for debugging
*/
toString(): string;
/**
* Like `getMessagesContentContextualAid`, but for a single turning point rather than a meta message group
* - does not include any header, only a 4thlevel header for the message(s) content
* @param dimension - the dimension of the message
* @param messagesToUse - the number of messages to use
* @param maxContentLengthChar - the maximum content length in characters
* @param beforeMessage
*/
static getMessagesContentContextualAidFromJustProvidedBeforeAndAfterMessages(beforeMessage: MetaMessage, afterMessage: MetaMessage, dimension?: number, messagesToUse?: number, maxContentLengthChar?: number, originalMessages?: Message[], type?: 'before-and-after' | 'within'): string;
/**
* Finds the index of a specific message content element (baseMessage), from a given provided id string that is either a MetaMessage or a BaseMessage
* - determines the instance of the message (meta or base) and returns the index of the message in the original messages array
* @param param0
* @returns
*/
static findIndexOfMessageFromId: ({ id, beforeMessage, afterMessage, messages, consoleLogger, }: {
/** The id of the meta/ormessge to find index */
id: string;
/** The message before the turning point (may be a meta) */
beforeMessage?: Message | null | undefined | MetaMessage;
/** The message after the turning point (may be a meta) */
afterMessage?: Message | null | undefined | MetaMessage;
/** The original array of messages for lookup these are the original messages (not meta) */
messages: Message[] | MetaMessage[];
consoleLogger?: Console;
}) => number;
/**
* Retrieves and formats message content from turning points to provide contextual analysis.
*
* This method extracts messages from the first and last turning points in the group,
* formats them according to the specified parameters, and returns a structured
* representation that can be used for analysis or display.
*
* @param options Configuration options for content retrieval and formatting
* @param options.dimension - Dimensional level of analysis (0 = base conversation, 1+ = meta-analysis of turning point groups)
* @param options.contextualType - How to present message context:
* - "within": Shows messages within the turning point group (first and last messages)
* - "before-and-after": Shows messages that appear before and after the turning point group
* @param options.messagesToUse - Number of messages to include in each context section (default: 2)
* @param options.maxContentLengthChar - Maximum length in characters for each message content (default: 8000)
*
* @returns Formatted string containing structured message content with appropriate headers and context
*
* @example
* // Get messages within a turning point group
* const withinContent = metaMessage.getMessagesContentContextualAid({
* dimension: 1,
* contextualType: "within"
* });
*
* @example
* // Get messages before and after a turning point group with custom limits
* const surroundingContent = metaMessage.getMessagesContentContextualAid({
* contextualType: "before-and-after",
* messagesToUse: 3,
* maxContentLengthChar: 5000
* });
*/
getMessagesContentContextualAid({ dimension, contextualType, messagesToUse, maxContentLengthChar }: {
/**
* Dimensional level of analysis:
* - 0: Base conversation analysis (individual messages)
* - 1+: Meta-analysis of turning point groups (higher abstraction)
*/
dimension?: number;
/**
* Context presentation strategy:
* - "within": Shows messages within the turning point span (first and last)
* - "before-and-after": Shows messages surrounding the turning point
*/
contextualType?: "before-and-after" | "within";
/**
* Number of messages to include in each context section
* (beginning/end of turning point or before/after turning point)
*/
messagesToUse?: number;
/**
* Maximum character length for individual message content before truncation
*/
maxContentLengthChar?: number;
}): string;
/**
* Formats the "within" context output
*/
private formatWithinContextOutput;
/**
* Formats the "before-and-after" context output
*/
private formatBeforeAfterContextOutput;
/**
* Factory method to create a category meta-message from turning points
*/
static createCategoryMetaMessage(category: string, points: TurningPoint[], index: number, originalMessages: Message[], dimension?: number): MetaMessage;
/**
* Factory method to create a section meta-message
*/
static createSectionMetaMessage(sectionPoints: TurningPoint[], sectionIndex: number, originalMessages: Message[]): MetaMessage;
getTurningPoints(): TurningPoint[];
}
/**
* Type guard to check if a message is a MetaMessage instance
*/
export declare function isMetaMessage(message: any): message is MetaMessage;
//# sourceMappingURL=Message.d.ts.map