| # Governance — classroom / boardroom / dojo |
|
|
| A clean-room reimplementation (from the behaviour of |
| [`github.com/openmindx/openmind`](https://github.com/openmindx/openmind) — Boardroom |
| multi-model consensus + Dojo head-to-head evaluation) of the decision layer that governs |
| training. Lives in `mindxtrain/governance/`; pure stdlib + pydantic, base-install importable. |
|
|
| ## The model |
|
|
| - **Classroom** (`governance/classroom.py`) — where an actor (model) trains. An actor |
| **graduates** when its persona imprint took: `graduate(imprint_report, min_delta=…)` |
| returns a `Graduation` (the motion the boardroom convenes on). Ties the governance layer |
| to `mindxtrain.eval.imprint`. |
| - **Boardroom** (`governance/boardroom.py`) — a panel of **any number** of role-based |
| members (advocate, critic, analyst, devil's advocate, expert, generalist). `convene(motion, |
| ballot)` tallies votes → `approved` / `rejected` / `disputed`. The boardroom **governs the |
| classroom**: it decides about training given a graduation. Preset boards: `classic_triad`, |
| `devils_court`, `full_board`, `peer_review`. |
| - **Dojo** (`governance/dojo.py`) — the boardroom's **dispute-settlement** extension. When a |
| boardroom is `disputed` (a tie or no quorum), a dojo settles it. **A dojo panel is always an |
| odd prime (≥ 3)** — an odd number of decisive judges cannot tie, so the dispute always |
| resolves. `Dojo.sized(n)` rounds a requested size to the nearest valid prime; `settle(motion, |
| ballot)` returns a final `DojoVerdict`. 2 is prime but even (can tie), so it is excluded. |
|
|
| ## Flow |
|
|
| ``` |
| classroom: train actor → measure imprint → graduate(report) ─► Graduation.motion |
| │ |
| boardroom: convene(motion, ballot) ─► approved / rejected / disputed │ |
| │ disputed │ |
| dojo (prime panel): settle_dispute(decision, dojo, ballot) ─► DojoVerdict (no tie) |
| ``` |
|
|
| Members vote via an explicit `{id: vote}` map or a callable `(member, motion) -> vote`, so |
| the whole layer is testable with no LLM and can later be backed by real models |
| (boardroom-of-LLMs, dojo head-to-head) — clean-room, never vendoring openmind's TypeScript. |
|
|
| ## Why prime |
|
|
| A boardroom can be any size because deliberation tolerates abstention and "no decision" |
| (escalate). A dojo must *settle* — so its panel is an odd prime: `approvals + rejections` |
| is odd, the majority is strict, and the verdict is final. See `governance/primes.py` |
| (`is_prime`, `next_prime`, `nearest_prime`) and `dojo.prime_dojo_size`. |
|
|
| ## Model-backed deliberation |
|
|
| `governance/panel.py` backs members + judges with **real models** (any OpenAI-compatible |
| backend — the same ollama / vLLM the operator serves). `deliberate(member, motion)` prompts a |
| member from its role stance and parses a `VERDICT: APPROVE|REJECT|ABSTAIN`; `model_ballot()` / |
| `model_judge_ballot()` return ballots you pass straight to `Boardroom.convene` / |
| `Dojo.settle`. Lazy + best-effort: a model that errors or returns no parseable verdict abstains |
| (boardroom) or is recorded as reject (dojo). The base URL resolves from |
| `MINDXTRAIN_OPENAI_BASE_URL` / `MINDXTRAIN_VLLM_BASE_URL` / `MINDXTRAIN_OLLAMA_BASE_URL`. |
|
|
| ## Coach surface |
|
|
| The **Boardroom** card (after the receipt card) convenes a board on a promotion motion and, |
| if disputed, settles it in a prime dojo: |
|
|
| - `GET /coach/api/boardroom/presets` — named boards → roles. |
| - `POST /coach/api/boardroom/convene` — `{motion, members:[{id,role,model}], quorum, votes?, |
| use_models?, base_url?}`. Tally supplied `votes`, or `use_models: true` to have each member's |
| model deliberate. Model calls run in a worker thread (`asyncio.to_thread`) so the operator |
| event loop never blocks on inference. Returns the decision + per-member deliberations. |
| - `POST /coach/api/dojo/settle` — `{motion, size, model?, votes?, use_models?, base_url?}`. |
| Sizes the panel to the nearest odd prime and settles. |
|
|
| ## Tests |
|
|
| - `tests/test_governance.py` — primes, any-N boardroom (majority / tie / no-quorum), prime-only |
| dojo (rejects non-prime panels, settles without tie), end-to-end classroom → disputed → dojo. |
| - `tests/test_governance_panel.py` — verdict parsing, role stances, model-backed ballots driving |
| a boardroom + dojo over a mocked chat backend, graceful backend-error handling. |
| - `tests/test_coach_governance_api.py` — convene (votes + model mode), dojo settle (prime sizing), |
| 422 paths, and the Coach card/JS presence. |
|
|
