# RTK Compression (Malti)

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

---

Il-kompressjoni RTK hija l-magna ta' kompressjoni ta' OmniRoute li tifhem il-kmandi għall-output tat-terminal u tal-għodod. Hija
ddisinjata għal sessjonijiet ta' aġenti tal-kodifikazzjoni fejn il-biċċa l-kbira tat-tkabbir tal-kuntest ġej minn reġistri tat-testijiet, output tal-build,
storbju mill-maniġers tal-pakketti, traskrizzjonijiet tax-shell, output ta' Docker, output ta' git, u stack traces.

RTK jista' jaħdem direttament b'`defaultMode: "rtk"` jew bħala l-ewwel pass f'pipeline f'saffi, normalment:

```txt
rtk -> caveman
```

Din l-ordni l-ewwel tikkompressa l-output storbjuż tal-magni, imbagħad tħalli lil Caveman jikkondensa l-proża li jifdal.

L-RTK upstream jirrapporta ffrankar ta' `60-90%` fl-output tal-kmandi. Is-sessjoni kampjun fir-README tiegħu tinżel minn
`~118,000` token standard għal `~23,900` token RTK, jiġifieri ffrankar ta' `79.7%` (`~80%`). OmniRoute juża
dik il-medja upstream għall-kalkolu tal-iffrankar f'saffi bil-kompressjoni tal-input ta' Caveman:

```txt
Medja RTK:      80% iffrankat
Input Caveman:  46% iffrankat
F'saffi:        1 - (1 - 0.80) * (1 - 0.46) = 89.2% iffrankat
Firxa:          1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

## Dak li Jikkompressa

Il-katalgu inkorporat bħalissa jinkludi 49 filtru f'dawn il-kategoriji:

| Kategorija | Eżempji                                                         |
| ---------- | --------------------------------------------------------------- |
| `git`      | `git status`, `git branch`, `git diff`, `git log`               |
| `test`     | Vitest, Jest, Pytest, Playwright, testijiet Go, testijiet Cargo |
| `build`    | TypeScript, ESLint, Biome, Prettier, Vite, Webpack, Turbo, Nx   |
| `package`  | `npm install`, `npm audit`, `pip`, `uv sync`, Poetry, Bundler   |
| `shell`    | `ls`, `find`, `grep`, reġistri ġeneriċi tax-shell               |
| `docker`   | `docker ps`, reġistri ta' Docker                                |
| `infra`    | Terraform, OpenTofu, `systemctl status`                         |
| `generic`  | Output JSON, stack traces, alternattiva ġenerika għall-output   |

Id-detettur f'`open-sse/services/compression/engines/rtk/commandDetector.ts` jikklassifika l-output
qabel l-għażla tal-filtru. Il-filtri jistgħu wkoll jaqblu skont mudell ta' kmand jew regex tal-output meta klassi ta'
kmand ma tkunx biżżejjed.

## Riżoluzzjoni tal-Filtri

RTK jgħabbi l-filtri f'din l-ordni:

1. Filtri tal-proġett minn `.rtk/filters.toml` u `.rtk/filters.json`, biss meta jkunu fdati.
2. Filtri globali minn `DATA_DIR/rtk/filters.toml` u `DATA_DIR/rtk/filters.json`.
3. Filtri inkorporati minn `open-sse/services/compression/engines/rtk/filters/`.

Fl-istess ambitu, il-filtri RTK TOML schema v1 jieħdu preċedenza fuq il-filtri JSON ta' OmniRoute. L-espressjonijiet TOML
`match_command` jiġu ċċekkjati qabel it-tqabbil skont it-tip ta' kmand sabiex filtru importat speċifiku għal kmand
ikun jista' jieħu preċedenza fuq filtru usa' f'dak l-ambitu. L-ambitu tal-proġett xorta jieħu preċedenza fuq l-ambitu
globali, irrispettivament mill-format tal-fajl.

Il-filtri tal-proġett jeħtieġu l-fiduċja apposta għaliex il-filtri regex jistgħu jibdlu kif l-output tal-għodod
jintwera lill-aġenti. Fajl tal-filtri tal-proġett jiġi aċċettat meta waħda minn dawn tkun vera:

- `rtkConfig.trustProjectFilters` huwa `true`.
- `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1` ikun issettjat.
- `.rtk/trust.json` ikun fih il-hash SHA-256 korrispondenti għall-fajl tal-filtri tal-proġett.

Eżempju ta' fajl tal-fiduċja:

```json
{
  "filtersSha256": "0123456789abcdef...",
  "filtersTomlSha256": "fedcba9876543210..."
}
```

Il-hashes huma separati: `filtersSha256` jagħti fiduċja lil `.rtk/filters.json`, filwaqt li `filtersTomlSha256`
jagħti fiduċja lil `.rtk/filters.toml`. Il-modifika ta' kwalunkwe fajl tinvalida biss l-entrata tal-fiduċja tiegħu stess. Il-fajls globali
jiġu installati mill-amministratur u jużaw l-imġiba eżistenti tal-fiduċja għall-filtri globali.

Il-filtri personalizzati jistgħu jkunu oġġett ta' filtru wieħed jew array ta' oġġetti ta' filtri. Il-filtri personalizzati invalidi
jinqabżu u jiġu rrappurtati mid-dijanjostika ta' `/api/context/rtk/filters`. Il-filtri inkorporati invalidi jfallu minnufih.

## Kompatibbiltà mal-iskema RTK TOML v1

OmniRoute jista’ janalizza, jivvalida, jittestja u jinstalla fajls ta’ filtri dikjarattivi li jużaw l-iskema RTK TOML v1.
L-oqsma appoġġjati huma `description`, `match_command`, `strip_ansi`, `filter_stderr`,
`strip_lines_matching`, `keep_lines_matching`, `replace`, `match_output`, `truncate_lines_at`,
`head_lines`, `tail_lines`, `max_lines`, `on_empty`, u testijiet integrati `[[tests.<filter>]]`.
Oqsma mhux magħrufa, espressjonijiet regolari invalidi jew mhux sikuri, regoli simultanji ta’ tneħħija/żamma, fajls ikbar minn
1 MiB, u referenzi għal filtri mhux magħrufa jiġu miċħuda. Fajl li t-testijiet integrati tiegħu jfallu jista’
jiġi vvalidat għall-ispezzjoni, iżda ma jistax jiġi installat jew mgħobbi. Il-fallimenti fit-tagħbija ta’ fajls personalizzati jibqgħu
fail-open: il-fajl invalidu jinqabeż u l-filtri l-oħra jkomplu jaħdmu.

OmniRoute jirċievi l-output tal-għodda wara li l-klijent ikun diġà qabad l-output, għalhekk `filter_stderr = true`
ma jistax ibiddel il-qbid tal-proċess. Il-qasam jiġi aċċettat bħala no-op u l-validazzjoni tirritorna twissija.
Dan huwa deskritt intenzjonalment bħala **kompatibbiltà mal-iskema RTK TOML v1**, mhux bħala kompatibbiltà sħiħa
mal-eżegwibbli RTK, mal-hooks tax-shell, mal-implimentazzjonijiet tal-kmandi Rust, jew mat-tqassim tat-trust store tiegħu.

Il-veduta RTK avvanzata tad-dashboard taċċetta TOML imwaħħal jew imtella’. Il-validazzjoni hija għall-qari biss.
L-installazzjoni tikteb `DATA_DIR/rtk/filters.toml` b’mod atomiku b’permessi restrittivi u taġġorna
l-katalgu tal-filtri attiv mingħajr ristartjar. Is-sostituzzjoni ta’ fajl eżistenti teħtieġ konferma espliċita `overwrite`
u l-ewwel toħloq `DATA_DIR/rtk/filters.toml.bak`.

## DSL tal-filtri

Il-filtri jużaw l-iskema JSON deskritta f’[Format tar-Regoli tal-Kompressjoni](./COMPRESSION_RULES_FORMAT.md).
Ir-runtime japplika dawn l-istadji f’din l-ordni:

```txt
stripAnsi -> filterStderr -> replace -> matchOutput -> drop/include lines
  -> truncateLineAt -> head/tail/maxLines -> onEmpty
```

Oqsma importanti:

| Qasam                        | Għan                                                                      |
| ---------------------------- | ------------------------------------------------------------------------- |
| `rules.stripAnsi`            | Neħħi s-sekwenzi tal-kulur/kontroll tat-terminal qabel it-tqabbil         |
| `rules.filterStderr`         | Innormallizza l-prefissi komuni ta’ stderr qabel it-tqabbil/iffiltrar     |
| `rules.replace`              | Applika sostituzzjonijiet regex ordnati                                   |
| `rules.matchOutput`          | Irritorna sommarju kompatt meta l-output jaqbel ma’ kundizzjoni magħrufa  |
| `rules.matchOutput[].unless` | Aqbeż it-taqsira meta jkun hemm mudell ta’ żball/falliment                |
| `rules.dropPatterns`         | Neħħi linji storbjużi                                                     |
| `rules.includePatterns`      | Ippreferi linji li fuqhom tista’ tittieħed azzjoni                        |
| `rules.collapsePatterns`     | Agħqad linji ripetuti li jaqblu                                           |
| `rules.deduplicate`          | Għażla fakultattiva għal kull filtru: agħqad linji duplikati konsekuttivi |
| `rules.truncateLineAt`       | Qasir kull linja b’mod sikur għall-Unicode                                |
| `rules.onEmpty`              | Messaġġ alternattiv jekk il-linji kollha jiġu ffiltrati                   |
| `tests[]`                    | Kampjuni integrati użati mill-gate tal-verifika                           |

Il-filtri integrati huma mistennija jinkludu kampjuni `tests[]` integrati. Il-filtri personalizzati għandhom jinkluduhom
ukoll, speċjalment meta jkunu kondiviżi bejn proġetti.

## Deduplikazzjoni tal-Linji (żewġ saffi)

RTK jikkollassa linji duplikati f’żewġ saffi indipendenti:

1. **`deduplicate` għal kull filtru (mhux attiv awtomatikament, valur predefinit `false`).** Filtru jista’ jistabbilixxi `rules.deduplicate: true`
   biex jikkollassa linji duplikati konsekuttivi _fl-output maqbul minn dak il-filtru_, qabel it-tronkament.
   Dan jitħaddem ġewwa `lineFilter.ts`. Għal filtri legacy, jiġi attivat awtomatikament meta l-filtru jiddefinixxi
   `collapsePatterns`. Skema: `deduplicate: z.boolean().default(false)` f’
   `open-sse/services/compression/engines/rtk/filterSchema.ts`.
2. **`deduplicateThreshold` għall-magna kollha (valur predefinit `3`).** Wara li jitħaddmu l-filtri kollha, il-magna tikkollassa
   kull sekwenza ta’ `>= deduplicateThreshold` linji konsekuttivi identiċi fir-riżultat kollu
   (`deduplicateRepeatedLines`, applikat f’`engines/rtk/index.ts`). Il-valur jiġi limitat għal 2–100 waqt
   in-normalizzazzjoni.

Il-pass għal kull filtru jitħaddem l-ewwel (ġewwa l-filtru), filwaqt li l-pass għall-magna kollha jitħaddem l-aħħar (fuq l-output
magħqud), għalhekk it-tnejn jikkomponu mingħajr għadd doppju.

## Raggruppament tal-Linji (`enableGrouping`)

Meta `rtkConfig.enableGrouping` ikun `true` (valur predefinit `false`), RTK iħaddem pass addizzjonali `groupSimilarLines`
fuq ir-riżultat wara d-deduplikazzjoni li jikkollassa sekwenzi ta’ linji konsekuttivi _kważi ekwivalenti_ (mhux identiċi byte b’byte).
`rtkConfig.groupingThreshold` (valur predefinit `3`) huwa t-tul minimu tas-sekwenza li jattiva
r-raggruppament. Dan huwa l-kontroparti strutturali ta’ `deduplicateThreshold`: id-deduplikazzjoni tittratta repetizzjonijiet eżatti,
filwaqt li r-raggruppament jittratta "l-istess forma b’differenzi żgħar". Iż-żewġ flags huma parti mill-JSON `rtkConfig`
ippersistit fit-tabella `key_value` (ara l-Konfigurazzjoni hawn fuq), għalhekk l-issettjar jibqa’ fis-seħħ wara li s-sistema terġa’ tinbeda.

## Tneħħija tal-Kummenti mill-Kodiċi (`stripCodeComments` / `preserveDocstrings`)

Meta `rtkConfig.applyToCodeBlocks` ikun attivat, RTK jista’ wkoll ineħħi l-kummenti minn blokok tal-kodiċi magħluqa b’fences:

- `stripCodeComments` (valur predefinit `false`) — mhux attiv awtomatikament. Meta jkun `true`, RTK ineħħi l-kummenti minn blokok magħluqa
  ta’ JavaScript u TypeScript. Storikament, il-flag kien jinqara iżda qatt ma kien jiġi applikat, għalhekk il-valur predefinit jibqa’
  "ippreserva" biex tiġi evitata bidla siekta fil-produzzjoni.
- `preserveDocstrings` (valur predefinit `true`) — meta jitneħħew il-kummenti, il-kummenti ta’ blokka JSDoc/`/** … */`
  jinżammu (dawn iġorru dokumentazzjoni tal-API li tiswa aktar mill-bytes li jiswew). Issettjah għal `false` biex tneħħi
  lil dawn ukoll.

It-tneħħija tal-kummenti hija implimentata f’`open-sse/services/compression/engines/rtk/codeStripper.ts`. Din tuża
l-**parser ta’ TypeScript** (mhux regex) sabiex literals ta’ strings, templates u regex qatt ma jitqiesu bi żball
bħala kummenti, u tabbanduna l-proċess kompletament meta jiġi identifikat JSX (sabiex il-kummenti fil-kontenituri tal-espressjonijiet JSX
qatt ma jiġu korrotti). Bħalissa, it-tneħħija tal-kummenti tapplika għal **JavaScript u TypeScript biss** — lingwi oħra
fis-sett `CodeLanguage` tal-istripper (Python, Rust, Go, Ruby, Java) għandhom kollass tal-linji vojta u
tal-ispazji bojod, iżda l-ebda tneħħija ta’ kummenti. L-eżekuzzjoni fuq il-blokka mnaddfa tiġi ttikkettata `rtk:code-strip` f’
`rulesApplied`.

> **Nota — GCF / il-kodifikazzjoni tabulari hija magna separata.** RTK **ma** fihx l-encoder JSON tabulari/kolonnari "GCF"
> (Graph Compact Format). Dak l-encoder — li ssostitwixxa encoder eqdem
> `omni-tabular` — jinsab fil-magna **headroom**
> (`open-sse/services/compression/engines/headroom/`, bil-codec inkluż lokalment taħt
> `headroom/gcf/`). Dan mhuwiex relatat mal-pipeline tal-filtri RTK iddokumentat hawnhekk.

## Konfigurazzjoni

Is-settings globali huma disponibbli permezz ta' `/api/settings/compression`. Is-settings speċifiċi għal RTK huma wkoll
disponibbli permezz ta' `/api/context/rtk/config`.

```json
{
  "defaultMode": "stacked",
  "autoTriggerMode": "stacked",
  "autoTriggerTokens": 32000,
  "stackedPipeline": [
    { "engine": "rtk", "intensity": "standard" },
    { "engine": "caveman", "intensity": "full" }
  ],
  "rtkConfig": {
    "enabled": true,
    "intensity": "standard",
    "applyToToolResults": true,
    "applyToCodeBlocks": false,
    "applyToAssistantMessages": false,
    "enabledFilters": [],
    "disabledFilters": [],
    "maxLinesPerResult": 120,
    "maxCharsPerResult": 12000,
    "deduplicateThreshold": 3,
    "customFiltersEnabled": true,
    "trustProjectFilters": false,
    "rawOutputRetention": "never",
    "rawOutputMaxBytes": 1048576,
    "enableGrouping": false,
    "groupingThreshold": 3,
    "stripCodeComments": false,
    "preserveDocstrings": true
  }
}
```

`enabledFilters` u `disabledFilters` jużaw IDs tal-filtri, pereżempju `test-vitest` jew `git-diff`.

L-istruttura sħiħa ta' `rtkConfig` hija definita minn `RtkConfig` / `DEFAULT_RTK_CONFIG` f'
`open-sse/services/compression/types.ts`. L-oġġett kollu jinħażen b'mod persistenti bħala valur JSON wieħed fit-tabella SQLite
`key_value` taħt `namespace = "compression"`, `key = "rtkConfig"`
(`src/lib/db/compression.ts`), u jiġi normalizzat waqt il-qari minn `normalizeRtkConfig`. Għalhekk, kull qasam hawn taħt
— inklużi `enableGrouping`, `groupingThreshold`, `stripCodeComments`, u `preserveDocstrings` —
jgħaddi bir-ritorn mill-istess maħżen u jibqa' ppreservat wara ristartjar.

| Ċavetta                | Default | Għan                                                                                                  |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `deduplicateThreshold` | `3`     | Għall-magna kollha: l-inqas numru ta' linji konsekuttivi identiċi biex jingħaqdu (limitat għal 2–100) |
| `enableGrouping`       | `false` | Fakultattiv: għaqqad sekwenzi ta' linji konsekuttivi kważi ekwivalenti                                |
| `groupingThreshold`    | `3`     | L-inqas sekwenza konsekuttiva ta' linji simili li tattiva r-raggruppament                             |
| `stripCodeComments`    | `false` | Fakultattiv: neħħi l-kummenti minn blokki tal-kodiċi magħluqa b'fence (jeħtieġ `applyToCodeBlocks`)   |
| `preserveDocstrings`   | `true`  | Meta jitneħħew il-kummenti, żomm il-blokki JSDoc/`/** … */`                                           |

## API

| Rotta                              | Metodu | Għan                                                      |
| ---------------------------------- | ------ | --------------------------------------------------------- |
| `/api/context/rtk/config`          | GET    | Aqra l-konfigurazzjoni RTK                                |
| `/api/context/rtk/config`          | PUT    | Aġġorna l-konfigurazzjoni RTK                             |
| `/api/context/rtk/filters`         | GET    | Elenka l-katalgu tal-filtri u d-dijanjostiċi tat-tagħbija |
| `/api/context/rtk/import`          | POST   | Ivvalida jew installa fajls tal-iskema RTK TOML v1        |
| `/api/context/rtk/test`            | POST   | Ipprevedi l-kompressjoni RTK għal payload wieħed ta' test |
| `/api/context/rtk/raw-output/[id]` | GET    | Aqra l-output mhux ipproċessat, redatt u miżmum           |
| `/api/compression/preview`         | POST   | Ipprevedi kwalunkwe modalità ta' kompressjoni             |

Payload tat-test RTK:

```json
{
  "command": "npm test",
  "text": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed",
  "config": {
    "intensity": "standard"
  }
}
```

Payload għall-previżjoni tal-kompressjoni:

```json
{
  "mode": "stacked",
  "messages": [
    {
      "role": "tool",
      "content": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed"
    }
  ],
  "config": {
    "rtkConfig": {
      "rawOutputRetention": "failures"
    }
  }
}
```

Ir-rotot tal-ġestjoni jeħtieġu awtentikazzjoni tal-ġestjoni tad-dashboard jew il-politika tal-API key korrispondenti.

Payload għall-validazzjoni ta' RTK TOML:

```json
{
  "action": "validate",
  "content": "schema_version = 1\n\n[filters.my-tool]\nmatch_command = \"^my-tool\\\\b\"\nmax_lines = 20\n"
}
```

Uża `"action": "install"` biex tinstalla l-fajl ivvalidat globalment. Żid `"overwrite": true` biss
wara li tirrieżamina u tikkonferma s-sostituzzjoni ta' fajl globali eżistenti.

## Irkupru tal-Output Mhux Ipproċessat

RTK normalment jirritorna biss test ikkompressat. Għad-debugging, `rawOutputRetention` jista’ jżomm output mhux ipproċessat u redatt:

| Valur      | Imġiba                                                                    |
| ---------- | ------------------------------------------------------------------------- |
| `never`    | Iżżommx output mhux ipproċessat                                           |
| `failures` | Żomm biss output li x’aktarx jindika falliment                            |
| `always`   | Żomm kull output mhux ipproċessat ikkompressat ta’ RTK, wara r-redazzjoni |

Il-fajls miżmuma jinkitbu taħt:

```txt
DATA_DIR/rtk/raw-output/
```

Is-sigrieti jiġu redatti qabel il-persistenza, inklużi bearer tokens komuni, API keys, Slack tokens,
AWS access keys, u valuri bl-istil ta’ assenjazzjoni `token=...`, `secret=...`, `password=...`. L-analitika
taħżen biss l-id tal-indikatur, id-daqs, u l-metadata tal-hash.

## Punt ta’ Verifika

Il-punt ta’ verifika ffukat iħaddem testijiet integrati tal-filtri inline mingħajr ma jsejjaħ kmandi esterni permezz tax-shell:

```bash
node --import tsx/esm --test tests/unit/compression/rtk-verify.test.ts
```

Il-punt ta’ verifika usa’ ta’ RTK huwa:

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

Ħaddem il-punt ta’ verifika wiesa’ tal-kompressjoni qabel ir-rilaxx:

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

## Estensjoni ta’ RTK

1. Żid jew aġġorna fajl JSON ta’ filtru.
2. Inkludi mill-inqas kampjun wieħed `tests[]` li jagħti prova tal-imġiba importanti.
3. Żid fixture taħt `tests/unit/compression/fixtures/rtk/` għal familji ġodda ta’ kmandi.
4. Żid kopertura għad-detezzjoni tal-kmandi meta tintroduċi klassi ġdida ta’ output.
5. Ħaddem il-punti ta’ verifika ta’ RTK, kemm dak speċifiku kif ukoll dak wiesa’.
6. Jekk il-filtru huwa lokali għall-proġett, ikkommetti `.rtk/filters.json` u aġġorna `.rtk/trust.json` biss wara r-rieżami.

---

## Livelli ta’ Intensità (v3.8.16+)

RTK jappoġġja **3 livelli ta’ intensità** li jibbilanċjaw bejn l-**aggressività tal-kompressjoni** u s-**sikurezza**. Il-livell jiġi ssettjat permezz ta’ `config.intensity` fil-konfigurazzjoni tal-engine.

### It-3 Livelli

| Livell               | Limitu tat-tronkament     | Iffrankar ta’ tokens | Riskju     | L-aħjar għal                               |
| -------------------- | ------------------------- | -------------------- | ---------- | ------------------------------------------ |
| `minimal`            | 24 linja kull sezzjoni    | ~20-40%              | Baxx ħafna | Produzzjoni b’kuntest kritiku              |
| `standard` (default) | 24 linja kull sezzjoni    | ~50-70%              | Baxx       | Sessjonijiet ta’ kuljum għall-ipprogrammar |
| `aggressive`         | 16-il linja kull sezzjoni | ~70-90%              | Medju      | Sessjonijiet twal, iffrankar massimu       |

### Fejn Iseħħ it-Tronkament

Il-limitu tat-tronkament jaffettwa `lineFilter.ts`:

```ts
// Minn open-sse/services/compression/engines/rtk/index.ts:329-330
config.intensity === "aggressive" ? 16 : 24,
config.intensity === "aggressive" ? 16 : 24,
```

Kemm il-**bidu** kif ukoll it-**tmiem** ta’ kull sezzjoni jiġu ppreservati; il-kontenut tan-nofs jitneħħa meta jidħol fis-seħħ it-tronkament.

### X’Jibqa’ u X’Jinqata’

| Kontenut                       | minimal         | standard        | aggressive      |
| ------------------------------ | --------------- | --------------- | --------------- |
| Żbalji / stack traces          | ✅ ippreservati | ✅ ippreservati | ✅ ippreservati |
| Fallimenti tat-testijiet       | ✅ ippreservati | ✅ ippreservati | ✅ ippreservati |
| Żbalji tal-build               | ✅ ippreservati | ✅ ippreservati | ✅ ippreservati |
| Testijiet li jgħaddu (verbose) | ✅ ippreservati | 🟡 ikkollassati | 🟡 ikkollassati |
| Output ta’ rutina (info logs)  | 🟡 ikkollassat  | 🟡 ikkollassat  | ❌ imneħħi      |
| Vireg tal-progress             | 🟡 ikkollassati | ❌ imneħħija    | ❌ imneħħija    |
| Banner / arti ASCII            | 🟡 ikkollassati | ❌ imneħħija    | ❌ imneħħija    |

### Għażla tal-Intensità t-Tajba

```
                  It-telf tal-kuntest huwa katastrofiku?
                  │
      ┌───────────┼───────────┐
      │           │           │
     IVA         LE         MHUX ĊERT
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      Kemm huwa       Ipprova `standard` l-ewwel
      │      kritiku         (jaħdem għal 80%
      │      t-throughput?   tal-każijiet)
      │           │
      │      ┌────┴────┐
      │      │         │
      │     BAXX      GĦOLI
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘
```

### Konfigurazzjoni tal-Intensità

**Għal kull combo** (fil-konfigurazzjoni tal-combo):

```json
{
  "combo": "my-coding-combo",
  "routing": {/* ... */},
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive"
  }
}
```

**B’mod programmatiku**:

`rtkEngine` (`@omniroute/open-sse/services/compression/engines/rtk`) huwa
`CompressionEngine` u m’għandux metodu `updateConfig`. Aġġorna l-konfigurazzjoni ta’ engine
permezz tar-registry helper minflok:

```ts
import { updateEngineConfig } from "@omniroute/open-sse/services/compression/engines/registry";

updateEngineConfig("rtk", { intensity: "aggressive" });
```

### Verifika tal-Effett

Uża l-**Punt ta’ Verifika** (ara hawn taħt) biex tikkonferma li l-filtru tiegħek huwa sikur fl-intensità magħżula:

```ts
import { runRtkFilterTests } from "omniroute/compression/engines/rtk/verify";

const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
  console.error("Il-filtri fallew bl-intensità aggressive");
}
```

---

## Żvilupp ta’ Filtri Personalizzati (v3.8.16+)

Id-direttorju `engines/rtk/filters/` fih **49+ fajl JSON ta’ filtri integrati**. Tista’ żżid il-filtri tiegħek stess biex tikkompressa l-output minn għodod personalizzati li mhumiex koperti mill-konfigurazzjonijiet predefiniti.

### Skema tal-Filtru (Zod)

```ts
{
  "id": "string",                      // Meħtieġ. Identifikatur tal-filtru (kebab-case, eż. "python-traceback")
  "label": "string",                   // Meħtieġ. Isem tal-filtru li jinqara mill-bniedem
  "description": "string",             // Fakultattiv (predefinit: ""). Deskrizzjoni qasira ta’ x’jagħmel il-filtru
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Fakultattiv (0-100, predefinit: 50). Ordni tal-eżekuzzjoni (ogħla = l-ewwel)
  "match": {
    "commands": ["string"],            // Ismijiet tal-kmandi li għandhom jitqabblu (eż. "python", "pytest")
    "patterns": ["string"],            // Mudelli regex biex jitqabblu mal-output
    "outputTypes": ["string"]          // Klassijiet tal-output identifikati (eż. "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Fakultattiv (predefinit: false). Neħħi l-kodiċijiet tal-kulur ANSI
    "replace": [                       // Regoli ta’ tfittxija u sostituzzjoni (predefinit: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Waqqaf minnufih meta jinstab qbil ma’ mudell (predefinit: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // Aqbeż jekk dan il-mudell jaqbel
      }
    ],
    "includePatterns": ["string"],     // Linji li għandhom jinżammu (mudelli regex, predefinit: [])
    "dropPatterns": ["string"],        // Linji li għandhom jitneħħew (mudelli regex, predefinit: [])
    "collapsePatterns": ["string"],    // Linji li għandhom jinġabru f’okkorrenza waħda (predefinit: [])
    "deduplicate": boolean,            // Fakultattiv (predefinit: false). Neħħi l-linji duplikati
    "truncateLineAt": number,          // Fakultattiv (predefinit: 0). Qassar il-linji għal għadd massimu ta’ karattri
    "maxLines": number,                // Fakultattiv (predefinit: 0). Limitu assolut fuq l-għadd totali ta’ linji
    "headLines": number,               // Fakultattiv (predefinit: 20). Żomm l-ewwel N linji tal-output li jaqbel
    "tailLines": number,               // Fakultattiv (predefinit: 20). Żomm l-aħħar N linji tal-output li jaqbel
    "onEmpty": "string",               // Fakultattiv (predefinit: ""). Messaġġ alternattiv jekk il-linji kollha jiġu ffiltrati
    "filterStderr": boolean            // Fakultattiv (predefinit: false). Iffiltra wkoll l-output stderr
  },
  "preserve": {
    "errorPatterns": ["string"],       // Mudelli li dejjem għandhom jinżammu (predefinit: [])
    "summaryPatterns": ["string"]      // Mudelli għal-linja tas-sommarju finali (predefinit: [])
  },
  "tests": [                           // Testijiet inline għall-verifika (predefinit: [])
    {
      "name": "string",               // Meħtieġ. Isem tat-test
      "input": "sample output",        // Meħtieġ. Test ta’ input bħala kampjun
      "expected": "expected output",   // Meħtieġ. Output ikkompressat mistenni
      "command": "optional command"    // Fakultattiv. Kuntest tal-kmand
    }
  ]
}
```

### Eżempju: Filtru ta’ Traceback ta’ Python

```json
{
  "id": "python-traceback",
  "label": "Python Traceback Filter",
  "description": "Compresses Python tracebacks to essential file/line locations and error type",
  "category": "test",
  "priority": 60,
  "match": {
    "commands": ["python", "python3", "pytest", "uv", "poetry"],
    "patterns": ["Traceback \\(most recent call last\\)", "Error", "Exception"],
    "outputTypes": ["error-traceback"]
  },
  "rules": {
    "stripAnsi": true,
    "includePatterns": [
      "Traceback \\(most recent call last\\)",
      "^\\s*File \".+\", line \\d+",
      "^\\s*[A-Z][a-zA-Z]+Error:",
      "^\\s*[A-Z][a-zA-Z]+Exception"
    ],
    "dropPatterns": ["site-packages/", "^\\s+[a-z_]+\\([^)]*\\)$"],
    "headLines": 5,
    "tailLines": 3,
    "maxLines": 25,
    "filterStderr": true
  },
  "preserve": {
    "errorPatterns": ["Error:", "Exception:", "Traceback"],
    "summaryPatterns": ["^[A-Z][a-zA-Z]+(?:Error|Exception):"]
  },
  "tests": [
    {
      "name": "preserves-error-type-and-location",
      "input": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n    do_thing()\n  File \"lib/utils.py\", line 17, in helper\n    return 1 / 0\nZeroDivisionError: division by zero",
      "expected": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n  File \"lib/utils.py\", line 17, in helper\nZeroDivisionError: division by zero",
      "command": "python app.py"
    }
  ]
}
```

### Tagħbija ta’ Filtri Personalizzati

Poġġi l-fajl f’post rikonoxxut:

```
~/.omniroute/rtk/filters/my-filter.json     # Livell tal-utent
<project>/.rtk/filters/my-filter.json      # Livell tal-proġett
```

Il-filtri jitgħabbew awtomatikament waqt l-istartjar permezz ta’ `loadRtkFilters()` f’`open-sse/services/compression/engines/rtk/filterLoader.ts`. Il-loader jiskopri l-filtri minn:

- Katalgu integrat: `open-sse/services/compression/engines/rtk/filters/`
- Direttorju tal-utent: `~/.omniroute/rtk/filters/`
- Direttorju tal-proġett: `<project>/.rtk/filters/`

Biex tgħabbi l-filtri b’mod programmatiku:

```ts
import { loadRtkFilters } from "@omniroute/open-sse/services/compression/engines/rtk/filterLoader";

// Għażliet: customFiltersEnabled (għabbi l-filtri tal-utent/tal-proġett, mixgħul b’mod predefinit),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });
```

### Validazzjoni

Il-filtri jiġu vvalidati mal-iskema Zod waqt it-tagħbija. Filtru bi struttura ħażina ma jitgħabbiex u jiġi rreġistrat żball:

```
RTK_FILTER_LOADER: il-filtru "my-filter" falla l-validazzjoni:
  - rules.replace.0.pattern: Regex invalidu
  - match.commands: ma jistax ikun vojt
```

Biex tivvalida l-filtri installati kollha, sejjaħ `runRtkFilterTests()`, li jiġi esportat minn `open-sse/services/compression/engines/rtk/verify.ts`.

### L-Aħjar Prattiki

1. **Dejjem inkludi `tests[]`** — dawn juru li l-filtru tiegħek jaħdem u jipprevjenu rigressjonijiet
2. **Uża `matchOutput` għal ċirkwiti qosra** — jekk linja waħda tirrakkonta l-istorja, ibdel il-blokka kollha
3. **Ippreferi `keep` minn `strip`** — regoli espliċiti ta' "dejjem ippreserva" huma aktar sikuri minn "dejjem neħħi"
4. **Ittestja fit-3 livelli kollha ta' intensità** — `minimal` għandu jkun mingħajr effett, filwaqt li `aggressive` xorta għandu jippreserva l-iżbalji
5. **Uża l-qasam `unless`** — ipproteġi ċ-ċirkwiti qosra b'"tattivax jekk X ikun preżenti"

---

## Irkupru tal-Output Mhux Maħdum u Xatba ta’ Verifika

Meta RTK jikkompressa l-output b’mod aggressiv, tista’ **tirkupra t-test oriġinali** għad-debugging, l-awditjar, jew ir-riproduzzjoni.

### Kif Jaħdem l-Irkupru tal-Output Mhux Maħdum

```
Output oriġinali (10K tokens)
        │
        ▼
Kompressjoni RTK (b’rawOutput.enabled=true)
        │
        ├─▶ Output ikkompressat (2K tokens)  ──▶ lejn l-LLM
        │
        └─▶ Output oriġinali (10K tokens)    ──▶ maħżun fid-DB
                                                  (marbut permezz ta’ request_id)
```

### Kif Tippermetti l-Ħżin tal-Output Mhux Maħdum

**Għal kull talba** (fil-konfigurazzjoni combo):

```json
{
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive",
    "rawOutput": {
      "enabled": true,
      "maxBytes": 1048576 // Limitu ta’ 1MB
    }
  }
}
```

**Valur predefinit**: `rawOutput.enabled: false` (jiffranka l-ispazju tal-ħżin).

### Spiża tal-Ħżin

| Għal kull talba           | Limitu ta’ 1MB  | Limitu ta’ 10MB  |
| ------------------------- | --------------- | ---------------- |
| Output ikkompressat medju | ~5KB            | ~5KB             |
| Output mhux maħdum maħżun | ~50-500KB       | ~500KB-5MB       |
| B’1000 talba kuljum       | 50-500MB/kuljum | 500MB-5GB/kuljum |

> **Rakkomandazzjoni**: Ippermetti l-output mhux maħdum biss għal **sessjonijiet ta’ debugging** jew **awditjar ibbażat fuq kampjuni**, mhux kontinwament.

### Kif Tirkupra l-Oriġinal

```ts
import { readRtkRawOutput } from "omniroute/compression/engines/rtk/rawOutput";

const raw = readRtkRawOutput(pointerId); // pointerId mill-istatistika tal-kompressjoni
if (raw) {
  console.log("Original output:", raw);
}
```

Il-`pointerId` jiġi rritornat f’`CompressionStats.rtkRawOutputPointers[]` wara l-kompressjoni.
Ara `open-sse/services/compression/engines/rtk/rawOutput.ts:102` għas-signature tal-funzjoni.

### Ix-Xatba ta’ Verifika

Il-**Verifika tal-Filtri RTK** (`open-sse/services/compression/engines/rtk/verify.ts`) tivvalida l-filtri kollha kontra t-`tests[]` tagħhom u tiżgura li l-imġiba tkun korretta fit-3 livelli kollha ta’ intensità.

**Sejjaħ `runRtkFilterTests()`** biex tħaddem il-verifika:

```ts
import { runRtkFilterTests } from "open-sse/services/compression/engines/rtk/verify";

const result = runRtkFilterTests();
console.log(`Passed: ${result.outcomes.filter((o) => o.passed).length}`);
console.log(`Failed: ${result.outcomes.filter((o) => !o.passed).length}`);
if (!result.passed) {
  console.error("Filters failed verification");
  result.outcomes
    .filter((o) => !o.passed)
    .forEach((o) => {
      console.error(
        `  - ${o.filterId} / ${o.testName}: expected "${o.expected}", got "${o.actual}"`
      );
    });
}
```

**Dak li tivvalida**:

1. Kull filtru jitgħabba u jgħaddi mill-validazzjoni tal-iskema
2. Kull entrata ta’ `tests[]` tipproduċi l-output mistenni
3. L-intensità `minimal` ma twettaq l-ebda operazzjoni (tippreserva l-oriġinal u tapplika biss filtri strutturali)
4. L-intensità `aggressive` tippreserva l-iżbalji, il-fallimenti tat-testijiet, u l-stack traces
5. L-output ikkompressat qatt ma jkun akbar mill-input oriġinali

- Sors: `open-sse/services/compression/engines/rtk/` (63 fajl, ~70KB)

- **Qabel tintegra bidla f’filtru** — dejjem żgura li t-testijiet jgħaddu
- **Wara li taġġorna l-engine RTK** — l-iskema setgħet inbidlet
- **Perjodikament waqt il-monitoraġġ** — jipproteġi kontra devjazzjonijiet fil-fixtures tat-testijiet
- **Meta żżid familja ġdida ta’ għodod/kmandi** — jagħti prova li l-filtru l-ġdid jaħdem

---

## Ara Wkoll

- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — Ħarsa ġenerali sħiħa lejn il-pipeline tal-kompressjoni
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — Reġistru tal-magni u magni integrati
- [EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md) — Magni personalizzati, pakketti lingwistiċi, pipelines f'munzelli
- Sors: `open-sse/services/compression/engines/rtk/` (63 fajl, ~70KB)