@sciexpr/ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,467 @@
+import { ExpressionRoot, ExpressionKind, ValidationError, ExpressionNode } from '@sciexpr/core';
+
+/** AI 补全上下文 */
+interface CompletionContext {
+    /** 当前已输入的文本 */
+    currentInput: string;
+    /** 光标位置（基于 0 的偏移量） */
+    cursorPosition: number;
+    /** 当前已解析的 AST（如果输入合法） */
+    currentAST?: ExpressionRoot;
+    /** 表达式类型 */
+    expressionType: ExpressionKind;
+    /** 周围文档上下文（如前后段落） */
+    surroundingText?: string;
+    /** 用户自定义上下文 */
+    customContext?: Record<string, unknown>;
+}
+/** 补全候选项 */
+interface CompletionItem {
+    /** 补全文本（LaTeX 源码） */
+    text: string;
+    /** 显示标签 */
+    label: string;
+    /** 描述/说明 */
+    description?: string;
+    /** 预览渲染 HTML */
+    previewHtml?: string;
+    /** 分类 */
+    category: 'symbol' | 'command' | 'template' | 'correction' | 'formula';
+    /** 排序权重（越高越靠前） */
+    score: number;
+}
+/** 补全结果 */
+interface CompletionResult {
+    /** 补全候选项列表 */
+    items: CompletionItem[];
+    /** 是否为 AI 生成（vs 本地静态匹配） */
+    source: 'ai' | 'local' | 'hybrid';
+    /** 请求耗时（ms） */
+    latencyMs?: number;
+}
+/**
+ * AI 补全提供者接口（SPI）
+ *
+ * 使用方实现此接口，将自己已有的 AI 模型注入引擎。
+ * 引擎不依赖任何特定 AI SDK。
+ */
+interface IAICompletionProvider {
+    /** 提供者唯一标识 */
+    readonly id: string;
+    /** 提供者名称 */
+    readonly name: string;
+    /**
+     * 获取补全候选项
+     * @param context 补全上下文
+     * @returns 补全结果
+     */
+    complete(context: CompletionContext): Promise<CompletionResult>;
+    /**
+     * 流式补全（可选）
+     * 用于打字机效果的实时补全
+     */
+    completeStream?(context: CompletionContext): AsyncIterable<CompletionItem>;
+    /**
+     * AI 纠错建议（可选）
+     * 当用户输入无效时，AI 给出修正建议
+     */
+    correct?(input: string, error: ValidationError): Promise<CompletionItem[]>;
+    /**
+     * 自然语言 → 公式转换（可选）
+     * "水的化学式" → "H₂O"
+     */
+    naturalLanguageToFormula?(query: string): Promise<CompletionItem[]>;
+}
+
+/** 知识库查询参数 */
+interface KBQueryParams {
+    /** 查询文本 */
+    query: string;
+    /** 查询类型限制 */
+    types?: ('element' | 'compound' | 'formula' | 'symbol' | 'reaction' | 'constant')[];
+    /** 最大返回数 */
+    maxResults?: number;
+    /** 语言偏好 */
+    language?: string;
+}
+/** 符号信息 */
+interface SymbolInfo {
+    /** LaTeX 命令或符号 */
+    symbol: string;
+    /** 名称 */
+    name: string;
+    /** 描述 */
+    description: string;
+    /** 分类 */
+    category: string;
+    /** 使用示例 */
+    example?: string;
+    /** 关联符号 */
+    relatedSymbols?: string[];
+}
+/** 公式模板 */
+interface FormulaTemplate {
+    /** 模板唯一标识 */
+    id: string;
+    /** 模板名称 */
+    name: string;
+    /** LaTeX 源码 */
+    latex: string;
+    /** 描述 */
+    description: string;
+    /** 分类 */
+    category: string;
+    /** 预览 HTML */
+    previewHtml?: string;
+}
+/** 化学元素详细信息 */
+interface ElementInfo {
+    /** 元素符号 */
+    symbol: string;
+    /** 元素名称 */
+    name: string;
+    /** 原子序数 */
+    atomicNumber: number;
+    /** 相对原子质量 */
+    atomicMass: number;
+    /** 族 */
+    group: number;
+    /** 周期 */
+    period: number;
+    /** 区块 */
+    block: 's' | 'p' | 'd' | 'f';
+    /** 电负性 */
+    electronegativity?: number;
+    /** 常见氧化态 */
+    oxidationStates?: number[];
+    /** 常见化合物 */
+    commonCompounds?: string[];
+}
+/** 知识库查询结果 */
+interface KBQueryResult {
+    /** 匹配的符号 */
+    symbols: SymbolInfo[];
+    /** 匹配的公式模板 */
+    formulas: FormulaTemplate[];
+    /** 匹配的元素 */
+    elements: ElementInfo[];
+    /** 原始 AI 响应（可选，用于调试） */
+    rawResponse?: string;
+}
+/**
+ * 知识库提供者接口（SPI）
+ *
+ * 使用方实现此接口，将自己的知识库/向量数据库注入引擎
+ */
+interface IKnowledgeBaseProvider {
+    readonly id: string;
+    readonly name: string;
+    /**
+     * 通用知识查询
+     */
+    query(params: KBQueryParams): Promise<KBQueryResult>;
+    /**
+     * 按符号搜索
+     */
+    searchSymbols(query: string, limit?: number): Promise<SymbolInfo[]>;
+    /**
+     * 按公式名搜索
+     */
+    searchFormulas(query: string, limit?: number): Promise<FormulaTemplate[]>;
+    /**
+     * 获取元素详细信息
+     */
+    getElementInfo(symbol: string): Promise<ElementInfo | null>;
+    /**
+     * 语义检索（可选，基于向量相似度）
+     * "跟水相关的化合物" → 语义匹配
+     */
+    semanticSearch?(query: string, limit?: number): Promise<KBQueryResult>;
+    /**
+     * 批量获取元素信息（可选）
+     */
+    getElementsBatch?(symbols: string[]): Promise<Map<string, ElementInfo>>;
+}
+
+/** 规范化修改记录 */
+interface NormalizationChange {
+    /** 修改类型 */
+    type: 'delimiter-fix' | 'command-fix' | 'unicode-convert' | 'format-unify' | 'chemical-fix';
+    /** 修改前 */
+    from: string;
+    /** 修改后 */
+    to: string;
+    /** 修改原因 */
+    reason: string;
+}
+/** 规范化结果 */
+interface NormalizedResult {
+    /** 规范化后的表达式文本 */
+    normalized: string;
+    /** 原始输入 */
+    original: string;
+    /** 置信度 0-1 */
+    confidence: number;
+    /** 所做的修改列表 */
+    changes: NormalizationChange[];
+    /** 规范化后的 AST */
+    ast: ExpressionRoot;
+}
+/**
+ * AI 规范化提供者接口（SPI）
+ *
+ * 用于统一不同 LLM 输出的格式差异：
+ * - ChatGPT 输出: $$H_2O$$
+ * - Claude 输出: \(H_2O\)
+ * - Gemini 输出: H₂O (Unicode)
+ * - 某模型输出: \ce{H2O}
+ *
+ * 引擎通过此接口将以上所有格式统一为标准格式
+ */
+interface IAINormalizerProvider {
+    readonly id: string;
+    readonly name: string;
+    /**
+     * 规范化 AI 输出
+     * @param input 原始 AI 输出
+     * @param targetFormat 目标格式
+     */
+    normalize(input: string, targetFormat: 'latex' | 'unicode' | 'chemical' | 'auto'): Promise<NormalizedResult>;
+    /**
+     * 自动检测并修复
+     */
+    detectAndFix(input: string): Promise<NormalizedResult>;
+    /**
+     * 批量规范化（可选）
+     */
+    normalizeBatch?(inputs: string[], targetFormat: 'latex' | 'unicode' | 'chemical'): Promise<NormalizedResult[]>;
+}
+
+/** 格式化风格 */
+interface FormatStyle {
+    /** 目标输出格式 */
+    outputFormat: 'latex' | 'unicode' | 'mathml';
+    /** 领域约定 */
+    domain?: 'physics' | 'chemistry' | 'mathematics' | 'biology' | 'general';
+    /** 是否使用 ISO 标准符号 */
+    isoStandard?: boolean;
+    /** 分数显示偏好 */
+    fractionStyle?: 'frac' | 'tfrac' | 'dfrac' | 'inline';
+    /** 自定义规则 */
+    customRules?: FormatRule[];
+}
+/** 格式化规则 */
+interface FormatRule {
+    id: string;
+    description: string;
+    /** 匹配条件 */
+    match: (node: ExpressionNode) => boolean;
+    /** 转换规则 */
+    apply: (node: ExpressionNode) => ExpressionNode;
+}
+/** 格式化建议 */
+interface FormatSuggestion {
+    description: string;
+    /** 修改前的 LaTeX */
+    before: string;
+    /** 修改后的 LaTeX */
+    after: string;
+    reason: string;
+    confidence: number;
+}
+/**
+ * AI 格式化提供者接口（SPI）
+ *
+ * 使用 AI 将表达式优化为特定领域的规范格式
+ */
+interface IAIFormatterProvider {
+    readonly id: string;
+    readonly name: string;
+    /**
+     * 格式化 AST
+     * @param ast 待格式化 AST
+     * @param style 目标风格
+     */
+    format(ast: ExpressionRoot, style: FormatStyle): Promise<ExpressionRoot>;
+    /**
+     * 格式建议（可选，不直接修改，返回建议列表）
+     */
+    suggest?(ast: ExpressionRoot, style: FormatStyle): Promise<FormatSuggestion[]>;
+}
+
+/** AI 缓存配置 */
+interface AICacheConfig {
+    enabled: boolean;
+    ttlMs: number;
+    maxSize: number;
+}
+/** AI 管线配置 */
+interface AIPipelineConfig {
+    completionProvider?: IAICompletionProvider;
+    knowledgeBaseProvider?: IKnowledgeBaseProvider;
+    normalizerProvider?: IAINormalizerProvider;
+    formatterProvider?: IAIFormatterProvider;
+    aiEnabled?: boolean;
+    completionDebounceMs?: number;
+    maxCompletions?: number;
+    cache?: AICacheConfig;
+}
+/**
+ * AI 管线
+ *
+ * 统一编排所有 AI Provider，处理回退逻辑和缓存。
+ * 默认使用内置回退实现（离线可用），外部 Provider 作为增强。
+ */
+declare class AIPipeline {
+    private completionProvider;
+    private knowledgeBaseProvider;
+    private normalizerProvider;
+    private formatterProvider;
+    private aiEnabled;
+    private maxCompletions;
+    private cache;
+    private completionCache;
+    private kbCache;
+    private eventListeners;
+    constructor(config?: AIPipelineConfig);
+    /**
+     * 获取智能补全（本地 + AI 混合）
+     */
+    getCompletions(context: CompletionContext): Promise<CompletionResult>;
+    /**
+     * 查询知识库
+     */
+    queryKnowledge(params: KBQueryParams): Promise<KBQueryResult>;
+    /**
+     * 规范化 AI 输出
+     */
+    normalize(input: string, format?: 'latex' | 'unicode' | 'chemical' | 'auto'): Promise<NormalizedResult>;
+    /**
+     * 格式化表达式
+     */
+    format(ast: ExpressionRoot, style?: Partial<FormatStyle>): Promise<ExpressionRoot>;
+    /**
+     * 自然语言 → 公式
+     */
+    naturalLanguageToFormula(query: string): Promise<CompletionItem[]>;
+    /**
+     * AI 纠错
+     */
+    correct(input: string, error: ValidationError): Promise<CompletionItem[]>;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    getCacheStats(): {
+        hits: number;
+        misses: number;
+        completionSize: number;
+        kbSize: number;
+    };
+    clearCache(): void;
+    on(event: string, callback: (...args: any[]) => void): void;
+    off(event: string, callback: (...args: any[]) => void): void;
+    private emit;
+    private getCached;
+    private setCache;
+}
+
+/** Prompt 模板定义 */
+interface PromptTemplate {
+    /** 模板名称 */
+    name: string;
+    /** System prompt 模板 */
+    system: string;
+    /** User message 模板 */
+    user: string;
+    /** 模板变量列表 */
+    variables: string[];
+}
+/** 内置 Prompt 模板 */
+declare const BUILTIN_PROMPTS: Record<string, PromptTemplate>;
+/**
+ * Prompt 注册表（支持自定义模板覆盖）
+ */
+declare class PromptRegistry {
+    private templates;
+    constructor();
+    /**
+     * 注册自定义 Prompt 模板（可覆盖内置）
+     */
+    register(template: PromptTemplate): void;
+    /**
+     * 获取模板
+     */
+    get(name: string): PromptTemplate | undefined;
+    /**
+     * 渲染模板为 system + user 消息
+     */
+    render(name: string, variables: Record<string, string>): {
+        system: string;
+        user: string;
+    } | null;
+    /**
+     * 获取所有已注册模板名称
+     */
+    list(): string[];
+    /**
+     * 移除自定义模板（不能移除内置模板）
+     */
+    remove(name: string): boolean;
+}
+
+/** 流数据源类型 */
+type StreamSource = {
+    type: 'sse';
+    url: string;
+} | {
+    type: 'websocket';
+    url: string;
+} | {
+    type: 'async-iterator';
+    iterator: AsyncIterable<string>;
+} | {
+    type: 'callback';
+    onRead: (callback: (chunk: string) => void) => void;
+};
+/**
+ * 流式 AI 响应适配器
+ * 支持 SSE / WebSocket / AsyncIterator
+ */
+interface IAIStreamAdapter {
+    /** 连接流式源 */
+    connect(source: StreamSource): Promise<void>;
+    /** 监听增量 token */
+    onToken(callback: (token: CompletionItem) => void): void;
+    /** 监听完成 */
+    onComplete(callback: (result: CompletionResult) => void): void;
+    /** 监听错误 */
+    onError(callback: (error: Error) => void): void;
+    /** 取消连接 */
+    abort(): void;
+}
+
+declare class BuiltinCompletionProvider implements IAICompletionProvider {
+    readonly id = "builtin-completion";
+    readonly name = "Built-in Symbol Completion";
+    complete(context: CompletionContext): Promise<CompletionResult>;
+}
+declare class BuiltinKnowledgeBase implements IKnowledgeBaseProvider {
+    readonly id = "builtin-kb";
+    readonly name = "Built-in Knowledge Base";
+    query(params: KBQueryParams): Promise<KBQueryResult>;
+    searchSymbols(query: string, limit?: number): Promise<SymbolInfo[]>;
+    searchFormulas(query: string, limit?: number): Promise<FormulaTemplate[]>;
+    getElementInfo(symbol: string): Promise<ElementInfo | null>;
+}
+declare class BuiltinNormalizer implements IAINormalizerProvider {
+    readonly id = "builtin-normalizer";
+    readonly name = "Built-in Regex Normalizer";
+    normalize(input: string, targetFormat: 'latex' | 'unicode' | 'chemical' | 'auto'): Promise<NormalizedResult>;
+    detectAndFix(input: string): Promise<NormalizedResult>;
+}
+declare class BuiltinFormatter implements IAIFormatterProvider {
+    readonly id = "builtin-formatter";
+    readonly name = "Built-in Rule Formatter";
+    format(ast: ExpressionRoot, _style: FormatStyle): Promise<ExpressionRoot>;
+}
+
+export { type AICacheConfig, AIPipeline, type AIPipelineConfig, BUILTIN_PROMPTS, BuiltinCompletionProvider, BuiltinFormatter, BuiltinKnowledgeBase, BuiltinNormalizer, type CompletionContext, type CompletionItem, type CompletionResult, type ElementInfo, type FormatRule, type FormatStyle, type FormatSuggestion, type FormulaTemplate, type IAICompletionProvider, type IAIFormatterProvider, type IAINormalizerProvider, type IAIStreamAdapter, type IKnowledgeBaseProvider, type KBQueryParams, type KBQueryResult, type NormalizationChange, type NormalizedResult, PromptRegistry, type PromptTemplate, type StreamSource, type SymbolInfo };