التطوير

تخطيط المستودع، وإعداد البيئة، وأوامر الاختبار/الفحص النصّي/فحص الأنواع المستخدمة عبر المستودع الموحّد (monorepo) لكاظمة.

---

1. تخطيط المستودع

kazma/
├── kazma-core/          # Agent runner, LLM provider, swarm, ConfigStore, safety, memory, skills, MCP, hub
├── kazma-gateway/       # Telegram/Discord/Slack adapters, agent_handler package, slash commands
├── kazma-ui/            # FastAPI app, SSE chat, swarm panel, settings, i18n, static assets
├── kazma-tui/           # Textual TUI dashboard
├── kazma-memory/        # Arabic tokenizer + SQLite/FTS5 search backend
├── kazma-skills/        # Native skills + manifests
├── kazma-cli/           # The `kazma` command surface
├── docs/                # Docusaurus site — single SoT (content under docs/docs/)
├── archive/             # Retired docs (former docs-v2, legacy pages)
├── tests/               # Cross-cutting tests
├── examples/            # Example skills (e.g. almuhalab_custom_skills)
├── scripts/             # Ops: migrate, smoke, tools-catalog regen, …
├── kubernetes/          # Sample K8s manifests (verify ports vs compose)
├── kazma.yaml           # Main config
├── kazma-permissions.yaml
├── kazma-security.yaml
├── services.yaml
├── pyproject.toml       # Single hatchling build for all 7 packages
├── Dockerfile           # Main agent image
├── docker-compose.yml   # Main agent compose
├── setup.ps1            # Windows bootstrap
└── run.sh               # Minimal E2E reproduction

---

2. إعداد البيئة

2.1 التثبيت (قابل للتحرير، كل الإضافات)

git clone <repo> kazma && cd kazma
python -m venv .venv

فعِّل البيئة الافتراضية حسب منصتك:

# Linux / macOS / WSL
source .venv/bin/activate

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

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

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

الإضافات (pyproject.toml:37-71):

الإضافة	المحتويات
rag	chromadb>=0.5.0, sentence-transformers>=3.0.0
dev	pytest, pytest-asyncio, pytest-cov, pytest-mock, ruff, mypy, locust
test	حزمة pytest + fakeredis
tracing	مُصدِّرات/أدوات opentelemetry-*
tui	textual>=8.0.0, python-bidi

2.2 Windows

.\setup.ps1            # validates env, syncs venv, runs import check

2.3 uv (يستخدمه run.sh)

uv sync --extra dev --extra cli --extra tui --extra rag

---

3. أسلوب الكود والاصطلاحات

من AGENTS.md:

• Python: تلميحات أنواع، docstrings، تسجيل.
• نمط logger = logging.getLogger(__name__).
• from __future__ import annotations لتلميحات الأنواع.
• اهتمام واحد لكل ملف؛ أبقِ الوحدات مركّزة.
• فحص تجميع Python قبل الالتزام: python -c "import py_compile; py_compile.compile(r'<file>', doraise=True); print('OK')"
• فحص صياغة JS قبل الالتزام: node --check "<file>"
• PowerShell: لا تستخدم &&/|| أبدًا؛ استخدم ; و$LASTEXITCODE.

---

4. الاختبار / الفحص النصّي / فحص الأنواع

# Python compile check (fast smoke)
.venv/Scripts/python.exe -c "import py_compile; py_compile.compile(r'kazma-core/kazma_core/llm_provider.py', doraise=True); print('OK')"

# JS syntax check
node --check "kazma-ui/kazma_ui/static/js/chat.js"

# Run tests
python -m pytest kazma-core/tests/ -v
python -m pytest tests/ -v                 # cross-cutting
python -m pytest -k majlis -v              # specific

# Lint
python -m ruff check kazma-core/kazma_core/
python -m ruff check kazma-tui/kazma_tui/  # (per services.yaml)

# Type check
python -m mypy kazma-tui/kazma_tui/        # (per services.yaml)

أوامر كل حزمة مُعلَنة أيضًا في services.yaml:

commands:
  install: "pip install -e kazma-tui/ -e kazma-core/"
  test: "python -m pytest kazma-tui/tests/ -v"
  lint: "python -m ruff check kazma-tui/kazma_tui/"
  typecheck: "python -m mypy kazma-tui/kazma_tui/"

---

5. موقع وثائق Docusaurus (docs/)

شجرة وثائق واحدة: docs/docs/ (Docusaurus 3.x). الإعداد: docs/sidebars.js، docs/docusaurus.config.js.

cd docs
npm install
npm start               # http://localhost:3000/kazma/
npm run build

# or via CLI:
kazma docs build
kazma docs serve

أعد توليد كتالوج الأدوات بعد إضافة أدوات:

python scripts/generate_tools_catalog.py

سياسة الخطط والأرشفة: docs/DOCS_CONSOLIDATION_PLAN.md، archive/README.md.

---

6. دورة حياة الخادم (التطوير)

أعد تشغيل خادم التطوير (PowerShell، من AGENTS):

Get-Process -Name python -ErrorAction SilentlyContinue |
  Where-Object { (Get-CimInstance Win32_Process -Filter ('ProcessId=' + $_.Id)).CommandLine -like '*uvicorn*kazma*' } |
  ForEach-Object { Stop-Process -Id $_.Id -Force }

cd 'G:\GitHubRepos\kazma'
& '.venv\Scripts\python.exe' -m uvicorn kazma_ui.app:create_app --factory --host 127.0.0.1 --port 9090

---

7. المساهمة

انظر CONTRIBUTING.md (الجذر) للدليل الكامل. قواعد سريعة:

• فرِّع من main لطلبات السحب (PRs).
• أبقِ توقيعات الواجهة البرمجية العامة مستقرة (إعادة هيكلة السرب حافظت عليها؛ افعل المثل).
• افحص التجميع/الصياغة قبل الالتزام.
• شغِّل مجموعة الاختبارات ذات الصلة.
• وثِّق الآثار الأمنية لأي أداة خطر جديدة أو علم إعدادات.

---

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

• جذر المستودع يحوي العديد من مجلدات .pytest_tmp_* من تشغيلات اختبار سابقة — فوضى متجاهَلة في git، آمنة للتنظيف.
• services.yaml محدود بأوامر kazma-tui؛ عامله كمثال، لا كمشغّل مهام معياري لكل الحزم.
• run.sh إعادة إنتاج نهاية-إلى-نهاية minimal (يثبّت، يشغّل المجموعة الكاملة، يمرّن وكيلًا حيًّا، يكتب EVAL.md) — مفيد للتحقّق شبيه بـ CI.