llmxml/dist/cjs/index.d.ts

Convert between markdown and LLM-friendly pseudo-XML

/**
 * Core types for the LLMXML library
 */
/**
 * Base node interface for the AST
 */
interface ASTNode {
    /** Type identifier for the node */
    type: string;
    /** Optional child nodes */
    children?: ASTNode[];
}
/**
 * Represents a Markdown heading (# Title)
 */
interface HeadingNode extends ASTNode {
    type: 'heading';
    /** Heading level (1-6) corresponding to #, ##, etc. */
    depth: number;
    /** The text content of the heading */
    text: string;
}
/**
 * Represents a plain text node
 */
interface TextNode extends ASTNode {
    type: 'text';
    /** The raw text content */
    value: string;
}
/**
 * Represents a code block (```lang\ncode\n```)
 */
interface CodeBlockNode extends ASTNode {
    type: 'code';
    /** The code block content */
    value: string;
    /** Optional language identifier */
    lang?: string;
}
/**
 * Represents an ordered or unordered list
 */
interface ListNode extends ASTNode {
    type: 'list';
    /** Whether this is an ordered (1. 2.) or unordered (- *) list */
    ordered: boolean;
    /** The list items */
    children: ListItemNode[];
}
/**
 * Represents a single item in a list
 */
interface ListItemNode extends ASTNode {
    type: 'listItem';
    /** The content of the list item */
    children: ASTNode[];
}
/**
 * Represents a paragraph of text, which may contain formatted elements
 */
interface ParagraphNode extends ASTNode {
    type: 'paragraph';
    /** The paragraph's content nodes */
    children: (TextNode | EmphasisNode | LinkNode)[];
}
/**
 * Represents emphasized text (*italic* or **bold**)
 */
interface EmphasisNode extends ASTNode {
    /** 'emphasis' for *italic*, 'strong' for **bold** */
    type: 'emphasis' | 'strong';
    /** The emphasized text */
    children: TextNode[];
}
/**
 * Represents a hyperlink [text](url)
 */
interface LinkNode extends ASTNode {
    type: 'link';
    /** The link's destination URL */
    url: string;
    /** The link text */
    children: TextNode[];
}
/**
 * Represents a pseudo-XML tag in the LLM format
 */
interface TagNode extends ASTNode {
    type: 'tag';
    /** The tag name, derived from the heading text */
    name: string;
    /** Tag attributes */
    attributes: {
        /** Original heading text */
        title: string;
        /** Original heading level */
        hlevel: string;
        /** Any additional attributes */
        [key: string]: string;
    };
}
/**
 * Warning codes for non-error conditions that should be reported
 */
type WarningCode = 
/** Multiple potential matches found for a section */
'AMBIGUOUS_MATCH'
/** Exact match not found, using fuzzy match */
 | 'FUZZY_MATCH'
/** Found match at different level than requested */
 | 'LEVEL_MISMATCH'
/** Match found in larger title */
 | 'PARTIAL_MATCH';
/**
 * Structure for warning events
 */
interface Warning {
    /** The type of warning */
    code: WarningCode;
    /** Human-readable warning message */
    message: string;
    /** Additional warning context */
    details: Record<string, unknown>;
}
/**
 * Error codes for failure conditions
 */
type ErrorCode = 
/** Failed to parse the document */
'PARSE_ERROR'
/** Requested section not found */
 | 'SECTION_NOT_FOUND'
/** Document format is invalid */
 | 'INVALID_FORMAT'
/** Invalid header level specified */
 | 'INVALID_LEVEL'
/** Multiple sections with same ID */
 | 'DUPLICATE_ID';

/**
 * Custom error class for LLMXML-specific errors
 */
declare class LLMXMLError extends Error {
    code: ErrorCode;
    details?: unknown | undefined;
    /**
     * Creates a new LLMXMLError
     *
     * @param message - Human-readable error message
     * @param code - Error code identifying the type of error
     * @param details - Optional additional error context
     */
    constructor(message: string, code: ErrorCode, details?: unknown | undefined);
}

/**
 * Configuration options for the LLMXML library
 */
interface LLMXMLOptions {
    /** Threshold for fuzzy matching (0-1, default: 0.7) */
    defaultFuzzyThreshold?: number;
    /** Warning emission level (default: 'all') */
    warningLevel?: 'all' | 'none' | 'ambiguous-only';
}
/**
 * Options for section extraction
 */
interface GetSectionOptions {
    /** Only match headers at this level */
    level?: number;
    /** Require exact matches */
    exact?: boolean;
    /** Include subsections in result */
    includeNested?: boolean;
    /** Minimum fuzzy match score (0-1) */
    fuzzyThreshold?: number;
}
/**
 * Main LLMXML class for converting between Markdown and LLM-friendly pseudo-XML
 */
declare class LLMXML {
    private readonly options;
    private warningHandlers;
    /**
     * Creates a new LLMXML instance
     *
     * @param options - Configuration options
     */
    constructor(options?: LLMXMLOptions);
    /**
     * Convert Markdown to LLM-XML format
     */
    toXML(markdown: string): Promise<string>;
    /**
     * Convert LLM-XML to Markdown format
     */
    toMarkdown(xml: string): Promise<string>;
    /**
     * Extract a single section from the document
     */
    getSection(content: string, title: string, options?: GetSectionOptions): Promise<string>;
    /**
     * Extract multiple matching sections from the document
     */
    getSections(content: string, title: string, options?: GetSectionOptions): Promise<string[]>;
    /**
     * Register a warning handler
     */
    onWarning(handler: (warning: Warning) => void): void;
    /**
     * Remove a previously registered warning handler
     *
     * @param event - The event type ('warning')
     * @param handler - The handler to remove
     */
    off(_event: 'warning', handler: (warning: Warning) => void): void;
    /**
     * Emit a warning to all registered handlers
     *
     * @param warning - The warning to emit
     */
    protected emitWarning(warning: Warning): void;
}
/**
 * Create a new LLMXML instance with the given options
 *
 * @param options - Configuration options
 * @returns A new LLMXML instance
 */
declare function createLLMXML(options?: LLMXMLOptions): LLMXML;

export { type ASTNode, type CodeBlockNode, type EmphasisNode, type ErrorCode, type GetSectionOptions, type HeadingNode, LLMXML, LLMXMLError, type LLMXMLOptions, type LinkNode, type ListItemNode, type ListNode, type ParagraphNode, type TagNode, type TextNode, type Warning, type WarningCode, createLLMXML };