alex/club-3090
1
0
Fork 0
Code Issues Pull Requests Actions 38 Packages Projects Releases Wiki Activity

composes: formalize Status enum + Caveats field (100% coverage)

Browse Source 
The previous "Status optional, only when not production" convention
left readers guessing whether absence-of-status meant "validated
production" or "author forgot to fill it in." Making Status required +
enumerated removes that ambiguity.

Schema enhancement (codified in AGENTS.md):
- Status: now REQUIRED, exactly one of:
    ✅ Production              — verify-full + stress + bench + soak PASS
    ⚠️ Production w/ caveats   — works under documented constraints
    🧪 Experimental             — under active validation
    👁️ Preview                  — known quality issues, not production
    ⏸️ Upstream-gated           — blocked by external action (PR/driver)
    🗑️ Deprecated               — kept for historical reference
- Caveats: REQUIRED if Status is ⚠️/👁️/⏸️/🗑️, OMITTED for ✅/🧪.
  Single-line summary or short bullet list with issue/PR links.

Status applied to all 27 composes (vLLM + llama-cpp, all topologies):
  ✅ Production:              20  (canonical Qwen + Gemma + llama.cpp + gemma-awq)
  ⚠️ Production w/ caveats:    4  (long-text*, long-vision, carnice-bf16mtp)
  ⏸️ Upstream-gated:           2  (gemma single boot-OOM, gemma dflash-int8 needs #42102)
  👁️ Preview:                  1  (qwopus-bf16mtp)
  🧪 Experimental:             0
  🗑️ Deprecated:               0

llama-cpp composes also gained `Genesis: N/A — llama.cpp engine` for
parity with the vLLM schema (Genesis is Qwen3-Next-specific and
vLLM-only; explicit N/A prevents future readers from looking for
patches that don't exist).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
noonghunna
2026-05-09 12:19:44 +00:00
parent 9fbce96120
commit e1137d6889
25 changed files with 48 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
AGENTS.md
View File

@@ -113,12 +113,28 @@ Every compose starts with a `Profile (at-a-glance)` block declaring the (Model,
# Vision: <yes | no>
# Max ctx: <e.g. 262K>
# Genesis: <none | v7.72.2 | N/A — Genesis is Qwen3-Next-specific>
# Status: <optional — only if not production: ⚠️ PREVIEW / BOOT-OOM / etc.>
# Status: <REQUIRED — exactly one of the enum values below>
# Caveats: <REQUIRED if Status is ⚠️ / 👁️ / ⏸️ / 🗑️; otherwise omit>
# Best for: <one short phrase — what workload this serves; ⭐ for canonical>
# ---------------------------------------------------------------------------
# (existing free-form description continues below)
```
**Status enum** — pick exactly one:
| Value | Meaning | Validation gate |
|---|---|---|
| `✅ Production` | Recommended for users. | verify-full 8/8 + verify-stress 7/7 + bench (BENCHMARKS row) + soak-continuous PASS. |
| `⚠️ Production w/ caveats` | Works under documented constraints; not the same as broken. | Same gates as Production, but a known-and-disclosed limitation exists (e.g., Cliff 2b at >50K). Caveats line MUST list the constraint. |
| `🧪 Experimental` | Under active validation; may not boot or pass all tests. | Typically untracked in git. No production guarantee. |
| `👁️ Preview` | Known quality issues; tracked but not for production. | E.g., quality regressions in soak / NIAH. Caveats line MUST list specific issues. |
| `⏸️ Upstream-gated` | Exists but blocked by external action (PR merge, driver fix, hardware ceiling). | Boots only with vendored override OR doesn't boot until external dep lands. Caveats line MUST point at the external dep. |
| `🗑️ Deprecated` | Kept for historical reference; will be removed. | N/A — flagged for cleanup. |
**Why this enum exists**: the previous "Status optional, only when not production" convention left readers guessing whether absence-of-status meant "validated production" or "author forgot to fill it in." Making Status required + enumerated removes that ambiguity. Users picking a config can scan to one field and know the lifecycle stage instantly; new contributors must consciously declare it when authoring.
The `Caveats:` line is REQUIRED whenever Status is ⚠️ / 👁️ / ⏸️ / 🗑️, OMITTED for ✅ / 🧪. Format: a single-line summary or a short bullet list, with links to issues / discussions / upstream PRs where relevant.
This rule applies to **shipped composes AND local-only test composes** — apply the convention even before deciding whether to ship; it avoids a rename later if the experiment graduates.
When testing a new model, create the directory hierarchy from the start: `models/<new-model>/<engine>/compose/<topology>/docker-compose.yml`. The hierarchy enforces the convention; filenames encode only the feature stack within that topology. When the model isn't Qwen3-Next, write `Genesis: N/A — Genesis is Qwen3-Next-specific` in the profile schema so readers don't expect Genesis-style perf folds where they don't apply.