pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-07-31 12:22:14 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
aacd43bb453eea33ca57d4e722cf15bfae4ccced
OmniRoute/docs/COMPRESSION_ENGINES.md
Diego Rodrigues de Sa e Souza 99c6dc7fd6 Release v3.7.9 (#1917) 
* chore(release): v3.7.9 — gemini-cli cloud code separation

* chore(provider): Update Jina AI model catalog (#1874)

Integrated into release/v3.7.9

* docs: update CHANGELOG for PR 1874 and retroactive credits

* fix: resolve stream defaults and codex prompt mapping (#1873, #1872)

* chore(compression): start caveman compression update

* feat(compression): expand caveman compression and analytics pipeline

Add caveman intensity levels, output mode instructions, validation, and
preview diffs across the compression pipeline.

Extend MCP and dashboard settings to support auto-trigger mode, system
prompt preservation, MCP description compression, and caveman rule
metadata. Record richer compression analytics with receipt fields,
validation fallbacks, output mode data, and add the related database
migration.

Improve preservation handling for code, URLs, markdown, math, and other
protected content while adding broad unit, integration, and golden-set
coverage for caveman parity and compression behavior.

* feat(compression): expose rule intensities and track usd savings

Add estimated USD savings to compression analytics so saved tokens can
be reported in cost terms alongside existing token metrics.

Expose caveman rule intensity metadata for settings consumers and add a
settings API route alias for rule lookup. Also preserve system prompts
when aggressive compression falls back to lite mode.

* feat(compression): RTK compression roadmap (#1889)

* chore(rtk): initialize compression roadmap branch

* feat(compression): add RTK engine and compression combos

Introduce RTK command-aware tool-output compression alongside
stacked RTK -> Caveman pipelines for mixed prompt contexts.

Add engine registration, declarative RTK filter packs, language-aware
Caveman rule loading, compression combo persistence and assignments,
analytics grouped by engine/combo, and new MCP/API endpoints for
configuration, previews, filters, and combo management.

Expose the new capabilities in the dashboard with dedicated Context &
Cache pages for Caveman, RTK, and compression combos, and update docs,
i18n strings, migrations, and tests to cover the expanded compression
surface.

* feat(compression): expand RTK DSL, filter catalog, and recovery APIs

Add RTK parity features across the compression pipeline, dashboard,
and management APIs. This expands the built-in filter catalog, adds
trust-gated custom filter loading, inline filter verification, code
stripping, smarter detection, and optional redacted raw-output
retention for authenticated recovery.

Also extend Caveman with file-based multilingual rule packs, localized
output-mode instructions, stricter preview/config schemas, engine
registry metadata, analytics fields, and broad unit test coverage for
RTK, rule loading, and stacked compression behavior.

* fix(auth): protect oauth routes and health reset operations

Require authenticated dashboard access for OAuth endpoints that can
create or import provider connections when login enforcement is
enabled.

Move `/api/monitoring/health` to the readonly public route list so
safe methods remain public while DELETE now returns 401 for anonymous
requests.

Also update Next.js native `.node` handling to avoid webpack parse
failures from external packages such as ngrok and keytar, and add
coverage for the new auth behavior.

* build(compression): ship RTK rule and filter assets with app bundles

Include compression JSON assets in Next output tracing, prepublish copies,
and pack artifact policy checks so standalone and packaged builds can
load RTK filters and caveman rule packs at runtime.

Also harden compression runtime behavior by resolving alternate asset
directories, scoping rule cache entries by source path, carrying RTK raw
output pointers through stacked runs, degrading oversized preview diffs,
and applying combo language/output mode defaults during chat routing.

Add coverage for packaging rules, provider-scoped model parsing, smart
truncate edge cases, raw output retention, and combo-driven compression
behavior.

* docs(workflows): update local repo paths to OmniRoute

Replace outdated `/home/diegosouzapw/dev/proxys/9router` references
with the current `OmniRoute` directory across deploy, release, and
version bump workflow guides so local command examples match the
renamed repository layout

* feat(compression): complete RTK parity coverage

* test(build): align next config assertions

---------

Co-authored-by: diegosouzapw <diego.souza.pw@gmail.com>

* feat(compression): expand caveman parity and MCP metadata compression

Compress MCP registry and list metadata descriptions for tools, prompts,
resources, and resource templates while keeping tool-response bodies
unchanged. Expose those savings in compression status as
`mcp_metadata_estimate` metadata rather than provider usage.

Add Caveman rule-pack support for custom regex flags and match-specific
replacement maps, update English rules for upstream parity, and tighten
article and pleasantry handling. Also process RTK multipart text blocks
independently so mixed media content compresses safely without
duplicating output.

* feat(compression): unify config validation and persist MCP savings

Centralize compression config schemas across settings, preview, RTK,
and combo APIs to enforce consistent validation for stacked pipelines
and engine-specific options.

Expand caveman and stacked compression behavior by applying default
combos at runtime, surfacing validation and fallback metadata, and
exposing aggressive and ultra adapter schemas for configuration UI and
tests.

Persist MCP description compression snapshots into analytics without
counting them as provider usage, and extend the dashboard with the new
RTK controls and localized labels.

* fix(auth): require dashboard management auth for compression preview

Block preview requests unless they come from a valid management session
token so protected settings cannot be probed through the preview API.

Add unit coverage for unauthenticated requests, invalid bearer tokens,
and successful authenticated preview execution.

* fix(compression): preserve stacked defaults and secure metadata routes

Only apply saved default compression combos when they contain a stacked
pipeline so seeded Caveman-only defaults do not replace the builtin
stacked behavior.

Also require management auth for compression language pack and rules
metadata endpoints, and defer usage receipt attachment until compression
analytics writes have completed to keep analytics records consistent.

* fix(compression): align seeded standard savings combo with stacked default

Update the seeded default compression combo to use the RTK then
Caveman pipeline in both fresh installs and upgraded databases.

Add a targeted migration and runtime guard that only rewrites the
legacy seeded record when its original metadata and single-step
pipeline still match, preserving user-customized default combos.
Refresh docs and tests to reflect the stacked default and expanded
RTK filter catalog.

* docs(compression): document RTK+Caveman stacked savings ranges

Refresh the compression docs and README to describe the default
stacked pipeline in terms of eligible-context savings instead of the
older generic token-saving range.

Add upstream RTK and Caveman benchmark references, explain the
multiplicative savings math behind the stacked default, and update
feature summaries plus package metadata to match the revised
positioning.

* feat(image-gen): add NanoGPT image generation provider (#1899)

Integrated into release/v3.7.9

* fix(codex): sanitize raw responses input (#1895)

Integrated into release/v3.7.9

* Fix combo provider breaker profile handling (#1891)

Integrated into release/v3.7.9

* fix(combos): align strategy contracts (#1892)

Integrated into release/v3.7.9

* feat(proxy): move proxy configuration to dedicated System → Proxy page (#1907)

Integrated into release/v3.7.9

* feat: add K/M/B/T cost shortener to prevent UI overflow (#1902)

Integrated into release/v3.7.9

* feat(providers): implement bulk paste for extra API keys (#1916)

Integrated into release/v3.7.9

* fix(migrations): treat duplicate-column ALTER as no-op (#1886)

Integrated into release/v3.7.9

* fix(analytics): robust model pricing resolution, dark mode charts and SQL aggregation fixes (#1896)

Integrated into release/v3.7.9 (migration renumbered to 044)

* fix(oauth): per-connection mutex for rotating refresh tokens (#1885)

Integrated into release/v3.7.9

* fix: resolve 3 bugs — Codex tool normalization (#1914), image gen proxy (#1904), zero-arg MCP tools (#1898)

- fix(codex): flatten Chat Completions tool format to Responses format in
  normalizeCodexTools. Prevents 'Missing required parameter: tools[0].name'
  upstream errors when clients send {type:'function', function:{name,...}}
  instead of {type:'function', name,...}.

- fix(proxy): add proxy-aware execution context to image generation route.
  Image requests now correctly use proxy settings from the connection's
  ProxyRegistry assignment, matching the pattern used by chat pipeline.

- fix(translator): inject properties:{} into zero-argument MCP tool schemas
  during Anthropic→OpenAI translation. OpenAI strict mode requires explicit
  properties even for empty object schemas.

Closes #1914, Closes #1904, Closes #1898

* chore(release): v3.7.9 — all changes in ONE commit

* fix: allow local ollama provider connections (#1893)

* fix(copilot): emit compatible reasoning text deltas (#1919)

Integrated into release/v3.7.9

* fix(api-manager): show validation errors inline in modals, not behind backdrop (#1920)

Integrated into release/v3.7.9

* docs: update changelog and pr body with merged prs

* fix(providers): route agentrouter through anthropic endpoint headers

Update the AgentRouter provider registry to use the Claude-compatible
messages API and required Anthropic-style authentication headers. This
bypasses unauthorized_client_error responses and exposes the supported
model list through passthrough configuration.

Also update the changelog and release PR notes to document the fix for
#1921

* feat(logs): show compression tokens in request log UI (#1923)

* docs: add PR #1923 to changelog

---------

Co-authored-by: diegosouzapw <diego.souza.pw@gmail.com>
Co-authored-by: backryun <bakryun0718@proton.me>
Co-authored-by: Aculeasis <42580940+Aculeasis@users.noreply.github.com>
Co-authored-by: Raxxoor <manker_lol@hotmail.com>
Co-authored-by: Randi <55005611+rdself@users.noreply.github.com>
Co-authored-by: Paijo <14921983+oyi77@users.noreply.github.com>
Co-authored-by: Tubagus <54710482+0xtbug@users.noreply.github.com>
Co-authored-by: smartenok-ops <smartenok@gmail.com>
Co-authored-by: Gi99lin <74502520+Gi99lin@users.noreply.github.com>
Co-authored-by: ivan-mezentsev <ivan@mezentsev.me>
Co-authored-by: Andrew Munsell <andrew@wizardapps.net>
2026-05-04 01:36:53 -03:00

144 lines
7.2 KiB
Markdown
Raw Blame History

# Compression Engines
OmniRoute compression is built around engine contracts. A mode can run one engine directly
(`caveman` or `rtk`) or a deterministic stacked pipeline that executes multiple engines in order.
## Modes
| Mode | Engine path | Intended input |
| ------------ | ---------------------------------- | -------------------------------------------- |
| `off` | none | Exact prompt preservation |
| `lite` | Caveman lite helpers | Low-risk always-on cleanup |
| `standard` | Caveman | Natural-language prompt condensation |
| `aggressive` | Caveman + history/tool summarizers | Long chat sessions |
| `ultra` | Caveman + pruning helpers | Context-limit recovery |
| `rtk` | RTK | Terminal, shell, build, test, and git output |
| `stacked` | Pipeline, default `rtk -> caveman` | Mixed tool logs and prose, max savings |
## Engine Registry
The registry lives in `open-sse/services/compression/engines/registry.ts`. Engines expose a shared
contract:
- `id`: stable engine id such as `caveman` or `rtk`
- `label`: dashboard-readable name
- `supports(mode)`: whether the engine can execute a compression mode
- `compress(input)`: transforms text/messages and returns stats
`strategySelector.ts` registers the built-in engines before compression runs. This lets preview,
runtime compression, stacked mode, tests, and future engines use the same execution path.
## Caveman
Caveman mode focuses on semantic condensation of normal prose:
- preserves code blocks, URLs, JSON, paths, and structured data
- removes filler, hedging, repeated context, and verbose connective phrasing
- supports language-aware file rule packs in `open-sse/services/compression/rules/`
- remains available through the legacy `standard`, `aggressive`, and `ultra` modes
The dashboard surface is `Dashboard -> Context & Cache -> Caveman`.
Caveman upstream reports `~75%` fewer output tokens, `65%` average output savings in benchmarks
with a `22-87%` range, and a `~46%` input-compression tool. OmniRoute uses the Caveman input-side
number when documenting stacked prompt/context savings; Caveman output mode remains a separate
response-behavior feature.
## RTK
RTK mode focuses on command and tool output:
- detects output classes such as `git status`, `git branch`, `git diff`, Vitest/Jest/Pytest,
Cargo/Go tests, TypeScript/Vite/Webpack builds, ESLint, npm audit/installs, Docker logs,
shell `find`/`grep`, stack traces, and generic logs
- applies 49 JSON filters from `open-sse/services/compression/engines/rtk/filters/`
- supports the RTK-style declarative pipeline: ANSI stripping, replace, match-output short-circuit,
strip/keep lines, per-line truncation, head/tail/max-line truncation, and on-empty fallback
- supports trust-gated project filters in `.rtk/filters.json` and global filters in
`DATA_DIR/rtk/filters.json`
- strips ANSI sequences, progress noise, repeated lines, and unhelpful boilerplate
- preserves actionable failures, warnings, summaries, changed files, and tail context
- can optionally retain redacted raw output for recovery/debugging through authenticated management
routes
The dashboard surface is `Dashboard -> Context & Cache -> RTK`.
Operational details for custom filters, trust, verify, and raw-output recovery live in
[`RTK_COMPRESSION.md`](RTK_COMPRESSION.md).
RTK upstream reports `60-90%` savings for command-output compression. Its README example shows a
30-minute Claude Code session going from `~118,000` tokens to `~23,900`, or `79.7%` saved.
## Stacked Pipelines
Stacked mode runs pipeline steps in order. The default is:
```txt
rtk -> caveman
```
Use this for coding-agent sessions where a prompt combines command output with human or assistant
prose. RTK reduces noisy tool logs first, then Caveman compresses remaining natural language.
Pipeline steps are configured with `stackedPipeline` in compression settings or through compression
combos.
When both engines reduce the same eligible payload, savings compound:
```txt
combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
average = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
range = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```
## Compression Combos
Compression combos are named compression profiles that can be assigned to routing combos:
- `compression_combos`: stores mode, pipeline, RTK config, language config, and default marker
- `compression_combo_assignments`: maps a compression combo to a routing combo
- runtime integration resolves an assigned compression combo before generic combo overrides
- analytics include `compression_combo_id` and `engine`
Dashboard surface: `Dashboard -> Context & Cache -> Compression Combos`.
## API Surface
| Route | Purpose |
| -------------------------------------- | ------------------------------------------ |
| `/api/settings/compression` | Global compression settings |
| `/api/compression/preview` | Preview any compression mode |
| `/api/compression/language-packs` | List available Caveman language packs |
| `/api/context/caveman/config` | Caveman settings alias |
| `/api/context/rtk/config` | RTK defaults and settings |
| `/api/context/rtk/filters` | RTK filter catalog |
| `/api/context/rtk/test` | RTK preview/test endpoint |
| `/api/context/rtk/raw-output/[id]` | Authenticated redacted raw-output recovery |
| `/api/context/combos` | Compression combo CRUD |
| `/api/context/combos/[id]/assignments` | Routing-combo assignment CRUD |
| `/api/context/analytics` | Compression analytics alias |
Management routes require management authentication or API-key policy checks.
## MCP Tools
Compression exposes five MCP tools:
| Tool | Scope | Purpose |
| ----------------------------------- | ------------------- | -------------------------------- |
| `omniroute_compression_status` | `read:compression` | Settings, analytics, cache stats |
| `omniroute_compression_configure` | `write:compression` | Update global settings |
| `omniroute_set_compression_engine` | `write:compression` | Set mode and optional pipeline |
| `omniroute_list_compression_combos` | `read:compression` | List compression combos |
| `omniroute_compression_combo_stats` | `read:compression` | Read combo/engine analytics |
## Validation
The focused gates for this area are:
```bash
node --import tsx/esm --test tests/unit/compression/rtk-*.test.ts tests/unit/compression/pipeline-integration.test.ts tests/unit/compression/context-compression-api.test.ts
node --import tsx/esm --test tests/unit/compression/*.test.ts tests/golden-set/*.test.ts tests/integration/compression-pipeline.test.ts tests/unit/api/compression/compression-api.test.ts
npm run typecheck:core
```
Reference in New Issue View Git Blame Copy Permalink