diff --git a/docs/compression/COMPRESSION_GUIDE.md b/docs/compression/COMPRESSION_GUIDE.md index 12b380379e..2eefbf514f 100644 --- a/docs/compression/COMPRESSION_GUIDE.md +++ b/docs/compression/COMPRESSION_GUIDE.md @@ -446,6 +446,60 @@ Caveman output mode is **opt-in** — set it via the combo config: } ``` +### Output Styles (catalog) + +Caveman output mode above is the **legacy single-style path**. Phase 4 generalized it +into a catalog of composable output styles: `OUTPUT_STYLE_CATALOG` in +`open-sse/services/compression/outputStyles/catalog.ts`. Each style is a system-prompt +instruction that makes the model itself produce cheaper output; styles can be enabled +together and are injected in catalog order. + +| Style | `id` | What it does | Instruction languages | +| --- | --- | --- | --- | +| Terse prose | `terse-prose` | Drop filler/articles/hedging; keep technical substance exact. Same text as the legacy caveman output mode (referenced, not re-typed). | en, pt-BR, ja, id | +| Less code | `less-code` | YAGNI ladder: smallest working change, no unrequested abstractions. | en only (backlog: [#10426](https://github.com/diegosouzapw/OmniRoute/issues/10426)) | +| Ponytail (lazy senior dev) | `ponytail` | "The best code is the code never written": reuse > rewrite, root cause > symptom, shortest working diff. | en, pt-BR, vi, ja, id | +| I have ADHD (action-first) | `i-have-adhd` | Action first (command/path/snippet before prose), numbered bounded steps, ONE concrete next step, no preamble/recap/closers. Adapted from [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT). | en, pt-BR, vi, ja, id | +| Terse CJK (文言) | `terse-cjk` | Classical-Chinese ultra-terse style. | zh (locale-gated: only offered when the detected language is `zh`) | + +Every style ships three intensity levels — `lite`, `full`, `ultra` — and every level +ends with the shared boundaries clause, which keeps code blocks, file paths, commands, +error strings, URLs and identifiers verbatim. + +#### How injection works + +`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`) resolves +the selection against the catalog (unknown ids and locale-mismatched styles are +dropped, never an error), concatenates the selected instructions in catalog order, +appends the boundaries clause **once**, and front-loads the result into the system +prompt behind a single idempotency marker (`[OmniRoute Output Styles]`) — re-applying +is a no-op. When the detected request language has a translation, the localized +instruction is injected instead of English. + +#### How to enable + +In the dashboard: **Context → Settings → Compression** — one row per style with an +on/off toggle and a level selector. Programmatically, the compression config persists +the selection as: + +```json +{ + "outputStyles": [ + { "id": "i-have-adhd", "level": "full" }, + { "id": "less-code", "level": "lite" } + ] +} +``` + +Back-compat: the legacy `outputMode: "caveman"` combo setting still works and maps to +`terse-prose`, byte-identical to the old injection in all four legacy languages. + +The style × language matrix is pinned by +`tests/unit/compression/output-styles-i18n-matrix.test.ts`: a new style cannot ship +without at least a pt-BR translation (or an explicit tracked exception), and an +existing style cannot silently lose a locale. To add a style, see +[EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md#adding-an-output-style). + ### Tool Result Compression The `toolResultCompressor.ts` module provides **5 specialized compression strategies** diff --git a/docs/compression/EXTENDING_COMPRESSION.md b/docs/compression/EXTENDING_COMPRESSION.md index 7b33f5b37d..e4d8cb6609 100644 --- a/docs/compression/EXTENDING_COMPRESSION.md +++ b/docs/compression/EXTENDING_COMPRESSION.md @@ -568,6 +568,40 @@ gate (`check:compression-budget`). --- +## Adding an Output Style + +Output styles (see the [guide's catalog table](./COMPRESSION_GUIDE.md#output-styles-catalog)) +are the response-side counterpart of the input engines: instead of compressing what you +send, they instruct the model to produce cheaper output. The registry is +`OUTPUT_STYLE_CATALOG` in `open-sse/services/compression/outputStyles/catalog.ts`, and +**one catalog entry is the entire feature**: the injector, the dashboard settings panel, +persistence and telemetry all enumerate the catalog — there is no other list to update. + +1. **Add one entry to `OUTPUT_STYLE_CATALOG`** with `id`, `label`, `description` and the + three English `levels` (`lite`, `full`, `ultra`). Every level must end with + `${SHARED_BOUNDARIES}` so code, paths, commands, errors and URLs stay verbatim. + The instruction text must be **static and deterministic** per + `(id, level, language)` — `${SHARED_BOUNDARIES}` is the only interpolation allowed. +2. **Translate it.** Ship at least a `pt-BR` block under `i18n`; `ponytail` and + `i-have-adhd` (en, pt-BR, vi, ja, id) are the reference shape. A deliberately + single-language style sets `locale` instead (like `terse-cjk` → `zh`) and is then + only offered under that locale. +3. **Update the matrix guard** — add the style's languages to `BASELINE_LANGUAGES` in + `tests/unit/compression/output-styles-i18n-matrix.test.ts`. The gate fails any new + non-locale-gated style without the required translations unless it carries an + explicit `KNOWN_ENGLISH_ONLY` entry with a tracking issue. +4. **Add a per-style test** modeled on + `tests/unit/compression/i-have-adhd-catalog.test.ts`: catalog shape, boundaries + clause per level, and an anchor asserting each translation is written in its own + language rather than copied English. +5. **Attribution**: if the style is adapted from an upstream project, credit it in a + source comment on the entry (e.g. `i-have-adhd` → ayghri/i-have-adhd, MIT) — same + rule as "Proposing an upstream-inspired improvement" above. + +No UI, schema or telemetry change is needed — those surfaces render from the catalog. + +--- + ## Best Practices ### Engine Development