@docscode/core 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,517 @@
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
+
+declare abstract class KairoPlugin {
+    protected ai: AICollaborator;
+    enabled: boolean;
+    constructor(ai: AICollaborator);
+    /**
+     * Called when the plugin is registered with the AICollaborator
+     */
+    abstract setup(): void;
+    /**
+     * Called to cleanup the plugin
+     */
+    abstract destroy(): void;
+    /**
+     * Enable/Disable the plugin
+     */
+    setEnabled(enabled: boolean): void;
+}
+
+/**
+ * PromptCache — LRU cache for LLM prompts.
+ *
+ * Prevents re-querying the LLM for identical prompts within a session.
+ * Critical for summarization and autocomplete performance.
+ *
+ * Uses a Map-based LRU: entries at the front are most recent,
+ * entries at the back are evicted first.
+ */
+declare class PromptCache {
+    private cache;
+    private readonly maxSize;
+    private totalHits;
+    private totalMisses;
+    constructor(maxSize?: number);
+    /** Retrieve cached result for a prompt. Returns null on miss. */
+    get(prompt: string): string | null;
+    /** Cache a result for a prompt. Evicts LRU entry if at capacity. */
+    set(prompt: string, value: string): void;
+    /** Check if a prompt is cached without counting as a hit */
+    has(prompt: string): boolean;
+    /** Remove a specific entry */
+    invalidate(prompt: string): void;
+    /** Clear all entries */
+    clear(): void;
+    /** Cache statistics */
+    stats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+        totalHits: number;
+        totalMisses: number;
+    };
+}
+
+interface StreamOptions {
+    systemPrompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+}
+interface CompleteOptions extends StreamOptions {
+}
+/**
+ * LLMAdapter — Kairo's universal LLM interface.
+ * Implement this to plug any model into the CRDT streaming pipeline.
+ * Zero SDK dependency by design — uses raw fetch for SSE streaming.
+ */
+interface LLMAdapter {
+    readonly provider: string;
+    readonly model: string;
+    /**
+     * Stream tokens one-by-one as an async generator.
+     * This feeds directly into StreamBuffer → Y.Text CRDT operations.
+     */
+    stream(prompt: string, options?: StreamOptions): AsyncGenerator<string>;
+    /** Non-streaming fallback for summarization / one-shot tasks */
+    complete(prompt: string, options?: CompleteOptions): Promise<string>;
+    /** Optional: embed text for semantic search / context retrieval */
+    embed?(text: string): Promise<number[]>;
+}
+
+interface Suggestion {
+    id: string;
+    type: 'insert' | 'delete' | 'replace';
+    from: number;
+    to?: number;
+    text?: string;
+    author: string;
+    timestamp: number;
+}
+interface FormatAdapter {
+    /** Supported format identifier */
+    readonly format: 'docx' | 'pdf' | 'gdoc' | 'markdown' | 'html' | 'txt' | string;
+    /** Parse a file/buffer into a Y.Doc */
+    read(source: Buffer | string): Promise<Y.Doc>;
+    /** Serialize a Y.Doc back to the native format */
+    write(doc: Y.Doc, original?: Buffer): Promise<Buffer>;
+    /** Map AI suggestions to format-native tracked changes */
+    applyTrackedChanges?(doc: Y.Doc, suggestions: Suggestion[]): Promise<Buffer>;
+}
+
+declare class SuggestionManager {
+    readonly doc: Y.Doc;
+    private suggestions;
+    constructor(doc: Y.Doc);
+    addSuggestion(suggestion: Omit<Suggestion, 'id' | 'timestamp'>): string;
+    getSuggestions(): Suggestion[];
+    resolveSuggestion(id: string, accept: boolean): void;
+}
+
+type KairoStatus = 'idle' | 'thinking' | 'writing' | 'reviewing';
+interface KairoMetadata {
+    name: string;
+    version: string;
+    capabilities: string[];
+    model?: string;
+}
+interface AICollaboratorOptions {
+    clientID?: number;
+    cacheSize?: number;
+    llm?: LLMAdapter;
+    streamFlushMs?: number;
+}
+/**
+ * AICollaborator — The AI peer inside your Yjs document.
+ *
+ * Appears as a real-time participant in the awareness protocol.
+ * Streams LLM tokens directly into Y.Text CRDT operations.
+ * Human peers see a live cursor and status indicator — just like a human collaborator.
+ */
+declare class AICollaborator {
+    readonly doc: Y.Doc;
+    readonly awareness: Awareness;
+    readonly clientID: number;
+    readonly suggestions: SuggestionManager;
+    readonly cache: PromptCache;
+    private _status;
+    private _plugins;
+    private _llm?;
+    private _streamFlushMs;
+    constructor(doc: Y.Doc, awareness: Awareness, options?: AICollaboratorOptions);
+    setStatus(status: KairoStatus): void;
+    setThinking(): void;
+    setWriting(): void;
+    setReviewing(): void;
+    setIdle(): void;
+    private _updateAwareness;
+    registerPlugin(plugin: KairoPlugin): void;
+    /**
+     * Insert text with AI attribution markers.
+     * Consuming editors can style/filter AI-generated content using these markers.
+     */
+    insertWithAttribution(text: Y.Text, index: number, content: string): void;
+    /**
+     * Stream LLM tokens directly into the document as CRDT operations.
+     *
+     * Modes:
+     * - 'insert': appends after current position
+     * - 'continue': appends to end of document
+     * - 'rewrite': clears existing text and rewrites
+     *
+     * Token cadence: tokens are batched with a 50ms flush interval for
+     * smooth real-time rendering without CRDT overload.
+     */
+    streamToDoc(yText: Y.Text, prompt: string, options?: {
+        systemPrompt?: string;
+        mode?: 'insert' | 'continue' | 'rewrite';
+        insertAt?: number;
+        signal?: AbortSignal;
+        onToken?: (token: string) => void;
+    }): Promise<{
+        tokensWritten: number;
+        durationMs: number;
+    }>;
+    /**
+     * One-shot: summarize a block of text and return the result (no streaming).
+     */
+    summarize(text: string, options?: {
+        maxTokens?: number;
+    }): Promise<string>;
+    destroy(): void;
+}
+
+/**
+ * ConflictResolver — Human-precedence CRDT conflict resolution for Kairo.
+ *
+ * Strategy:
+ * 1. Human edits always win over AI edits in the same position.
+ * 2. AI edits made within 500ms of a human edit at the same offset are rolled back.
+ * 3. Attribution is preserved — every merged character knows who wrote it.
+ *
+ * This is surfaced as a Y.Doc observer that monitors for concurrent human+AI
+ * writes and reorders them deterministically.
+ */
+interface ConflictEvent {
+    type: 'human_overrides_ai' | 'ai_deferred' | 'concurrent_edit';
+    position: number;
+    humanClientId: number;
+    aiClientId: number;
+    timestamp: number;
+}
+type ConflictHandler = (event: ConflictEvent) => void;
+declare class ConflictResolver {
+    private doc;
+    private conflictLog;
+    private handlers;
+    private aiClientIds;
+    constructor(doc: Y.Doc, aiClientIds?: number[]);
+    /** Register a client ID as an AI participant */
+    registerAI(clientId: number): void;
+    /** Listen for conflict events */
+    onConflict(handler: ConflictHandler): void;
+    /** Get the conflict log */
+    getLog(): ConflictEvent[];
+    /** Clear the conflict log */
+    clearLog(): void;
+    private _observe;
+    private _emit;
+}
+/**
+ * MergePolicy — Determines how concurrent AI and human edits are resolved.
+ *
+ * Kairo uses "human-precedence linear merge":
+ * - Human text is always displayed first at the same logical position
+ * - AI suggestions appear as tracked changes until accepted
+ * - This matches the mental model of track-changes in Word/Google Docs
+ */
+declare class MergePolicy {
+    static readonly HUMAN_WINS = "human_wins";
+    static readonly LAST_WRITE_WINS = "last_write_wins";
+    static readonly AI_WINS = "ai_wins";
+    static isAIGenerated(attrs: Record<string, any> | null | undefined): boolean;
+    static getAuthor(attrs: Record<string, any> | null | undefined): 'ai' | 'human';
+}
+
+interface KairoConnectOptions {
+    /** Document content */
+    content: Buffer | string;
+    /** Document format. Auto-detected from fileName if omitted. */
+    format?: 'docx' | 'pdf' | 'gdoc' | 'markdown' | 'html' | 'txt' | string;
+    /** Optional file name for format auto-detection */
+    fileName?: string;
+    /** LLM adapter. Required for AI features. */
+    llm?: LLMAdapter;
+    /** Behaviors to activate. Default: all registered. */
+    behaviors?: ('autocomplete' | 'summarize')[];
+    /** Format adapter override. If omitted, uses registered adapter for format. */
+    adapter?: FormatAdapter;
+    /** Custom AI client ID. Auto-generated if omitted. */
+    clientId?: number;
+    /** Flush interval for streaming to CRDT in ms. Default: 50ms. */
+    streamFlushMs?: number;
+    /** Enable conflict resolution observer. Default: true. */
+    conflictResolution?: boolean;
+}
+/**
+ * KairoSession — A live, AI-collaborative document session.
+ *
+ * The session holds the Yjs document, the AI collaborator peer,
+ * the conflict resolver, and the format adapter for write-back.
+ *
+ * Treat this like a live Google Docs tab — it's a real-time shared artifact.
+ */
+declare class KairoSession {
+    readonly doc: Y.Doc;
+    readonly ai: AICollaborator;
+    readonly conflictResolver?: ConflictResolver;
+    private readonly _adapter?;
+    constructor(doc: Y.Doc, ai: AICollaborator, adapter?: FormatAdapter, conflictResolver?: ConflictResolver);
+    /** Export the document back to its original format */
+    export(): Promise<Buffer>;
+    /** Get the plain text content of the document */
+    getText(key?: string): string;
+    /** Get word count */
+    wordCount(): number;
+    /** Destroy the session and free resources */
+    destroy(): void;
+}
+/**
+ * Kairo — The Document CRDT Abstraction Layer (DCAL) entry point.
+ *
+ * One-line AI collaboration for any document:
+ *   const session = await kairo.connect({ file: 'report.docx', llm: new OpenAIAdapter() });
+ *   await session.ai.streamToDoc(yText, 'Improve the executive summary');
+ *   const output = await session.export();
+ */
+declare class Kairo {
+    private formatAdapters;
+    /** Register a format adapter (DOCX, PDF, MD, HTML, GDoc, etc.) */
+    registerFormatAdapter(adapter: FormatAdapter): this;
+    /** Connect to a document and start an AI session */
+    connect(options: KairoConnectOptions): Promise<KairoSession>;
+    /** Open multiple documents concurrently */
+    connectAll(configs: KairoConnectOptions[]): Promise<KairoSession[]>;
+    private _detectFormat;
+}
+/** Singleton Kairo instance for quick use */
+declare const kairo: Kairo;
+
+/**
+ * OpenAIAdapter — Production streaming adapter using raw fetch (zero SDK).
+ * Works with OpenAI API and any OpenAI-compatible endpoint (Together, Groq, etc.)
+ */
+declare class OpenAIAdapter implements LLMAdapter {
+    readonly provider = "openai";
+    readonly model: string;
+    private apiKey;
+    private baseUrl;
+    constructor(options?: {
+        apiKey?: string;
+        model?: string;
+        baseUrl?: string;
+    });
+    stream(prompt: string, options?: StreamOptions): AsyncGenerator<string>;
+    complete(prompt: string, options?: StreamOptions): Promise<string>;
+    embed(text: string): Promise<number[]>;
+}
+
+/**
+ * AnthropicAdapter — Production Claude streaming via raw fetch SSE.
+ * Zero SDK dependency. Uses Messages API with streaming.
+ */
+declare class AnthropicAdapter implements LLMAdapter {
+    readonly provider = "anthropic";
+    readonly model: string;
+    private apiKey;
+    constructor(options?: {
+        apiKey?: string;
+        model?: string;
+    });
+    stream(prompt: string, options?: StreamOptions): AsyncGenerator<string>;
+    complete(prompt: string, options?: StreamOptions): Promise<string>;
+}
+
+/**
+ * OllamaAdapter — Local-first LLM streaming via Ollama REST API.
+ * No cloud. No API key. Pure local inference.
+ * Works with llama3, mistral, codellama, phi3, gemma2, qwen2.5, etc.
+ */
+declare class OllamaAdapter implements LLMAdapter {
+    readonly provider = "ollama";
+    readonly model: string;
+    private baseUrl;
+    constructor(options?: {
+        model?: string;
+        baseUrl?: string;
+    });
+    stream(prompt: string, options?: StreamOptions): AsyncGenerator<string>;
+    complete(prompt: string, options?: StreamOptions): Promise<string>;
+    /** Check if Ollama is running and model is available */
+    isAvailable(): Promise<boolean>;
+}
+
+/**
+ * GeminiAdapter — Google Gemini streaming via raw fetch SSE.
+ * Supports Gemini 2.0 Flash, Gemini 1.5 Pro/Flash.
+ * Zero SDK dependency.
+ */
+declare class GeminiAdapter implements LLMAdapter {
+    readonly provider = "gemini";
+    readonly model: string;
+    private apiKey;
+    constructor(options?: {
+        apiKey?: string;
+        model?: string;
+    });
+    stream(prompt: string, options?: StreamOptions): AsyncGenerator<string>;
+    complete(prompt: string, options?: StreamOptions): Promise<string>;
+}
+
+/**
+ * MockLLMAdapter — Test/offline LLM adapter.
+ *
+ * Returns deterministic responses without any network call.
+ * Perfect for unit tests and offline development.
+ */
+declare class MockLLMAdapter implements LLMAdapter {
+    readonly provider = "mock";
+    readonly model: string;
+    private delay;
+    constructor(options?: {
+        model?: string;
+        delay?: number;
+    });
+    stream(prompt: string, options?: StreamOptions): AsyncGenerator<string>;
+    complete(prompt: string, options?: StreamOptions): Promise<string>;
+    embed(text: string): Promise<number[]>;
+    private _respond;
+}
+
+/**
+ * Kairo Canonical Document Model — The universal CRDT schema.
+ *
+ * Every document format (DOCX, PDF, MD, HTML, GDoc) normalizes to this schema.
+ * The AI peer reads and writes exclusively via this model.
+ *
+ * Schema:
+ *   metadata: Y.Map  — title, author, format, source, lastModified, etc.
+ *   content: Y.Array — ordered array of Block Y.Maps
+ *
+ * Block structure (Y.Map):
+ *   type:  'p' | 'h1'–'h6' | 'li' | 'code' | 'table' | 'blockquote' | 'hr' | 'image'
+ *   id:    string (stable UUID for anchor references)
+ *   text:  Y.Text (the actual content, with rich attributes for formatting)
+ *   meta:  Y.Map (optional, e.g. { lang: 'typescript' } for code blocks)
+ *
+ * Text attributes (Y.Text marks):
+ *   ai-generated:  true         — marks AI-inserted ranges
+ *   ai-client-id:  number       — which AI peer inserted this
+ *   ai-timestamp:  number       — when
+ *   ai-model:      string       — which model
+ *   bold / italic / code:       — inline formatting
+ */
+type BlockType = 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'li' | 'oli' | 'code' | 'table' | 'blockquote' | 'hr' | 'image';
+interface CanonicalBlockMeta {
+    lang?: string;
+    level?: number;
+    src?: string;
+    alt?: string;
+    aiConfidence?: number;
+    [key: string]: unknown;
+}
+declare class CanonicalDoc {
+    readonly yDoc: Y.Doc;
+    constructor(yDoc: Y.Doc);
+    get metadata(): Y.Map<any>;
+    get content(): Y.Array<any>;
+    /**
+     * Add a block to the document.
+     * Returns the Y.Text of the block so callers can further instrument it.
+     */
+    addBlock(type: BlockType | string, text?: string, meta?: CanonicalBlockMeta): Y.Text;
+    /** Convenience: add a paragraph block */
+    addParagraph(text?: string): Y.Text;
+    /** Convenience: add a heading block */
+    addHeading(level: 1 | 2 | 3 | 4 | 5 | 6, text: string): Y.Text;
+    /** Set or update metadata on an existing block's Y.Text */
+    setBlockMeta(yText: Y.Text, meta: CanonicalBlockMeta): void;
+    /** Get block by index */
+    getBlock(index: number): Y.Map<any> | undefined;
+    /** Find block by id */
+    findById(id: string): Y.Map<any> | undefined;
+    /** Get all text content as plain string */
+    toPlainText(): string;
+    /** Get document stats */
+    stats(): {
+        blockCount: number;
+        charCount: number;
+        wordCount: number;
+    };
+    /** Get AI-contributed character count */
+    aiContributions(): {
+        charCount: number;
+        blockCount: number;
+    };
+}
+
+/**
+ * AutocompletePlugin — Trigger AI completions with '...' in the document.
+ * When a human types '...' at the end of any text, Kairo's AI peer takes over
+ * and streams a continuation directly into the shared document.
+ */
+declare class AutocompletePlugin extends KairoPlugin {
+    private targetTextName;
+    private adapter;
+    private _deepObserver;
+    constructor(ai: AICollaborator, adapter: LLMAdapter, targetTextName?: string);
+    setup(): void;
+    destroy(): void;
+    private _handleUpdate;
+    private _generateSuggestion;
+}
+
+/**
+ * SummarizationPlugin — Trigger document summarization with '/summarize' in the text.
+ * The AI peer generates a summary and inserts it as a blockquote below the trigger.
+ */
+declare class SummarizationPlugin extends KairoPlugin {
+    private targetTextName;
+    private adapter;
+    private _deepObserver;
+    constructor(ai: AICollaborator, adapter: LLMAdapter, targetTextName?: string);
+    setup(): void;
+    destroy(): void;
+    private _handleUpdate;
+    private _performSummarization;
+}
+
+declare class StreamBuffer {
+    private text;
+    private clientID;
+    private buffer;
+    private flushInterval;
+    private timer;
+    private currentIndex;
+    constructor(text: Y.Text, clientID: number, startIndex: number, flushInterval?: number);
+    /**
+     * Add a new token to the buffer
+     */
+    push(token: string): void;
+    /**
+     * Immediately flush the buffer to the Yjs document
+     */
+    flush(): void;
+    /**
+     * Stop any pending flushes
+     */
+    stop(): void;
+}
+
+declare class DoclingClient {
+    convert(filePathOrBase64: string): Promise<any>;
+}
+
+export { AICollaborator, type AICollaboratorOptions, AnthropicAdapter, AutocompletePlugin, type BlockType, type CanonicalBlockMeta, CanonicalDoc, type CompleteOptions, ConflictResolver, DoclingClient, type FormatAdapter, GeminiAdapter, Kairo, type KairoConnectOptions, type KairoMetadata, KairoPlugin, KairoSession, type KairoStatus, type LLMAdapter, MergePolicy, MockLLMAdapter, OllamaAdapter, OpenAIAdapter, PromptCache, StreamBuffer, type StreamOptions, type Suggestion, SuggestionManager, SummarizationPlugin, kairo };