@docscode/core 1.0.0

package/src/cli/index.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+
+const program = new Command();
+
+program
+  .name('kairo')
+  .description('CLI to scaffold Kairo AI plugins and integrations')
+  .version('1.0.0');
+
+program
+  .command('create-plugin')
+  .description('Scaffold a new Kairo plugin')
+  .argument('<name>', 'Name of the plugin')
+  .action((name) => {
+    const className = name.charAt(0).toUpperCase() + name.slice(1) + 'Plugin';
+    const fileName = `${className}.ts`;
+    const targetPath = path.join(process.cwd(), fileName);
+
+    const template = `import { KairoPlugin, AICollaborator } from 'kairo';
+
+export class ${className} extends KairoPlugin {
+  constructor(ai: AICollaborator) {
+    super(ai);
+  }
+
+  public setup() {
+    console.log('[Kairo] ${className} initialized');
+    // Hook into Yjs document updates here
+  }
+
+  public destroy() {
+    // Cleanup resources
+  }
+}
+`;
+
+    fs.writeFileSync(targetPath, template);
+    console.log(chalk.green(`\n✔ Created ${className} at ${targetPath}`));
+    console.log(chalk.cyan(`\nNext steps:`));
+    console.log(`1. Implement your logic in setup()`);
+    console.log(`2. Register it: ai.registerPlugin(new ${className}(ai));\n`);
+  });
+
+program.parse();

package/src/docling-client.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const getDirname = () => {
+  if (typeof __dirname !== 'undefined') return __dirname;
+  return path.dirname(fileURLToPath((import.meta as any).url));
+};
+const _dirname = getDirname();
+const BRIDGE_PATH = path.join(_dirname, '../scripts/docling_bridge.py');
+
+export class DoclingClient {
+  async convert(filePathOrBase64: string): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const pythonProcess = spawn('python', [BRIDGE_PATH, filePathOrBase64]);
+      
+      let output = '';
+      let error = '';
+
+      pythonProcess.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+
+      pythonProcess.stderr.on('data', (data) => {
+        error += data.toString();
+      });
+
+      pythonProcess.on('close', (code) => {
+        if (code !== 0) {
+          reject(new Error(`Python process exited with code ${code}: ${error}`));
+          return;
+        }
+
+        try {
+          const result = JSON.parse(output);
+          if (result.error) {
+            reject(new Error(result.error));
+          } else {
+            resolve(result);
+          }
+        } catch (e) {
+          reject(new Error(`Failed to parse Python output: ${output}`));
+        }
+      });
+    });
+  }
+}

package/src/editors/MonacoAdapter.ts

@@ -0,0 +1,22 @@
+import { AICollaborator } from '../AICollaborator.js';
+
+export class MonacoAdapter {
+  constructor(
+    private editor: any, // monaco.editor.IStandaloneCodeEditor
+    private ai: AICollaborator,
+    private fieldName: string = 'content'
+  ) {
+    // Monaco doesn't have a direct "plugin" system for awareness cursors
+    // in the same way Tiptap does out-of-the-box, but we can hook into
+    // y-monaco if the user is using it.
+    // For Kairo, the AICollaborator already handles Yjs awareness.
+    // This adapter simply provides a convenient wrapper.
+  }
+
+  public static bind(editor: any, ai: AICollaborator, fieldName: string = 'content'): MonacoAdapter {
+    return new MonacoAdapter(editor, ai, fieldName);
+  }
+
+  // Monaco-specific UI bindings can be added here, such as custom decorations
+  // for AI-generated text or inline ghost text suggestions.
+}

package/src/editors/ProseMirrorAdapter.ts

@@ -0,0 +1,17 @@
+import { AICollaborator } from '../AICollaborator.js';
+
+export class ProseMirrorAdapter {
+  constructor(
+    private view: any, // EditorView
+    private ai: AICollaborator,
+    private fieldName: string = 'content'
+  ) {
+    // ProseMirror integration. The AICollaborator syncs via Yjs.
+    // This adapter can be extended to add ProseMirror decorations
+    // for AI text highlighting or suggestion overlays.
+  }
+
+  public static bind(view: any, ai: AICollaborator, fieldName: string = 'content'): ProseMirrorAdapter {
+    return new ProseMirrorAdapter(view, ai, fieldName);
+  }
+}

package/src/editors/QuillAdapter.ts

@@ -0,0 +1,27 @@
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
+import { AICollaborator } from '../AICollaborator.js';
+import { AutocompletePlugin } from '../AutocompletePlugin.js';
+import { SummarizationPlugin } from '../SummarizationPlugin.js';
+import { LLMAdapter } from '../LLMAdapter.js';
+
+/**
+ * High-level adapter for Quill editors using y-quill.
+ */
+export class QuillAdapter {
+  /**
+   * Bind Kairo to a Quill instance. 
+   * Since y-quill binding is external, we need the doc and awareness explicitly.
+   */
+  public static bind(doc: Y.Doc, awareness: Awareness, adapter: LLMAdapter, options: { field?: string } = {}) {
+    const { field = 'content' } = options;
+    
+    const kairo = new AICollaborator(doc, awareness);
+    kairo.registerPlugin(new AutocompletePlugin(kairo, adapter, field));
+    kairo.registerPlugin(new SummarizationPlugin(kairo, adapter, field));
+
+    console.log('[Kairo] QuillAdapter bound successfully.');
+    
+    return kairo;
+  }
+}

package/src/editors/TiptapAdapter.ts

@@ -0,0 +1,50 @@
+import { Editor } from '@tiptap/core';
+import { AICollaborator } from '../AICollaborator.js';
+import { AutocompletePlugin } from '../AutocompletePlugin.js';
+import { SummarizationPlugin } from '../SummarizationPlugin.js';
+import { LLMAdapter } from '../LLMAdapter.js';
+
+export interface TiptapAdapterOptions {
+  field?: string;
+  plugins?: ('autocomplete' | 'summarize')[];
+}
+
+/**
+ * High-level adapter to bind Kairo to a Tiptap editor instance.
+ */
+export class TiptapAdapter {
+  public static bind(editor: Editor, adapter: LLMAdapter, options: TiptapAdapterOptions = {}) {
+    const { field = 'content', plugins = ['autocomplete', 'summarize'] } = options;
+    
+    // 1. Get the underlying Yjs doc from Tiptap's collaboration extension
+    // Note: This assumes the user is using the @tiptap/extension-collaboration
+    const collaborationExtension = editor.extensionManager.extensions.find((e: any) => e.name === 'collaboration');
+    
+    if (!collaborationExtension) {
+      throw new Error('[Kairo] TiptapAdapter requires @tiptap/extension-collaboration to be active.');
+    }
+
+    const doc = collaborationExtension.options.document;
+    const awareness = collaborationExtension.options.awareness;
+
+    if (!doc || !awareness) {
+      throw new Error('[Kairo] Could not find Yjs Document or Awareness in Tiptap editor.');
+    }
+
+    // 2. Initialize AICollaborator
+    const kairo = new AICollaborator(doc, awareness);
+
+    // 3. Register requested plugins
+    if (plugins.includes('autocomplete')) {
+      kairo.registerPlugin(new AutocompletePlugin(kairo, adapter, field));
+    }
+    
+    if (plugins.includes('summarize')) {
+      kairo.registerPlugin(new SummarizationPlugin(kairo, adapter, field));
+    }
+
+    console.log('[Kairo] TiptapAdapter bound successfully.');
+    
+    return kairo;
+  }
+}

package/src/format-adapter.ts

@@ -0,0 +1,25 @@
+import * as Y from 'yjs';
+
+export interface Suggestion {
+  id: string;
+  type: 'insert' | 'delete' | 'replace';
+  from: number;
+  to?: number;
+  text?: string;
+  author: string;
+  timestamp: number;
+}
+
+export 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>;
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// ─── Core DCAL Engine ──────────────────────────────────────────────────────────
+export { Kairo, KairoSession, kairo } from './kairo.js';
+export type { KairoConnectOptions } from './kairo.js';
+
+// ─── AI Collaborator Peer ─────────────────────────────────────────────────────
+export { AICollaborator } from './AICollaborator.js';
+export type { KairoStatus, KairoMetadata, AICollaboratorOptions } from './AICollaborator.js';
+
+// ─── LLM Adapters (zero SDK, raw fetch) ───────────────────────────────────────
+export type { LLMAdapter, StreamOptions, CompleteOptions } from './LLMAdapter.js';
+export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+export { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
+export { OllamaAdapter } from './adapters/OllamaAdapter.js';
+export { GeminiAdapter } from './adapters/GeminiAdapter.js';
+export { MockLLMAdapter } from './MockLLMAdapter.js';
+
+// ─── CRDT Model ───────────────────────────────────────────────────────────────
+export { CanonicalDoc } from './canonical-model.js';
+export type { BlockType, CanonicalBlockMeta } from './canonical-model.js';
+
+// ─── Format Adapter Interface ─────────────────────────────────────────────────
+export type { FormatAdapter } from './format-adapter.js';
+
+// ─── Plugins ──────────────────────────────────────────────────────────────────
+export type { KairoPlugin } from './KairoPlugin.js';
+export { AutocompletePlugin } from './AutocompletePlugin.js';
+export { SummarizationPlugin } from './SummarizationPlugin.js';
+
+// ─── Infrastructure ───────────────────────────────────────────────────────────
+export { StreamBuffer } from './StreamBuffer.js';
+export { PromptCache } from './PromptCache.js';
+export { ConflictResolver, MergePolicy } from './ConflictResolver.js';
+export { SuggestionManager } from './suggestion-manager.js';
+export type { Suggestion } from './suggestion-manager.js';
+
+// ─── Document Intelligence ────────────────────────────────────────────────────
+export { DoclingClient } from './docling-client.js';

package/src/kairo.ts

@@ -0,0 +1,151 @@
+import * as Y from 'yjs';
+import { AICollaborator } from './AICollaborator.js';
+import type { FormatAdapter } from './format-adapter.js';
+import type { LLMAdapter } from './LLMAdapter.js';
+import { AutocompletePlugin } from './AutocompletePlugin.js';
+import { SummarizationPlugin } from './SummarizationPlugin.js';
+import { ConflictResolver } from './ConflictResolver.js';
+import { Awareness } from 'y-protocols/awareness';
+
+export 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.
+ */
+export class KairoSession {
+  public readonly ai: AICollaborator;
+  public readonly conflictResolver?: ConflictResolver;
+  private readonly _adapter?: FormatAdapter;
+
+  constructor(
+    public readonly doc: Y.Doc,
+    ai: AICollaborator,
+    adapter?: FormatAdapter,
+    conflictResolver?: ConflictResolver,
+  ) {
+    this.ai = ai;
+    this._adapter = adapter;
+    this.conflictResolver = conflictResolver;
+  }
+
+  /** Export the document back to its original format */
+  async export(): Promise<Buffer> {
+    if (!this._adapter) throw new Error('[Kairo] No format adapter — cannot export.');
+    return this._adapter.write(this.doc);
+  }
+
+  /** Get the plain text content of the document */
+  getText(key: string = 'content'): string {
+    return this.doc.getText(key).toString();
+  }
+
+  /** Get word count */
+  wordCount(): number {
+    return this.getText().split(/\s+/).filter(Boolean).length;
+  }
+
+  /** Destroy the session and free resources */
+  destroy() {
+    this.ai.destroy();
+    this.doc.destroy();
+  }
+}
+
+/**
+ * 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();
+ */
+export class Kairo {
+  private formatAdapters: Map<string, FormatAdapter> = new Map();
+
+  /** Register a format adapter (DOCX, PDF, MD, HTML, GDoc, etc.) */
+  registerFormatAdapter(adapter: FormatAdapter): this {
+    this.formatAdapters.set(adapter.format, adapter);
+    return this; // chainable
+  }
+
+  /** Connect to a document and start an AI session */
+  async connect(options: KairoConnectOptions): Promise<KairoSession> {
+    const format = options.format ?? this._detectFormat(options.fileName ?? '');
+    const adapter = options.adapter ?? this.formatAdapters.get(format);
+
+    let doc: Y.Doc;
+
+    if (adapter) {
+      doc = await adapter.read(options.content);
+    } else {
+      // Fallback: treat as plain text
+      doc = new Y.Doc();
+      const text = typeof options.content === 'string' ? options.content : options.content.toString('utf-8');
+      doc.getText('content').insert(0, text);
+    }
+
+    const awareness = new Awareness(doc);
+    const ai = new AICollaborator(doc, awareness, {
+      llm: options.llm,
+      clientID: options.clientId,
+      streamFlushMs: options.streamFlushMs,
+    });
+
+    // Register behaviors
+    const behaviors = options.behaviors ?? ['autocomplete', 'summarize'];
+    if (options.llm) {
+      if (behaviors.includes('autocomplete')) ai.registerPlugin(new AutocompletePlugin(ai, options.llm));
+      if (behaviors.includes('summarize')) ai.registerPlugin(new SummarizationPlugin(ai, options.llm));
+    }
+
+    // Conflict resolver
+    let conflictResolver: ConflictResolver | undefined;
+    if (options.conflictResolution !== false) {
+      conflictResolver = new ConflictResolver(doc, [ai.clientID]);
+    }
+
+    return new KairoSession(doc, ai, adapter, conflictResolver);
+  }
+
+  /** Open multiple documents concurrently */
+  async connectAll(configs: KairoConnectOptions[]): Promise<KairoSession[]> {
+    return Promise.all(configs.map(c => this.connect(c)));
+  }
+
+  private _detectFormat(file: Buffer | string): string {
+    if (typeof file !== 'string') return 'txt';
+    const ext = file.split('.').pop()?.toLowerCase() ?? '';
+    const map: Record<string, string> = {
+      docx: 'docx', pdf: 'pdf', md: 'markdown', markdown: 'markdown',
+      html: 'html', htm: 'html', txt: 'txt',
+    };
+    return map[ext] ?? 'txt';
+  }
+}
+
+/** Singleton Kairo instance for quick use */
+export const kairo = new Kairo();

package/src/suggestion-manager.ts

@@ -0,0 +1,39 @@
+import * as Y from 'yjs';
+import { Suggestion } from './format-adapter.js';
+export type { Suggestion } from './format-adapter.js';
+
+export class SuggestionManager {
+  private suggestions: Y.Map<any>;
+
+  constructor(public readonly doc: Y.Doc) {
+    this.suggestions = doc.getMap('kairo-suggestions');
+  }
+
+  addSuggestion(suggestion: Omit<Suggestion, 'id' | 'timestamp'>): string {
+    const id = Math.random().toString(36).substring(7);
+    const fullSuggestion: Suggestion = {
+      ...suggestion,
+      id,
+      timestamp: Date.now()
+    };
+    
+    this.suggestions.set(id, fullSuggestion);
+    return id;
+  }
+
+  getSuggestions(): Suggestion[] {
+    return Array.from(this.suggestions.values()) as Suggestion[];
+  }
+
+  resolveSuggestion(id: string, accept: boolean) {
+    const suggestion = this.suggestions.get(id) as Suggestion;
+    if (!suggestion) return;
+
+    if (accept) {
+      // Apply the edit to the actual document content
+      // This logic depends on the specific format/block
+    }
+
+    this.suggestions.delete(id);
+  }
+}