Contributions are welcome — bug reports, algorithm improvements, new extractors, new LLM providers, documentation fixes, and test coverage.
Read AGENTS.md first. It is the single source of truth for AI assistants and human contributors alike. Key sections:
- §3 — Quick start and the pre-commit hook pitfall
- §5 — Code style (naming convention, async contract, prompt storage)
- §6 — Branching and commit format
- §7 — Checklist for adding a new algorithm operator
- §8 — Checklist for adding a new LLM provider
新建或修改 Prompt、动态输入组装、附加指令或模型可见输出约束时,必须按 Prompt 文本审核标准 审核受影响的完整请求。该文件是规则正文的唯一来源;审核记录应引用规则编号、具体位置、覆盖范围和结论。
未修改的历史 Prompt 不要求为形式统一批量迁移。文本审核通过不替代目标模型的效果、输出 token 和耗时验证;具体实验要求按任务的验收目标执行。
git clone git@github.com:EverMind-AI/EverAlgo.git
cd everalgo
uv sync --all-packages --group dev
uv run pre-commit install
ls .git/hooks/pre-commit # must existSee Installation for details.
Before opening a Merge Request (GitLab) or Pull Request (GitHub mirror), run the full check suite:
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pyright
uv run pytestAll five commands must pass. CI runs the same checks and will reject the MR / PR if any fail.
EverAlgo uses Gitmoji + Conventional Commits:
<emoji> <type>(<scope>): <description>
Examples:
✨ feat(user-memory): add ProfileExtractor prompt zh variant
🐛 fix(boundary): correct token count for emoji-only messages
♻️ refactor(rank): extract shared fusion helper
✅ test(clustering): cover acluster_by_llm fast-path edge case
📝 docs(concepts): clarify stateless-design operator contract
The scope is the distribution name without the everalgo- prefix (e.g. core, boundary, user-memory).
For cross-cutting changes use ci, repo, or docs.
The MR / PR title is load-bearing: the primary GitLab repo squash-merges the MR title verbatim onto main, and git-cliff parses these messages for CHANGELOGs. Keep the same format when contributing via the GitHub mirror.
Every MR that adds, changes, or removes user-visible behaviour must include a one-line entry in the affected package's packages/everalgo-<dist>/CHANGELOG.md under the ## [Unreleased] section. Use the Keep a Changelog subsection that fits: ### Added, ### Changed, ### Fixed, ### Removed, or ### Performance.
Internal refactors, test-only changes, and CI tweaks do not need an entry.
At release time, the [Unreleased] section is promoted to the new version header. Writing the entry in the MR — when the author has full context — produces better release notes than reconstructing from git history later. See releasing.md for the full policy.
Work on short-lived branches off main:
feat/<topic>
fix/<bug>
docs/<topic>
refactor/<topic>
Open a Merge Request (GitLab, primary) or Pull Request (GitHub mirror) and squash-merge into main.
main is protected; direct push is denied.
Follow the checklist in AGENTS.md §7. In summary:
- Pick the right subpackage based on the algorithm axis.
- Write the operator as a module-level function or a stateless class implementing the relevant
Protocol. - Store prompt strings as module-level constants in
<subpkg>/prompts/en/<name>.py(andzh/if applicable). - Re-export the operator in
<subpkg>/__init__.pyand add it to__all__. - Write tests using
FakeLLMClient— no real network calls in defaultpytest. - Add a CHANGELOG entry under
## [Unreleased]inpackages/everalgo-<dist>/CHANGELOG.md(see releasing.md). - Run the full check suite before opening the MR / PR.
Open an issue or discussion on the primary GitLab repo or the GitHub mirror.