Metadata-Version: 2.1
Name: aichatclient
Version: 3.6.6
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)


```

## سیستم پلاگین
برای تغیرات روی هوش مصنوعی بدون تغییر درکد اصلی کتابخانه  که میتونید رفتارشو 
شخصی سازی کنید
با این قابلیت میتونی:
- کلمات بد رو فیلتر کنی
- به پاسخ‌ها ایموجی اضافه کنی
- متن رو قبل از ارسال به 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 داخلی) |

---

## شروع سریع مثال
```python
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)  # "سلام 🤐 😊"



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


```python
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
```python
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)
```
##  مدیریت پلاگین‌ها در زمان اجرا

```python

from aichatclient import ChatGroup, ActionPlugin

# ساختن پلاگین
plugin = ActionPlugin(name="my_plugin", before_ai=lambda x: x.upper())

# ساختن کلاینت
chat = ChatGroup(
    system_prompt="تو یک دستیاری",
    api_key="your-key",
    plugins=[plugin]
)

# مدیریت در زمان اجرا
chat.disable_plugin("my_plugin")   # غیرفعال کردن
chat.enable_plugin("my_plugin")    # فعال کردن دوباره
chat.add_plugin(new_plugin)        # اضافه کردن پلاگین جدید
chat.remove_plugin("old_plugin")   # حذف پلاگین
chat.list_plugins()                # ['my_plugin', ...]


```
##  ترتیب اجرا::
ورودی کاربر
    ↓
پلاگین‌های before_ai (بر اساس priority از کوچیک به بزرگ)
    ↓
ارسال به AI + system_prompt
    ↓
دریافت پاسخ از AI
    ↓
پلاگین‌های after_ai (بر اساس priority از کوچیک به بزرگ)
    ↓
نمایش به کاربر
pip install --upgrade aichatclient
```
