البداية السريعة

اجعل كاظمة يعمل ويستجيب للرسائل في أقل من 10 دقائق. يغطّي هذا الدليل مسارات التثبيت الثلاثة وأقصر طريق إلى محادثة عاملة.

---

1. المتطلبات المسبقة

المتطلب	التفاصيل
Python	>=3.11, <3.14 (مُعلَن في pyproject.toml).
Git	للاستنساخ / kazma update (مسار تثبيت git).
مفتاح مُزوّد نماذج لغوية	واحد على الأقل من: OpenAI، DeepSeek، Anthropic، Google (ADC)، xAI، OpenRouter، NVIDIA NIM — أو خادم محلي (Ollama / LM Studio).
Node.js (اختياري)	فقط إذا أردت بناء/تقديم موقع وثائق Docusaurus (docs/). غير مطلوب لتشغيل كاظمة نفسه.

ملاحظة حول الإضافات: التثبيت الأساسي pip install -e . يثبّت كل ما يلزم لتشغيل الوكيل وواجهة الويب وTUI والبوابات والسرب. الإضافة rag (chromadb، sentence-transformers) مطلوبة فقط للذاكرة المتجهية / RAG — انظر الذاكرة وRAG.

---

2. التثبيت

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

المسار A — تثبيت قابل للتعديل (موصى به للتطوير)

git clone <your-repo-url> kazma
cd kazma
python -m venv .venv
# Windows (Git Bash / PowerShell):
.venv\Scripts\activate
# POSIX:
source .venv/bin/activate

pip install -e ".[rag,dev]"

• [rag] يضيف chromadb>=0.5.0 + sentence-transformers>=3.0.0.
• [dev] يضيف pytest، pytest-asyncio، ruff، mypy، locust، وغيرها.

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

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

يُشغّل الحاوية الأمر uvicorn kazma_ui.app:create_app --factory --host 0.0.0.0 --port 8000 بصلاحيات المستخدم غير الجذر kazma. يفحص الصحة المسار /api/gateway/status كل 30 ثانية. انظر النشر.

المسار C — Windows الأصلي (setup.ps1)

# From a PowerShell prompt in the repo root:
.\setup.ps1

يُنشئ setup.ps1 البيئة الافتراضية (venv)، ويثبّت الإصدار القابل للتعديل مع الإضافات، ويُهيّئ أدلة البيانات. لا تربط أوامر PowerShell مطلقًا باستخدام && أو || — استخدم ; وتحقّق من $LASTEXITCODE.

---

3. الضبط

يقرأ كاظمة الإعدادات من ثلاث طبقات (بترتيب أسبقية متصاعد للقراءات أثناء التشغيل):

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

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

ملف .env الأدنى

انسخ .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 تُقرأ كبدائل عامة من متغيرات البيئة بواسطة مُزوّد النماذج اللغوية. المُزوّدون الآخرون (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: litellm     # string only — see Configuration for what this actually does
  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: 8000

المرجع الكامل مفتاحًا بمفتاح موجود في الإعدادات.

---

4. التشغيل

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

kazma serve
# or: kazma-web
# or: python -m uvicorn kazma_ui.app:create_app --factory --host 127.0.0.1 --port 8000

افتح http://127.0.0.1:8000. ينبغي أن ترى لوحة التحكم. انتقل إلى Chat وأرسل رسالة.

أمان الارتباط: يرتبط kazma serve بالعنوان 127.0.0.1 افتراضيًا. ويتحوّل إلى 0.0.0.0 فقط عندما يكون KAZMA_SECRET مضبوطًا (kazma-cli/.../main.py:110). لا تعرّض الخادم للعموم مطلقًا دون ضبط KAZMA_SECRET — وإلا فإن نقطة نهاية الموافقة البشرية في الحلقة (HITL) تكون بلا مصادقة.

TUI

kazma-tui

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

التحقّق عبر CLI

kazma status

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

---

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

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

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

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

---

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

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

connectors:
  telegram:
    enabled: true

أعد تشغيل الخادم. يستطلع مُكيّف Telegram عبر الاستطلاع الطويل (long-polling) (أو عبر webhook على المسار /api/webhooks/telegram إذا كان مضبوطًا). جرّب الأوامر /help و/status و/model في البوت.

عزل المنصات: لا يدخل chat_id الخاص بـ Telegram ولا user_id ولا message_id مطلقًا في حالة الرسم البياني LangGraph — بل تظل محفوظة في SessionStore وتُعاد إضافتها عند الرد عبر _build_target_id(). انظر البوابات والمنصات.

---

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

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

---

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

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