aichatclient 3.5.5

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)

pip install --upgrade aichatclient