Metadata-Version: 2.4
Name: dpapiamir
Version: 0.1.0
Summary: DeepSeek API، من تطوير أمير — مكتبة Python للتفاعل مع DeepSeek Chat Web API (PoW تلقائي، رفع ملفات، Vision)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: wasmtime>=17.0.0
Requires-Dist: DrissionPage>=4.1.1.2

# DPAPIAMIR

**DPAPIAMIR** — اختصار **D**eep**S**eek **API** من تطوير **AMIR**: أداة عربية للتفاعل مع **DeepSeek Chat** من الطرفية مباشرةً، دون الحاجة إلى المتصفح أو النسخة المدفوعة للـ API.

تقوم المكتبة بالنيابة عنك بكل الخطوات المزعجة تلقائياً:
- التقاط الجلسة (الكوكيز + التوكن) من المتصفح **مرة واحدة فقط**.
- حل **Proof-of-Work (PoW)** تلقائياً حتى تتمكن من إرسال الرسائل.
- رفع الملفات (صور، نصوص، PDF...) وإرفاقها بالسؤال.
- دعم نماذج **Instant / Expert / Vision**، وتفعيل **التفكير** و**البحث** و**العرض المباشر** (التدفق)

---

## ماذا يعني الاسم؟

| المقطع | المعنى |
|---|---|
| **DP** | **D**eep**S**eek — النموذج الذي تعمل معه المكتبة |
| **API** | واجهة البرمجة (Application Programming Interface) التي تتعامل معها |
| **AMIR** | هُوية المطوّر — من تطوير **أمير** |

أي: **"DeepSeek API، من تطوير أمير"** — مكتبة شخصية احترافية تجمع بين التقنية (DeepSeek API) وهوية مطوّرها (أمير).

> للاستيراد والتثبيت يُستخدم الاسم التقني `dpapiamir` (بحروف صغيرة)، بينما `DPAPIAMIR` هي العلامة التجارية.

---

## المتطلبات

| المتطلب | التفصيل |
|---|---|
| Python | الإصدار 3.10 أو أحدث |
| متصفح | Google Chrome أو Microsoft Edge (للالتقاط الأول للجلسة فقط) |
| المكتبات | تُثبَّت عبر الأمر أدناه |

### التثبيت

```bash
pip install -r requirements.txt
```

---

## أول تشغيل (التقاط الجلسة)

عند أول تشغيل للأداة لا توجد جلسة محفوظة، فتُفتح نافذة متصفح تلقائياً:

1. إذا كنت مسجلاً دخولك في DeepSeek، ستُلتقط الجلسة خلال ثوانٍ.
2. إذا لم تكن مسجلاً، سجّل الدخول في نافذة المتصفح ثم اضغط **Enter** في الطرفية.
3. تُحفظ الجلسة في ملف `session.json`، وتُستخدم في كل مرة بعد ذلك.

> الجلسة صالحة لفترة، وعندما تنتهي ستعيد الأداة فتح المتصفح وتُحدّثها تلقائياً دون تدخل منك.

---

## الوضع التفاعلي (REPL)

شغّل:

```bash
python cli.py
```

ستظهر قائمة بالتعليمات ثم تبدأ الكتابة عند `>` مثل:

```
Instant> رسالتك هنا
```

### ماذا يعني النص قبل `>`؟

هو **حالة إعداداتك الحالية** باختصار:

| الـ prompt | المعنى |
|---|---|
| `Instant>` | النموذج العادي، بلا تفكير وبلا بحث |
| `Expert>` | نموذج Expert |
| `Expert+Think>` | Expert مع تفعيل التفكير |
| `Vision+Search>` | نموذج Vision مع تفعيل البحث |
| `Instant+Think+Search>` | العادي مع تفعيل التفكير والبحث معاً |

الأداة تبقى بهذه الإعدادات حتى تغيّرها بأمر، أو تعيد التعيين بأمر `/new`.

---

### شرح أوامر الوضع التفاعلي بالتفصيل

#### إدارة الجلسات

| الأمر | الوظيفة | مثال |
|---|---|---|
| `/new` | يبدأ جلسة جديدة **ويعيد تعيين كل الإعدادات** (النموذج/التفكير/البحث/التدفق). استخدمه عندما تريد بدء موضوع جديد من الصفر. | `/new` |
| `/session <id>` | يتابع محادثة **سابقة** بمعرّفها. استخدمه لمواصلة الحديث حيث توقفت. | `/session 4766d459-47c7-45ce-aeb5-93c5279f8a8f` |
| `/list` | يعرض قائمة الجلسات السابقة (المعرّف + العنوان + التاريخ) لتعرف معرّف الجلسة التي تريد متابعتها. | `/list` |
| `/history <id>` | يعرض كامل محادثة جلسة سابقة (رسائلك وردود النموذج) للاطلاع فقط، دون تغيير أي شيء. | `/history 4766d459-47c7-45ce-aeb5-93c5279f8a8f` |

> **تنبيه:** أي رسالة تكتبها دون تحديد جلسة بـ `/session` تُنشئ جلسة جديدة تلقائياً.

#### اختيار النموذج

| الأمر | الوظيفة | متى تستخدمه |
|---|---|---|
| `/expert` | يستخدم نموذج Expert (أقوى وأدق). **ملاحظة:** Expert لا يدعم البحث، لذلك يُعطّل البحث تلقائياً عند تفعيله. | المهام المعقدة، البرمجة، التحليل العميق |
| `/noexpert` | يعود إلى النموذج العادي Instant. | الرسائل السريعة والعادية |
| `/vision` | يستخدم نموذج Vision الذي يفهم **الصور**. | طرح سؤال عن صورة أو إرفاق صورة |
| `/novision` | يعود إلى النموذج العادي. | بعد الانتهاء من أسئلة الصور |

#### تحكم سلوك الإجابة

| الأمر | الوظيفة | ملاحظات |
|---|---|---|
| `/think` | يفعل **التفكير**: النموذج يفكّر داخلياً قبل الإجابة، فيظهر قسم "التفكير" ثم "الإجابة". | يستغرق وقتاً أطول لكن الإجابة أدق |
| `/nothink` | يعطّل التفكير (الإجابة مباشرة). | الأسرع |
| `/search` | يفعل **البحث**: النموذج يبحث في الإنترنت ويستند لمعلومات حديثة. | مفيد للأسئلة الزمنية (الأخبار، الأسعار) |
| `/nosearch` | يعطّل البحث. | إجابات مباشرة دون إنترنت |

#### العرض المباشر (التدفق)

| الأمر | الوظيفة | متى تستخدمه |
|---|---|---|
| `/stream` | يعرض الرد **كلمة كلمة** أثناء توليده (مفعّل افتراضياً). | عندما تريد مشاهدة الكتابة الحية |
| `/nostream` | ينتظر اكتمال الرد ثم يعرضه كاملاً دفعة واحدة. | عندما تريد الرد النهائي فوراً دون انتظار |

#### أدوات عامة

| الأمر | الوظيفة |
|---|---|
| `/status` | يعرض ملخصاً كاملاً للإعدادات الحالية (النموذج، التفكير، البحث، التدفق، الجلسة). |
| `/clear` | يمسح شاشة الطرفية. |
| `/help` | يعرض قائمة الأوامر المختصرة. |
| `/exit` | يخرج من البرنامج. |

---

### إرفاق ملفات أثناء الكتابة

اكتب مسارات الملفات كجزء من الرسالة وسيتم رفعها وإرفاقها تلقائياً:

```
Instant> ما محتوى هذا الملف؟ C:\Users\me\Documents\report.pdf
Instant> وصف هذه الصورة apples.jpeg
```

- مع نموذج **Vision** تُقبل الصور.
- الملفات تُرفع وتُعالج قبل إرسال السؤال.

---

## الوضع أحادي السطر (بدون فتح الواجهة)

أحياناً تريد سؤالاً واحداً فقط. الأمر نفسه يدعم ذلك مباشرة:

```bash
python cli.py "ما هي عاصمة فرنسا؟"
```

### شرح الأعلام (flags) بالتفصيل

| العلم | الوظيفة | مثال |
|---|---|---|
| `--list` | يعرض قائمة الجلسات ثم يخرج. | `python cli.py --list` |
| `--history <id>` | يعرض تاريخ جلسة ثم يخرج. | `python cli.py --history <session_id>` |
| `--session <id>` | يتابع محادثة سابقة. يجب أن يأتي **قبل** نص الرسالة. | `python cli.py --session <id> "أكمل حديثنا"` |
| `--expert` | نموذج Expert (يعطّل البحث تلقائياً). | `python cli.py --expert "اشرح التفاضل والتكامل"` |
| `--vision` | نموذج Vision لقراءة الصور. | `python cli.py --vision "ماذا في هذه الصورة؟" photo.jpg` |
| `--think` | يفعل التفكير. | `python cli.py --think "حل هذه المسألة"` |
| `--search` | يفعل البحث في الإنترنت. | `python cli.py --search "أحدث أخبار التقنية"` |
| `--nostream` | يعطّل العرض المباشر (الرد كاملاً بعد الانتهاء). | `python cli.py --nostream "قل مرحبا"` |

### أمثلة جاهزة

```bash
# سؤال عادي
python cli.py "ما هي عاصمة فرنسا؟"

# سؤال مع البحث في الإنترنت
python cli.py --search "أسعار الذهب اليوم"

# سؤال قوي مع التفكير
python cli.py --expert --think "اكتب لي خطة مشروع برمجي"

# سؤال عن صورة
python cli.py --vision "وصف هذه الصورة" apples.jpeg

# متابعة محادثة سابقة
python cli.py --session 4766d459-47c7-45ce-aeb5-93c5279f8a8f "أكمل حديثنا"
```

---

## الاستخدام كمكتبة في مشروعك

يمكنك استخدام الوظائف نفسها داخل كود Python:

```python
from dpapiamir import ChatOptions, DeepSeekClient, capture_session, load_session

# 1) اجلب جلسة (مرة واحدة) أو حمّلها من session.json
session = load_session()
if session is None:
    session = capture_session()

# 2) أنشئ العميل
client = DeepSeekClient(session)

# 3) أرسل سؤالاً عادياً مع البحث
result = client.run_chat(
    'ما هي عاصمة فرنسا؟',
    options=ChatOptions(search_enabled=True),
)
print(result.answer)

# 4) سؤال عن صورة بنموذج Vision
result = client.run_chat(
    'ما محتوى هذه الصورة؟',
    files=['apples.jpeg'],
    options=ChatOptions(model_type='vision'),
)
print(result.answer)
```

### الواجهات المتاحة في المكتبة

| الدالة | الوظيفة |
|---|---|
| `capture_session()` | يفتح المتصفح ويلتقط جلسة جديدة ويحفظها. |
| `load_session()` | يحمّل الجلسة المحفوظة من `session.json`. |
| `client.run_chat(...)` | يرسل رسالة (مع ملفات اختيارياً) ويعيد `ChatResult`. |
| `client.stream_chat(...)` | مثل `run_chat` لكن يعيد الأحداث تباعاً للعرض المباشر. |
| `client.upload_file(...)` | يرفع ملفاً ويعيد معرّفه. |
| `client.create_chat_session()` | ينشئ جلسة جديدة ويعيد معرّفها. |
| `client.list_sessions()` | يعيد قائمة الجلسات السابقة. |
| `client.get_history(...)` | يعيد تاريخ محادثة. |
| `client.print_sessions()` / `client.print_history(...)` | نسخ تُطبع مباشرة في الطرفية. |

---

## كيف تعمل الأداة من الداخل؟

1. **الجلسة**: تُلتقط من المتصفح وتُحفظ في `session.json` (كوكيز + هيدرات، بعد إزالة هيدرات HTTP/2 المبتدئة بـ `:` لأنها تسبب أخطاء).
2. **Proof-of-Work**: قبل كل طلب، تُطلب "تحدٍ" من الخادم عبر `POST /chat/create_pow_challenge`، ويُحل باستخدام ملف WASM (`sha3_wasm_v1.wasm`) ثم يُرسل الجواب في الهيدر `x-ds-pow-response`.
3. **الرفع**: `POST /file/upload_file` مع هيدرات `x-file-size`, `x-model-type`, `x-thinking-enabled`، ثم تُتابَع الحالة حتى `SUCCESS`.
4. **الرسائل**: `POST /chat/completion`، والرد يأتي بتنسيق SSE (تدفق) يُحلل لاستخراج التفكير والإجابة.
5. **انتهاء الجلسة**: عند ظهور علامات `INVALID_TOKEN` / `INVALID_POW_RESPONSE` / `UNAUTHORIZED`، تُعيد الأداة فتح المتصفح وتُحدّث الجلسة تلقائياً.

---

## بنية المشروع

```
dpapiamir/
  __init__.py   # الصادرات العامة للمكتبة
  config.py     # الثوابت والمسارات
  errors.py     # أنواع الأخطاء المخصصة
  models.py     # ChatOptions / ChatResult والأدوات المساعدة
  pow.py        # حل Proof-of-Work عبر wasmtime
  sse.py        # تحليل تدفق SSE (StreamParser)
  http.py       # طبقة النقل و clean_headers
  storage.py    # حفظ/تحميل الجلسة
  browser.py    # التقاط الجلسة من المتصفح
  client.py     # DeepSeekClient (الواجهة الرئيسية)
  resources/    # sha3_wasm_v1.wasm
cli.py          # واجهة سطر الأوامر + الوضع التفاعلي (REPL)
examples/       # أمثلة جاهزة
requirements.txt
pyproject.toml
README.md
```

---

## أسئلة شائعة

**لماذا فُتح المتصفح؟**
لأن الجلسة لم تكن محفوظة أو انتهت صلاحيتها، فتحت الأداة المتصفح لالتقاطها. سجّل الدخول واضغط Enter وسيُحفظ كل شيء تلقائياً.

**هل الأداة تحفظ محادثاتي في الموقع؟**
لا، محادثاتك تبقى في حسابك على DeepSeek كما هي. الأداة تحفظ الجلسة فقط (الكوكيز والتوكن).

**لماذا الإجابة تظهر كلمة كلمة؟**
لأن العرض المباشر (التدفق) مفعّل افتراضياً. أوقفه بـ `/nostream` أو `--nostream`.

**لماذا مع Expert لا يعمل البحث؟**
لأن نموذج Expert في DeepSeek لا يدعم البحث، فتعطله الأداة تلقائياً لتجنب الأخطاء.
