@bmx-labs/chat-widget 0.0.1 → 0.0.2

package/README.md

@@ -8,6 +8,14 @@ A reusable chat AI widget for React/Next.js apps. Fixed bottom-right with highes
 npm i @bmx-labs/chat-widget react react-dom
 ```
 
+```bash
+yarn add @bmx-labs/chat-widget react react-dom
+```
+
+```bash
+pnpm add @bmx-labs/chat-widget react react-dom
+```
+
 ## Usage
 
 ```tsx
@@ -43,7 +51,7 @@ export default function App() {
 type PineconeRAGAdapterConfig = {
   openAIApiKey: string;
   pineconeApiKey: string;
-  pineconeIndexUrl: string; // e.g. https://bmx-xxxx.svc.region.pinecone.io
+  pineconeIndexUrl: string;
   namespace?: string; // default: 'bmx-docs'
   topK?: number; // default: 4
   chatModel?: string; // default: gpt-4o-mini
@@ -68,23 +76,10 @@ type PineconeRAGAdapterConfig = {
 ## Development
 
 ```bash
-npm install
-npm run build
-npm run dev
+pnpm i
+pnpm dev
 ```
 
-### GitHub Actions (Publish on tag)
-
-1. Create an npm token and add it as `NPM_TOKEN` in GitHub repository secrets.
-2. Push a tag to trigger publish:
-
-```bash
-git tag v0.1.1
-git push --tags
-```
-
-The workflow at `.github/workflows/publish.yml` will build and publish to npm.
-
 ## License
 
 This project is licensed as **GNU AGPLv3**.

package/dist/adapters/context/PineconeRAGAdapter.d.ts

@@ -1,39 +1,74 @@
-import type { BmxChatApiAdapter, ChatMessage } from "../../types";
-export interface PineconeRAGAdapterConfig {
-    openAIApiKey: string;
-    pineconeApiKey: string;
-    /** Example: https://myindex-abc123.svc.us-east1-aws.pinecone.io */
-    pineconeIndexUrl: string;
-    namespace?: string;
-    topK?: number;
-    chatModel?: string;
-    embeddingModel?: string;
-    openAIBaseURL?: string;
-    enableStreaming?: boolean;
-    maxContextTokens?: number;
-    minScoreThreshold?: number;
-    debug?: boolean;
-}
+import type { BmxChatApiAdapter, ChatMessage, PineconeRAGAdapterConfig } from "../../types";
+/**
+ * Pinecone RAG Adapter.
+ *
+ * This adapter uses Pinecone for vector search and OpenAI for chat completion.
+ * It embeds the user's query, retrieves the most relevant context from Pinecone,
+ * builds a system prompt with the context, and calls OpenAI chat to generate the final response.
+ */
 export declare class PineconeRAGAdapter implements BmxChatApiAdapter {
+    /**
+     * OpenAI API key.
+     */
     private openAIApiKey;
+    /**
+     * Pinecone API key.
+     */
     private pineconeApiKey;
+    /**
+     * Pinecone index URL.
+     */
     private pineconeIndexUrl;
+    /**
+     * Pinecone namespace.
+     */
     private namespace;
+    /**
+     * Number of relevant chunks to retrieve.
+     */
     private topK;
+    /**
+     * OpenAI model for chat completion.
+     */
     private chatModel;
+    /**
+     * OpenAI model for embeddings.
+     */
     private embeddingModel;
+    /**
+     * OpenAI API base URL.
+     */
     private openAIBaseURL;
-    private enableStreaming;
+    /**
+     * Maximum context tokens.
+     */
     private maxContextTokens;
+    /**
+     * Minimum score threshold.
+     */
     private minScoreThreshold;
+    /**
+     * Logger.
+     */
     private logger;
+    /**
+     * Dynamic context.
+     */
+    private dynamicContext?;
+    /**
+     * Initialize the adapter.
+     *
+     * @param {PineconeRAGAdapterConfig} cfg - The configuration.
+     */
     constructor(cfg: PineconeRAGAdapterConfig);
-    private embed;
-    private queryPinecone;
-    private preprocessQuery;
-    private estimateTokens;
-    private truncateContext;
-    private buildSystemPrompt;
+    /**
+     * Send a message to the adapter.
+     *
+     * @param {ChatMessage[]} history - The history of messages.
+     * @param {string} input - The input message.
+     * @param {AbortSignal} options?.signal - The abort signal.
+     * @returns {Promise<ChatMessage>} The response message.
+     */
     sendMessage(history: ChatMessage[], input: string, options?: {
         signal?: AbortSignal;
     }): Promise<ChatMessage>;

package/dist/adapters/context/debug.d.ts

@@ -0,0 +1,11 @@
+import { PineconeQueryMatch } from "../../types";
+import { Logger } from "../../utils/logger";
+/**
+ * Debug logging for the filtered matches.
+ *
+ * @param {string} processedInput - The processed input.
+ * @param {PineconeQueryMatch[]} allMatches - The all matches.
+ * @param {PineconeQueryMatch[]} filteredMatches - The filtered matches.
+ * @param {Logger} logger - The logger.
+ */
+export declare function debugFilterMatches(processedInput: string, allMatches: PineconeQueryMatch[], filteredMatches: PineconeQueryMatch[], logger: Logger): void;

package/dist/adapters/context/fetchers.d.ts

@@ -0,0 +1,40 @@
+import { ChatCompletionResult, OpenAIModel, PineconeQueryMatch } from "../../types";
+import { Logger } from "../../utils/logger";
+/**
+ * Embeds text using OpenAI embeddings.
+ *
+ * @param {string} text - The text to embed.
+ * @param {string} openAIBaseURL - The OpenAI API base URL.
+ * @param {string} openAIApiKey - The OpenAI API key.
+ * @param {string} embeddingModel - The OpenAI embedding model.
+ * @param {AbortSignal} signal - The abort signal.
+ * @returns {Promise<number[]>} The embedding.
+ */
+export declare function getEmbeddedVector(text: string, openAIBaseURL: string, openAIApiKey: string, embeddingModel: string, signal?: AbortSignal): Promise<number[]>;
+/**
+ * Calls OpenAI Chat Completions API and returns the assistant content.
+ *
+ * @param {string} openAIBaseURL - The OpenAI API base URL.
+ * @param {string} openAIApiKey - The OpenAI API key.
+ * @param {OpenAIModel} model - The OpenAI chat model.
+ * @param {Array<{role: string; content: string}>} messages - The chat messages.
+ * @param {Logger} logger - The logger.
+ * @param {AbortSignal} signal - Abort signal.
+ * @returns {Promise<ChatCompletionResult>} The assistant content.
+ */
+export declare function getChatCompletion(openAIBaseURL: string, openAIApiKey: string, model: OpenAIModel, messages: Array<{
+    role: string;
+    content: string;
+}>, logger: Logger, signal?: AbortSignal): Promise<ChatCompletionResult>;
+/**
+ * Queries Pinecone for the most relevant matches.
+ *
+ * @param {number[]} vector - The embedding vector.
+ * @param {string} pineconeIndexUrl - The Pinecone index URL.
+ * @param {string} pineconeApiKey - The Pinecone API key.
+ * @param {number} topK - The number of relevant matches to retrieve.
+ * @param {string} namespace - The Pinecone namespace.
+ * @param {AbortSignal} signal - The abort signal.
+ * @returns {Promise<PineconeQueryMatch[]>} The relevant matches.
+ */
+export declare function queryPinecone(vector: number[], pineconeIndexUrl: string, pineconeApiKey: string, topK: number, namespace: string, signal?: AbortSignal): Promise<PineconeQueryMatch[]>;

package/dist/adapters/context/index.d.ts

@@ -1,2 +1 @@
-export { MorphexAdapter } from "./MorphexAdapter";
 export { PineconeRAGAdapter } from "./PineconeRAGAdapter";

package/dist/adapters/context/processing.d.ts

@@ -0,0 +1,96 @@
+import { ChatMessage, PineconeQueryMatch } from "../../types";
+import { Logger } from "../../utils/logger";
+/**
+ * Preprocesses the query for better retrieval.
+ *
+ * @param {string} query - The query.
+ * @returns {string} The preprocessed query.
+ */
+export declare function preprocessQuery(query: string): string;
+/**
+ * Optionally fetches dynamic (live) context and appends it to the retrieved
+ * Pinecone matches before prompting the LLM.
+ *
+ * Typical use cases include live token prices, on-chain metrics, or any
+ * time-sensitive information you want the assistant to reference. This keeps
+ * the adapter decoupled from arbitrary APIs while allowing the host app to
+ * supply additional context blocks on demand.
+ *
+ * Behavior:
+ * - If `dynamicContext` is not provided, returns `filteredMatches` unchanged.
+ * - If the provider returns blocks, they are converted into synthetic matches
+ *   (scored as 1 to prioritize) and merged with existing matches.
+ * - The merged list is truncated by `maxContextTokens` to control cost.
+ * - Any errors are logged and the original matches are returned (no throw).
+ *
+ * @param {string} processedInput - A normalized version of the user's input (e.g., after query expansion)
+ * @param {PineconeQueryMatch[]} filteredMatches - Matches already filtered by score and topK
+ * @param {number} maxContextTokens - Hard cap for context tokens to keep OpenAI cost bounded
+ * @param {Logger} logger - Logger instance for structured (optional) debug output
+ * @param {Function} dynamicContext - Optional async provider that returns additional context blocks
+ * @param {AbortSignal} options - Optional AbortSignal for cancellation
+ * @returns {PineconeQueryMatch[]} The merged and truncated list of matches ready for prompting
+ */
+export declare function processDynamicContext(processedInput: string, filteredMatches: PineconeQueryMatch[], maxContextTokens: number, logger: Logger, dynamicContext?: (input: string, options?: {
+    signal?: AbortSignal;
+}) => Promise<Array<{
+    title?: string;
+    url?: string;
+    text: string;
+}>>, options?: {
+    signal?: AbortSignal;
+}): Promise<PineconeQueryMatch[]>;
+/**
+ * Coarse token estimator used for quick context-size budgeting.
+ *
+ * The heuristic assumes ~4 characters per token. This is intentionally simple
+ * and fast; for strict budgeting consider a model-specific tokenizer if needed.
+ *
+ * @param {string} text - Arbitrary text to estimate token count for
+ * @returns {number} Estimated token count
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Truncates a list of matches so that the combined preview text fits within a
+ * specified token budget. Preserves order and partially truncates the last
+ * match if needed (and if there is enough remaining budget to be meaningful).
+ *
+ * Rationale: Keeping the most relevant matches at the top and avoiding hard cuts
+ * that remove all context for the last item often yields better LLM answers.
+ *
+ * @param {PineconeQueryMatch[]} matches - Ordered list of matches (highest priority first)
+ * @param {number} maxContextTokens - Total token budget for all match texts combined
+ * @returns {PineconeQueryMatch[]} A truncated list of matches within the token budget
+ */
+export declare function truncateContext(matches: PineconeQueryMatch[], maxContextTokens: number): PineconeQueryMatch[];
+/**
+ * Refuse gracefully if no relevant matches are found.
+ *
+ * @param {Logger} logger - The logger.
+ */
+export declare function createNoMatchesResponse(logger: Logger): ChatMessage;
+/**
+ * Extracts sources from the matches.
+ *
+ * @param {PineconeQueryMatch[]} matches - The matches.
+ * @returns {Array<{ title: string; url: string }>} The sources.
+ */
+export declare function extractSources(matches: PineconeQueryMatch[]): Array<{
+    title: string;
+    url: string;
+}>;
+/**
+ * Ensures that the content has a Sources section with real links from context.
+ *
+ * @param {string} content - The content.
+ * @param {PineconeQueryMatch[]} finalMatches - The final matches.
+ * @returns {string} The content with the Sources section.
+ */
+export declare function ensureSources(content: string, finalMatches: PineconeQueryMatch[]): string;
+/**
+ * Builds the system prompt for the LLM.
+ *
+ * @param {PineconeQueryMatch[]} matches - The matches.
+ * @returns {string} The system prompt.
+ */
+export declare function buildSystemPrompt(matches: PineconeQueryMatch[]): string;

package/dist/adapters/index.d.ts

@@ -1,2 +1,2 @@
 export { createMockAdapter } from "./mock";
-export { MorphexAdapter, PineconeRAGAdapter } from "./context";
+export { PineconeRAGAdapter } from "./context";

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { BmxChatBot } from "./components/BmxChatBot";
 export type { BmxChatApiAdapter, ChatMessage, ChatRole } from "./types";
-export { createMockAdapter, MorphexAdapter, PineconeRAGAdapter, } from "./adapters";
+export { createMockAdapter, PineconeRAGAdapter } from "./adapters";