docufresh-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vamsi Manthena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# DocuFresh-AI
+
+[![npm version](https://img.shields.io/npm/v/docufresh-ai.svg)](https://www.npmjs.com/package/docufresh-ai)
+[![license](https://img.shields.io/npm/l/docufresh-ai.svg)](https://github.com/manthenavamsi/docufresh-ai/blob/main/LICENSE)
+
+AI-powered content freshening for [docufresh](https://www.npmjs.com/package/docufresh). Keep your documents updated with real-world facts using **Wikipedia + browser-based AI**.
+
+**No API keys required!** The AI runs entirely in your browser or Node.js.
+
+## Features
+
+- **Wikipedia Integration** - Fetch current facts from Wikipedia (free, no auth)
+- **Browser-Based AI** - Uses [Transformers.js](https://huggingface.co/docs/transformers.js) to run AI locally
+- **No API Keys** - Everything runs locally, no OpenAI/Gemini keys needed
+- **Smart Rewriting** - AI rewrites sentences to incorporate fresh facts naturally
+- **Paragraph Generation** - Generate entire paragraphs about topics
+
+## Installation
+
+```bash
+npm install docufresh-ai
+```
+
+**Note:** Requires Node.js 18+ (for native fetch support).
+
+## Quick Start
+
+```javascript
+import DocuFreshAI from 'docufresh-ai';
+
+const ai = new DocuFreshAI();
+
+// First call downloads the AI model (~250MB)
+await ai.init();
+
+// Get facts from Wikipedia
+const text = 'Albert Einstein: {{ai_fact:Albert_Einstein}}';
+console.log(await ai.process(text));
+// "Albert Einstein: Albert Einstein was a German-born theoretical physicist..."
+
+// Rewrite sentences with current facts
+const text2 = '{{ai_rewrite:World_population:The world has X people}}';
+console.log(await ai.process(text2));
+// "The world has approximately 8.1 billion people"
+
+// Generate paragraphs
+const text3 = '{{ai_paragraph:SpaceX}}';
+console.log(await ai.process(text3));
+// "SpaceX is an American spacecraft manufacturer..."
+```
+
+## AI Markers
+
+| Marker | Description | Example |
+|--------|-------------|---------|
+| `{{ai_fact:topic}}` | Get Wikipedia fact | `{{ai_fact:Moon}}` |
+| `{{ai_describe:topic}}` | Short description | `{{ai_describe:Python_(programming_language)}}` |
+| `{{ai_rewrite:topic:template}}` | Rewrite with facts (X = placeholder) | `{{ai_rewrite:Bitcoin:Bitcoin is worth X}}` |
+| `{{ai_paragraph:topic}}` | Generate paragraph | `{{ai_paragraph:Climate_change}}` |
+| `{{ai_summary:topic}}` | Condensed summary | `{{ai_summary:Artificial_intelligence}}` |
+| `{{ai_answer:topic:question}}` | Answer question | `{{ai_answer:Sun:How hot is it?}}` |
+| `{{ai_link:topic}}` | Wikipedia URL | `{{ai_link:JavaScript}}` |
+| `{{ai_updated:topic}}` | Last update date | `{{ai_updated:Tesla,_Inc.}}` |
+
+## API Reference
+
+### `new DocuFreshAI(options?)`
+
+Create a new instance.
+
+```javascript
+const ai = new DocuFreshAI({
+  model: 'Xenova/flan-t5-small',  // AI model (default)
+  cacheTTL: 1000 * 60 * 60,       // Wikipedia cache: 1 hour
+  onProgress: (p) => console.log(p) // Model download progress
+});
+```
+
+### `ai.init()`
+
+Initialize the AI engine. Downloads the model on first run (~250MB).
+
+```javascript
+await ai.init();
+```
+
+### `ai.process(text, customData?)`
+
+Process text with AI markers.
+
+```javascript
+const result = await ai.process('{{ai_fact:Mars}}');
+```
+
+### `ai.processWithDocufresh(text, customData?)`
+
+Process with both AI markers and [docufresh](https://www.npmjs.com/package/docufresh) basic markers.
+
+```javascript
+// Requires: npm install docufresh
+const result = await ai.processWithDocufresh(
+  '{{current_year}}: {{ai_fact:Moon}}'
+);
+// "2026: The Moon is Earth's only natural satellite..."
+```
+
+### Direct Methods
+
+```javascript
+// Get Wikipedia fact
+const fact = await ai.getFact('JavaScript');
+
+// Get full summary
+const summary = await ai.getSummary('React_(JavaScript_library)');
+
+// Search Wikipedia
+const results = await ai.search('programming languages', 5);
+
+// Rewrite with AI
+const rewritten = await ai.rewrite(
+  'JavaScript was created in 1995',
+  'JS has been around for X years'
+);
+
+// Generate paragraph
+const paragraph = await ai.generateParagraph('Node.js', 'Runtime for JavaScript');
+```
+
+## Use Cases
+
+### Keep Blog Posts Fresh
+
+```javascript
+const blogPost = `
+# Tech Industry Update
+
+{{ai_paragraph:Artificial_intelligence}}
+
+Current AI trends show {{ai_rewrite:ChatGPT:ChatGPT has X users}}.
+
+Last updated: {{ai_updated:Artificial_intelligence}}
+`;
+
+const fresh = await ai.process(blogPost);
+```
+
+### Dynamic Documentation
+
+```javascript
+const docs = `
+## About Python
+
+{{ai_fact:Python_(programming_language)}}
+
+**Latest version info:** {{ai_rewrite:Python_(programming_language):Python X is the latest}}
+
+[Learn more]({{ai_link:Python_(programming_language)}})
+`;
+```
+
+### Q&A Sections
+
+```javascript
+const faq = `
+**Q: How far is the Moon?**
+A: {{ai_answer:Moon:How far is it from Earth?}}
+
+**Q: What is the Sun made of?**
+A: {{ai_answer:Sun:What is it made of?}}
+`;
+```
+
+## Browser Usage
+
+```html
+<script type="module">
+  import DocuFreshAI from 'https://esm.sh/docufresh-ai';
+
+  const ai = new DocuFreshAI({
+    onProgress: (p) => {
+      if (p.status === 'progress') {
+        console.log(`Loading: ${Math.round(p.loaded/p.total*100)}%`);
+      }
+    }
+  });
+
+  document.getElementById('content').innerHTML = await ai.process(
+    document.getElementById('content').innerHTML
+  );
+</script>
+```
+
+## Available Models
+
+| Model | Size | Quality | Speed |
+|-------|------|---------|-------|
+| `Xenova/flan-t5-small` | ~250MB | Good | Fast |
+| `Xenova/flan-t5-base` | ~900MB | Better | Slower |
+| `Xenova/flan-t5-large` | ~3GB | Best | Slowest |
+
+```javascript
+const ai = new DocuFreshAI({ model: 'Xenova/flan-t5-base' });
+```
+
+## Caching
+
+- Wikipedia responses are cached for 1 hour by default
+- AI model is cached after first download (browser localStorage / Node.js cache)
+- Customize cache TTL:
+
+```javascript
+const ai = new DocuFreshAI({
+  cacheTTL: 1000 * 60 * 30  // 30 minutes
+});
+
+// Clear cache manually
+ai.clearCache();
+```
+
+## TypeScript
+
+Full TypeScript support included:
+
+```typescript
+import DocuFreshAI, { WikipediaSummary } from 'docufresh-ai';
+
+const ai = new DocuFreshAI();
+const summary: WikipediaSummary = await ai.getSummary('TypeScript');
+```
+
+## Requirements
+
+- **Node.js 18+** (for native fetch)
+- **Modern browser** (Chrome 89+, Firefox 89+, Safari 15+)
+- **~250MB** disk space for default AI model
+
+## Related
+
+- [docufresh](https://www.npmjs.com/package/docufresh) - Base library for simple markers
+- [Transformers.js](https://huggingface.co/docs/transformers.js) - The AI engine
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "docufresh-ai",
+  "version": "0.1.0",
+  "description": "AI-powered content freshening for docufresh - Uses Wikipedia + browser-based AI (no API keys needed)",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node tests/ai.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "docufresh",
+    "ai",
+    "transformers",
+    "wikipedia",
+    "content-update",
+    "fresh-content",
+    "browser-ai",
+    "text-generation",
+    "fact-checking",
+    "dynamic-content"
+  ],
+  "author": "Vamsi Manthena <manthenavamsi@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manthenavamsi/docufresh-ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manthenavamsi/docufresh-ai/issues"
+  },
+  "homepage": "https://github.com/manthenavamsi/docufresh-ai#readme",
+  "peerDependencies": {
+    "docufresh": ">=0.1.0"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.0.0"
+  }
+}

package/src/ai-engine.js

@@ -0,0 +1,295 @@
+/**
+ * AI Engine
+ * Uses Transformers.js for browser-based text generation
+ * No API keys required - models run locally!
+ */
+
+import { pipeline, env } from '@huggingface/transformers';
+
+// Configure Transformers.js for both Node.js and browser
+env.allowLocalModels = false;  // Always download from Hugging Face
+
+/**
+ * Supported models with metadata
+ */
+const SUPPORTED_MODELS = {
+  'small': {
+    id: 'Xenova/flan-t5-small',
+    name: 'FLAN-T5 Small',
+    size: '250MB',
+    quality: 'good',
+    description: 'Fast, lightweight model for simple tasks'
+  },
+  'base': {
+    id: 'Xenova/flan-t5-base',
+    name: 'FLAN-T5 Base',
+    size: '900MB',
+    quality: 'better',
+    description: 'Balanced model for most use cases'
+  },
+  'large': {
+    id: 'Xenova/flan-t5-large',
+    name: 'FLAN-T5 Large',
+    size: '3GB',
+    quality: 'best',
+    description: 'Highest quality, requires more memory'
+  }
+};
+
+// Only enable browser cache in browser environment
+if (typeof window !== 'undefined') {
+  env.useBrowserCache = true;
+}
+
+class AIEngine {
+  /**
+   * Get list of available model keys
+   * @returns {string[]} Array of model keys ('small', 'base', 'large')
+   */
+  static getAvailableModels() {
+    return Object.keys(SUPPORTED_MODELS);
+  }
+
+  /**
+   * Get information about a specific model
+   * @param {string} modelKey - Model key ('small', 'base', 'large')
+   * @returns {object|null} Model info object or null if not found
+   */
+  static getModelInfo(modelKey) {
+    return SUPPORTED_MODELS[modelKey] || null;
+  }
+
+  constructor(options = {}) {
+    // Default to 'small' model - users can switch to 'base' or 'large' for better quality
+    this.model = this.resolveModel(options.model || 'small');
+    this.generator = null;
+    this.initialized = false;
+    this.initializing = false;
+    this.onProgress = options.onProgress || null;
+  }
+
+  /**
+   * Resolve a model input to a full Hugging Face model ID
+   * - 'small' (default), 'base', 'large' -> resolves to predefined model
+   * - Custom model ID (e.g., 'facebook/bart-large-cnn') -> used as-is
+   * @param {string} modelInput - Model key or custom model ID
+   * @returns {string} Full Hugging Face model ID
+   */
+  resolveModel(modelInput) {
+    // Check if it's a predefined model key
+    if (SUPPORTED_MODELS[modelInput]) {
+      return SUPPORTED_MODELS[modelInput].id;
+    }
+    // Otherwise, treat as custom model ID
+    return modelInput;
+  }
+
+  /**
+   * Initialize the AI model
+   * Downloads and loads the model (first time may take a while)
+   */
+  async init() {
+    if (this.initialized) return;
+    if (this.initializing) {
+      // Wait for existing initialization
+      while (this.initializing) {
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+      return;
+    }
+
+    this.initializing = true;
+
+    try {
+      console.log(`Loading AI model: ${this.model}...`);
+
+      // Create text2text-generation pipeline
+      this.generator = await pipeline('text2text-generation', this.model, {
+        progress_callback: (progress) => {
+          if (this.onProgress) {
+            this.onProgress(progress);
+          }
+          if (progress.status === 'progress') {
+            const percent = Math.round((progress.loaded / progress.total) * 100);
+            console.log(`Downloading model: ${percent}%`);
+          }
+        }
+      });
+
+      this.initialized = true;
+      console.log('AI model loaded successfully!');
+    } catch (error) {
+      console.error('Failed to initialize AI engine:', error.message);
+      throw error;
+    } finally {
+      this.initializing = false;
+    }
+  }
+
+  /**
+   * Rewrite a sentence incorporating a fact
+   * @param {string} fact - The fact to incorporate
+   * @param {string} template - Template sentence (X marks where fact goes)
+   * @returns {Promise<string>} - Rewritten sentence
+   */
+  async rewriteSentence(fact, template) {
+    await this.init();
+
+    // If template has X placeholder, do simple replacement first
+    let baseText = template;
+    if (template.includes('X') || template.includes('x')) {
+      // Extract key info from fact (first sentence or first 100 chars)
+      const keyInfo = this.extractKeyInfo(fact);
+      baseText = template.replace(/\bX\b/gi, keyInfo);
+    }
+
+    // Use AI to polish the sentence
+    const prompt = `Rewrite this sentence to be more natural and informative: "${baseText}"
+Based on this fact: ${fact.slice(0, 500)}
+Output only the rewritten sentence:`;
+
+    try {
+      const result = await this.generator(prompt, {
+        max_new_tokens: 100,
+        temperature: 0.7,
+        do_sample: true
+      });
+
+      const output = result[0]?.generated_text?.trim();
+      return output || baseText;
+    } catch (error) {
+      console.error('AI rewrite error:', error.message);
+      return baseText; // Return template with placeholder filled
+    }
+  }
+
+  /**
+   * Generate a paragraph about a topic using facts
+   * @param {string} topic - The topic name
+   * @param {string} facts - Facts about the topic
+   * @returns {Promise<string>} - Generated paragraph
+   */
+  async generateParagraph(topic, facts) {
+    await this.init();
+
+    const prompt = `Write a brief, informative paragraph about ${topic} based on these facts:
+${facts.slice(0, 800)}
+
+Write a 2-3 sentence summary:`;
+
+    try {
+      const result = await this.generator(prompt, {
+        max_new_tokens: 150,
+        temperature: 0.7,
+        do_sample: true
+      });
+
+      const output = result[0]?.generated_text?.trim();
+      return output || facts.slice(0, 200);
+    } catch (error) {
+      console.error('AI generate error:', error.message);
+      return facts.slice(0, 200); // Return truncated facts as fallback
+    }
+  }
+
+  /**
+   * Summarize text
+   * @param {string} text - Text to summarize
+   * @param {number} maxLength - Max length of summary
+   * @returns {Promise<string>} - Summary
+   */
+  async summarize(text, maxLength = 100) {
+    await this.init();
+
+    const prompt = `Summarize this in one sentence: ${text.slice(0, 1000)}`;
+
+    try {
+      const result = await this.generator(prompt, {
+        max_new_tokens: maxLength,
+        temperature: 0.5
+      });
+
+      return result[0]?.generated_text?.trim() || text.slice(0, maxLength);
+    } catch (error) {
+      console.error('AI summarize error:', error.message);
+      return text.slice(0, maxLength);
+    }
+  }
+
+  /**
+   * Answer a question based on context
+   * @param {string} question - The question
+   * @param {string} context - Context to answer from
+   * @returns {Promise<string>} - Answer
+   */
+  async answerQuestion(question, context) {
+    await this.init();
+
+    const prompt = `Answer this question based on the context.
+Context: ${context.slice(0, 800)}
+Question: ${question}
+Answer:`;
+
+    try {
+      const result = await this.generator(prompt, {
+        max_new_tokens: 100,
+        temperature: 0.3
+      });
+
+      return result[0]?.generated_text?.trim() || 'Unable to answer';
+    } catch (error) {
+      console.error('AI answer error:', error.message);
+      return 'Unable to answer';
+    }
+  }
+
+  /**
+   * Extract key information from a fact (first sentence or key phrase)
+   */
+  extractKeyInfo(fact) {
+    // Get first sentence
+    const firstSentence = fact.split(/[.!?]/)[0];
+
+    // If it's short enough, use it
+    if (firstSentence.length <= 100) {
+      return firstSentence.trim();
+    }
+
+    // Otherwise extract key numbers or phrases
+    const numbers = fact.match(/[\d,]+(\.\d+)?(\s*(million|billion|trillion|percent|%|years|days))?/gi);
+    if (numbers && numbers.length > 0) {
+      return numbers[0];
+    }
+
+    // Fallback to truncated first sentence
+    return firstSentence.slice(0, 100).trim() + '...';
+  }
+
+  /**
+   * Check if the engine is ready
+   */
+  isReady() {
+    return this.initialized;
+  }
+
+  /**
+   * Get the current model name
+   */
+  getModel() {
+    return this.model;
+  }
+
+  /**
+   * Change the model (requires re-initialization)
+   * @param {string} modelName - 'small', 'base', 'large', or custom model ID
+   */
+  async setModel(modelName) {
+    this.model = this.resolveModel(modelName);
+    this.initialized = false;
+    this.generator = null;
+    await this.init();
+  }
+}
+
+export { AIEngine };
+export default AIEngine;

package/src/index.d.ts

@@ -0,0 +1,181 @@
+/**
+ * DocuFresh-AI TypeScript Declarations
+ */
+
+export interface WikipediaSummary {
+  title: string;
+  description: string;
+  extract: string;
+  extractShort: string;
+  thumbnail: string | null;
+  url: string | null;
+  timestamp: string;
+  error?: boolean;
+}
+
+export interface WikipediaSearchResult {
+  title: string;
+  description: string;
+  url: string;
+}
+
+export interface WikipediaClientOptions {
+  cacheTTL?: number;
+}
+
+/**
+ * Predefined model keys
+ */
+export type ModelKey = 'small' | 'base' | 'large';
+
+/**
+ * Model information
+ */
+export interface ModelInfo {
+  id: string;
+  name: string;
+  size: string;
+  quality: 'good' | 'better' | 'best';
+  description: string;
+}
+
+export declare class WikipediaClient {
+  constructor(options?: WikipediaClientOptions);
+  getSummary(topic: string): Promise<WikipediaSummary>;
+  getFact(topic: string): Promise<string>;
+  getDescription(topic: string): Promise<string>;
+  search(query: string, limit?: number): Promise<WikipediaSearchResult[]>;
+  normalizeTopic(topic: string): string;
+  clearCache(): void;
+}
+
+export interface AIEngineOptions {
+  model?: ModelKey | string;
+  onProgress?: (progress: any) => void;
+}
+
+export declare class AIEngine {
+  /**
+   * Get list of available model keys
+   */
+  static getAvailableModels(): ModelKey[];
+
+  /**
+   * Get information about a specific model
+   */
+  static getModelInfo(modelKey: ModelKey): ModelInfo | null;
+
+  constructor(options?: AIEngineOptions);
+  init(): Promise<void>;
+  rewriteSentence(fact: string, template: string): Promise<string>;
+  generateParagraph(topic: string, facts: string): Promise<string>;
+  summarize(text: string, maxLength?: number): Promise<string>;
+  answerQuestion(question: string, context: string): Promise<string>;
+  isReady(): boolean;
+  getModel(): string;
+  setModel(modelName: ModelKey | string): Promise<void>;
+  resolveModel(modelInput: ModelKey | string): string;
+}
+
+export interface AIMarkers {
+  ai_fact: (topic: string) => Promise<string>;
+  ai_describe: (topic: string) => Promise<string>;
+  ai_rewrite: (topic: string, template: string) => Promise<string>;
+  ai_paragraph: (topic: string) => Promise<string>;
+  ai_summary: (topic: string) => Promise<string>;
+  ai_answer: (topic: string, question: string) => Promise<string>;
+  ai_link: (topic: string) => Promise<string>;
+  ai_updated: (topic: string) => Promise<string>;
+}
+
+export declare function createAIMarkers(
+  wikipedia: WikipediaClient,
+  ai: AIEngine
+): AIMarkers;
+
+export declare function registerAIMarkers(
+  docufresh: any,
+  wikipedia: WikipediaClient,
+  ai: AIEngine
+): AIMarkers;
+
+export interface DocuFreshAIOptions {
+  /** Model to use: 'small' (default), 'base', 'large', or custom model ID */
+  model?: ModelKey | string;
+  cacheTTL?: number;
+  onProgress?: (progress: any) => void;
+}
+
+export declare class DocuFreshAI {
+  /**
+   * Get list of available model keys
+   */
+  static getAvailableModels(): ModelKey[];
+
+  /**
+   * Get information about a specific model
+   */
+  static getModelInfo(modelKey: ModelKey): ModelInfo | null;
+
+  constructor(options?: DocuFreshAIOptions);
+
+  /**
+   * Initialize the AI engine (downloads model on first run)
+   */
+  init(): Promise<void>;
+
+  /**
+   * Process text with AI markers
+   * @param text - Text containing {{ai_*}} markers
+   * @param customData - Optional custom data for variable replacement
+   */
+  process(text: string, customData?: Record<string, string | number>): Promise<string>;
+
+  /**
+   * Process text with both docufresh and AI markers
+   * Requires docufresh to be installed
+   */
+  processWithDocufresh(text: string, customData?: Record<string, string | number>): Promise<string>;
+
+  /**
+   * Get a fact from Wikipedia
+   */
+  getFact(topic: string): Promise<string>;
+
+  /**
+   * Get a summary from Wikipedia
+   */
+  getSummary(topic: string): Promise<WikipediaSummary>;
+
+  /**
+   * Search Wikipedia
+   */
+  search(query: string, limit?: number): Promise<WikipediaSearchResult[]>;
+
+  /**
+   * Rewrite text using AI
+   */
+  rewrite(fact: string, template: string): Promise<string>;
+
+  /**
+   * Generate a paragraph using AI
+   */
+  generateParagraph(topic: string, context: string): Promise<string>;
+
+  /**
+   * Check if the AI engine is ready
+   */
+  isReady(): boolean;
+
+  /**
+   * Get the current AI model name
+   */
+  getModel(): string;
+
+  /**
+   * Clear the Wikipedia cache
+   */
+  clearCache(): void;
+}
+
+export default DocuFreshAI;

package/src/index.js

@@ -0,0 +1,257 @@
+/**
+ * DocuFresh-AI
+ * AI-powered content freshening using Wikipedia + browser-based AI
+ * No API keys required!
+ *
+ * @version 0.1.0
+ */
+
+import { WikipediaClient } from './wikipedia.js';
+import { AIEngine } from './ai-engine.js';
+import { registerAIMarkers, createAIMarkers } from './markers.js';
+
+/**
+ * DocuFreshAI - Main class for AI-powered content freshening
+ */
+class DocuFreshAI {
+  /**
+   * Get list of available model keys
+   * @returns {string[]} Array of model keys ('small', 'base', 'large')
+   * @example
+   * DocuFreshAI.getAvailableModels(); // ['small', 'base', 'large']
+   */
+  static getAvailableModels() {
+    return AIEngine.getAvailableModels();
+  }
+
+  /**
+   * Get information about a specific model
+   * @param {string} modelKey - Model key ('small', 'base', 'large')
+   * @returns {object|null} Model info with id, name, size, quality, description
+   * @example
+   * DocuFreshAI.getModelInfo('base');
+   * // { id: 'Xenova/flan-t5-base', name: 'FLAN-T5 Base', size: '900MB', ... }
+   */
+  static getModelInfo(modelKey) {
+    return AIEngine.getModelInfo(modelKey);
+  }
+
+  /**
+   * Create a DocuFreshAI instance
+   * @param {object} options - Configuration options
+   * @param {string} options.model - Model to use: 'small' (default), 'base', 'large', or custom model ID
+   * @param {number} options.cacheTTL - Wikipedia cache TTL in ms (default: 1 hour)
+   * @param {function} options.onProgress - Callback for model download progress
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.wikipedia = new WikipediaClient({
+      cacheTTL: options.cacheTTL
+    });
+    this.ai = new AIEngine({
+      model: options.model,
+      onProgress: options.onProgress
+    });
+    this.markers = null;
+    this.ready = false;
+    this.docufresh = null;
+  }
+
+  /**
+   * Initialize the AI engine
+   * This downloads and loads the AI model (may take time on first run)
+   * @returns {Promise<void>}
+   */
+  async init() {
+    if (this.ready) return;
+
+    console.log('Initializing DocuFresh-AI...');
+
+    // Initialize AI engine (downloads model)
+    await this.ai.init();
+
+    // Create markers
+    this.markers = createAIMarkers(this.wikipedia, this.ai);
+
+    this.ready = true;
+    console.log('DocuFresh-AI ready!');
+  }
+
+  /**
+   * Process text with AI markers
+   * Handles async markers that fetch from Wikipedia and generate with AI
+   *
+   * @param {string} text - Text containing {{ai_*}} markers
+   * @param {object} customData - Optional custom data for basic markers
+   * @returns {Promise<string>} - Processed text
+   */
+  async process(text, customData = {}) {
+    if (!this.ready) {
+      await this.init();
+    }
+
+    let result = text;
+
+    // Replace custom data first (simple sync replacement)
+    for (const [key, value] of Object.entries(customData)) {
+      const pattern = new RegExp(`{{${key}}}`, 'g');
+      result = result.replace(pattern, String(value));
+    }
+
+    // Find all AI markers
+    const markerPattern = /{{(ai_\w+):([^}]*)}}/g;
+    const matches = [...result.matchAll(markerPattern)];
+
+    // Process each AI marker
+    for (const match of matches) {
+      const fullMarker = match[0];
+      const markerName = match[1];
+      const paramsString = match[2];
+
+      // Split parameters by : (but not within the params themselves)
+      const params = paramsString.split(':').map(p => p.trim());
+
+      const markerFn = this.markers[markerName];
+
+      if (markerFn) {
+        try {
+          const replacement = await markerFn(...params);
+          result = result.replace(fullMarker, replacement);
+        } catch (error) {
+          console.error(`Error processing ${markerName}:`, error.message);
+          // Leave marker unchanged on error
+        }
+      }
+    }
+
+    // Also handle simple ai_* markers without params
+    const simplePattern = /{{(ai_\w+)}}/g;
+    const simpleMatches = [...result.matchAll(simplePattern)];
+
+    for (const match of simpleMatches) {
+      const fullMarker = match[0];
+      const markerName = match[1];
+
+      const markerFn = this.markers[markerName];
+
+      if (markerFn) {
+        try {
+          const replacement = await markerFn();
+          result = result.replace(fullMarker, replacement);
+        } catch (error) {
+          console.error(`Error processing ${markerName}:`, error.message);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Process text and also use base docufresh markers
+   * Requires docufresh to be installed
+   *
+   * @param {string} text - Text with both regular and AI markers
+   * @param {object} customData - Custom data
+   * @returns {Promise<string>} - Processed text
+   */
+  async processWithDocufresh(text, customData = {}) {
+    // Lazy load docufresh
+    if (!this.docufresh) {
+      try {
+        const docufreshModule = await import('docufresh');
+        this.docufresh = docufreshModule.default || docufreshModule;
+      } catch (error) {
+        console.warn('docufresh not installed, skipping basic markers');
+        return this.process(text, customData);
+      }
+    }
+
+    // First process with base docufresh (sync markers)
+    let result = this.docufresh.process(text, customData);
+
+    // Then process AI markers (async)
+    result = await this.process(result, {});
+
+    return result;
+  }
+
+  /**
+   * Get a fact from Wikipedia
+   * Convenience method for direct access
+   *
+   * @param {string} topic - Wikipedia topic
+   * @returns {Promise<string>} - Fact text
+   */
+  async getFact(topic) {
+    return this.wikipedia.getFact(topic);
+  }
+
+  /**
+   * Get a summary from Wikipedia
+   * @param {string} topic - Wikipedia topic
+   * @returns {Promise<object>} - Summary object
+   */
+  async getSummary(topic) {
+    return this.wikipedia.getSummary(topic);
+  }
+
+  /**
+   * Search Wikipedia
+   * @param {string} query - Search query
+   * @param {number} limit - Max results
+   * @returns {Promise<Array>} - Search results
+   */
+  async search(query, limit = 5) {
+    return this.wikipedia.search(query, limit);
+  }
+
+  /**
+   * Rewrite text using AI
+   * @param {string} fact - Fact to incorporate
+   * @param {string} template - Template with X placeholder
+   * @returns {Promise<string>} - Rewritten text
+   */
+  async rewrite(fact, template) {
+    if (!this.ready) await this.init();
+    return this.ai.rewriteSentence(fact, template);
+  }
+
+  /**
+   * Generate a paragraph using AI
+   * @param {string} topic - Topic name
+   * @param {string} context - Context/facts
+   * @returns {Promise<string>} - Generated paragraph
+   */
+  async generateParagraph(topic, context) {
+    if (!this.ready) await this.init();
+    return this.ai.generateParagraph(topic, context);
+  }
+
+  /**
+   * Check if the AI engine is ready
+   * @returns {boolean}
+   */
+  isReady() {
+    return this.ready;
+  }
+
+  /**
+   * Get the current AI model name
+   * @returns {string}
+   */
+  getModel() {
+    return this.ai.getModel();
+  }
+
+  /**
+   * Clear the Wikipedia cache
+   */
+  clearCache() {
+    this.wikipedia.clearCache();
+  }
+}
+
+// Export everything
+export { DocuFreshAI, WikipediaClient, AIEngine, registerAIMarkers, createAIMarkers };
+export default DocuFreshAI;

package/src/markers.js

@@ -0,0 +1,133 @@
+/**
+ * AI-Powered Markers
+ * Extends docufresh with intelligent content generation
+ */
+
+/**
+ * Create AI marker functions
+ * @param {WikipediaClient} wikipedia - Wikipedia client instance
+ * @param {AIEngine} ai - AI engine instance
+ * @returns {object} - Marker functions
+ */
+function createAIMarkers(wikipedia, ai) {
+  return {
+    /**
+     * Get a fact about a topic from Wikipedia
+     * Usage: {{ai_fact:topic_name}}
+     * Example: {{ai_fact:Albert_Einstein}} → "Albert Einstein was a German-born theoretical physicist..."
+     */
+    ai_fact: async (topic) => {
+      const fact = await wikipedia.getFact(topic);
+      return fact;
+    },
+
+    /**
+     * Get a short description of a topic
+     * Usage: {{ai_describe:topic_name}}
+     * Example: {{ai_describe:Python_(programming_language)}} → "General-purpose programming language"
+     */
+    ai_describe: async (topic) => {
+      const description = await wikipedia.getDescription(topic);
+      return description;
+    },
+
+    /**
+     * Rewrite a sentence incorporating current facts
+     * Usage: {{ai_rewrite:topic:template_with_X}}
+     * Example: {{ai_rewrite:world_population:The world has X people}}
+     *       → "The world has approximately 8.1 billion people"
+     */
+    ai_rewrite: async (topic, template) => {
+      // Get fact from Wikipedia
+      const fact = await wikipedia.getFact(topic);
+
+      // Use AI to rewrite naturally
+      const rewritten = await ai.rewriteSentence(fact, template);
+      return rewritten;
+    },
+
+    /**
+     * Generate a paragraph about a topic
+     * Usage: {{ai_paragraph:topic_name}}
+     * Example: {{ai_paragraph:SpaceX}} → "SpaceX, founded by Elon Musk..."
+     */
+    ai_paragraph: async (topic) => {
+      // Get facts from Wikipedia
+      const summary = await wikipedia.getSummary(topic);
+
+      // Use AI to generate a paragraph
+      const paragraph = await ai.generateParagraph(summary.title, summary.extract);
+      return paragraph;
+    },
+
+    /**
+     * Get a summary of a topic
+     * Usage: {{ai_summary:topic_name}}
+     * Example: {{ai_summary:Climate_change}} → "Climate change refers to..."
+     */
+    ai_summary: async (topic) => {
+      const summary = await wikipedia.getSummary(topic);
+
+      // Use AI to create a concise summary
+      const condensed = await ai.summarize(summary.extract);
+      return condensed;
+    },
+
+    /**
+     * Answer a question using Wikipedia as context
+     * Usage: {{ai_answer:topic:question}}
+     * Example: {{ai_answer:Moon:How far is it from Earth?}}
+     *       → "The Moon is approximately 384,400 km from Earth"
+     */
+    ai_answer: async (topic, question) => {
+      // Get context from Wikipedia
+      const summary = await wikipedia.getSummary(topic);
+
+      // Use AI to answer
+      const answer = await ai.answerQuestion(question, summary.extract);
+      return answer;
+    },
+
+    /**
+     * Get the Wikipedia URL for a topic
+     * Usage: {{ai_link:topic_name}}
+     * Example: {{ai_link:JavaScript}} → "https://en.wikipedia.org/wiki/JavaScript"
+     */
+    ai_link: async (topic) => {
+      const summary = await wikipedia.getSummary(topic);
+      return summary.url || `https://en.wikipedia.org/wiki/${wikipedia.normalizeTopic(topic)}`;
+    },
+
+    /**
+     * Get the last updated date for Wikipedia article
+     * Usage: {{ai_updated:topic_name}}
+     * Example: {{ai_updated:Bitcoin}} → "2024-01-15"
+     */
+    ai_updated: async (topic) => {
+      const summary = await wikipedia.getSummary(topic);
+      if (summary.timestamp) {
+        return new Date(summary.timestamp).toLocaleDateString();
+      }
+      return 'Unknown';
+    }
+  };
+}
+
+/**
+ * Register AI markers with a docufresh instance
+ * @param {DocuFresh} docufresh - The docufresh instance
+ * @param {WikipediaClient} wikipedia - Wikipedia client
+ * @param {AIEngine} ai - AI engine
+ */
+function registerAIMarkers(docufresh, wikipedia, ai) {
+  const markers = createAIMarkers(wikipedia, ai);
+
+  for (const [name, fn] of Object.entries(markers)) {
+    docufresh.registerMarker(name, fn);
+  }
+
+  return markers;
+}
+
+export { createAIMarkers, registerAIMarkers };
+export default registerAIMarkers;

package/src/wikipedia.js

@@ -0,0 +1,185 @@
+/**
+ * Wikipedia API Client
+ * Fetches facts and summaries from Wikipedia (no auth required)
+ */
+
+class WikipediaClient {
+  constructor(options = {}) {
+    this.baseUrl = 'https://en.wikipedia.org/api/rest_v1';
+    this.cache = new Map();
+    this.cacheTTL = options.cacheTTL || 1000 * 60 * 60; // 1 hour default
+  }
+
+  /**
+   * Get a summary/fact about a topic from Wikipedia
+   * @param {string} topic - The Wikipedia article title (use underscores for spaces)
+   * @returns {Promise<object>} - Summary data with extract, title, description
+   */
+  async getSummary(topic) {
+    const normalizedTopic = this.normalizeTopic(topic);
+
+    // Check cache first
+    const cached = this.getFromCache(normalizedTopic);
+    if (cached) return cached;
+
+    try {
+      const url = `${this.baseUrl}/page/summary/${encodeURIComponent(normalizedTopic)}`;
+      const response = await this.fetch(url);
+
+      if (!response.ok) {
+        throw new Error(`Wikipedia API error: ${response.status}`);
+      }
+
+      const data = await response.json();
+
+      const result = {
+        title: data.title,
+        description: data.description || '',
+        extract: data.extract || '',
+        extractShort: data.extract_html ? this.stripHtml(data.extract).slice(0, 200) : '',
+        thumbnail: data.thumbnail?.source || null,
+        url: data.content_urls?.desktop?.page || null,
+        timestamp: data.timestamp || new Date().toISOString()
+      };
+
+      // Cache the result
+      this.setCache(normalizedTopic, result);
+
+      return result;
+    } catch (error) {
+      console.error(`Wikipedia fetch error for "${topic}":`, error.message);
+      return {
+        title: topic,
+        description: '',
+        extract: `Unable to fetch information about ${topic}`,
+        extractShort: '',
+        thumbnail: null,
+        url: null,
+        timestamp: new Date().toISOString(),
+        error: true
+      };
+    }
+  }
+
+  /**
+   * Get a specific fact/extract from Wikipedia
+   * @param {string} topic - The topic to look up
+   * @returns {Promise<string>} - The fact/extract text
+   */
+  async getFact(topic) {
+    const summary = await this.getSummary(topic);
+    return summary.extract || `Information about ${topic} not available`;
+  }
+
+  /**
+   * Get a short description of a topic
+   * @param {string} topic - The topic to look up
+   * @returns {Promise<string>} - Short description
+   */
+  async getDescription(topic) {
+    const summary = await this.getSummary(topic);
+    return summary.description || summary.extractShort || topic;
+  }
+
+  /**
+   * Search Wikipedia for articles matching a query
+   * @param {string} query - Search query
+   * @param {number} limit - Max results (default 5)
+   * @returns {Promise<Array>} - Array of search results
+   */
+  async search(query, limit = 5) {
+    try {
+      const url = `https://en.wikipedia.org/w/api.php?action=opensearch&search=${encodeURIComponent(query)}&limit=${limit}&format=json&origin=*`;
+      const response = await this.fetch(url);
+
+      if (!response.ok) {
+        throw new Error(`Wikipedia search error: ${response.status}`);
+      }
+
+      const data = await response.json();
+      // OpenSearch returns [query, titles, descriptions, urls]
+      const titles = data[1] || [];
+      const descriptions = data[2] || [];
+      const urls = data[3] || [];
+
+      return titles.map((title, i) => ({
+        title,
+        description: descriptions[i] || '',
+        url: urls[i] || ''
+      }));
+    } catch (error) {
+      console.error(`Wikipedia search error for "${query}":`, error.message);
+      return [];
+    }
+  }
+
+  /**
+   * Normalize topic string for Wikipedia API
+   */
+  normalizeTopic(topic) {
+    return topic
+      .trim()
+      .replace(/\s+/g, '_')  // Spaces to underscores
+      .replace(/^_+|_+$/g, ''); // Trim underscores
+  }
+
+  /**
+   * Strip HTML tags from text
+   */
+  stripHtml(html) {
+    return html.replace(/<[^>]*>/g, '');
+  }
+
+  /**
+   * Get from cache if not expired
+   */
+  getFromCache(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+
+    if (Date.now() - item.timestamp > this.cacheTTL) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return item.data;
+  }
+
+  /**
+   * Set cache item
+   */
+  setCache(key, data) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+
+  /**
+   * Fetch wrapper - works in both Node.js and browser
+   */
+  async fetch(url) {
+    // Use global fetch (available in Node 18+ and browsers)
+    if (typeof fetch !== 'undefined') {
+      return fetch(url, {
+        headers: {
+          'User-Agent': 'DocuFresh-AI/0.1.0 (https://github.com/manthenavamsi/docufresh-ai)',
+          'Accept': 'application/json'
+        }
+      });
+    }
+
+    // Fallback for older Node.js (shouldn't be needed with Node 18+)
+    throw new Error('fetch is not available. Please use Node.js 18+ or a browser environment.');
+  }
+}
+
+export { WikipediaClient };
+export default WikipediaClient;