# Compression Engines (Kiswahili)

🌐 **Languages:** 🇺🇸 [English](../../../../compression/COMPRESSION_ENGINES.md) · 🇪🇹 [am](../../../am/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇦 [ar](../../../ar/docs/compression/COMPRESSION_ENGINES.md) · 🇦🇿 [az](../../../az/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇬 [bg](../../../bg/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇩 [bn](../../../bn/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇦 [bs](../../../bs/docs/compression/COMPRESSION_ENGINES.md) · 🇨🇿 [cs](../../../cs/docs/compression/COMPRESSION_ENGINES.md) · 🇩🇰 [da](../../../da/docs/compression/COMPRESSION_ENGINES.md) · 🇩🇪 [de](../../../de/docs/compression/COMPRESSION_ENGINES.md) · 🇬🇷 [el](../../../el/docs/compression/COMPRESSION_ENGINES.md) · 🇪🇸 [es](../../../es/docs/compression/COMPRESSION_ENGINES.md) · 🇪🇪 [et](../../../et/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇷 [fa](../../../fa/docs/compression/COMPRESSION_ENGINES.md) · 🇫🇮 [fi](../../../fi/docs/compression/COMPRESSION_ENGINES.md) · 🇫🇷 [fr](../../../fr/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇪 [ga](../../../ga/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [gu](../../../gu/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇬 [ha](../../../ha/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇱 [he](../../../he/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [hi](../../../hi/docs/compression/COMPRESSION_ENGINES.md) · 🇭🇷 [hr](../../../hr/docs/compression/COMPRESSION_ENGINES.md) · 🇭🇺 [hu](../../../hu/docs/compression/COMPRESSION_ENGINES.md) · 🇦🇲 [hy](../../../hy/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇩 [id](../../../id/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇬 [ig](../../../ig/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇹 [it](../../../it/docs/compression/COMPRESSION_ENGINES.md) · 🇯🇵 [ja](../../../ja/docs/compression/COMPRESSION_ENGINES.md) · 🇬🇪 [ka](../../../ka/docs/compression/COMPRESSION_ENGINES.md) · 🇰🇭 [km](../../../km/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [kn](../../../kn/docs/compression/COMPRESSION_ENGINES.md) · 🇰🇷 [ko](../../../ko/docs/compression/COMPRESSION_ENGINES.md) · 🇱🇹 [lt](../../../lt/docs/compression/COMPRESSION_ENGINES.md) · 🇱🇻 [lv](../../../lv/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [ml](../../../ml/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [mr](../../../mr/docs/compression/COMPRESSION_ENGINES.md) · 🇲🇾 [ms](../../../ms/docs/compression/COMPRESSION_ENGINES.md) · 🇲🇹 [mt](../../../mt/docs/compression/COMPRESSION_ENGINES.md) · 🇲🇲 [my](../../../my/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇵 [ne](../../../ne/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇱 [nl](../../../nl/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇴 [no](../../../no/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [or](../../../or/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [pa](../../../pa/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇭 [phi](../../../phi/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇱 [pl](../../../pl/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇹 [pt](../../../pt/docs/compression/COMPRESSION_ENGINES.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/COMPRESSION_ENGINES.md) · 🇷🇴 [ro](../../../ro/docs/compression/COMPRESSION_ENGINES.md) · 🇷🇺 [ru](../../../ru/docs/compression/COMPRESSION_ENGINES.md) · 🇱🇰 [si](../../../si/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇰 [sk](../../../sk/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇮 [sl](../../../sl/docs/compression/COMPRESSION_ENGINES.md) · 🇷🇸 [sr](../../../sr/docs/compression/COMPRESSION_ENGINES.md) · 🇸🇪 [sv](../../../sv/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [ta](../../../ta/docs/compression/COMPRESSION_ENGINES.md) · 🇮🇳 [te](../../../te/docs/compression/COMPRESSION_ENGINES.md) · 🇹🇭 [th](../../../th/docs/compression/COMPRESSION_ENGINES.md) · 🇹🇷 [tr](../../../tr/docs/compression/COMPRESSION_ENGINES.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/COMPRESSION_ENGINES.md) · 🇵🇰 [ur](../../../ur/docs/compression/COMPRESSION_ENGINES.md) · 🇺🇿 [uz](../../../uz/docs/compression/COMPRESSION_ENGINES.md) · 🇻🇳 [vi](../../../vi/docs/compression/COMPRESSION_ENGINES.md) · 🇳🇬 [yo](../../../yo/docs/compression/COMPRESSION_ENGINES.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/COMPRESSION_ENGINES.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/COMPRESSION_ENGINES.md)

---

Ukandamizaji wa OmniRoute umejengwa kuzunguka mikataba ya injini. Modi inaweza kuendesha injini moja moja kwa moja
(`caveman` au `rtk`) au bomba lililopangwa kwa njia bainifu linalotekeleza injini nyingi kwa mpangilio.

## Njia

| Njia         | Njia ya injini                                                                         | Ingizo lililokusudiwa                                    |
| ------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `off`        | hakuna                                                                                 | Uhifadhi kamili wa kidokezo                              |
| `lite`       | Visadia vya Caveman lite                                                               | Usafishaji usio na hatari, unaoendelea kila wakati       |
| `standard`   | Caveman                                                                                | Ufupishaji wa kidokezo cha lugha asilia                  |
| `aggressive` | Caveman + vifupishaji vya historia/zana                                                | Vikao virefu vya gumzo                                   |
| `ultra`      | Caveman + visadia vya kupunguza                                                        | Urejeshaji wa kikomo cha muktadha                        |
| `rtk`        | RTK                                                                                    | Pato la terminal, shell, build, test, na git             |
| `omniglyph`  | OmniGlyph                                                                              | Muktadha kama picha kwenye waya asilia wa mtoa huduma    |
| `stacked`    | Bomba. Chaguo-msingi la ombi ni `session-dedup -> lite`. `rtk -> caveman` ni ya hiari. | Logi za zana mchanganyiko na nathari, akiba ya juu zaidi |

### Wasifu wa mgandamizo wa OmniGlyph

Injini ya `omniglyph` (kifurushi `omniglyph`, 1.4.0+) inakubali wasifu wa kisemantiki uliotajwa, uliowekwa kimataifa kupitia `omniglyph.profile` katika mipangilio ya mgandamizo au kwa kila hatua kupitia usanidi wa hatua wa bomba lililopangwa:

| Wasifu        | Mpaka                                                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| `aggressive`  | Chaguo-msingi. Sera ambayo risiti zilizochapishwa zilipima — mfumo wa picha, nyaraka za zana na historia mnene |
| `balanced`    | Huacha hali hai ikiwa asilia, hulinda zamu 8 za mwisho, huangusha historia ya zamani iliyofungwa               |
| `coding-safe` | Huacha mamlaka, skimu za zana na pato la zana hai zikiwa asilia, hulinda zamu 12 za mwisho                     |
| `passthrough` | Hupitisha bila kubadilisha; injini inarukwa                                                                    |

Wasifu ni **dari, si sakafu**: `mergeCompressionProfileOptions` katika kifurushi inakataa kumruhusu mpigaji simu kubatilisha kufungua tena njia yenye hasara ambayo wasifu uliifunga, kwa hivyo `preserveSystemPrompt: false` kwa kila hatua haiwezi kuwezesha tena mgandamizo wa mfumo chini ya `coding-safe`.

Imepimwa kwenye msingi huu wa msimbo: `coding-safe` na `balanced` huongeza `minCompressChars` hadi kiwango chake cha juu na huweka mfumo, skimu za zana na matokeo ya zana yakiwa asilia, kwa hivyo kikao ambacho bado hakijakusanya historia huishia kwenye `below_min_chars` na injini haibadilishi chochote. Ndiyo maana chaguo-msingi ni `aggressive` badala ya wasifu salama zaidi.

Kifurushi hutatua upeo wake wa modeli na wasifu kutoka kwa usanidi wake wa mazingira. OmniRoute haikabidhi uamuzi kamwe: adapta huweka lango la modeli kwenye upeo mkali zaidi wa kifurushi, kwa hivyo mipangilio ya mazingira ya mwenyeji inaweza tu kupunguza orodha ya kuruhusiwa, kamwe haipanui zaidi ya risiti zilizopimwa za OmniRoute.

## Sajili ya Injini

Sajili ipo katika `open-sse/services/compression/engines/registry.ts`. Injini hutoa mkataba wa pamoja:

- `id`: kitambulisho thabiti cha injini kama vile `caveman` au `rtk`
- `apply(text, config)`: njia ya zamani ya utekelezaji inayotumiwa na mfululizo wa hatua zilizopangwa
- `compress(input, config)`: njia kuu ya utekelezaji inayorejesha maandishi + takwimu
- `getConfigSchema()`: hurejesha muundo unaofanana na JSON-Schema wa usanidi halali
- `validateConfig(config)`: hurejesha `{ valid, errors[] }`

Usajili hutumia `registerCompressionEngine(engine)` (au `registerEngine` kwa hali za kina),
ambayo huita `assertValidEngine()` na `validateConfig(defaultConfig)` kabla ya kukubali.
Tumia `unregisterCompressionEngine(id)` kuondoa injini wakati wa utekelezaji.

`strategySelector.ts` husajili injini zilizojengewa ndani kabla ya mfinyazo kuendeshwa. Hii huruhusu uhakiki,
mfinyazo wakati wa utekelezaji, hali iliyopangwa kwa hatua, majaribio, na injini za baadaye kutumia njia ileile ya utekelezaji.

### Mfinyazo wa maelezo ya MCP (yanayohusiana)

Sajili tofauti hubana metadata ya maelezo ya zana za MCP katika kiwango cha sajili — tazama
`open-sse/mcp-server/descriptionCompressor.ts` na [MCP-SERVER.md](../frameworks/MCP-SERVER.md). Hutumia tena
kanuni za Caveman lakini hufanya kazi kwenye metadata ya zana, si data za maombi.

### Injini za ziada zilizojengewa ndani

Mbali na Caveman, RTK, na LLMLingua-2, sajili huja na injini kadhaa maalumu zisizopoteza data /
za kimuundo (zinazotumiwa na mifuatano ya hatua zilizopangwa, mazingira ya majaribio, na majaribio):

| Injini        | Id              | Inachofanya                                                                                                                                                                                           |
| ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CCR           | `ccr`           | Content-Compress-Retrieve (H4): hubadilisha mafungu makubwa ya maandishi yanayofuatana kwa marejeleo yanayotegemea maudhui, ili mafungu yanayorudiwa/makubwa yatumwe mara moja na kurejelewa baadaye. |
| headroom      | `headroom`      | SmartCrusher (H3 + N5): ubanaji wa kijedwali usiopoteza data wa data za safu za JSON zinazofanana kuwa muundo wa kisafu wa `[N rows]`.                                                                |
| ionizer       | `ionizer`       | Uteuzi wa sampuli za safu za mwanzo/katikati/mwisho kwa mafungu makubwa sana yanayofanana, huku sehemu ya katikati iliyoachwa ikihifadhiwa kama rejeleo la CCR linalotegemea maudhui.                 |
| session-dedup | `session-dedup` | Uondoaji wa urudufu kati ya zamu unaotegemea maudhui (uliohamasishwa na TokenMizer): huondoa maandishi ambayo tayari yameonekana katika zamu za awali za kipindi hicho hicho.                         |

**Maagizo ya itifaki ya urejeshaji ya CCR (#8033):** mara ya kwanza CCR inapobadilisha ≥1 fungu katika
ombi, injini huongeza mwanzoni ujumbe mmoja wa `system` usioathiriwa na kurudiwa (unaoanza na
alama tambulishi ya `[CCR protocol]`) unaomfundisha mpigaji mkataba wa alama → zana: maana ya
alama ya `[CCR retrieve hash=<24hex> chars=N]`, kwamba hash lazima inakiliwe bila kubadilishwa
(herufi zote 24 za hex — hash zilizonakiliwa vibaya ndizo chanzo kinachowezekana cha hitilafu za "fungu halijapatikana"),
na kwamba alama ya `[dedup:ref sha=...]` inamaanisha "angalia nyuma katika historia", si "ita
zana". Dokezo huingizwa **tu wakati `tools[]` zilizotangazwa na mpigaji zinathibitisha kuwa anaweza
kufikia `omniroute_ccr_retrieve`** (`callerSupportsCcrRetrieve()` katika
`open-sse/services/compression/engines/ccr/protocolInstruction.ts`) — mpigaji wa kawaida
anayeoana na OpenAI bila zana hiyo hapokei kamwe maagizo ya kuita kitu ambacho
hawezi kufikia. Kutobadilika kunapotekelezwa mara nyingi kunahakikishwa kwa kuchanganua historia ya ujumbe kutafuta alama tambulishi
kabla ya kuingiza, hivyo maombi ya zamu nyingi (yanayocheza tena ujumbe wa awali) hayakusanyi
dokezo moja kwa kila zamu.

## Caveman

Hali ya Caveman inalenga ufupishaji wa kisemantiki wa nathari ya kawaida:

- huhifadhi vizuizi vya msimbo, URL, JSON, njia, na data iliyopangwa
- huondoa maneno ya kujaza, kauli za tahadhari, muktadha unaorudiwa, na vifungu virefu vya kuunganisha mawazo
- hutumia vifurushi vya kanuni za faili vinavyozingatia lugha katika `open-sse/services/compression/rules/`
- huendelea kupatikana kupitia hali za zamani za `standard`, `aggressive`, na `ultra`

Sehemu yake kwenye dashibodi ni `Dashboard -> Context & Cache -> Caveman`.

Mradi wa msingi wa Caveman unaripoti tokeni za matokeo zilizopungua kwa `~75%`, uokoaji wa wastani wa matokeo wa `65%` katika majaribio ya utendaji
ukiwa na masafa ya `22-87%`, na zana ya ukandamizaji wa ingizo ya `~46%`. OmniRoute hutumia takwimu ya upande wa ingizo wa Caveman
inapoandika kuhusu uokoaji uliounganishwa wa prompt/muktadha; hali ya matokeo ya Caveman inabaki kuwa kipengele tofauti
cha tabia ya majibu.

## RTK

Hali ya RTK inalenga matokeo ya amri na zana:

- hutambua aina za matokeo kama vile `git status`, `git branch`, `git diff`, Vitest/Jest/Pytest,
  majaribio ya Cargo/Go, ujenzi wa TypeScript/Vite/Webpack, ESLint, ukaguzi/usakinishaji wa npm, kumbukumbu za Docker,
  `find`/`grep` za shell, stack traces, na kumbukumbu za kawaida
- hutumia vichujio 49 vya JSON kutoka `open-sse/services/compression/engines/rtk/filters/`
- hutumia pipeline elekezi ya mtindo wa RTK: kuondoa ANSI, kubadilisha, njia ya mkato ya match-output,
  kuondoa/kuhifadhi mistari, ukataji kwa kila mstari, ukataji wa mwanzo/mwisho/idadi ya juu ya mistari, na chaguo mbadala wakati hakuna kitu
- hutumia vichujio vya mradi vinavyodhibitiwa kwa uaminifu katika `.rtk/filters.json` na vichujio vya jumla katika
  `DATA_DIR/rtk/filters.json`
- huondoa mfuatano wa ANSI, kelele za maendeleo, mistari inayorudiwa, na maandishi ya kawaida yasiyosaidia
- huhifadhi hitilafu zinazoweza kushughulikiwa, maonyo, muhtasari, faili zilizobadilishwa, na muktadha wa mwisho
- inaweza kwa hiari kuhifadhi matokeo ghafi yaliyofichwa taarifa nyeti ili yaweze kurejeshwa/kutumika katika utatuzi kupitia njia za usimamizi
  zilizothibitishwa

Sehemu yake kwenye dashibodi ni `Dashboard -> Context & Cache -> RTK`.

Maelezo ya uendeshaji kuhusu vichujio maalum, uaminifu, uthibitishaji, na urejeshaji wa matokeo ghafi yanapatikana katika
[`RTK_COMPRESSION.md`](./RTK_COMPRESSION.md).

Mradi wa msingi wa RTK unaripoti uokoaji wa `60-90%` kwa ukandamizaji wa matokeo ya amri. Mfano wake wa README unaonyesha kipindi cha dakika
30 cha Claude Code kikishuka kutoka tokeni `~118,000` hadi `~23,900`, au uokoaji wa `79.7%`.

## LLMLingua-2 (Upogoaji wa Kisemantiki)

Hali ya LLMLingua-2 hufanya **upogoaji wa kisemantiki wa tokeni** kwenye nathari kwa kutumia kiainishaji kidogo cha tokeni cha ONNX,
ikikamilisha injini za Caveman na RTK zinazotegemea kanuni:

- hukandamiza nathari katika ujumbe usio wa mfumo pekee; vizuizi vya msimbo vilivyozungushiwa uzio na miundo mingine inayohifadhiwa
  haibadilishwi kamwe
- huendesha backend ya `@atjsh/llmlingua-2` (ONNX kupitia `@huggingface/transformers`) katika
  worker thread, hivyo inference ya modeli haizuii kamwe event loop ya ombi
- **inaweza kuunganishwa** (`stackPriority` 35): katika pipeline iliyounganishwa huendeshwa baada ya
  injini za kimuundo (CCR, session-dedup, headroom, Caveman) lakini kabla ya `ultra`, kwa kuwa
  upogoaji wa kisemantiki huwa na ufanisi zaidi kwenye maandishi ambayo tayari yamekandamizwa kimuundo — kwa mfano
  `rtk -> caveman -> llmlingua`
- **huruhusu mfumo kuendelea baada ya hitilafu yoyote** (optional deps zinazokosekana, kuanzisha worker, kupakia modeli, inference,
  au timeout) → maandishi asili hurudishwa bila kubadilishwa, si hitilafu kamwe

Mahali ilipo injini: `open-sse/services/compression/engines/llmlingua/`. Sehemu yake kwenye dashibodi
ni `Dashboard -> Context & Cache -> LLMLingua`.

### Modeli

Modeli chaguo-msingi ni **TinyBERT** (`atjsh/llmlingua-2-js-tinybert-meetingbank`, ~57 MB,
ya haraka). Modeli ya **BERT-base** yenye usahihi wa juu zaidi (`Arcoldd/llmlingua4j-bert-base-onnx`,
~710 MB) inapatikana kupitia sehemu ya `model` ya usanidi wa injini. `@huggingface/transformers`
hupakua modeli iliyochaguliwa inapohitajika kutoka HuggingFace Hub hadi
`${DATA_DIR}/models/llmlingua` wakati wa mwito wa kwanza (`modelStore.ts`); badilisho la usanidi la `modelPath`
huielekeza kwenye nakala ya ndani badala yake (usakinishaji wa nje ya mtandao / uliotenganishwa na mtandao).

### Vitegemezi vya hiari na usakinishaji unapohitajika

Rundo la runtime peer la LLMLingua linaloweza kuondolewa ni la **hiari**. Package mbili zimetangazwa kama
`optionalDependencies` katika `package.json` na zimehifadhiwa kuwa **external** na production build
(`scripts/build/prepublish.ts` haizifungashi):

| Package              | Toleo (lililofungwa) | Maelezo                                    |
| -------------------- | -------------------- | ------------------------------------------ |
| `@atjsh/llmlingua-2` | `2.0.5`              | Package kuu; hutangaza nyingine kama peers |
| `js-tiktoken`        | `^1.0.20`            | Tokenizer                                  |

`@huggingface/transformers` imefungwa kwenye `^4.2.0` (inashirikiwa na njia ya embeddings za ndani na
pia hufuatiliwa ndani ya standalone bundle); `@atjsh/llmlingua-2@2.0.5` huitumia kama peer kwa
`"^3.5.2 || ^4.0.0"`, hivyo Transformers.js v3 na v4 zote zinatumika. Tangu 2.0.4,
`@atjsh/llmlingua-2` haihitaji tena `@tensorflow/tfjs`, jambo lililoondoa mchangiaji mmoja mkubwa zaidi
(TensorFlow.js) kutoka kwenye rundo la SLM. Ni package mbili zilizo hapo juu pekee ndizo SLM
peers zinazoweza kuondolewa. `npm install` ya kawaida (dev) husakinisha rundo la hiari kiotomatiki isipokuwa vitegemezi vya hiari
vimeachwa nje.

**Kwa nini usakinishaji unapohitajika:** package iliyochapishwa kupitia npm, standalone bundle, na Docker image
husambazwa **bila** deps hizi ili zisibebe uzito mkubwa. Zisipokuwepo, ukaguzi wa vitegemezi wa worker
(jaribio la resolve la `@atjsh/llmlingua-2` katika `worker.ts`) hushindwa na injini
**huendelea kimya baada ya hitilafu** — kuchagua LLMLingua hakufanyi chochote (maandishi hurudishwa bila kubadilishwa, hakuna
hitilafu inayorekodiwa). Ili kuiwasha katika mazingira yaliyopogolewa, sakinisha rundo la hiari:

```bash
# funga kwenye matoleo yaliyotangazwa katika optionalDependencies za package.json
npm install @atjsh/llmlingua-2@2.0.5 js-tiktoken
```

Kuondolewa kwa `@tensorflow/tfjs` (2.0.4+) huondoa mchangiaji wa awali aliyekuwa mkubwa zaidi wa ~800 MB
— ukubwa uliobaki unatokana na runtime za transformers.js + onnxruntime-node,
pamoja na modeli ya TinyBERT (~57 MB) inayopakuliwa inapotumika kwa mara ya kwanza (si kupitia npm).

Kwa kila mazingira:

- **Utengenezaji / `npm install`** — husakinishwa kiotomatiki isipokuwa ulitumia `--omit=optional`
  (au `--no-optional`). Hakuna hatua inayohitajika.
- **npm ya kimataifa (`npm i -g omniroute`) / inayojitegemea** — tekeleza amri ya usakinishaji iliyo hapo juu ndani ya
  saraka ya kifurushi kilichosakinishwa, au sakinisha upya bila kuacha vitegemezi vya hiari.
- **Docker** — ongeza amri ya usakinishaji katika safu ya taswira inayotokana; taswira iliyochapishwa
  imeundwa kuwa nyepesi kimakusudi.
- **VPS (PM2)** — sakinisha kwenye `node_modules` ya programu, kisha anzisha upya mchakato ili
  worker ichunguze tena geti.
- **Next inayojitegemea ghafi (`npm run build` → `.build/next/standalone/server.js`)** — ufuatiliaji
  unaojitegemea hausafirishi worker WALA vitegemezi vya hiari, kwa hivyo injini huruhusu kimyakimya
  utendaji kuendelea inaposhindwa. `scripts/build/colocate-standalone.mjs` hutumia tena vyote viwili (esbuild ya worker +
  mkusanyiko wa vitegemezi vya hiari ndani ya mti unaojitegemea); huendeshwa kiotomatiki kupitia
  hook ya npm ya `postbuild` baada ya kila build. Inaweza kurudiwa bila madhara, na hushindwa kwa upole wakati vitegemezi havipo.

**Thibitisha kuwa inatumika:** LLMLingua ikiwa imechaguliwa, maandishi halisi hupungua kwa kweli (injini
huacha kuruhusu utendaji kuendelea inaposhindwa), na ombi la kwanza huanzisha upakuaji wa modeli ndani ya
`${DATA_DIR}/models/llmlingua`. Geti huchunguza `@atjsh/llmlingua-2` pekee kimakusudi —
peers nyingine ni za ESM pekee na `require.resolve` hutupa hitilafu kwao hata zinapokuwapo — kwa hivyo
worker bado huruhusu utendaji kuendelea inaposhindwa ikiwa peer yoyote haipo kwa kweli wakati wa `import()`.

## Mabomba Yaliyopangwa kwa Safu

Hali ya safu huendesha hatua za bomba kwa mpangilio. Chaguo-msingi ni:

```txt
rtk -> caveman
```

Tumia hii kwa vipindi vya mawakala wa usimbaji ambapo kidokezo huchanganya matokeo ya amri na maandishi ya binadamu au msaidizi. RTK hupunguza kwanza kumbukumbu za zana zenye kelele, kisha Caveman hubana lugha asilia iliyobaki.

Hatua za bomba husanidiwa kwa `stackedPipeline` katika mipangilio ya ubanaji au kupitia michanganyiko ya ubanaji.

Injini zote mbili zinapopunguza data ileile inayostahiki, uokoaji huongezeka kwa kuzidishana:

```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%
```

## Kichujio cha Mti wa Ufikivu wa MCP

Kichujio mahiri cha mti wa ufikivu wa MCP ni safu ya ubanaji baada ya utekelezaji inayoendesha kwenye **matokeo ya zana** za MCP, si kwenye vidokezo au muktadha. Inalenga data ndefu za mti wa ufikivu na picha za hali ya kivinjari zinazorejeshwa na zana kama Playwright, computer-use, na seva za MCP za uendeshaji otomatiki wa kivinjari.

### Kinachofanya

1. **Kuondoa kelele** — huondoa vipengee tupu vya jumla/maandishi (`- generic:`, `- text: ""`)
2. **Kukunja vipengee jirani** — wakati mistari ≥ `collapseThreshold` (chaguo-msingi 30) inayofuatana ni marudio ya kimuundo, huikunja kuwa mistari `collapseKeepHead` ya kwanza (chaguo-msingi 10) + muhtasari wa idadi + mistari `collapseKeepTail` ya mwisho (chaguo-msingi 5)
3. **Kuhifadhi marejeleo** — nanga za `[ref=eXX]` zinazohitajika na Playwright/computer-use haziguswi kamwe
4. **Kukatisha kwa lazima** — ikiwa maandishi baada ya kukunjwa bado yanazidi `maxTextChars` (chaguo-msingi 50,000), huyakatisha pamoja na kidokezo cha urambazaji ili wakala aweze kuendelea kufanya kazi

### Mahali injini ilipo

```txt
open-sse/services/compression/engines/mcpAccessibility/
  index.ts            ← sehemu ya kuingilia ya smartFilterText()
  collapseRepeated.ts ← algoriti ya kukunja vipengee jirani
  constants.ts        ← DEFAULT_MCP_ACCESSIBILITY_CONFIG
```

### Usanidi

Hudhibitiwa na `compression.mcpAccessibility` katika mipangilio ya jumla (uhamishaji 056). Usanidi wa chaguo-msingi:

```json
{
  "enabled": true,
  "maxTextChars": 50000,
  "collapseThreshold": 30,
  "collapseKeepHead": 10,
  "collapseKeepTail": 5,
  "minLengthToProcess": 2000
}
```

Kichujio hutumika tu kwa data za matokeo ya zana ambazo `type` yake ni `"text"` na urefu wake unazidi `minLengthToProcess`. Hakiathiri ubanaji wa vidokezo au data za maombi.

### Uokoaji unaotarajiwa

60–80% kwenye matokeo ya zana za picha za hali ya kivinjari, kulingana na uchangamano wa ukurasa. Algoriti ya kukunja ni O(n) kulingana na idadi ya mistari na huongeza muda wa kusubiri usio na maana.

### Kichujio hiki dhidi ya injini za ubanaji zilizo hapo juu

| Kipengele          | Caveman / RTK / Stacked      | Kichujio cha ufikivu cha MCP           |
| ------------------ | ---------------------------- | -------------------------------------- |
| Lengo              | Vidokezo vya ombi / muktadha | Matokeo ya zana za MCP                 |
| Kichochezi         | Mpangilio wa hali ya ubanaji | `compression.mcpAccessibility.enabled` |
| Upeo               | Ujumbe wote wa SSE           | Matokeo ya zana pekee                  |
| Nanga za marejeleo | Haitumiki                    | Huhifadhiwa bila masharti              |

---

## Michanganyiko ya Mfinyazo

Michanganyiko ya mfinyazo ni wasifu wa mfinyazo wenye majina ambao unaweza kuhusishwa na michanganyiko ya uelekezaji:

- `compression_combos`: huhifadhi modi, mnyororo wa uchakataji, usanidi wa RTK, usanidi wa lugha, na kiashirio chaguo-msingi
- `compression_combo_assignments`: huhusisha mchanganyiko wa mfinyazo na mchanganyiko wa uelekezaji
- muunganisho wa wakati wa utekelezaji hutatua mchanganyiko wa mfinyazo uliohusishwa kabla ya ubatilishaji wa jumla wa mchanganyiko
- takwimu za uchanganuzi zinajumuisha `compression_combo_id` na `engine`

Sehemu ya dashibodi: `Dashboard -> Context & Cache -> Compression Combos`.

## Kiolesura cha API

| Njia                                   | Madhumuni                                                                   |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `/api/settings/compression`            | Mipangilio ya jumla ya mfinyazo (inajumuisha usanidi wa `mcpAccessibility`) |
| `/api/compression/preview`             | Hakiki modi yoyote ya mfinyazo                                              |
| `/api/compression/language-packs`      | Orodhesha vifurushi vya lugha vya Caveman vinavyopatikana                   |
| `/api/context/caveman/config`          | Jina mbadala la mipangilio ya Caveman                                       |
| `/api/context/rtk/config`              | Chaguo-msingi na mipangilio ya RTK                                          |
| `/api/context/rtk/filters`             | Katalogi ya vichujio vya RTK                                                |
| `/api/context/rtk/test`                | Endpointi ya kuhakiki/kujaribu RTK                                          |
| `/api/context/rtk/raw-output/[id]`     | Urejeshaji uliothibitishwa wa matokeo ghafi yaliyofichwa taarifa nyeti      |
| `/api/context/combos`                  | CRUD ya michanganyiko ya mfinyazo                                           |
| `/api/context/combos/[id]/assignments` | CRUD ya uhusishaji wa michanganyiko ya uelekezaji                           |
| `/api/context/analytics`               | Jina mbadala la uchanganuzi wa mfinyazo                                     |

Njia za usimamizi zinahitaji uthibitishaji wa usimamizi au ukaguzi wa sera ya ufunguo wa API.

## Zana za MCP

Mfinyazo unatoa zana tano za MCP:

| Zana                                | Upeo                | Madhumuni                                    |
| ----------------------------------- | ------------------- | -------------------------------------------- |
| `omniroute_compression_status`      | `read:compression`  | Mipangilio, uchanganuzi, takwimu za akiba    |
| `omniroute_compression_configure`   | `write:compression` | Sasisha mipangilio ya jumla                  |
| `omniroute_set_compression_engine`  | `write:compression` | Weka modi na mnyororo wa hiari wa uchakataji |
| `omniroute_list_compression_combos` | `read:compression`  | Orodhesha michanganyiko ya mfinyazo          |
| `omniroute_compression_combo_stats` | `read:compression`  | Soma uchanganuzi wa mchanganyiko/injini      |

## Upeo na mambo yasiyojumuishwa

**Embeddings hazifinyazwi kamwe.** `open-sse/handlers/embeddings.ts` haiiti kamwe injini yoyote ya
mfinyazo — miili ya ombi/jibu hupitishwa moja kwa moja kwa kitekelezaji bila kubadilishwa.
Hili kwa sasa ni la kimuundo (embeddings na ukamilishaji wa gumzo hushughulikiwa na vishughulikiaji tofauti), si
ukaguzi wa wakati wa utekelezaji, lakini linamaanisha kuwa wasiwasi wa upotoshaji wa vekta katika #8034 hauna sehemu ya kujitokeza
kwenye njia ya embeddings.

**Kichujio cha kutenga kwa kila modeli/endpointi (#8034).** Kwa ukamilishaji wa gumzo, mwendeshaji anaweza kutaja
vitambulisho vya modeli / malengo ya `provider/model` ambayo hayapaswi kamwe kufinyazwa — hatua ya ulinzi inayofaa ikiwa
mfinyazo utaunganishwa karibu zaidi na njia inayokaribiana na embeddings baadaye, na yenye manufaa kwa ujumla
kwa modeli yoyote ambayo prompt yake lazima ibaki sawasawa baiti kwa baiti (tathmini thabiti, viambishi awali
vinavyoathiriwa na akiba, n.k.).

- Sehemu ya mipangilio: `exclusions?: string[]` kwenye usanidi wa jumla wa mfinyazo
  (`GET`/`PUT /api/settings/compression`), unaohifadhiwa kupitia namespace iliyopo ya mfinyazo ya `key_value`
  (`src/lib/db/compression.ts`) — hakuna jedwali jipya.
- Kichupo cha dashibodi: **Dashboard → Compression → Exclusions**
  (`/dashboard/compression/exclusions`).
- Sintaksia ya ruwaza: `*` ndiyo wildcard pekee. Kila metaherufi nyingine ya regex katika ruwaza
  huepukwa kabla ya ulinganishaji, kwa hiyo `gpt-5.6` hulingana na mfuatano halisi pekee, kamwe si `gpt-5x6`
  (salama dhidi ya ReDoS, yenye mipaka, bila vidadisi vilivyopachikwa). Ruwaza hulinganishwa bila kujali ukubwa wa herufi dhidi ya
  kitambulisho tupu cha modeli na muunganisho wa `provider/model` — `gpt-5-6`, `openai/gpt-5-6`,
  na `openai/*` zote hufanya kazi, na `*` pekee hutenga kila modeli.
- Ulinganishaji: `isCompressionExcluded()` / `normalizeCompressionExclusions()` katika
  `open-sse/services/compression/exclusions.ts`. `chatCore.ts` hukagua lengo lililotengwa
  mara tu baada ya kutatua mipangilio ya mfinyazo, **kabla ya injini yoyote kuendeshwa**, na hushughulikia ulinganifu
  sawa kabisa na mfinyazo kuzimwa kwa jumla — mwili wa ombi unaweza kuthibitishwa kuwa
  unafanana baiti kwa baiti. Kurukwa kunarekodiwa kupitia `writeCompressionSkip(..., "excluded")` ili
  kuonekana katika uchanganuzi.
- Chaguo-msingi (orodha tupu/isiyokuwepo): sawa na tabia ya kabla ya #8034 — hakuna kinachotengwa.

## Vikwazo vinavyojulikana

- **LLMLingua-2 (SLM) inahitaji vitegemezi vya hiari vilivyowekwa pamoja.** Worker huendeshwa tu katika
  build ya uzalishaji wakati `@atjsh/llmlingua-2` + vitegemezi sawia vimewekwa pamoja ndani ya
  `dist/node_modules` (angalia `scripts/build/colocateOptionals.mjs`, #4286). Bila hivyo,
  engine huruhusu operesheni kuendelea inaposhindwa (hurejesha maandishi asili). Utatuzi wa worker hautegemei tena
  `import.meta.url` (huacha kufanya kazi katika bundle inayojitegemea) — hutumia runtime
  cwd / `argv[1]` kama msingi.
- **Vifurushi vya lugha vya Caveman `de` / `fr` / `ja` havijakamilika.** Huja na kanuni za `context` +
  `filler` + `structural`, lakini bila vifurushi vya `dedup` / `ultra`, kwa hivyo kiwango cha `ultra`
  hakina nguvu zaidi ya `full` kwa lugha hizo (hutumia kanuni zake pekee — hakuna
  matumizi ya kimyakimya ya kanuni za Kiingereza za `dedup`/`ultra`, ambazo zingeharibu maandishi ya lugha nyingine).
  `en` / `es` / `id` / `pt-BR` zimekamilika. Michango ya `dedup.json` + `ultra.json`
  kwa vifurushi ambavyo havijakamilika inakaribishwa.
- **Telemetry iliyopangwa kwa tabaka huorodhesha tu engine zilizofanya mbano.** Hatua ya pipeline iliyopangwa kwa tabaka ambayo
  engine yake iliendeshwa lakini ikatoa uokoaji wa 0 % hurejesha `stats:null`, na hivyo haionekani katika
  `engineBreakdown` — haiwezi kutofautishwa na hatua iliyorukwa. Kutofautisha
  "iliendeshwa, 0 %" na "ilirukwa" kungehitaji mabadiliko ya modeli ya uchanganuzi na kumeahirishwa.

## Uthibitishaji

Milango inayolengwa kwa eneo hili ni:

```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
node --import tsx/esm --test tests/unit/compression/mcpAccessibility*.test.ts
npm run typecheck:core
```