Development

Repository layout, environment setup, and the test/lint/typecheck commands used across the Kazma monorepo.

---

1. Repository layout

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/        # Skill manifests (data)
├── kazma-cli/           # The `kazma` command surface
├── docs/                # Existing Docusaurus site (v3.4)
├── docs-v2/             # This rewrite
├── tests/               # Cross-cutting tests
├── examples/            # Example skills (e.g. almuhalab_custom_skills)
├── kubernetes/          # Hub API manifests (see Deployment §4)
├── 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. Environment setup

2.1 Install (editable, all extras)

git clone <repo> kazma && cd kazma
python -m venv .venv
source .venv/bin/activate        # POSIX
# or: .venv\Scripts\activate      # Windows

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

Extras (pyproject.toml:37-71):

Extra	Contents
rag	chromadb>=0.5.0, sentence-transformers>=3.0.0
dev	pytest, pytest-asyncio, pytest-cov, pytest-mock, ruff, mypy, locust
test	pytest stack + fakeredis
tracing	opentelemetry-* exporters/instrumentors
tui	textual>=8.0.0, python-bidi

2.2 Windows

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

2.3 uv (used by run.sh)

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

---

3. Code style & conventions

From AGENTS.md:

• Python: type hints, docstrings, logging.
• logger = logging.getLogger(__name__) pattern.
• from __future__ import annotations for type hints.
• One concern per file; keep modules focused.
• Compile-check Python before committing: python -c "import py_compile; py_compile.compile(r'<file>', doraise=True); print('OK')"
• Syntax-check JS before committing: node --check "<file>"
• PowerShell: never &&/||; use ; and $LASTEXITCODE.

---

4. Test / lint / typecheck

# 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)

Per-package commands are also declared in 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. The Docusaurus docs site (docs/)

The existing docs site is Docusaurus 3.4 (docs/package.json):

kazma docs build        # npm install && npm run build
kazma docs serve        # npm run start (port 3000)

This docs-v2/ tree is content intended to be folded into that site (see the integration note in the audit summary). The Docusaurus sidebars.js and docusaurus.config.js live in docs/.

---

6. Server lifecycle (development)

Restart the dev server (PowerShell, from AGENTS.md):

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 8090

---

7. Contributing

See CONTRIBUTING.md (root) for the full guide. Quick rules:

• Branch off main for PRs.
• Keep public API signatures stable (the swarm refactor preserved them; do the same).
• Compile/syntax-check before committing.
• Run the relevant test suite.
• Document security implications of any new danger tool or config flag.

---

Documentation Audit Notes

• The repo root has many .pytest_tmp_* directories from prior test runs — git-ignored clutter, safe to clean.
• services.yaml is scoped to kazma-tui commands; treat it as an example, not the canonical task runner for all packages.
• run.sh is a minimal end-to-end reproduction (installs, runs the full suite, exercises a live agent, writes EVAL.md) — useful for CI-like validation.