البدء السريع

شغّل كاظمه واجعلها تجيب الرسائل في أقل من 10 دقائق. هذا الدليل هو مصدر الحقيقة للتثبيت — أبقِه متزامنًا مع pyproject.toml وsetup.ps1 / setup.sh والإعدادات ← الحزم.

بعد kazma serve، افتح / — فهي المحادثة، وليست لوحة التحكم. التشغيل الأول يطلب مفتاح مزوّد واحدًا ونموذجًا واحدًا. المفتشات تحت المزيد.

---

1. المتطلبات الأساسية

المتطلب	التفصيل
Python	>=3.11, <3.15 (مُعلَن في pyproject.toml). يُنصح بـ 3.12 أو 3.13.
Git	للاستنساخ / ترقيات المشغّل عبر kazma update (مسار تثبيت git).
مفتاح مزوّد LLM	واحد على الأقل من: OpenAI، Anthropic، Google ‏(ADC)، DeepSeek، xAI، OpenRouter، NVIDIA NIM، Mistral، Together، Cohere، Fireworks، Perplexity، AI21 — أو خادم محلي (Ollama / LM Studio). ‏Azure OpenAI وAWS Bedrock مدعومان أصلًا أيضًا.
Node.js ‏(اختياري)	فقط إذا أردت بناء/تقديم موقع توثيق Docusaurus ‏(docs/). غير مطلوب لتشغيل كاظمه نفسها.

ملاحظة حول الحزم الإضافية: تثبيت pip install -e . المجرد يشمل بالفعل الوكيل، وواجهة الويب، وTUI ‏(textual تبعية أساسية)، والبوابات، والسرب، ومكتبات توليد المستندات. الحزمة الإضافية rag ‏(chromadb، sentence-transformers، sqlite-vec) هي ما تضيفه لذاكرة المتجهات / الاسترجاع الكثيف — انظر الذاكرة وRAG. لا توجد حزمة إضافية [cli]؛ kazma-cli تُشحن في الحزمة (wheel).

---

2. التثبيت

اختر مسارًا واحدًا. كلها تنتج نفس السكربتات الطرفية: kazma، kazma-tui، kazma-web.

‏README المستودع فيه بداية سريعة قصيرة ملائمة لويندوز (المنافذ، ERR_CONNECTION_RESET). فضّل هذا الدليل للتفاصيل.

المسار أ — سكربت الإقلاع (موصى به)

git clone https://github.com/Mubder/kazma.git
cd kazma

# Windows (PowerShell) — never chain with && / ||; use ; and $LASTEXITCODE
.\setup.ps1

# Linux / macOS / WSL
chmod +x setup.sh
./setup.sh

السكربت: يتطلب Python 3.11+، ويثبّت uv إن كان مفقودًا، ويشغّل uv sync --extra rag --extra dev --extra tui، وينسخ .env.example → .env عند الحاجة، ويتحقق من استيراد LangGraph / aiosqlite / textual. وهو لا يثبّت [all] ‏(فهي تجرّ torch وPlaywright وWeasyPrint وTemporal وE2B).

المسار ب — تثبيت قابل للتحرير (يدوي)

git clone https://github.com/Mubder/kazma.git kazma
cd kazma
python -m venv .venv

نشّط البيئة الافتراضية لمنصتك:

# Linux / macOS / WSL (bash, zsh)
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

:: Windows (CMD)
.venv\Scripts\activate.bat

# Same extras as the bootstrap scripts:
uv sync --extra rag --extra dev --extra tui
# or:
pip install -e ".[rag,dev,tui]"
# Everything:
# uv sync --all-extras
# pip install -e ".[all]"

حزم إضافية اختيارية (ثبّت ما تحتاجه فقط؛ الإعدادات ← الحزم يمكنها إضافتها لاحقًا):

الحزمة الإضافية	الحزم	ما تفعّله
[rag]	chromadb, sentence-transformers, sqlite-vec	ذاكرة متجهات / استرجاع كثيف
[dev]	pytest, pytest-asyncio, pytest-cov, pytest-mock, ruff, mypy, locust, pre-commit	اختبارات + تنقيط الشيفرة + خطاطيف git
[test]	pytest stack + pytest-timeout + fakeredis	‏CI أخف من dev
[tui]	textual, python-bidi	لوحة طرفية (kazma-tui؛ textual أساسية أيضًا)
[observability]	prometheus-client	نقطة نهاية سحب /metrics
[web]	playwright	مهارة أتمتة المتصفح (ثم playwright install chromium)
[push]	pywebpush	‏Web Push عند اكتمال الدور (تعطيل ذاتي عند غيابها)
[document]	reportlab, python-docx, openpyxl, pypdf, …	نفس مكتبات النواة؛ الحزمة الإضافية أبقيت للتثبيتات الصريحة
[ocr]	pytesseract, pdf2image, pillow	‏OCR ‏(يحتاج Tesseract نظاميًا)
[convert]	weasyprint	‏HTML→PDF ‏(يحتاج خطوط نظام التشغيل / GTK على بعض المضيفين)
[document-platform]	document + ocr + convert + pymupdf + pypdfium2	محرّكات ذكاء المستندات الكاملة
[docling]	docling	إنقاذ محلي لملفات PDF الصعبة بعد PyMuPDF
[index]	tree-sitter, tree-sitter-python, tree-sitter-javascript	فهرس قاعدة الشيفرة (احتياطي regex يعمل دائمًا)
[sandbox]	e2b-code-interpreter	‏python_exec على Firecracker ‏(E2B_API_KEY)
[durable]	temporalio	سرب ملفوف بـ Temporal ‏(KAZMA_TEMPORAL_HOST)
[database]	psycopg, pymysql, pymongo	مشغّلات إضافية لمهارة عميل قواعد البيانات
[postgres]	psycopg[binary,pool], langgraph-checkpoint-postgres	حالة مشتركة متعددة النسخ
[all]	ميتا — كل الحزم الإضافية أعلاه	للراحة؛ ثقيلة

المهارات الأصلية (المتصفح، التقويم، document-generator، document-platform، قواعد البيانات) تُحمَّل دائمًا. استدعاء أداة خلفيتها غير مثبتة يعيد تلميح تثبيت بدل الانهيار. ثبّت الحزمة الإضافية لتفعيل تلك الخلفية.

أول استخدام لذكاء المستندات: افتح /documents بعد البدء (محللات النص الأساسية تعمل بلا حزم إضافية). لمحرّكات التحويل/الحجب: pip install -e ".[document-platform]"؛ وهي تجلب أيضًا PyMuPDF، قارئ PDF الذي يعيد نص ملفات PDF العربية وأرقامها وخلايا جداولها إلى ترتيب القراءة. حزم نظام اختيارية: Tesseract ‏(OCR؛ التعرّف الضوئي على العربية غير مؤهَّل — فهو لا يقرأ الأرقام العربية الهندية)، ClamAV ‏(فحص البرمجيات الخبيثة)، LibreOffice ‏(ملفات .doc/.xls/.ppt القديمة، وبعض التحويلات، وملفات PDF العربية بجودة كاملة). تُحلَّل المستندات في عملية عاملة منفصلة لها حدود للذاكرة والمعالج؛ وهذا الوضع الافتراضي لا يحصر الوصول إلى الملفات ولا إلى الشبكة، لذا استخدم ملف تعريف العامل في الحاوية للمستندات التي لا تثق بها. الدليل: ذكاء المستندات.

ويندوز: ClamAV. يفعّل الإنتاج الإغلاق عند الفشل لفحص البرمجيات الخبيثة، لذا تُرفض الرفوعات حتى يستطيع clamscan الفحص فعلًا. ثبّت Cisco ClamAV، ثم نزّل قاعدة بيانات الفيروسات بـ freshclam. تُشحن الحزمة البرامج بلا تواقيع. تشغّل كاظمه clamdscan عندما يكون ذلك البرنامج على PATH، وclamscan خلاف ذلك. يحتاج clamdscan إلى clamd يعمل. مجلد ويندوز يحوي التنفيذيين معًا، فلا تضف ذلك المجلد إلى PATH إلا إذا كان البرنامج الخفي يعمل. اترك clamdscan خارج PATH وضع clamscan وحدها هناك. الخطوات: كيف أفعّل فحص البرمجيات الخبيثة؟.

المسار ج — Docker Compose للإنتاج

cp .env.example .env      # then edit .env (see step 3)
docker compose up -d --build

يثبّت الصورة .[rag,postgres,document-platform]، وتستمع على منفذ الحاوية 8000، ويوائم compose ‏المضيف 9090 → 8000 ‏(HOST_PORT للتجاوز). فحص الصحة يضرب /health/ready كل 30 ثانية (فترة بدء 300 ثانية). انظر النشر.

لا تبدأ بـ python -m uvicorn الخام على ويندوز — ذلك يفرض حلقة Proactor ويسقط نقاط حفظ Postgres بصمت. استخدم kazma serve / الحارس.

---

3. التهيئة

تقرأ كاظمه التهيئة من ثلاث طبقات (بأسبقية متزايدة لقراءات وقت التشغيل):

1. kazma.yaml — الافتراضيات التصريحية (مصدر الحقيقة عند الإقلاع الأول).
2. ConfigStore ‏(SQLite) — ‏kazma-data/settings.db؛ تلغي kazma.yaml بعد الإقلاع الأول.
3. متغيرات البيئة — تغلب في مساعدات محددة (مثل KAZMA_SECRET وKAZMA_VECTOR_PATH).

قواعد الأسبقية الكاملة موثقة في التهيئة ← أسبقية التجاوز.

.env الأدنى

انسخ .env.example إلى .env واضبط مفتاح مزوّد واحدًا على الأقل:

# Linux / macOS / WSL
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

# Required for the OpenAI provider:
OPENAI_API_KEY=sk-...

# Or, for DeepSeek (key stored via provider config, not a dedicated env var —
# see Configuration). Local servers (Ollama/LM Studio) need no key.

# Optional: Telegram gateway
# TELEGRAM_BOT_TOKEN=123456:ABC...

# Optional: protect HITL approval endpoints (recommended for any non-localhost deploy)
# KAZMA_SECRET=generate-a-long-random-string

مهم: فقط OPENAI_API_KEY وKAZMA_API_KEY تُقرآن كاحتياطيين عامين لمتغيرات البيئة من قبل مزوّد LLM. المزوّدون الآخرون (DeepSeek، Anthropic، xAI، …) يُمَفتَحون عبر قائمة مزوّدي ConfigStore / ‏kazma.yaml — لا توجد متغيرات بيئة مخصصة DEEPSEEK_API_KEY / ANTHROPIC_API_KEY يقرؤها الكود. انظر التهيئة ← مفاتيح API.

تحقق من kazma.yaml

افتح kazma.yaml وتأكد:

agent:
  name: kazma
  language: ar        # 'ar' enables RTL + Arabic UI; 'en' for English
  rtl: true

models:
  default: gpt-4o-mini
  router: kazma       # Kazma's own router — not an import of LiteLLM
  fallback: gpt-4o-mini

llm:
  base_url: https://api.openai.com/v1
  model: gpt-4o-mini
  max_tokens: 4096
  temperature: 0.7
  timeout: 60.0
  input_cost_per_1m: 0.15
  output_cost_per_1m: 0.6

ui:
  host: 127.0.0.1
  port: 9090

المرجع الكامل مفتاحًا بمفتاح في التهيئة.

---

4. التشغيل

واجهة الويب (الأكثر شيوعًا)

kazma serve              # default host 127.0.0.1, port 9090
kazma serve 9091         # if 9090 is taken (common on Windows + WSL/Docker)

على مضيف مراقَب (مهمة مجدولة / systemd / launchd)، التقط git pull عبر الحارس — لا تقتل python/uvicorn يدويًا:

& '.venv\Scripts\python.exe' scripts\service\kazma_guard.py --reload

افتح عنوان URL المطبوع في الطرفية (مثل http://127.0.0.1:9090 أو :9091). استخدم http، وليس https. انتقل إلى المحادثة وأرسل رسالة.

اختبار دخان:

curl http://127.0.0.1:9091/health

أمان الربط: المضيف الافتراضي هو 127.0.0.1. غير الاسترجاعي (KAZMA_HOST=0.0.0.0) يتطلب سرًّا قويًا KAZMA_SECRET وإلا خرجت العملية. على الاسترجاعي، يُولَّد سر تلقائيًا للعملية إن لم يُضبط (ولا يُخزَّن).
‏ERR_CONNECTION_RESET على :9090 في ويندوز: غالبًا portproxy قديم لـ WSL/Docker على 9090، وليس كاظمه — انظر استكشاف الأخطاء وإصلاحها §15.0 وشغّل kazma serve 9091.

‏TUI

kazma-tui

لوحة Textual بتبويبات للوحة التحكم والمحادثة والملفات والتتبعات والسرب والإعدادات. ‏TUI في المقام الأول عرض قابلية مراقبة للقراءة فقط للفرادى الأساسيين (تهيّئ ModelRegistry وSwarmEngine عند الإطلاق الأول إذا لم يكونا موجودين).

kazma ask (بلا خادم ويب)

نفس مشرف LangGraph، دون uvicorn. الرموز تتدفق إلى stdout؛ وأسطر الأدوات تذهب إلى stderr.

kazma ask "What files define the supervisor graph?"
kazma ask --plan "Add a rate limiter to the API"
kazma ask --json "fix the tests"          # NDJSON events (token/tool/done)
echo "summarize README.md" | kazma ask --json --no-stream -

على TTY، أدوات الخطر تطالب بـ y/N ‏(أو a = السماح لهذه الجلسة). الدخل المموّار عبر أنبوب / kazma ask - يفشل مغلقًا (لا HITL على دخل مستهلَك). --yolo هي بوابة الهروب الصريحة بلا واجهة. مساحة العمل هي cwd ‏(--workspace PATH للتجاوز).

‏ACP: ‏kazma acp هو Agent Client Protocol‏ JSON-RPC على stdio. وجّه Zed / JetBrains إلى ذلك الأمر. يبث الوكيل أجزاء session/update واستدعاءات الأدوات، ويطلب من المحرر الموافقة على أدوات الخطر عبر session/request_permission.

تحقق عبر CLI

kazma status

يستطلع الخادم قيد التشغيل (/api/gateway/status، /api/swarm/status) ويطبع إصدارات Python/كاظمه ومسار التهيئة وإصدارات الحزم الرئيسية.

---

5. أرسل أول رسالة لك

بمجرد أن يعمل kazma serve، تكون أسرع حلقة هي دردشة واجهة الويب. خلف الكواليس:

1. يُرسَل نصك بـ POST إلى /api/chat/stream ‏(SSE).
2. عقدة المشرف تستدعي LLM النشط بالأدوات المسجَّلة.
3. إذا استدعى LLM أداة خطر (مثل file_write، shell_exec)، يتوقف التنفيذ مؤقتًا ويُبعث حدث SSE ‏approval_required.
4. وافق عبر زر واجهة الويب → POST /api/approve/\{thread_id\} → يستأنف الرسم البياني بـ Command(resume=\{"approved": true\}).

يمكنك مشاهدة استدعاءات الأدوات واستخدام الرموز والتكلفة تتدفق عائدة كأحداث SSE. انظر ‏API ونقاط التوسعة ← عقد أحداث SSE.

---

6. فعّل قناة ثانية (تيليجرام، اختياري)

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

connectors:
  telegram:
    enabled: true

أعد تشغيل الخادم. يستقصي محوّل تيليجرام عبر الاستقصاء الطويل (أو webhook على /api/webhooks/telegram إذا هُيّئ). جرّب /help و/status و/model في البوت.

عزل المنصات: ‏chat_id وuser_id وmessage_id في تيليجرام لديك لا تدخل أبدًا حالة LangGraph — إنها تعيش في SessionStore وتُعاد إرفاقها عند الرد عبر _build_target_id(). انظر البوابات والمنصات.

---

7. الخطوات التالية

إذا أردت…	اقرأ
فهم المحرك	البنية
ضبط كل إعداد	التهيئة
إضافة أداة / مهارة مخصصة	المهارات وMCP والأدوات
تشغيل سرب متعدد العمال	تنسيق السرب
تأمين نشر إنتاجي	الأمان والسلامة + النشر
استخدام كاظمه بالعربية	الميزات العربية والثقافية

---

ملاحظات تدقيق الوثائق

• استرجاع الذاكرة تلقائي: في كل دور تبحث كاظمه عمّا يدور حوله السؤال في المحادثات السابقة والحقائق المحفوظة، ولا تعطي النموذج شيئًا حين لا يطابق شيء؛ وكل دور يكتمل يُحفظ (الذاكرة وRAG ← recall()). أما «خط أنابيب الذاكرة رباعي الطبقات» في README القديم فقد أُزيل عند الانتقال إلى ذاكرة V2.
• tiktoken ليست تبعية معلَنة؛ عدّ الرموز يعود إلى ارشادية أحرف/4 ما لم تنفّذ pip install tiktoken بنفسك.