irovanai 0.2.1__tar.gz

irovanai-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Irovan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

irovanai-0.2.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE README.md
+recursive-include src/irovanai py.typed

irovanai-0.2.1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.1
+Name: irovanai
+Version: 0.2.1
+Summary: Fast, dependency-free Python client for Irovan AI (کتابخانه پایتون آیروان)
+Author: Irovan
+License: MIT
+Project-URL: Homepage, https://github.com/irovan/irovanai
+Project-URL: Repository, https://github.com/irovan/irovanai.git
+Project-URL: Issues, https://github.com/irovan/irovanai/issues
+Keywords: irovan,ai,chatbot,persian,farsi,api,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# irovanai
+
+کتابخانه **سریع** و **بدون وابستگی** پایتون برای هوش مصنوعی آیروان (`irovan-slim` / `plus`).
+
+- ⚡ اتصال پایدار (keep-alive): درخواست‌های بعدی بدون ساخت دوباره‌ی اتصال
+- 🔁 تلاش مجدد خودکار برای خطای شبکه، ۵xx و ۴۲۹
+- 🚀 ارسال هم‌زمان چند پیام با `chat_many`
+- 🧠 گفتگو با حافظه (`session`)
+- 🖼 تحلیل و ساخت تصویر
+- ⏱ نسخه‌ی `async`
+- 📦 فقط کتابخانه‌ی استاندارد پایتون؛ روی گوشی (Pydroid / Termux) هم کار می‌کند
+
+## نصب
+
+```bash
+pip install irovanai
+```
+
+یا از گیت‌هاب:
+
+```bash
+pip install git+https://github.com/irovan/irovanai.git
+```
+
+اگر `git` ندارید (مثلاً Pydroid):
+
+```bash
+pip install https://github.com/irovan/irovanai/archive/refs/heads/main.zip
+```
+
+یا فقط فایل `irovanai.py` را کنار کد خودتان بگذارید؛ نیازی به نصب نیست.
+
+## دریافت کلید API
+
+کلید را از پلتفرم توسعه‌دهندگان آیروان بگیرید: https://chat.irovan.ir
+
+## شروع سریع
+
+```python
+from irovanai import Irovan
+
+ai = Irovan(api_key="YOUR_API_KEY")
+print(ai.chat("سلام"))
+```
+
+کلید را می‌توانید در متغیر محیطی بگذارید:
+
+```bash
+export IROVAN_API_KEY="YOUR_API_KEY"   # ویندوز: set IROVAN_API_KEY=...
+```
+
+```python
+ai = Irovan()
+```
+
+میان‌بر یک‌خطی:
+
+```python
+from irovanai import ask
+print(ask("سلام", api_key="YOUR_API_KEY"))
+```
+
+## مدل‌ها
+
+```python
+ai.chat("سلام", model="slim")   # سریع و سبک
+ai.chat("سلام", model="plus")   # قوی‌تر
+```
+
+## ارسال هم‌زمان (سرعت بالا)
+
+```python
+rs = ai.chat_many(["سلام", "پایتون چیست؟", "یک جوک بگو"], workers=8)
+for r in rs:
+    print(r.reply)
+```
+
+ترتیب خروجی همان ترتیب ورودی است. با `return_exceptions=True` خطاها به‌جای متوقف‌کردن کار، در لیست برمی‌گردند.
+
+## کش پاسخ
+
+```python
+ai = Irovan(api_key="...", cache_size=100)  # پیام متنی تکراری دوباره به سرور نمی‌رود
+```
+
+## گفتگو با حافظه
+
+```python
+c = ai.session(system="تو یک دستیار مودب هستی.")
+c.send("اسم من علی است")
+print(c.send("اسم من چیست؟"))
+c.reset()
+```
+
+> تاریخچه داخل متن پیام ارسال می‌شود، چون API هر درخواست را مستقل دریافت می‌کند.
+
+## تصویر
+
+```python
+print(ai.analyze_image("photo.png", "این تصویر چه چیزی را نشان می‌دهد؟"))
+
+ai.generate_image("یک خیار تازه روی پس‌زمینه سفید").save("cucumber.png")
+```
+
+## Async
+
+```python
+import asyncio
+from irovanai import AsyncIrovan
+
+async def main():
+    ai = AsyncIrovan(api_key="YOUR_API_KEY")
+    rs = await ai.chat_many(["سلام", "خوبی؟"])
+    print([r.reply for r in rs])
+
+asyncio.run(main())
+```
+
+## خط فرمان
+
+```bash
+irovanai "سلام" -m slim
+irovanai "این چیست؟" -m plus -i photo.png
+irovanai                      # گفتگوی تعاملی
+python -m irovanai "سلام"     # روش دیگر
+```
+
+## تنظیمات
+
+```python
+Irovan(
+    api_key="...",
+    model="slim",
+    timeout=120,     # مهلت هر درخواست (ثانیه)
+    retries=2,       # تلاش مجدد
+    cache_size=0,    # 0 = بدون کش
+)
+```
+
+## مدیریت خطا
+
+```python
+from irovanai import Irovan, AuthenticationError, RateLimitError, NetworkError, APIError
+
+try:
+    print(Irovan(api_key="...").chat("سلام"))
+except AuthenticationError:
+    print("کلید نامعتبر است")
+except RateLimitError:
+    print("درخواست زیاد؛ کمی بعد تلاش کنید")
+except NetworkError as e:
+    print("مشکل شبکه:", e)
+except APIError as e:
+    print("خطای سرور:", e, e.status_code)
+```
+
+## پیام خوش‌آمدگویی
+
+هنگام اولین ساخت کلاینت در هر اجرا، عبارت `Welcome irovanai` چاپ می‌شود. برای خاموش‌کردن:
+
+```bash
+export IROVAN_QUIET=1   # ویندوز: set IROVAN_QUIET=1
+```
+
+## تست
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## مجوز
+
+MIT

irovanai-0.2.1/README.md

@@ -0,0 +1,174 @@
+# irovanai
+
+کتابخانه **سریع** و **بدون وابستگی** پایتون برای هوش مصنوعی آیروان (`irovan-slim` / `plus`).
+
+- ⚡ اتصال پایدار (keep-alive): درخواست‌های بعدی بدون ساخت دوباره‌ی اتصال
+- 🔁 تلاش مجدد خودکار برای خطای شبکه، ۵xx و ۴۲۹
+- 🚀 ارسال هم‌زمان چند پیام با `chat_many`
+- 🧠 گفتگو با حافظه (`session`)
+- 🖼 تحلیل و ساخت تصویر
+- ⏱ نسخه‌ی `async`
+- 📦 فقط کتابخانه‌ی استاندارد پایتون؛ روی گوشی (Pydroid / Termux) هم کار می‌کند
+
+## نصب
+
+```bash
+pip install irovanai
+```
+
+یا از گیت‌هاب:
+
+```bash
+pip install git+https://github.com/irovan/irovanai.git
+```
+
+اگر `git` ندارید (مثلاً Pydroid):
+
+```bash
+pip install https://github.com/irovan/irovanai/archive/refs/heads/main.zip
+```
+
+یا فقط فایل `irovanai.py` را کنار کد خودتان بگذارید؛ نیازی به نصب نیست.
+
+## دریافت کلید API
+
+کلید را از پلتفرم توسعه‌دهندگان آیروان بگیرید: https://chat.irovan.ir
+
+## شروع سریع
+
+```python
+from irovanai import Irovan
+
+ai = Irovan(api_key="YOUR_API_KEY")
+print(ai.chat("سلام"))
+```
+
+کلید را می‌توانید در متغیر محیطی بگذارید:
+
+```bash
+export IROVAN_API_KEY="YOUR_API_KEY"   # ویندوز: set IROVAN_API_KEY=...
+```
+
+```python
+ai = Irovan()
+```
+
+میان‌بر یک‌خطی:
+
+```python
+from irovanai import ask
+print(ask("سلام", api_key="YOUR_API_KEY"))
+```
+
+## مدل‌ها
+
+```python
+ai.chat("سلام", model="slim")   # سریع و سبک
+ai.chat("سلام", model="plus")   # قوی‌تر
+```
+
+## ارسال هم‌زمان (سرعت بالا)
+
+```python
+rs = ai.chat_many(["سلام", "پایتون چیست؟", "یک جوک بگو"], workers=8)
+for r in rs:
+    print(r.reply)
+```
+
+ترتیب خروجی همان ترتیب ورودی است. با `return_exceptions=True` خطاها به‌جای متوقف‌کردن کار، در لیست برمی‌گردند.
+
+## کش پاسخ
+
+```python
+ai = Irovan(api_key="...", cache_size=100)  # پیام متنی تکراری دوباره به سرور نمی‌رود
+```
+
+## گفتگو با حافظه
+
+```python
+c = ai.session(system="تو یک دستیار مودب هستی.")
+c.send("اسم من علی است")
+print(c.send("اسم من چیست؟"))
+c.reset()
+```
+
+> تاریخچه داخل متن پیام ارسال می‌شود، چون API هر درخواست را مستقل دریافت می‌کند.
+
+## تصویر
+
+```python
+print(ai.analyze_image("photo.png", "این تصویر چه چیزی را نشان می‌دهد؟"))
+
+ai.generate_image("یک خیار تازه روی پس‌زمینه سفید").save("cucumber.png")
+```
+
+## Async
+
+```python
+import asyncio
+from irovanai import AsyncIrovan
+
+async def main():
+    ai = AsyncIrovan(api_key="YOUR_API_KEY")
+    rs = await ai.chat_many(["سلام", "خوبی؟"])
+    print([r.reply for r in rs])
+
+asyncio.run(main())
+```
+
+## خط فرمان
+
+```bash
+irovanai "سلام" -m slim
+irovanai "این چیست؟" -m plus -i photo.png
+irovanai                      # گفتگوی تعاملی
+python -m irovanai "سلام"     # روش دیگر
+```
+
+## تنظیمات
+
+```python
+Irovan(
+    api_key="...",
+    model="slim",
+    timeout=120,     # مهلت هر درخواست (ثانیه)
+    retries=2,       # تلاش مجدد
+    cache_size=0,    # 0 = بدون کش
+)
+```
+
+## مدیریت خطا
+
+```python
+from irovanai import Irovan, AuthenticationError, RateLimitError, NetworkError, APIError
+
+try:
+    print(Irovan(api_key="...").chat("سلام"))
+except AuthenticationError:
+    print("کلید نامعتبر است")
+except RateLimitError:
+    print("درخواست زیاد؛ کمی بعد تلاش کنید")
+except NetworkError as e:
+    print("مشکل شبکه:", e)
+except APIError as e:
+    print("خطای سرور:", e, e.status_code)
+```
+
+## پیام خوش‌آمدگویی
+
+هنگام اولین ساخت کلاینت در هر اجرا، عبارت `Welcome irovanai` چاپ می‌شود. برای خاموش‌کردن:
+
+```bash
+export IROVAN_QUIET=1   # ویندوز: set IROVAN_QUIET=1
+```
+
+## تست
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## مجوز
+
+MIT

irovanai-0.2.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "irovanai"
+dynamic = ["version"]
+description = "Fast, dependency-free Python client for Irovan AI (کتابخانه پایتون آیروان)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Irovan" }]
+dependencies = []
+keywords = ["irovan", "ai", "chatbot", "persian", "farsi", "api", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/irovan/irovanai"
+Repository = "https://github.com/irovan/irovanai.git"
+Issues = "https://github.com/irovan/irovanai/issues"
+
+[project.scripts]
+irovanai = "irovanai:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "irovanai.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+irovanai = ["py.typed"]

irovanai-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

irovanai-0.2.1/src/irovanai/__init__.py

@@ -0,0 +1,498 @@
+"""
+irovanai - کتابخانه پایتون برای API هوش مصنوعی آیروان (Irovan AI)
+
+بدون هیچ وابستگی خارجی (فقط کتابخانه استاندارد پایتون)، با اتصال پایدار (keep-alive)،
+تلاش مجدد خودکار، ارسال هم‌زمان چند درخواست، نسخه async و حافظه گفتگو.
+
+    from irovanai import Irovan
+    ai = Irovan(api_key="YOUR_API_KEY")
+    print(ai.chat("سلام"))
+"""
+import argparse
+import asyncio
+import base64
+import functools
+import gzip
+import http.client
+import json
+import mimetypes
+import os
+import re
+import socket
+import ssl
+import sys
+import threading
+import time
+import urllib.request
+import zlib
+from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+from urllib.parse import urlparse
+
+__version__ = "0.2.1"
+__all__ = [
+    "Irovan", "AsyncIrovan", "Chat", "Response", "encode_image", "ask",
+    "IrovanError", "AuthenticationError", "APIError", "RateLimitError", "NetworkError",
+]
+
+DEFAULT_BASE_URL = "https://chat.irovan.ir"
+DEFAULT_MODEL = "slim"
+ENV_KEY = "IROVAN_API_KEY"
+USER_AGENT = "irovanai/" + __version__
+
+QUIET_ENV = "IROVAN_QUIET"
+_banner_shown = False
+
+_RETRY_STATUS = (429, 500, 502, 503, 504)
+_URL_RE = re.compile(r"https?://[^\s\"'<>)\]]+")
+_DATA_RE = re.compile(r"data:image/[a-zA-Z0-9.+-]+;base64,[A-Za-z0-9+/=]+")
+
+
+def _show_banner() -> None:
+    """پیام خوش‌آمدگویی را یک‌بار در هر اجرا چاپ می‌کند (با IROVAN_QUIET=1 خاموش می‌شود)."""
+    global _banner_shown
+    if _banner_shown or os.environ.get(QUIET_ENV):
+        return
+    _banner_shown = True
+    try:
+        print("Welcome irovanai", flush=True)
+    except Exception:
+        pass
+
+
+# ───────────────────────── خطاها ─────────────────────────
+class IrovanError(Exception):
+    """خطای پایه‌ی کتابخانه."""
+
+
+class AuthenticationError(IrovanError):
+    """کلید API ارسال نشده یا نامعتبر است."""
+
+
+class NetworkError(IrovanError):
+    """خطای اتصال یا تایم‌اوت."""
+
+
+class APIError(IrovanError):
+    """سرور خطا برگردانده است."""
+
+    def __init__(self, message, status_code=None, payload=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+class RateLimitError(APIError):
+    """تعداد درخواست‌ها بیش از حد مجاز است."""
+
+
+# ───────────────────────── پاسخ ─────────────────────────
+@dataclass
+class Response:
+    """پاسخ API آیروان."""
+
+    ok: bool
+    model: str
+    type: str
+    reply: str
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __str__(self) -> str:
+        return self.reply
+
+    def save(self, path: str) -> str:
+        """اگر پاسخ یک تصویر است (data URI یا لینک)، آن را در فایل ذخیره می‌کند."""
+        text = (self.reply or "").strip()
+        m = _DATA_RE.search(text)
+        if m:
+            data = base64.b64decode(m.group(0).split(",", 1)[1])
+        else:
+            m = _URL_RE.search(text)
+            if not m:
+                raise IrovanError("پاسخ شامل تصویر یا لینک تصویر نیست.")
+            req = urllib.request.Request(m.group(0), headers={"User-Agent": USER_AGENT})
+            try:
+                with urllib.request.urlopen(req, timeout=60) as r:
+                    data = r.read()
+            except OSError as e:
+                raise NetworkError(f"دانلود تصویر ناموفق بود: {e}") from e
+        with open(path, "wb") as f:
+            f.write(data)
+        return path
+
+
+def encode_image(image: Union[str, bytes, os.PathLike]) -> str:
+    """مسیر فایل، بایت‌ها یا data URI را به data URI تبدیل می‌کند."""
+    if isinstance(image, (bytes, bytearray)):
+        return "data:image/png;base64," + base64.b64encode(bytes(image)).decode()
+    image = os.fspath(image)
+    if image.startswith("data:"):
+        return image
+    mime = mimetypes.guess_type(image)[0] or "image/png"
+    with open(image, "rb") as f:
+        return f"data:{mime};base64," + base64.b64encode(f.read()).decode()
+
+
+# ───────────────────────── انتقال (سریع) ─────────────────────────
+class _Transport:
+    """اتصال HTTP پایدار (keep-alive) به‌ازای هر thread؛ بدون نیاز به کتابخانه خارجی."""
+
+    def __init__(self, base_url: str, timeout: float):
+        u = urlparse(base_url)
+        self.scheme = u.scheme or "https"
+        self.host = u.hostname
+        self.port = u.port
+        self.prefix = u.path.rstrip("/")
+        self.timeout = timeout
+        self._local = threading.local()
+        self._ctx = ssl.create_default_context()
+
+    def _conn(self):
+        c = getattr(self._local, "conn", None)
+        if c is None:
+            if self.scheme == "https":
+                c = http.client.HTTPSConnection(
+                    self.host, self.port, timeout=self.timeout, context=self._ctx)
+            else:
+                c = http.client.HTTPConnection(self.host, self.port, timeout=self.timeout)
+            self._local.conn = c
+        return c
+
+    def close(self):
+        c = getattr(self._local, "conn", None)
+        if c is not None:
+            try:
+                c.close()
+            except Exception:
+                pass
+        self._local.conn = None
+
+    def post(self, path: str, body: bytes, headers: Dict[str, str]) -> Tuple[int, bytes, Optional[float]]:
+        for attempt in (0, 1):  # تلاش دوم برای اتصال قدیمی که سرور بسته است
+            try:
+                c = self._conn()
+                c.request("POST", self.prefix + path, body=body, headers=headers)
+                r = c.getresponse()
+                data = r.read()
+                enc = (r.getheader("Content-Encoding") or "").lower()
+                if enc == "gzip":
+                    data = gzip.decompress(data)
+                elif enc == "deflate":
+                    data = zlib.decompress(data)
+                if (r.getheader("Connection") or "").lower() == "close":
+                    self.close()
+                ra = r.getheader("Retry-After")
+                try:
+                    retry_after = float(ra) if ra else None
+                except ValueError:
+                    retry_after = None
+                return r.status, data, retry_after
+            except socket.timeout:
+                self.close()
+                raise
+            except (http.client.HTTPException, OSError):
+                self.close()
+                if attempt == 1:
+                    raise
+        raise NetworkError("اتصال برقرار نشد")  # pragma: no cover
+
+
+# ───────────────────────── کلاینت ─────────────────────────
+class Irovan:
+    """کلاینت اصلی.
+
+    پارامترها:
+        api_key:    کلید API (یا متغیر محیطی IROVAN_API_KEY)
+        model:      مدل پیش‌فرض: "slim" یا "plus"
+        timeout:    مهلت هر درخواست (ثانیه)
+        retries:    تعداد تلاش مجدد برای خطای شبکه/۵xx/۴۲۹
+        cache_size: اگر بیشتر از صفر باشد، پاسخ پیام‌های متنی تکراری را نگه می‌دارد
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = DEFAULT_MODEL,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 120,
+        retries: int = 2,
+        cache_size: int = 0,
+    ):
+        self.api_key = api_key or os.environ.get(ENV_KEY)
+        if not self.api_key:
+            raise AuthenticationError(
+                f"کلید API داده نشد. آن را به Irovan(api_key=...) بدهید یا متغیر {ENV_KEY} را تنظیم کنید.")
+        _show_banner()
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = max(0, int(retries))
+        self.cache_size = max(0, int(cache_size))
+        self._cache: "OrderedDict[Tuple[str, str], Response]" = OrderedDict()
+        self._cache_lock = threading.Lock()
+        self._transport = _Transport(self.base_url, timeout)
+        self._headers = {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json; charset=utf-8",
+            "Accept": "application/json",
+            "Accept-Encoding": "gzip",
+            "User-Agent": USER_AGENT,
+        }
+
+    # ---- context manager ----
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def close(self):
+        """اتصال thread فعلی را می‌بندد."""
+        self._transport.close()
+
+    # ---- هسته ----
+    @staticmethod
+    def _delay(attempt: int, retry_after: Optional[float]) -> float:
+        return min(retry_after if retry_after else 0.5 * (2 ** attempt), 10.0)
+
+    @staticmethod
+    def _error_message(obj: Any, status: int) -> str:
+        if isinstance(obj, dict):
+            msg = obj.get("error") or obj.get("message")
+            if msg:
+                return msg if isinstance(msg, str) else json.dumps(msg, ensure_ascii=False)
+        return f"HTTP {status}"
+
+    def _parse(self, status: int, data: bytes) -> Response:
+        try:
+            obj = json.loads(data.decode("utf-8"))
+        except ValueError:
+            raise APIError("پاسخ نامعتبر از سرور", status, data[:500].decode("utf-8", "replace"))
+        if not isinstance(obj, dict):
+            raise APIError("پاسخ نامعتبر از سرور", status, obj)
+        msg = self._error_message(obj, status)
+        if status in (401, 403):
+            raise AuthenticationError(msg)
+        if status == 429:
+            raise RateLimitError(msg, status, obj)
+        if status >= 400 or obj.get("ok") is False:
+            raise APIError(msg, status, obj)
+        return Response(
+            ok=bool(obj.get("ok", True)),
+            model=obj.get("model", ""),
+            type=obj.get("type", ""),
+            reply=obj.get("reply", ""),
+            raw=obj,
+        )
+
+    def _request(self, payload: Dict[str, Any]) -> Response:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        last: Optional[Exception] = None
+        for attempt in range(self.retries + 1):
+            try:
+                status, data, retry_after = self._transport.post("/api/chat", body, self._headers)
+            except socket.timeout as e:
+                raise NetworkError("مهلت درخواست تمام شد (timeout)") from e
+            except (http.client.HTTPException, OSError) as e:
+                last = NetworkError(f"خطا در اتصال: {e}")
+                if attempt < self.retries:
+                    time.sleep(self._delay(attempt, None))
+                    continue
+                raise last from e
+            if status in _RETRY_STATUS and attempt < self.retries:
+                time.sleep(self._delay(attempt, retry_after))
+                continue
+            return self._parse(status, data)
+        raise last or NetworkError("درخواست ناموفق بود")  # pragma: no cover
+
+    # ---- API عمومی ----
+    def chat(
+        self,
+        message: str,
+        model: Optional[str] = None,
+        image: Optional[Union[str, bytes, os.PathLike]] = None,
+        use_cache: Optional[bool] = None,
+    ) -> Response:
+        """ارسال پیام (و در صورت نیاز تصویر) و دریافت پاسخ."""
+        model = model or self.model
+        cacheable = image is None and (self.cache_size > 0 if use_cache is None else use_cache)
+        key = (model, message)
+        if cacheable and self.cache_size > 0:
+            with self._cache_lock:
+                hit = self._cache.get(key)
+                if hit is not None:
+                    self._cache.move_to_end(key)
+                    return hit
+        payload: Dict[str, Any] = {"message": message, "model": model}
+        if image is not None:
+            payload["image"] = encode_image(image)
+        resp = self._request(payload)
+        if cacheable and self.cache_size > 0:
+            with self._cache_lock:
+                self._cache[key] = resp
+                while len(self._cache) > self.cache_size:
+                    self._cache.popitem(last=False)
+        return resp
+
+    def analyze_image(
+        self,
+        image: Union[str, bytes, os.PathLike],
+        question: str = "این تصویر چه چیزی را نشان می‌دهد؟",
+        model: str = "plus",
+    ) -> Response:
+        """تحلیل تصویر (پیش‌فرض با مدل plus)."""
+        return self.chat(question, model=model, image=image)
+
+    def generate_image(self, prompt: str, model: Optional[str] = None) -> Response:
+        """ساخت تصویر از روی توضیح متنی."""
+        return self.chat(f"عکس : {prompt} : بساز", model=model, use_cache=False)
+
+    def chat_many(
+        self,
+        messages: Sequence[str],
+        model: Optional[str] = None,
+        workers: int = 8,
+        return_exceptions: bool = False,
+    ) -> List[Any]:
+        """ارسال هم‌زمان چند پیام (سریع‌تر از حلقه). ترتیب خروجی همان ترتیب ورودی است."""
+        messages = list(messages)
+        if not messages:
+            return []
+
+        def one(m: str):
+            try:
+                return self.chat(m, model=model)
+            except Exception as e:  # noqa: BLE001
+                if return_exceptions:
+                    return e
+                raise
+
+        with ThreadPoolExecutor(max_workers=max(1, min(workers, len(messages)))) as ex:
+            return list(ex.map(one, messages))
+
+    def session(self, system: Optional[str] = None, model: Optional[str] = None, max_turns: int = 10) -> "Chat":
+        """گفتگوی چندمرحله‌ای با حافظه."""
+        return Chat(self, system=system, model=model, max_turns=max_turns)
+
+
+# ───────────────────────── گفتگو با حافظه ─────────────────────────
+class Chat:
+    """نگه‌داری تاریخچه گفتگو. تاریخچه داخل متن پیام برای مدل ارسال می‌شود.
+
+        c = ai.session(system="تو یک دستیار مودب هستی")
+        c.send("اسم من علی است")
+        print(c.send("اسم من چیست؟"))
+    """
+
+    def __init__(self, client: Irovan, system: Optional[str] = None,
+                 model: Optional[str] = None, max_turns: int = 10):
+        self.client = client
+        self.system = system
+        self.model = model
+        self.max_turns = max_turns
+        self.history: List[Tuple[str, str]] = []
+
+    def _build(self, message: str) -> str:
+        if not self.history and not self.system:
+            return message
+        parts = []
+        if self.system:
+            parts.append(self.system)
+        for u, a in self.history[-self.max_turns:]:
+            parts.append(f"کاربر: {u}\nدستیار: {a}")
+        parts.append(f"کاربر: {message}\nدستیار:")
+        return "\n\n".join(parts)
+
+    def send(self, message: str, image: Optional[Union[str, bytes, os.PathLike]] = None) -> Response:
+        resp = self.client.chat(self._build(message), model=self.model, image=image, use_cache=False)
+        self.history.append((message, resp.reply))
+        return resp
+
+    def reset(self):
+        self.history.clear()
+
+
+# ───────────────────────── نسخه async ─────────────────────────
+class AsyncIrovan:
+    """نسخه async؛ درخواست‌ها در thread pool اجرا می‌شوند.
+
+        ai = AsyncIrovan(api_key="...")
+        rs = await ai.chat_many(["سلام", "خوبی؟"])
+    """
+
+    def __init__(self, *args, workers: int = 16, **kwargs):
+        self._client = Irovan(*args, **kwargs)
+        self._pool = ThreadPoolExecutor(max_workers=workers)
+
+    async def _run(self, fn, *args, **kwargs):
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self._pool, functools.partial(fn, *args, **kwargs))
+
+    async def chat(self, message, model=None, image=None, use_cache=None) -> Response:
+        return await self._run(self._client.chat, message, model=model, image=image, use_cache=use_cache)
+
+    async def analyze_image(self, image, question="این تصویر چه چیزی را نشان می‌دهد؟", model="plus") -> Response:
+        return await self._run(self._client.analyze_image, image, question, model)
+
+    async def generate_image(self, prompt, model=None) -> Response:
+        return await self._run(self._client.generate_image, prompt, model)
+
+    async def chat_many(self, messages: Sequence[str], model=None, return_exceptions=False) -> List[Any]:
+        return await asyncio.gather(
+            *[self.chat(m, model=model) for m in messages], return_exceptions=return_exceptions)
+
+    def close(self):
+        self._pool.shutdown(wait=False)
+
+
+# ───────────────────────── میان‌بر ─────────────────────────
+def ask(message: str, api_key: Optional[str] = None, model: str = DEFAULT_MODEL) -> str:
+    """یک پیام بفرست و فقط متن پاسخ را بگیر."""
+    with Irovan(api_key=api_key, model=model) as ai:
+        return ai.chat(message).reply
+
+
+# ───────────────────────── خط فرمان ─────────────────────────
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="irovanai", description="چت با هوش مصنوعی آیروان")
+    p.add_argument("message", nargs="?", help="متن پیام (اگر نداده شود، حالت گفتگوی تعاملی)")
+    p.add_argument("-m", "--model", default=DEFAULT_MODEL, help="slim یا plus")
+    p.add_argument("-i", "--image", help="مسیر تصویر برای تحلیل")
+    p.add_argument("-o", "--output", help="ذخیره‌ی تصویر پاسخ در این فایل")
+    p.add_argument("-k", "--key", help="کلید API (یا متغیر IROVAN_API_KEY)")
+    p.add_argument("--version", action="version", version=__version__)
+    args = p.parse_args(argv)
+    if args.message:  # خروجی تمیز برای استفاده در اسکریپت‌ها
+        global _banner_shown
+        _banner_shown = True
+    try:
+        ai = Irovan(api_key=args.key, model=args.model)
+        if args.message:
+            r = ai.chat(args.message, image=args.image)
+            if args.output:
+                print("ذخیره شد:", r.save(args.output))
+            else:
+                print(r.reply)
+            return 0
+        chat = ai.session()
+        print("گفتگو شروع شد. برای خروج: exit")
+        while True:
+            try:
+                text = input("شما: ").strip()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                break
+            if text.lower() in ("exit", "quit", "خروج"):
+                break
+            if text:
+                print("ایروان:", chat.send(text).reply)
+        return 0
+    except IrovanError as e:
+        print(f"خطا: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

irovanai-0.2.1/src/irovanai/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from . import main
+
+sys.exit(main())

irovanai-0.2.1/src/irovanai.egg-info/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.1
+Name: irovanai
+Version: 0.2.1
+Summary: Fast, dependency-free Python client for Irovan AI (کتابخانه پایتون آیروان)
+Author: Irovan
+License: MIT
+Project-URL: Homepage, https://github.com/irovan/irovanai
+Project-URL: Repository, https://github.com/irovan/irovanai.git
+Project-URL: Issues, https://github.com/irovan/irovanai/issues
+Keywords: irovan,ai,chatbot,persian,farsi,api,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# irovanai
+
+کتابخانه **سریع** و **بدون وابستگی** پایتون برای هوش مصنوعی آیروان (`irovan-slim` / `plus`).
+
+- ⚡ اتصال پایدار (keep-alive): درخواست‌های بعدی بدون ساخت دوباره‌ی اتصال
+- 🔁 تلاش مجدد خودکار برای خطای شبکه، ۵xx و ۴۲۹
+- 🚀 ارسال هم‌زمان چند پیام با `chat_many`
+- 🧠 گفتگو با حافظه (`session`)
+- 🖼 تحلیل و ساخت تصویر
+- ⏱ نسخه‌ی `async`
+- 📦 فقط کتابخانه‌ی استاندارد پایتون؛ روی گوشی (Pydroid / Termux) هم کار می‌کند
+
+## نصب
+
+```bash
+pip install irovanai
+```
+
+یا از گیت‌هاب:
+
+```bash
+pip install git+https://github.com/irovan/irovanai.git
+```
+
+اگر `git` ندارید (مثلاً Pydroid):
+
+```bash
+pip install https://github.com/irovan/irovanai/archive/refs/heads/main.zip
+```
+
+یا فقط فایل `irovanai.py` را کنار کد خودتان بگذارید؛ نیازی به نصب نیست.
+
+## دریافت کلید API
+
+کلید را از پلتفرم توسعه‌دهندگان آیروان بگیرید: https://chat.irovan.ir
+
+## شروع سریع
+
+```python
+from irovanai import Irovan
+
+ai = Irovan(api_key="YOUR_API_KEY")
+print(ai.chat("سلام"))
+```
+
+کلید را می‌توانید در متغیر محیطی بگذارید:
+
+```bash
+export IROVAN_API_KEY="YOUR_API_KEY"   # ویندوز: set IROVAN_API_KEY=...
+```
+
+```python
+ai = Irovan()
+```
+
+میان‌بر یک‌خطی:
+
+```python
+from irovanai import ask
+print(ask("سلام", api_key="YOUR_API_KEY"))
+```
+
+## مدل‌ها
+
+```python
+ai.chat("سلام", model="slim")   # سریع و سبک
+ai.chat("سلام", model="plus")   # قوی‌تر
+```
+
+## ارسال هم‌زمان (سرعت بالا)
+
+```python
+rs = ai.chat_many(["سلام", "پایتون چیست؟", "یک جوک بگو"], workers=8)
+for r in rs:
+    print(r.reply)
+```
+
+ترتیب خروجی همان ترتیب ورودی است. با `return_exceptions=True` خطاها به‌جای متوقف‌کردن کار، در لیست برمی‌گردند.
+
+## کش پاسخ
+
+```python
+ai = Irovan(api_key="...", cache_size=100)  # پیام متنی تکراری دوباره به سرور نمی‌رود
+```
+
+## گفتگو با حافظه
+
+```python
+c = ai.session(system="تو یک دستیار مودب هستی.")
+c.send("اسم من علی است")
+print(c.send("اسم من چیست؟"))
+c.reset()
+```
+
+> تاریخچه داخل متن پیام ارسال می‌شود، چون API هر درخواست را مستقل دریافت می‌کند.
+
+## تصویر
+
+```python
+print(ai.analyze_image("photo.png", "این تصویر چه چیزی را نشان می‌دهد؟"))
+
+ai.generate_image("یک خیار تازه روی پس‌زمینه سفید").save("cucumber.png")
+```
+
+## Async
+
+```python
+import asyncio
+from irovanai import AsyncIrovan
+
+async def main():
+    ai = AsyncIrovan(api_key="YOUR_API_KEY")
+    rs = await ai.chat_many(["سلام", "خوبی؟"])
+    print([r.reply for r in rs])
+
+asyncio.run(main())
+```
+
+## خط فرمان
+
+```bash
+irovanai "سلام" -m slim
+irovanai "این چیست؟" -m plus -i photo.png
+irovanai                      # گفتگوی تعاملی
+python -m irovanai "سلام"     # روش دیگر
+```
+
+## تنظیمات
+
+```python
+Irovan(
+    api_key="...",
+    model="slim",
+    timeout=120,     # مهلت هر درخواست (ثانیه)
+    retries=2,       # تلاش مجدد
+    cache_size=0,    # 0 = بدون کش
+)
+```
+
+## مدیریت خطا
+
+```python
+from irovanai import Irovan, AuthenticationError, RateLimitError, NetworkError, APIError
+
+try:
+    print(Irovan(api_key="...").chat("سلام"))
+except AuthenticationError:
+    print("کلید نامعتبر است")
+except RateLimitError:
+    print("درخواست زیاد؛ کمی بعد تلاش کنید")
+except NetworkError as e:
+    print("مشکل شبکه:", e)
+except APIError as e:
+    print("خطای سرور:", e, e.status_code)
+```
+
+## پیام خوش‌آمدگویی
+
+هنگام اولین ساخت کلاینت در هر اجرا، عبارت `Welcome irovanai` چاپ می‌شود. برای خاموش‌کردن:
+
+```bash
+export IROVAN_QUIET=1   # ویندوز: set IROVAN_QUIET=1
+```
+
+## تست
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## مجوز
+
+MIT

irovanai-0.2.1/src/irovanai.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/irovanai/__init__.py
+src/irovanai/__main__.py
+src/irovanai/py.typed
+src/irovanai.egg-info/PKG-INFO
+src/irovanai.egg-info/SOURCES.txt
+src/irovanai.egg-info/dependency_links.txt
+src/irovanai.egg-info/entry_points.txt
+src/irovanai.egg-info/top_level.txt
+tests/test_irovanai.py

irovanai-0.2.1/src/irovanai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

irovanai-0.2.1/src/irovanai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+irovanai = irovanai:main

irovanai-0.2.1/src/irovanai.egg-info/top_level.txt

@@ -0,0 +1 @@
+irovanai

irovanai-0.2.1/tests/test_irovanai.py

@@ -0,0 +1,136 @@
+import asyncio
+import io
+import os
+from contextlib import redirect_stdout
+import gzip
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer as HTTPServer
+
+os.environ.setdefault("IROVAN_QUIET", "1")
+
+import irovanai  # noqa: E402
+from irovanai import (APIError, AsyncIrovan, AuthenticationError, Irovan,
+                      RateLimitError, encode_image)
+
+STATE = {"fail": 0, "calls": 0, "conns": set()}
+
+
+class H(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *a):
+        pass
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(n).decode("utf-8"))
+        STATE["calls"] += 1
+        STATE["conns"].add(self.client_address)
+        key = self.headers.get("X-API-Key")
+        if key == "bad":
+            return self._send(401, {"ok": False, "error": "invalid key"})
+        if body["message"] == "limit":
+            return self._send(429, {"ok": False, "error": "slow down"})
+        if STATE["fail"] > 0:
+            STATE["fail"] -= 1
+            return self._send(503, {"ok": False, "error": "busy"})
+        self._send(200, {"ok": True, "model": "irovan-slim", "type": "ai",
+                         "reply": "echo:" + body["message"], "m": body["model"],
+                         "img": bool(body.get("image"))})
+
+    def _send(self, code, obj):
+        data = gzip.compress(json.dumps(obj, ensure_ascii=False).encode("utf-8"))
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Encoding", "gzip")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+
+class T(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.srv = HTTPServer(("127.0.0.1", 0), H)
+        cls.srv.daemon_threads = True
+        threading.Thread(target=cls.srv.serve_forever, daemon=True).start()
+        cls.url = f"http://127.0.0.1:{cls.srv.server_port}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.srv.shutdown()
+
+    def ai(self, **kw):
+        kw.setdefault("api_key", "k")
+        return Irovan(base_url=self.url, **kw)
+
+    def test_banner(self):
+        os.environ.pop("IROVAN_QUIET", None)
+        irovanai._banner_shown = False
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            self.ai()
+            self.ai()
+        os.environ["IROVAN_QUIET"] = "1"
+        self.assertEqual(buf.getvalue(), "Welcome irovanai\n")  # فقط یک‌بار
+
+    def test_chat_and_keepalive(self):
+        STATE["conns"].clear()
+        ai = self.ai()
+        for i in range(5):
+            self.assertEqual(ai.chat(f"سلام{i}").reply, f"echo:سلام{i}")
+        self.assertEqual(len(STATE["conns"]), 1)  # یک اتصال برای همه
+
+    def test_model_and_image(self):
+        r = self.ai().analyze_image(b"abc")
+        self.assertTrue(r.raw["img"])
+        self.assertEqual(r.raw["m"], "plus")
+        self.assertTrue(encode_image(b"x").startswith("data:image/png;base64,"))
+
+    def test_auth_error(self):
+        with self.assertRaises(AuthenticationError):
+            self.ai(api_key="bad").chat("hi")
+
+    def test_rate_limit(self):
+        with self.assertRaises(RateLimitError):
+            self.ai(retries=0).chat("limit")
+
+    def test_retry_on_503(self):
+        STATE["fail"] = 2
+        self.assertEqual(self.ai(retries=2).chat("x").reply, "echo:x")
+        STATE["fail"] = 1
+        with self.assertRaises(APIError):
+            self.ai(retries=0).chat("x")
+
+    def test_cache(self):
+        ai = self.ai(cache_size=4)
+        ai.chat("c1")
+        before = STATE["calls"]
+        ai.chat("c1")
+        self.assertEqual(STATE["calls"], before)
+
+    def test_chat_many_order(self):
+        msgs = [f"m{i}" for i in range(20)]
+        out = self.ai().chat_many(msgs, workers=5)
+        self.assertEqual([r.reply for r in out], ["echo:" + m for m in msgs])
+
+    def test_session_memory(self):
+        c = self.ai().session(system="SYS")
+        c.send("اسم من علی است")
+        r = c.send("اسم من چیست؟")
+        self.assertIn("علی", r.reply)
+        self.assertIn("SYS", r.reply)
+
+    def test_async(self):
+        async def go():
+            a = AsyncIrovan(api_key="k", base_url=self.url)
+            rs = await a.chat_many(["a", "b", "c"])
+            a.close()
+            return [r.reply for r in rs]
+        self.assertEqual(asyncio.run(go()), ["echo:a", "echo:b", "echo:c"])
+
+
+if __name__ == "__main__":
+    unittest.main()