pip install aichatclient

🇬🇧 English

AiChatClient is a Python toolkit for building custom assistant workflows on top of OpenAI-compatible chat APIs. You control the assistant's identity, instructions, reference data, memory, and saved configuration, in plain Python or through the bundled Flask web chat.

✨ Features

Scope. AiChatClient is a foundation for assistant workflows. It does not include autonomous task execution, built-in external tools, semantic/vector search, or an agent planner. Implement those in your application.

📦 Install

pip install aichatclient
python -m pip install --upgrade aichatclient   # upgrade

Requirements: a supported Python version (see package metadata), an API key, an OpenAI-compatible endpoint, and network access to it. The openai SDK and Flask are installed automatically.

🚀 Quick start

export AICUSTOM_API_KEY="your-api-key"      # PowerShell: $env:AICUSTOM_API_KEY = "your-api-key"

import os
from aichatclient import AICustom

assistant = AICustom(
    api_key=os.environ["AICUSTOM_API_KEY"],
    base_url="https://api.example.com/v1",
    model_name="provider/model-name",
    nickname="my_assistant",
    system_prompt="You are a helpful programming assistant.",
)
assistant.create_model()        # saves the config (the API key is NEVER saved)

print(assistant.chat("Hello! What can you help me with?"))

for m in assistant.get_history(limit=10):
    print(m["role"], m["content"])

Next time, just load it:

assistant = AICustom.load_model("my_assistant")   # key from AICUSTOM_API_KEY

🧩 Core classes

🛠️ Create an assistant

assistant = AICustom(
    api_key=api_key,
    base_url="https://api.example.com/v1",
    model_name="provider/model-name",
    nickname="python_mentor",
    system_prompt="You are a Python mentor. Explain accurately with small examples.",
    personality="Patient, clear, and practical",
    expertise="Python programming",
    limitations="If uncertain, say so.",
    memory=True,
    conversation_id="learning-session-1",
)
assistant.create_model()

💬 Load and chat

assistant = AICustom.load_model(
    "my_assistant",
    api_key=api_key,                       # optional if AICUSTOM_API_KEY is set
    conversation_id="support-session-42",  # overrides apply to this instance only
    timeout=90,
)

assistant.chat("Explain Python decorators.")
assistant.chat("What is a decorator?", short=True)   # brief, direct reply

Overrides don't change the saved file; call create_model() to persist them. Lightweight wrapper:

from aichatclient.aiclient import AiClient

client = AiClient.load_model(name="my_assistant", api_key=api_key)
client.chat("Lists vs tuples?")
client.get_history(limit=25)

🧠 Memory & history

assistant.get_history(limit=20)                         # current model + conversation
AICustom.list_history(nickname="my_assistant",
                      conversation_id="default", limit=100)
assistant.clear_history()                               # returns deleted row count
AICustom.clear_all_history(nickname="my_assistant",
                           conversation_id="support-session-42")

⚠️ AICustom.clear_all_history() with no filters deletes every message in the database. Config files are not affected.

• Separate conversations: use a different conversation_id per user/session. IDs are labels, not access control.
• Disable memory: memory=False. Nothing is sent from history or saved; existing history stays.

📚 Reference datasets

assistant = AICustom(
    api_key=api_key,
    base_url="https://api.example.com/v1",
    model_name="provider/model-name",
    nickname="product_helper",
    system_prompt="Answer using the supplied product data.",
    dataset="data/products.jsonl",
)

Simple token-overlap matching adds up to five matching lines (within a context-size limit) to the system message. It is not embedding search, a vector DB, or fine-tuning.

🗃️ Manage saved models

assistant.create_model()                              # save non-secret config
AICustom.list_models(storage_dir="./assistant_data")  # sorted names
AICustom.delete_model("my_assistant")                 # config only; history is kept
assistant.rename_model("support_assistant")           # FileExistsError if taken

🌐 Web chat

from aichatclient import AICustom, ChatApp

ai = AICustom.load_model("my_assistant")
ChatApp(ai=ai).run(host="127.0.0.1", port=5000, debug=False)

Open http://127.0.0.1:5000. Keep host="127.0.0.1" and debug=False unless you have deliberately secured the deployment.

📁 Storage & environment variables

.ai_custom/
├── configs/<nickname>.json      # non-secret configuration
├── databases/history.sqlite3    # conversation history
├── datasets/
└── logs/

🧯 Errors & troubleshooting

• Missing API key: pass api_key= or set AICUSTOM_API_KEY. Keys are never stored, so each process needs one.
• Model not found: check AICustom.list_models() and the same storage_dir / AICUSTOM_HOME.
• Empty history: history is per model and conversation_id; check memory=True.
• Provider rejects a request: remove unsupported extra_model_params; verify base_url and model_name.

🔐 Security

1. Never hard-code or commit API keys. If a key was ever exposed, revoke it and create a new one.
2. Don't commit .ai_custom/, history databases, or private datasets.
3. Protect the storage directory; history may contain sensitive data.
4. Authenticate and authorize users in your own app.
5. Treat dataset files as untrusted input.
6. Use HTTPS endpoints.
7. Double-check the scope before clear_all_history().

🇮🇷 فارسی

pip install aichatclient
python -m pip install --upgrade aichatclient   # به‌روزرسانی

export AICUSTOM_API_KEY="your-api-key"      # PowerShell: $env:AICUSTOM_API_KEY = "your-api-key"

import os
from aichatclient import AICustom

assistant = AICustom(
    api_key=os.environ["AICUSTOM_API_KEY"],
    base_url="https://api.example.com/v1",
    model_name="provider/model-name",
    nickname="my_assistant",
    system_prompt="تو یک دستیار برنامه‌نویسی مفید هستی.",
)
assistant.create_model()        # تنظیمات ذخیره می‌شود (کلید API هرگز ذخیره نمی‌شود)

print(assistant.chat("سلام! چه کمکی از تو برمی‌آید؟"))

for m in assistant.get_history(limit=10):
    print(m["role"], m["content"])

assistant = AICustom.load_model("my_assistant")   # کلید از AICUSTOM_API_KEY خوانده می‌شود

assistant = AICustom.load_model(
    "my_assistant",
    api_key=api_key,                       # اگر AICUSTOM_API_KEY تنظیم باشد اختیاری است
    conversation_id="support-session-42",  # فقط روی همین نمونه اعمال می‌شود
    timeout=90,
)

assistant.chat("دکوراتور در پایتون چیست؟")
assistant.chat("دکوراتور چیست؟", short=True)   # پاسخ کوتاه و مستقیم

from aichatclient import AiClient

client = AiClient.load_model(name="my_assistant", api_key=api_key)
client.chat("تفاوت list و tuple چیست؟")
client.get_history(limit=25)

assistant.get_history(limit=20)                         # مدل و گفتگوی فعلی
AICustom.list_history(nickname="my_assistant",
                      conversation_id="default", limit=100)
assistant.clear_history()                               # تعداد ردیف‌های حذف‌شده را برمی‌گرداند
AICustom.clear_all_history(nickname="my_assistant",
                           conversation_id="support-session-42")

assistant = AICustom(
    api_key=api_key,
    base_url="https://api.example.com/v1",
    model_name="provider/model-name",
    nickname="product_helper",
    system_prompt="فقط بر اساس داده‌های محصول پاسخ بده.",
    dataset="data/products.jsonl",
)

assistant.create_model()                              # ذخیره‌ی تنظیمات غیرمحرمانه
AICustom.list_models(storage_dir="./assistant_data")  # فهرست مرتب‌شده‌ی نام‌ها
AICustom.delete_model("my_assistant")                 # فقط تنظیمات؛ تاریخچه می‌ماند
assistant.rename_model("support_assistant")           # اگر نام تکراری باشد FileExistsError

from aichatclient import AICustom, ChatApp

ai = AICustom.load_model("my_assistant")
ChatApp(ai=ai).run(host="127.0.0.1", port=5000, debug=False)

.ai_custom/
├── configs/<nickname>.json      # تنظیمات غیرمحرمانه
├── databases/history.sqlite3    # تاریخچه‌ی گفتگو
├── datasets/
└── logs/