@equinor/fusion-framework-cli-plugin-ai-chat 1.0.4 → 2.0.0

package/dist/types/chat.d.ts

@@ -1,6 +1,16 @@
 /**
- * CLI command for interactive chat with AI models.
- * Enhanced with AI options including chat, embedding, and search capabilities.
+ * Fully configured Commander command for `ffc ai chat`.
+ *
+ * Wraps the base `_command` with shared AI options (chat, embedding, and
+ * search) from `@equinor/fusion-framework-cli-plugin-ai-base` via
+ * {@link withAiOptions}. This is the value imported by
+ * {@link registerChatPlugin} when mounting the command onto the CLI tree.
+ *
+ * @example
+ * ```ts
+ * import { command } from '@equinor/fusion-framework-cli-plugin-ai-chat/chat';
+ * program.addCommand(command);
+ * ```
  */
 export declare const command: import("commander").Command;
 export default command;

package/dist/types/index.d.ts

@@ -1,7 +1,20 @@
 import type { Command } from 'commander';
 /**
- * Registers the AI chat plugin command with the CLI program
- * @param program - The Commander program instance to register commands with
+ * Registers the `ai chat` CLI plugin command with the Fusion Framework CLI program.
+ *
+ * Call this function from a CLI plugin entry point to add the interactive
+ * AI chat command (`ffc ai chat`) to the CLI command tree. The function
+ * delegates to {@link registerAiPlugin} from `@equinor/fusion-framework-cli-plugin-ai-base`
+ * to wire up shared AI options (Azure OpenAI, Azure Cognitive Search) and
+ * attach the chat-specific sub-command.
+ *
+ * @param program - The root `Commander` {@link Command} instance that owns the CLI command tree
+ *
+ * @example
+ * ```ts
+ * import { registerChatPlugin } from '@equinor/fusion-framework-cli-plugin-ai-chat';
+ * registerChatPlugin(program);
+ * ```
  */
 export declare function registerChatPlugin(program: Command): void;
 export default registerChatPlugin;

package/dist/types/system-message-template.d.ts

@@ -1,10 +1,27 @@
 /**
- * System message template for FUSION framework chat assistant
+ * Creates the system message prompt for the Fusion Framework AI chat assistant.
  *
- * This template emphasizes using FUSION knowledge from the provided context
- * to provide accurate and comprehensive answers about the FUSION framework.
+ * Builds a system-role message that instructs the LLM to prioritise
+ * Fusion-specific knowledge from the provided RAG context. The returned
+ * string is used as the first message in the chat completion request so the
+ * model grounds its answers in retrieved Fusion documentation, code examples,
+ * and API references.
  *
- * @param context - The retrieved context from the vector store containing FUSION knowledge
- * @returns Formatted system message string for the AI chat assistant
+ * Use this when constructing the message array for an Azure OpenAI chat
+ * completion call inside the `ai chat` command.
+ *
+ * @param context - Concatenated page content retrieved from the Azure Cognitive Search
+ *   vector store. Each document's text is joined with newlines before being passed here.
+ * @returns A formatted system message string ready to be used as the `content` of a
+ *   `ChatMessage` with `role: 'system'`.
+ *
+ * @example
+ * ```ts
+ * const systemMsg = createSystemMessage(retrievedDocs);
+ * const messages: ChatMessage[] = [
+ *   { role: 'system', content: systemMsg },
+ *   { role: 'user', content: userQuestion },
+ * ];
+ * ```
  */
 export declare function createSystemMessage(context: string): string;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.0.4";
+export declare const version = "2.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli-plugin-ai-chat",
-  "version": "1.0.4",
+  "version": "2.0.0",
   "description": "AI chat plugin for Fusion Framework CLI providing interactive chat with AI models",
   "main": "dist/esm/index.js",
   "type": "module",
@@ -40,16 +40,17 @@
     "@langchain/core": "^1.0.1",
     "commander": "^14.0.1",
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-cli-plugin-ai-base": "1.0.4",
-    "@equinor/fusion-framework-module-ai": "2.0.1",
-    "@equinor/fusion-framework-module": "5.0.5"
+    "@equinor/fusion-framework-cli-plugin-ai-base": "2.0.0",
+    "@equinor/fusion-framework-module-ai": "3.0.0",
+    "@equinor/fusion-framework-module": "6.0.0"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-cli": "^13.2.0"
+    "@equinor/fusion-framework-cli": "^14.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-cli": "^14.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/chat.ts

@@ -17,69 +17,59 @@ import {
 import { StringOutputParser } from '@langchain/core/output_parsers';
 
 /**
- * CLI command: `ai chat`
+ * CLI command definition for `ffc ai chat`.
  *
- * Interactive chat with Large Language Models using inquirer for a smooth CLI experience.
- * Enhanced with vector store context retrieval for more accurate and relevant responses.
+ * Provides an interactive, readline-based chat session with an Azure OpenAI
+ * model. Each user message triggers a Retrieval-Augmented Generation (RAG)
+ * pipeline that:
  *
- * Features:
- * - Interactive conversation mode with inquirer prompts
- * - Real-time streaming responses from AI models
- * - Intelligent message history compression using AI summarization
- * - Automatic vector store context retrieval for enhanced responses
- * - Special commands: exit, quit, clear, help
- * - Support for Azure OpenAI models and Azure Cognitive Search
- * - Live typing effect for AI responses
- * - Configurable context retrieval limits
+ * 1. Retrieves relevant documents from an Azure Cognitive Search vector store.
+ * 2. Injects the retrieved context into a system prompt via {@link createSystemMessage}.
+ * 3. Streams the model's response token-by-token to stdout using a
+ *    {@link RunnableSequence} LangChain chain.
  *
- * Usage:
- *   $ ffc ai chat [options]
+ * The command also manages conversation history with automatic AI-based
+ * compression: when the history reaches 10 messages the oldest 5 are
+ * summarised into a single assistant message, keeping token usage bounded
+ * while preserving conversational context.
  *
- * Options:
- *   --openai-api-key <key>              API key for Azure OpenAI
- *   --openai-api-version <version>       API version (default: 2024-02-15-preview)
- *   --openai-instance <name>             Azure OpenAI instance name
- *   --openai-chat-deployment <name>      Azure OpenAI chat deployment name
- *   --openai-embedding-deployment <name> Azure OpenAI embedding deployment name
- *   --azure-search-endpoint <url>        Azure Search endpoint URL
- *   --azure-search-api-key <key>        Azure Search API key
- *   --azure-search-index-name <name>     Azure Search index name
- *   --use-context                        Use vector store context (default: true)
- *   --context-limit <number>             Max context documents to retrieve (default: 5)
- *   --history-limit <number>             Max messages to keep in conversation history (default: 20, auto-compresses at 10)
- *   --verbose                            Enable verbose output
+ * @remarks
+ * Requires `--openai-chat-deployment` and `--azure-search-index-name` at
+ * minimum. All options can alternatively be supplied as environment variables
+ * (see {@link CommandOptions}).
  *
- * Environment Variables:
- *   AZURE_OPENAI_API_KEY                    API key for Azure OpenAI
- *   AZURE_OPENAI_API_VERSION                API version
- *   AZURE_OPENAI_INSTANCE_NAME              Instance name
- *   AZURE_OPENAI_CHAT_DEPLOYMENT_NAME        Chat deployment name
- *   AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME   Embedding deployment name
- *   AZURE_SEARCH_ENDPOINT                    Azure Search endpoint
- *   AZURE_SEARCH_API_KEY                     Azure Search API key
- *   AZURE_SEARCH_INDEX_NAME                  Azure Search index name
+ * @example
+ * ```sh
+ * # Basic interactive chat
+ * ffc ai chat
  *
- * Interactive Commands:
- *   exit/quit  - End the conversation
- *   clear      - Clear conversation history
- *   help       - Show available commands
- *   Ctrl+C     - Exit immediately
+ * # With explicit deployment and search config
+ * ffc ai chat \
+ *   --openai-chat-deployment gpt-4o \
+ *   --azure-search-endpoint https://my.search.windows.net \
+ *   --azure-search-index-name fusion-docs
  *
- * Examples:
- *   $ ffc ai chat
- *   $ ffc ai chat --context-limit 10
- *   $ ffc ai chat --history-limit 100
- *   $ ffc ai chat --verbose --azure-search-endpoint https://my-search.search.windows.net
+ * # Increase context window and enable verbose logging
+ * ffc ai chat --context-limit 10 --verbose
+ * ```
  */
+
 /**
- * Command options for the chat command
+ * Merged option set for the `ai chat` command.
+ *
+ * Extends the shared {@link AiOptions} from
+ * `@equinor/fusion-framework-cli-plugin-ai-base` with chat-specific flags
+ * for verbose logging, context retrieval depth, and conversation history size.
+ *
+ * Every option can be supplied via the corresponding `AZURE_*` / `OPENAI_*`
+ * environment variable instead of a CLI flag.
  */
 type CommandOptions = AiOptions & {
-  /** Enable verbose output for debugging */
+  /** Enable verbose output for debugging. */
   verbose?: boolean;
-  /** Maximum number of context documents to retrieve from vector store */
+  /** Maximum number of context documents to retrieve from the vector store (default `5`). */
   contextLimit?: number;
-  /** Maximum number of messages to keep in conversation history */
+  /** Maximum number of messages to keep in conversation history before compression (default `20`). */
   historyLimit?: number;
 };
 
@@ -417,8 +407,18 @@ Summary:`;
   });
 
 /**
- * CLI command for interactive chat with AI models.
- * Enhanced with AI options including chat, embedding, and search capabilities.
+ * Fully configured Commander command for `ffc ai chat`.
+ *
+ * Wraps the base `_command` with shared AI options (chat, embedding, and
+ * search) from `@equinor/fusion-framework-cli-plugin-ai-base` via
+ * {@link withAiOptions}. This is the value imported by
+ * {@link registerChatPlugin} when mounting the command onto the CLI tree.
+ *
+ * @example
+ * ```ts
+ * import { command } from '@equinor/fusion-framework-cli-plugin-ai-chat/chat';
+ * program.addCommand(command);
+ * ```
  */
 export const command = withAiOptions(_command, {
   includeChat: true,

package/src/index.ts

@@ -3,8 +3,21 @@ import { registerAiPlugin } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import { command as chatCommand } from './chat.js';
 
 /**
- * Registers the AI chat plugin command with the CLI program
- * @param program - The Commander program instance to register commands with
+ * Registers the `ai chat` CLI plugin command with the Fusion Framework CLI program.
+ *
+ * Call this function from a CLI plugin entry point to add the interactive
+ * AI chat command (`ffc ai chat`) to the CLI command tree. The function
+ * delegates to {@link registerAiPlugin} from `@equinor/fusion-framework-cli-plugin-ai-base`
+ * to wire up shared AI options (Azure OpenAI, Azure Cognitive Search) and
+ * attach the chat-specific sub-command.
+ *
+ * @param program - The root `Commander` {@link Command} instance that owns the CLI command tree
+ *
+ * @example
+ * ```ts
+ * import { registerChatPlugin } from '@equinor/fusion-framework-cli-plugin-ai-chat';
+ * registerChatPlugin(program);
+ * ```
  */
 export function registerChatPlugin(program: Command): void {
   registerAiPlugin(program, chatCommand);

package/src/system-message-template.ts

@@ -1,11 +1,28 @@
 /**
- * System message template for FUSION framework chat assistant
+ * Creates the system message prompt for the Fusion Framework AI chat assistant.
  *
- * This template emphasizes using FUSION knowledge from the provided context
- * to provide accurate and comprehensive answers about the FUSION framework.
+ * Builds a system-role message that instructs the LLM to prioritise
+ * Fusion-specific knowledge from the provided RAG context. The returned
+ * string is used as the first message in the chat completion request so the
+ * model grounds its answers in retrieved Fusion documentation, code examples,
+ * and API references.
  *
- * @param context - The retrieved context from the vector store containing FUSION knowledge
- * @returns Formatted system message string for the AI chat assistant
+ * Use this when constructing the message array for an Azure OpenAI chat
+ * completion call inside the `ai chat` command.
+ *
+ * @param context - Concatenated page content retrieved from the Azure Cognitive Search
+ *   vector store. Each document's text is joined with newlines before being passed here.
+ * @returns A formatted system message string ready to be used as the `content` of a
+ *   `ChatMessage` with `role: 'system'`.
+ *
+ * @example
+ * ```ts
+ * const systemMsg = createSystemMessage(retrievedDocs);
+ * const messages: ChatMessage[] = [
+ *   { role: 'system', content: systemMsg },
+ *   { role: 'user', content: userQuestion },
+ * ];
+ * ```
  */
 export function createSystemMessage(context: string): string {
   return `You are a helpful assistant specialized in the FUSION framework. Your primary goal is to use FUSION knowledge from the provided context to answer questions accurately and comprehensively.

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '1.0.4';
+export const version = '2.0.0';