🤖 Mehdi Akbari AI Assistant The most advanced React chatbot widget with RAG (Document Chat) and Function Calling

This library is a complete solution for adding AI capabilities to React and Next.js websites. Unlike other packages, this assistant can read your PDF files, connect to your website’s APIs, and respond using live streaming (ChatGPT‑style typing).

✨ Key Features 🧠 Chat with Documents (Client‑Side RAG): Provide PDF, TXT, or MD files and let the assistant answer based on them — no vector server required.

🛠 Function Calling (Tools): Let the assistant perform real actions (e.g., fetch product prices, book appointments, change website theme).

⚡ Streaming Responses: Live typing animation similar to ChatGPT.

🔌 Multi‑Provider Support: Fully compatible with Groq (fast & free) and OpenAI (GPT‑4/3.5).

🌍 Full Persian & English Support: Automatic RTL/LTR handling.

🔒 Privacy‑First: All document processing happens in the user’s browser.

📝 Markdown Rendering: Beautiful code blocks, tables, and lists.

💾 Persistent Memory: Chat history stored in LocalStorage.

📦 Installation bash npm install mehdi-akbari-ai-assistant-free zod

or

yarn add mehdi-akbari-ai-assistant-free zod Note: Installing zod is required only if you want to use the “tools” (Function Calling) feature.

🚀 Quick Start Guide

1. Import the styles In your main project file (e.g., _app.tsx or layout.tsx):

tsx import 'mehdi-akbari-ai-assistant-free/dist/styles.css'; 2. Basic Usage (with Groq) tsx import { AiAssistant } from 'mehdi-akbari-ai-assistant-free/react';

function App() { return ( <AiAssistant apiKey="gsk_..." // API key from console.groq.com provider="groq" title="AI Assistant" welcomeMessage="Hello! How can I help you today?" lang="fa" /> ); } 🛠 Advanced Feature: Function Calling (Connect to Your API) You can give the assistant “tools” so it can perform real actions — for example, fetching product prices or changing the website theme.

tsx import { z } from "zod"; // For defining tool input schemas

const myTools = [ { name: "get_product_price", description: "Returns the price of a product", schema: z.object({ productName: z.string() }), func: async ({ productName }) => { // Connect to your real API here if (productName.includes("phone")) return "$400"; return "Unavailable"; } }, { name: "change_theme", description: "Switch website theme to dark or light", schema: z.object({ mode: z.enum(["dark", "light"]) }), func: async ({ mode }) => { document.body.className = mode; return Theme changed to ${mode}.; } } ];

// Usage: 🧠 Advanced Feature: RAG (Chat with Documents) Method 1: Online Files (Direct URLs) Perfect for site rules, documentation, or user guides.

tsx <AiAssistant apiKey="..." knowledgeFileUrls={[ "https://example.com/rules.pdf", "https://example.com/guide.txt" ]} systemPrompt="Answer only based on the provided documents." /> Method 2: User‑Uploaded Files Ideal for tools like “PDF Analyzer”.

tsx const [files, setFiles] = useState<File[]>([]);

🔌 Provider Selection Choose between fast/cheap models (Groq) or smarter models (OpenAI).

Using OpenAI (ChatGPT) tsx Using Groq (Default) tsx ⚠️ Fixing Next.js Error (Module not found: fs) If you encounter an fs error in Next.js 13/14, add this to next.config.js:

js /** @type {import('next').NextConfig} */ const nextConfig = { webpack: (config, { isServer }) => { if (!isServer) { config.resolve.fallback = { ...config.resolve.fallback, fs: false, path: false, os: false, }; } return config; }, }; export default nextConfig; 🎨 Theming (Customize Appearance) Modify colors using CSS variables in your global stylesheet:

css :root { --ai-primary: #3b82f6; /* Primary color / --ai-bg: #ffffff; / Background / --ai-user-bg: #dbeafe; / User message / --ai-bot-bg: #f3f4f6; / Bot message / --ai-text: #0f172a; / Text color */ } ⚙️ Full Props API Reference Prop Name Type Default Description apiKey string required API key. provider 'groq' \ 'openai' 'groq' AI provider. tools AiTool[] [] Tools for Function Calling. model string auto AI model name. knowledgeFileUrls string[] [] URLs for RAG documents. knowledgeFiles File[] [] Local files for RAG. systemPrompt string ... Assistant behavior instructions. title string AI Assistant Chat header title. welcomeMessage string ... Initial message. lang 'fa' \ 'en' 'fa' Language & direction (RTL/LTR). persistLocally boolean true Persist chat history. lottieAnimationData string URL Floating button animation. isFullScreen boolean false Open chat in full‑screen mode. Developed with ❤️ by Mehdi Akbari

🤖 Mehdi Akbari AI Assistant

پیشرفته‌ترین ویجت چت‌بات React با قابلیت RAG (گفتگو با داکیومنت) و Function Calling

این کتابخانه یک راهکار کامل برای اضافه کردن هوش مصنوعی به وبسایت‌های React و Next.js است. بر خلاف سایر پکیج‌ها، این دستیار می‌تواند فایل‌های PDF شما را بخواند، به APIهای سایت شما متصل شود و به صورت استریم (تایپ زنده) پاسخ دهد.

✨ ویژگی‌های کلیدی

• 🧠 چت با فایل‌ها (Client-Side RAG): فایل‌های PDF، TXT یا MD را به ربات بدهید تا بر اساس آن‌ها پاسخ دهد (بدون نیاز به سرور وکتور).
• 🛠 اجرای دستورات (Function Calling): ربات می‌تواند کارهای واقعی انجام دهد (مثل استعلام قیمت، رزرو وقت، تغییر تم سایت).
• ⚡ پاسخ‌دهی جریانی (Streaming): تایپ شدن کلمات به صورت زنده (مانند ChatGPT).
• 🔌 پشتیبانی از چند سرویس: سازگاری کامل با Groq (رایگان و سریع) و OpenAI (GPT-4/3.5).
• 🌍 کاملاً فارسی و انگلیسی: پشتیبانی خودکار از راست‌چین (RTL) و چپ‌چین (LTR).
• 🔒 حریم خصوصی: پردازش فایل‌ها در مرورگر کاربر انجام می‌شود.
• 📝 پشتیبانی از Markdown: نمایش زیبای کدها (Syntax Highlighting)، جداول و لیست‌ها.
• 💾 حافظه پایدار: ذخیره تاریخچه چت در LocalStorage.

📦 نصب

npm install mehdi-akbari-ai-assistant-free zod
# یا
yarn add mehdi-akbari-ai-assistant-free zod

نکته: نصب zod فقط در صورتی اجباری است که بخواهید از قابلیت "ابزارها" استفاده کنید.

🚀 راهنمای استفاده سریع
۱. ایمپورت استایل‌ها

در فایل اصلی پروژه (مثلاً _app.tsx یا layout.tsx) استایل‌ها را فراخوانی کنید:

code
Tsx
download
content_copy
expand_less
import 'mehdi-akbari-ai-assistant-free/dist/styles.css';
۲. استفاده ساده (با Groq)
code
Tsx
download
content_copy
expand_less
import { AiAssistant } from 'mehdi-akbari-ai-assistant-free/react';

function App() {
  return (
    <div className="App">
      <AiAssistant 
        apiKey="gsk_..." // کلید API از console.groq.com
        provider="groq"
        title="دستیار هوشمند"
        welcomeMessage="سلام! چطور می‌توانم کمکتان کنم؟"
        lang="fa"
      />
    </div>
  );
}
🛠 قابلیت پیشرفته: اتصال به API (Function Calling)

شما می‌توانید به ربات "ابزار" بدهید تا کارهای واقعی انجام دهد. مثلاً گرفتن قیمت ارز یا لیست محصولات.

code
Tsx
download
content_copy
expand_less
import { z } from "zod"; // برای تعریف ورودی توابع

const myTools = [
  {
    name: "get_product_price",
    description: "قیمت یک محصول را برمی‌گرداند",
    schema: z.object({ productName: z.string() }),
    func: async ({ productName }) => {
      // اینجا می‌توانید به API واقعی خود وصل شوید
      if (productName.includes("گوشی")) return "۲۰,۰۰۰,۰۰۰ تومان";
      return "ناموجود";
    }
  },
  {
    name: "change_theme",
    description: "تغییر تم سایت به تاریک یا روشن",
    schema: z.object({ mode: z.enum(["dark", "light"]) }),
    func: async ({ mode }) => {
      document.body.className = mode;
      return `تم سایت به ${mode} تغییر کرد.`;
    }
  }
];

// استفاده در کامپوننت:
<AiAssistant 
  apiKey="..." 
  tools={myTools} 
  welcomeMessage="من می‌توانم قیمت‌ها را چک کنم یا تم سایت را عوض کنم!"
/>
🧠 قابلیت پیشرفته: گفتگو با داکیومنت (RAG)
روش اول: فایل‌های آنلاین (لینک مستقیم)

مناسب برای آموزش قوانین سایت یا داکیومنت‌های فنی.

code
Tsx
download
content_copy
expand_less
<AiAssistant 
  apiKey="..."
  knowledgeFileUrls={[
    "https://example.com/rules.pdf",
    "https://example.com/guide.txt"
  ]}
  systemPrompt="فقط بر اساس فایل‌های داده شده پاسخ بده."
/>
روش دوم: فایل‌های آپلود شده توسط کاربر

مناسب برای ساخت ابزارهایی مثل "آنالیزور PDF".

code
Tsx
download
content_copy
expand_less
const [files, setFiles] = useState<File[]>([]);

<AiAssistant 
  apiKey="..."
  knowledgeFiles={files} 
/>
🔌 انتخاب سرویس‌دهنده (Provider)

شما می‌توانید بین مدل‌های ارزان/سریع (Groq) و مدل‌های هوشمندتر (OpenAI) انتخاب کنید.

استفاده با OpenAI (ChatGPT):

code
Tsx
download
content_copy
expand_less
<AiAssistant 
  apiKey="sk-proj-..." 
  provider="openai"
  model="gpt-4-turbo"
/>

استفاده با Groq (پیش‌فرض):

code
Tsx
download
content_copy
expand_less
<AiAssistant 
  apiKey="gsk_..." 
  provider="groq" 
  model="llama-3.1-8b-instant"
/>
⚠️ رفع خطای Next.js (Module not found: fs)

اگر در Next.js 13/14 با خطای fs مواجه شدید، کد زیر را به next.config.js اضافه کنید:

code
JavaScript
download
content_copy
expand_less
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        fs: false,
        path: false,
        os: false,
      };
    }
    return config;
  },
};
export default nextConfig;
🎨 شخصی‌سازی ظاهر (Theming)

رنگ‌ها را با CSS Variables در فایل استایل گلوبال خود تغییر دهید:

code
CSS
download
content_copy
expand_less
:root {
  --ai-primary: #3b82f6;       /* رنگ اصلی */
  --ai-bg: #ffffff;            /* پس‌زمینه */
  --ai-user-bg: #dbeafe;       /* پیام کاربر */
  --ai-bot-bg: #f3f4f6;        /* پیام ربات */
  --ai-text: #0f172a;          /* رنگ متن */
}
⚙️ لیست کامل پراپ‌ها (API Reference)
نام پراپ	نوع	پیش‌فرض	توضیحات
apiKey	string	الزامی	کلید API.
provider	'groq' | 'openai'	'groq'	انتخاب سرویس‌دهنده.
tools	AiTool[]	[]	لیست ابزارها برای Function Calling.
model	string	(auto)	نام مدل هوش مصنوعی.
knowledgeFileUrls	string[]	[]	لینک فایل‌ها برای RAG.
knowledgeFiles	File[]	[]	فایل‌های لوکال برای RAG.
systemPrompt	string	...	دستورالعمل رفتار ربات.
title	string	AI Assistant	عنوان هدر چت.
welcomeMessage	string	...	پیام شروع.
lang	'fa' | 'en'	'fa'	زبان و جهت (RTL/LTR).
persistLocally	boolean	true	ذخیره تاریخچه چت.
lottieAnimationData	string	URL	لینک انیمیشن دکمه شناور.
isFullScreen	boolean	false	باز شدن به صورت تمام صفحه.

Developed with ❤️ by Mehdi Akbari