aichatclient 3.6.7

A simple and extensible Python client for chatting with multiple AI models via OpenAI-compatible APIs

🤖 AiClient – کتابخانه چت با هوش مصنوعی (Python)

یک کتابخانه‌ی ساده، تمیز و قابل‌انتشار برای ارتباط با مدل‌های مختلف هوش مصنوعی (LLM) با استفاده از SDK رسمی OpenAI و پشتیبانی از Base URL سفارشی (مانند Liara AI).

این پروژه برای توسعه‌دهندگانی ساخته شده که می‌خواهند بدون درگیری با جزئیات پیچیده، به‌سرعت یک سیستم چت هوشمند، دستیار AI یا API مبتنی بر LLM بسازند.

---

✨ ویژگی‌ها

• ✅ پشتیبانی از مدل‌های متنوع (OpenAI، Google، Anthropic، Qwen، Grok و ...)
• ✅ مدیریت ساده System Prompt
• ✅ قابلیت استفاده با Base URL سفارشی
• ✅ ساختار مینیمال و قابل توسعه
• ✅ مناسب برای پروژه‌های واقعی و انتشار عمومی
• ✅ مدیریت خطا به‌صورت ایمن و خوانا -✅ با ویس هوش مصنوعی

---

📦 نصب

pip install aichatclient

Python نسخه 3.8 یا بالاتر موردنیاز است.

---

🚀 شروع سریع (Quick Start)

from aichatclient import AiClient
system_prompt = ""
chat = AiClient(
    system_prompt=system_prompt,
    api_key="",
    base_url="https://ai.liara.ir/api/v1/",
    model="openai/gpt-4o-mini",
    voice="man1"   # اختیاری برای تبدیل متن به ویس
)

response = ai.chat("سلام، خودتو معرفی کن")
print(response)

#  استفاده از متد چت با ویس
chat.chat_voice("سلام اسمتچیه")

---

🧠 ساختار کلاس AiClient

Constructor

AiClient(system_prompt, api_key, model, base_url="https://ai.liara.ir/api/v1")

پارامترها

پارامتر	نوع	توضیح
system_prompt	str	پیام سیستمی برای کنترل رفتار مدل
api_key	str	کلید API سرویس هوش مصنوعی
model	str	نام مدل انتخابی
base_url	str	آدرس API (قابل تغییر)

---

📚 دریافت لیست مدل‌ها

برای مشاهده مدل‌های پشتیبانی‌شده:

models = ai.list_model()
for model in models:
    print(model)

📌 این طراحی باعث می‌شود کتابخانه به یک سرویس خاص وابسته نباشد.

---

💬 ارسال پیام (Chat)

reply = ai.chat("هوش مصنوعی چیست؟")
print(reply)

قابلیت ذخیره خودکار مکالمات (Auto Logging)

معرفی این قابلیت به شما امکان می‌دهد تمام مکالمات خود را به صورت خودکار در فایل JSON یا دیتابیس SQLite ذخیره کنید.

📝 تابع chat_log - دکوراتور ذخیره‌سازی خودکار مکالمات

🎯 معرفی

دکوراتور chat_log یک ابزار قدرتمند برای ذخیره‌سازی خودکار مکالمات و خروجی‌های توابع است. این دکوراتور می‌تواند مکالمات را در فرمت‌های JSON، SQLite یا هر دو به صورت همزمان ذخیره کند.

---

✨ ویژگی‌ها

• ✅ ذخیره خودکار خروجی return و print
• ✅ پشتیبانی از JSON و SQLite
• ✅ تولید شناسه یکتا برای هر مکالمه
• ✅ ذخیره زمان به صورت فارسی و میلادی
• ✅ نمایش زیبا و کاربردی خروجی
• ✅ کار کردن حتی بدون return
• ✅ ذخیره اطلاعات کلاینت (system_prompt, model)
• ✅ مدیریت خطاهای احتمالی

---

📦 نحوه استفاده

سینتکس پایه

پارامتر نوع پیش‌فرض توضیحات db_type str "json" نوع ذخیره‌سازی: "json"، "sqlite" یا "both" db_path str "chat_logs" مسیر فایل یا دایرکتوری ذخیره‌سازی pretty_print bool True نمایش خروجی زیبا در ترمینال انواع ذخیره‌سازی

@chat_log(db_type="json", db_path="my_chats.json")
def deta_json():
    print("سلام دنیا!")
    return "نتیجه تابع"

نحوه استفاده :

from aichatclient import AiClient, chat_log

@chat_log(db_type="json", db_path="my_chats.json")
def main():
    chat = AiClient(
        system_prompt="تو یک دستیار هستی",
        api_key="your-api-key",
        model="gpt4o",
        voice = "man3" # اختیاری 
    )
    
    response = chat.chat("سلام چطوری؟")
    print(response)
    
    return response  # مهم: حتماً response رو برگردون



if __name__ == "__main__":
    main()

from aichatclient import ChatDB

# نمایش 5 مکالمه آخر
ChatDB.list_all(db_path="chats/chat.json", limit=5)

# پیدا کردن مکالمه خاص
conv = ChatDB.find("a3f9d2c1", db_path="chats/voice_chat")
if conv:
    print(conv['timestamp_fa'])
    print(conv['return_value'])

from aichatclient import AiClient

client = AiClient(
    system_prompt="تو یک متخصص پایتون هستی",
    api_key="your-api-key",
    base_url="https://api.gapgpt.app/v1",
    model="gpt-4o",
    voice="man1"
)

# چت متنی
response = client.chat("دکوراتور چیست؟")
print(response)

# چت صوتی
voice_response = client.chat_voice("لطفاً یک شعر بگو")
print(voice_response)

# نمایش مدل‌ها
models = client.list_model()
print(models)

نمونه استفاده ChatGroup

from aichatclient import ChatGroup, chat_log

@chat_log(db_type="json", db_path="group_test.json", pretty_print=True)
def test_chatgroup():
    group = ChatGroup(
        system_prompt="تو یک دستیار حرفه‌ای هستی",
        api_key="",
        base_url="https://api.gapgpt.app/v1"
    )
    
    # تست مدل‌های مختلف
    result1 = group.gpt4o("سلام! بگو چه خبر؟")
    result2 = group.gapgpt_qwen_3_5("یک شعر کوتاه بگو")
    
    return f"GPT-4o: {result1}\nQwen: {result2}"

test_chatgroup()

from aichatclient import ChatGroup


img = ChatGroup(
    system_prompt='',
    api_key='',
    base_url=''
)


img.generate_image("image hacker")

متد های در تابع ChatGroup

┌─────────────────────┬─────────────────────────────────────────────────────┐ │ متد │ توضیحات │ ├─────────────────────┼─────────────────────────────────────────────────────┤ │ gpt4o(text) │ چت با مدل GPT-4o │ │ gapgpt_qwen_3_5(text)│ چت با مدل Qwen 3.5 │ │ generate_image(text)│ تولید تصویر با متن │ │ voice_text(file) │ تبدیل فایل صوتی به متن │

لیست صدا ها در متد chat_voice

═════════════ 🎵 صداهای موجود ═══════════════════════════════════════════════════════════════════════════════

┌────────────┬──────────────────┐ │ نام صدا │ توضیحات │ ├────────────┼──────────────────┤ │ man1 │ راد │ │ man2 │ پیام │ │ man3 │ بهمن │ │ man4 │ برنا │ │ man5 │ کیان │ │ man6 │ نیما │ │ man7 │ آریا │ │ woman1 │ شیوا │ │ woman2 │ مهتاب │ │ woman3 │ نگار │ │ woman4 │ ریما │ │ boy1 │ آرش │ └────────────┴──────────────────┘

خروجی

• در حالت موفق: str (پاسخ مدل)
• در حالت خطا: پیام خطای قابل فهم به زبان فارسی

---

🛡️ مدیریت خطا

در متد chat از try / except استفاده شده تا:

• برنامه کرش نکند
• خطاها قابل ردیابی باشند
• تجربه توسعه‌دهنده بهتر شود

نمونه خروجی خطا:

خطا در ارتباط با API: Connection timeout

---

🏗️ موارد استفاده (Use Cases)

• 🤖 ربات چت
• 🧠 دستیار هوشمند
• 🌐 API هوش مصنوعی
• 🛠️ ابزارهای مبتنی بر LLM
• 📊 تحلیل متن و تولید محتوا -وب اپ داخلی

📘 مستندات کلاس ChatApp

رای راه‌اندازی یک وب‌اپلیکیشن چت با هوش مصنوعی سازنده (Constructor)

ChatApp(api_key, base_url, system_prompt, model="openai/gpt-4o-mini")

پارامترها: پارامتر نوع توضیحات api_key= str کلید API برای دسترسی به سرویس هوش مصنوعی base_url= str آدرس پایه API system_prompt= str پرامپت سیستم (نحوه رفتار ربات) model= str مدل مورد استفاده

متدها

run(host='0.0.0.0', port=5000, debug=False)

مثال‌های استفاده

from aichatclient import ChatApp

app = ChatApp(
    api_key="your-api-key-here",
    base_url="https://ai.liara.ir/api/v1/your-endpoint",
    system_prompt="تو یک دستیار مفید و دوستانه هستی. به زبان فارسی پاسخ بده."
)

app.run(port=5000)

کلاس : ChatGroup

from aichatclient import  AiClient


chat = AiClient(
    system_prompt='bot',
    api_key='sk-',
    base_url='https://api.gapgpt.app/v1',
    model='gpt-4o'
    
)


print(chat.chat("hi"))

متدهای کلاس ChatGroup: این کلاس قدرتمند، ورودی‌های کلیدی مانند system_prompt، api_key و base_url را می‌پذیرد و شامل متدهای زیر است:

• gpt4o: برای تعامل با مدل GPT-4o
• generate_image: برای تولید تصاویر با هوش مصنوعی
• gapgpt_qwen_3_5: پشتیبانی از مدل Qwen 3.5
• voice_text: برای تبدیل گفتار به متن

نمونه

نمونه استفاده:

from aichatclient import ChatGroup

chat = ChatGroup(
system_prompt='', # اینجا مقدار پیش‌فرض یا دلخواه را قرار دهید
api_key='', # کلید API خود را اینجا قرار دهید
base_url='', # URL پایه سرویس خود را اینجا قرار دهید
model='gpt-4o' # یا هر مدل دیگری که می‌خواهید استفاده کنید
)

aichat = chat.gpt4o('hi')

print(aichat)
# ساخت تصویر باهوش مصنوعی
image_response = chat.generate_image(prompt="یک منظره زیبا از کوهستان")
print(image_response)

سیستم پلاگین

برای تغیرات روی هوش مصنوعی بدون تغییر درکد اصلی کتابخانه که میتونید رفتارشو شخصی سازی کنید با این قابلیت میتونی:

• کلمات بد رو فیلتر کنی
• به پاسخ‌ها ایموجی اضافه کنی
• متن رو قبل از ارسال به AI تغییر بدی
• پاسخ AI رو بعد از دریافت تغییر بدی
• فقط در شرایط خاص پلاگین رو اجرا کنی
• چندین پلاگین رو با اولویت‌های مختلف اجرا کنی

---

ساختار اصلی

کلاس ActionPlugin

برای ساختن یک پلاگین جدید استفاده میشه. که پارامتر های این کلاس :

پارامتر	نوع	پیش‌فرض	توضیح
name	str	الزامی	اسم یکتا برای پلاگین
before_ai	function	None	تابع قبل از ارسال (ورودی: متن کاربر، خروجی: متن جدید)
after_ai	function	None	تابع بعد از دریافت (ورودی: پاسخ AI، خروجی: پاسخ جدید)
condition	function	None	شرط اجرا (اگر True برگردونه، پلاگین اجرا میشه)
priority	int	0	اولویت (عدد کمتر = زودتر اجرا میشه)
enabled	bool	True	فعال/غیرفعال بودن

متدهای کلاس

متد	ورودی	خروجی	توضیح
execute_before(text)	str	str	اجرای تابع before_ai روی متن
execute_after(text)	str	str	اجرای تابع after_ai روی متن

---

کلاس PluginManager

برای مدیریت چندین پلاگین با هم.

متدها

متد	ورودی	خروجی	توضیح
register(plugin)	ActionPlugin	self	اضافه کردن پلاگین
unregister(name)	str	None	حذف پلاگین با اسم
enable(name)	str	None	فعال کردن پلاگین
disable(name)	str	None	غیرفعال کردن پلاگین
process_before(text)	str	str	اجرای همه before_ai ها
process_after(text)	str	str	اجرای همه after_ai ها

---

کلاس‌هایی که از پلاگین پشتیبانی میکنن

کلاس	متدهای پشتیبانی شده
AiClient	chat()
ChatGroup	gpt4o(), generate_image(), gapgpt_qwen_3_5(), voice_text()
ChatApp	(از طریق AiClient داخلی)

---

شروع سریع مثال

from aichatclient import ActionPlugin, AiClient

# تعریف توابع
def filter_bad_words(text):
    return text.replace("خر", "***").replace("احمق", "🤐")

def add_emoji(text):
    return text + " 😊"

# ساخت پلاگین
my_plugin = ActionPlugin(
    name="my_filter",
    before_ai=filter_bad_words,
    after_ai=add_emoji
)

# استفاده در کلاینت
client = AiClient(
    system_prompt="تو یک دستیاری",
    api_key="your-key",
    model="gpt-4o",
    base_url="https://api.gapgpt.app/v1",
    plugins=[my_plugin]
)

response = client.chat("سلام احمق ")
print(response)  # "سلام 🤐 😊"

پلاگین با شرط:

# فقط برای متن‌های بلند اجرا بشه

def only_long_text(text):
    return len(text) > 20

plugin = ActionPlugin(
    name="long_only",
    before_ai=lambda x: f"[متن بلند]: {x}",
    condition=only_long_text
)

پلاگین با اولویت

اولویت 0 اول اجرا میشه، بعد 1، بعد 2

plugin1 = ActionPlugin(name="first", before_ai=lambda x: f"1-{x}", priority=0)
plugin2 = ActionPlugin(name="second", before_ai=lambda x: f"2-{x}", priority=1)
plugin3 = ActionPlugin(name="third", before_ai=lambda x: f"3-{x}", priority=2)

ترتیب اجرا::

ورودی کاربر ↓ پلاگین‌های before_ai (بر اساس priority از کوچیک به بزرگ) ↓ ارسال به AI + system_prompt ↓ دریافت پاسخ از AI ↓ پلاگین‌های after_ai (بر اساس priority از کوچیک به بزرگ) ↓

نمایش به کاربر

pip install --upgrade aichatclient