@equinor/fusion-framework-cli-plugin-ai-chat

Interactive AI chat plugin for the Fusion Framework CLI (ffc). It adds the ffc ai chat command, which opens a readline-based conversation with an Azure OpenAI model, grounded in Fusion documentation retrieved from an Azure Cognitive Search vector store (Retrieval-Augmented Generation).

[!WARNING] Work in progress — API surface and behaviour may change without notice. Intended for internal testing of vector-store search capabilities; not recommended for production use.

Who should use this

Developers and maintainers who want to ask natural-language questions about the Fusion Framework codebase from the terminal. The command augments LLM answers with context retrieved from an indexed documentation store, so responses are Fusion-specific rather than generic.

Quick start

Install the plugin

pnpm add -D @equinor/fusion-framework-cli-plugin-ai-chat

Register the plugin in fusion-cli.config.ts

import { defineFusionCli } from '@equinor/fusion-framework-cli';

export default defineFusionCli(() => ({
  plugins: ['@equinor/fusion-framework-cli-plugin-ai-chat'],
}));

Start a chat session

ffc ai chat \
  --openai-chat-deployment gpt-4o \
  --azure-search-endpoint https://my-search.search.windows.net \
  --azure-search-index-name fusion-docs

All flags can also be supplied as environment variables (see Environment variables below).

Key concepts

Retrieval-Augmented Generation (RAG)

Every user message triggers a similarity search against the configured Azure Cognitive Search index. The top-k documents are injected into a system prompt built by createSystemMessage, so the LLM prioritises Fusion-specific knowledge over general training data.

Conversation history compression

When the message history reaches 10 messages, the oldest 5 are summarised into a single assistant message using an AI call. A hard cap (--history-limit, default 20) drops the oldest non-summary messages if the history still exceeds the limit after compression.

LangChain chain pipeline

The command constructs a RunnableSequence from @langchain/core:

1. Format prompt — retrieves context, builds the system message, and assembles the ChatMessage[] array.
2. Chat model — invokes the Azure OpenAI chat deployment.
3. String output parser — extracts the streamed text for display.

API surface

| Export | Module | Description | |---|---|---| | registerChatPlugin | index.ts | Registers the ai chat command on a Commander program. Default export. | | command | chat.ts | Pre-configured Commander Command with all AI and chat-specific options. | | createSystemMessage | system-message-template.ts | Builds the RAG system prompt from retrieved context. | | version | version.ts | Auto-generated package version string. |

Command reference — ffc ai chat

Options

| Flag | Default | Description | |---|---|---| | --openai-api-key <key> | — | API key for Azure OpenAI | | --openai-api-version <version> | 2024-02-15-preview | Azure OpenAI API version | | --openai-instance <name> | — | Azure OpenAI instance name | | --openai-chat-deployment <name> | — | Chat model deployment name (required) | | --openai-embedding-deployment <name> | — | Embedding deployment name | | --azure-search-endpoint <url> | — | Azure Cognitive Search endpoint (required) | | --azure-search-api-key <key> | — | Azure Cognitive Search API key (required) | | --azure-search-index-name <name> | — | Search index name (required) | | --context-limit <number> | 5 | Maximum context documents to retrieve per message | | --history-limit <number> | 20 | Maximum messages before compression kicks in | | --verbose | false | Print retrieval diagnostics and chain execution details |

Environment variables

Every CLI flag has an equivalent environment variable:

| Variable | Maps to | |---|---| | AZURE_OPENAI_API_KEY | --openai-api-key | | AZURE_OPENAI_API_VERSION | --openai-api-version | | AZURE_OPENAI_INSTANCE_NAME | --openai-instance | | AZURE_OPENAI_CHAT_DEPLOYMENT_NAME | --openai-chat-deployment | | AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME | --openai-embedding-deployment | | AZURE_SEARCH_ENDPOINT | --azure-search-endpoint | | AZURE_SEARCH_API_KEY | --azure-search-api-key | | AZURE_SEARCH_INDEX_NAME | --azure-search-index-name |

Interactive commands

| Input | Effect | |---|---| | clear | Clears conversation history | | Ctrl+C | Exits immediately |

Common patterns

Run with environment variables only

export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o"
export AZURE_SEARCH_ENDPOINT="https://my-search.search.windows.net"
export AZURE_SEARCH_API_KEY="..."
export AZURE_SEARCH_INDEX_NAME="fusion-docs"

ffc ai chat

Retrieve more context per query

ffc ai chat --context-limit 10

Keep a longer conversation history

ffc ai chat --history-limit 50

Debug retrieval and chain execution

ffc ai chat --verbose

License

ISC