Metadata-Version: 2.1
Name: aichatclient
Version: 3.5.5
Summary: A simple and extensible Python client for chatting with multiple AI models via OpenAI-compatible APIs
Home-page: https://github.com/amirhossinpython/aichatclient
Author: Amirhossein Khazaei
Author-email: 
Keywords: ai openai llm chatbot client
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: openai
Requires-Dist: py-persian-tts
Requires-Dist: flask

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

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

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

---

## ✨ ویژگی‌ها

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

---

## 📦 نصب

```bash
pip install aichatclient
```

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

---

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

```python
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

```python
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 (قابل تغییر) |

---

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

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

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

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

---

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

```python
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	نمایش خروجی زیبا در ترمینال
انواع ذخیره‌سازی
```python
@chat_log(db_type="json", db_path="my_chats.json")
def deta_json():
    print("سلام دنیا!")
    return "نتیجه تابع"
```


## نحوه استفاده :
```python
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()
```
```python
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'])

```
```python
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
```python
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()
```
```python
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` استفاده شده تا:

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

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

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

---

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

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



## 📘 مستندات کلاس ChatApp
رای راه‌اندازی یک وب‌اپلیکیشن چت با هوش مصنوعی
سازنده (Constructor)
```python
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)

## مثال‌های استفاده
```python

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



```python

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`: برای تبدیل گفتار به متن
## نمونه
**نمونه استفاده:**

```python
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
```
