najm-chatbot

Abstracts multiple LLM providers (OpenAI, Anthropic, Ollama, etc.) behind a unified factory interface, allowing runtime provider selection and swapping without code changes. Implements a provider registry pattern that normalizes API differences across vendors, handling authentication, request/response transformation, and error mapping to a common schema.

Bridges Model Context Protocol (MCP) tool definitions into a schema-based function registry that normalizes tool calling across different LLM providers. Converts MCP tool schemas into provider-native function calling formats (OpenAI functions, Anthropic tools, etc.), handles tool invocation routing, and manages request/response marshaling between the LLM and tool implementations.

Provides a centralized configuration system for AI behavior parameters (temperature, max tokens, system prompts, model selection, provider settings) with environment variable and file-based overrides. Implements a settings hierarchy that allows global defaults, per-conversation overrides, and runtime adjustments without redeploying the application.

Implements a stateful chat agent that maintains conversation history, manages context windows, and orchestrates multi-turn interactions with LLMs. Handles message accumulation, context truncation strategies (sliding window, summarization), and state persistence across requests. Integrates with the LLM provider factory and MCP tool adapter to enable tool-augmented conversations.

Provides pre-built React components for rendering chat interfaces (message list, input field, typing indicators, tool call visualization) with hooks for state management and event handling. Components are styled and composable, allowing developers to embed chat UI into React applications with minimal custom code. Integrates with the chat agent via props/callbacks for message sending and state updates.

Defines an abstraction layer for persisting and retrieving conversation state (message history, agent state, metadata) to external storage backends. Supports pluggable storage adapters (database, Redis, file system) with a common interface, enabling applications to choose persistence strategy without changing agent code. Handles serialization/deserialization and optional encryption of sensitive conversation data.

Provides a templating system for defining and managing system prompts with variable substitution, allowing dynamic prompt construction based on conversation context, user metadata, or runtime parameters. Supports prompt versioning and A/B testing of different instruction sets. Integrates with the chat agent to inject system prompts at conversation start or dynamically update them mid-conversation.

Implements error handling patterns for LLM API failures (rate limits, timeouts, invalid responses) with configurable fallback strategies (retry with backoff, provider failover, cached response fallback). Normalizes errors across different LLM providers into a common error schema, enabling consistent error handling in application code. Supports circuit breaker pattern to prevent cascading failures.

Provides utilities for estimating token usage before sending requests to LLMs, tracking cumulative tokens in a conversation, and enforcing context window limits. Implements provider-specific token counting (using provider APIs or local approximations) and automatically truncates or summarizes messages when approaching token limits. Integrates with the chat agent to prevent context window overflow.

Implements streaming support for LLM responses, allowing partial responses to be rendered progressively as tokens arrive rather than waiting for the complete response. Handles stream parsing, error recovery within streams, and integration with React UI components for real-time message updates. Supports both server-sent events (SSE) and WebSocket streaming protocols.