AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• core/, memory/, learning/, reasoning/, safety/, training/ hold the primary Python packages referenced in pyproject.toml.
• Top-level orchestrators and demos live at the repo root (for example main_orchestrator.py, run_onboarding.py, demo_*).
• Web UI assets are under dashboard/ and dashboard-v3/ (frontend tooling and static assets).
• Tests are in tests/ plus root-level test_*.py integration checks.
• Supporting material lives in docs/, datasets/, research/, and scripts/.

Build, Test, and Development Commands

• python -m venv venv && source venv/bin/activate creates an isolated Python env.
• pip install -r requirements.txt installs runtime dependencies.
• pip install -e ".[dev]" installs dev tools (pytest/black/flake8/mypy).
• python main_orchestrator.py runs the primary orchestration flow.
• python run_onboarding.py launches the onboarding flow for profiles.
• cd dashboard && npm install && npm run dev starts the dashboard (adjust path if using dashboard-v3).

Coding Style & Naming Conventions

• Indentation: 4 spaces for Python; keep line length at 100 (Black default).
• Naming: snake_case for functions/variables/files, PascalCase for classes, UPPER_SNAKE_CASE for constants.
• Format/lint locally with black . and flake8 before major changes.

Testing Guidelines

• Pytest is the standard runner; use pytest to execute the full suite.
• Test discovery follows tests/ plus test_*.py at repo root; name new tests test_<feature>.py.
• Prefer focused tests (pytest tests/test_feature.py -k case_name) when iterating.

Commit & Pull Request Guidelines

• Commit history favors short, imperative summaries, sometimes with a type prefix like feat: or fix:.
• Keep commits scoped to one logical change; mention benchmarks or demos impacted.
• PRs should include a clear summary, list of tests run, and screenshots for UI changes.

Configuration & Secrets

• Runtime config is sourced from .env; use .env.example as the template.
• Never commit API keys or personal tokens; document required env vars in PRs when adding new ones.

Skills Catalog

• Full merged skills from QuLabInfinite, echo_prime, and achlys are tracked in docs/merged_skills_catalog.md.
• Machine-readable merged skills are tracked in docs/merged_skills_catalog.json.
• Rebuild the catalog with: python scripts/build_skill_catalog.py