# User Guide (Malti)

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

---

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

Gwida kompluta għall-konfigurazzjoni tal-fornituri, il-ħolqien ta’ kombinazzjonijiet, l-integrazzjoni tal-għodod CLI, u d-distribuzzjoni ta’ OmniRoute.

---

## Werrej

- [Prezzijiet f'Ħarsa Ġenerali](#-pricing-at-a-glance)
- [Każijiet ta' Użu](#-use-cases)
- [Setup tal-Provider](#-provider-setup)
- [Integrazzjoni tal-CLI](#-cli-integration)
- [Tqegħid (Deployment)](#-deployment)
- [Mudelli Disponibbli](#-available-models)
- [Karatteristiċi Avvanzati](#-advanced-features)
- [Routing Awtomatiku (Zero-config)](#-auto-routing-zero-config)
- [Integrazzjoni MCP & A2A](#-mcp--a2a-integration)
- [Sistema ta' Ħiliet (Skills)](#-skills-system)
- [Sistema ta' Memorja](#-memory-system)
- [Webhooks](#-webhooks)
- [Aġenti Cloud](#-cloud-agents)
- [Ġestjoni Programmattika](#-programmatic-management)
- [CLI Intern](#-internal-cli)
- [Applikazzjoni Desktop (Electron)](#-desktop-application-electron)

---

## 💰 Ħarsa lejn il-Prezzijiet

| Livell                 | Provditur         | Piża             | Tneħħija tal-Quota             | L-Aħjar Għal                |
| ---------------------- | ----------------- | ---------------- | ------------------------------ | --------------------------- |
| **💳 SOTTISKRIZZJONI** | Claude Code (Pro) | $20/xahar        | 5h + ġimgħija                  | Diġà sottokrit              |
|                        | Codex (Plus/Pro)  | $20-200/xahar    | 5h + ġimgħija                  | Utenti OpenAI               |
|                        | GitHub Copilot    | $10-19/xahar     | Xahrewwa                       | Utenti GitHub               |
| **🔑 API KEY**         | DeepSeek          | Ħlas skont l-użu | L-ebda                         | Rati irħas                  |
|                        | Groq              | Ħlas skont l-użu | L-ebda                         | Inferenza ultra mgħaġġla    |
|                        | xAI (Grok)        | Ħlas skont l-użu | L-ebda                         | Rati Grok 4                 |
|                        | Mistral           | Ħlas skont l-użu | L-ebda                         | Mudelli ospitati fl-UE      |
|                        | Perplexity        | Ħlas skont l-użu | L-ebda                         | Riki mbieraq bil-fittxien   |
|                        | Together AI       | Ħlas skont l-użu | L-ebda                         | Mudelli b'ħarsien miftuħ    |
|                        | Fireworks AI      | Ħlas skont l-użu | L-ebda                         | Stampi FLUX malajr          |
|                        | Cerebras          | Ħlas skont l-użu | L-ebda                         | Veloċità ta' skala wafer    |
|                        | Cohere            | Ħlas skont l-użu | L-ebda                         | Command R+ RAG              |
|                        | NVIDIA NIM        | Ħlas skont l-użu | L-ebda                         | Mudelli għall-intrapriża    |
|                        | Baidu Qianfan     | Ħlas skont l-użu | L-ebda                         | Mudelli ERNIE               |
| **💰 RĦAS**            | GLM-4.7           | $0.6/1M          | Ta' kuljum fis-10AM            | Riserva baġitarja           |
|                        | MiniMax M2.1      | $0.2/1M          | 5 sigħat lissirqi              | L-għażla irħas              |
|                        | Kimi K2           | $9/xahar fiss    | 10M tokens/xahar               | Piża previżibbli            |
| **🆓 B'XEJN**          | Qoder             | $0               | Limiti tal-provditur japplikaw | Verifika l-katalogu attwali |
|                        | Kiro              | $0               | ~50 krediti/xahar              | B'xejn ta' Claude           |

---

## 🎨 Xi Ġuriex

### Ġurija 1: "Għandi sottoskrizzjoni ta' Claude Pro"

**Problema:** Il-quota ġġorrula mhux użata, limiti ta' rata waqt programmazzjoni intensiva

```
Kombinazzjoni: "maximize-claude"
  1. cc/claude-opus-4-7        (uża s-sottoskrizzjoni b'mod sħiħ)
  2. glm/glm-4.7               (riserva rħisa meta l-quota tispiċċa)
  3. if/qwen3.8-max-preview       (riserva bla spiża għall-emerġenza)

Piża ta' kull xahar: $20 (sottoskrizzjoni) + ~$5 (riserva) = $25 totali
vs. $20 + limiti jseħħu = frustrazzjoni
```

### Ġurija 2: "Irrid piża żero"

**Problema:** Ma nistax naffordja s-sottoskrizzjonijiet, jeħtiġli AI affidabbli għall-programmazzjoni

```
Kombinazzjoni: "zero-cost"
  1. if/kimi-k2.7-code          (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)
  2. kr/qwen3-coder-next        (riserva b'xejn ta' Kiro)

Piża ta' kull xahar: $0
Kwalità: verifika l-mudell, il-limiti, il-privatezza, u l-SLA għal xogħolek
```

### Ġurija 3: "Jeħtiġli programmazzjoni 24/7, bla interruzzjonijiet"

**Problema:** Skadenzi, ma nistax naffordja waqfa

```
Kombinazzjoni: "always-on"
  1. cc/claude-opus-4-7        (l-aqwa kwalità)
  2. cx/gpt-5.5                (sottoskrizzjoni oħra)
  3. glm/glm-4.7               (rħisa, ġġedded ta' kuljum)
  4. minimax/MiniMax-M2.1      (irħas, tneħħija ta' 5h)
  5. if/deepseek-v4-flash       (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)

Riżultat: 5 saffi ta' riserva jwessgħu r-resiljenza; disponibbiltà ta' l-avvenniet mhijiwa garantita
Piża ta' kull xahar: $20-200 (sottoskrizzjonijiet) + $10-20 (riserva)
```

### Ġurija 4: "Irrid AI B'XEJN fi OpenClaw"

**Problema:** Jeħtiġli assistent AI f'applikazzjonijiet tal-messaġġi, totalment b'xejn

```
Kombinazzjoni: "openclaw-free"
  1. if/qwen3.8-max-preview     (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)
  2. if/deepseek-v4-flash       (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)
  3. if/kimi-k2.7-code          (aċċess imniżżel b'xejn; limiti ta' rata jistgħu japplikaw)

Piża ta' kull xahar: $0
Aċċess permezz ta': WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```

---

## 📖 Konfigurazzjoni tal-Providers

Biex iżżid għadd kbir ta’ konnessjonijiet b’ċavetta API minn fajl CSV jew JSON, uża **Dashboard → Providers → Import from file**. Il-kolonni huma pożizzjonali (`provider,name,apiKey,baseUrl,priority`); `provider` irid ikun diġà jeżisti bħala provider immaniġġjat jew node kompatibbli. Ara [Importazzjoni ta’ providers minn fajl CSV jew JSON](../providers/CSV-IMPORT.md).

### 🔐 Providers b’Abbonament

#### Claude Code (Pro/Max)

```bash
Dashboard → Providers → Qabbad Claude Code
→ Login OAuth → Aġġornament awtomatiku tat-token
→ Monitoraġġ tal-kwota ta’ 5 sigħat + ta’ kull ġimgħa

Mudelli:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001
```

**Parir Professjonali:** Uża Opus għal kompiti kumplessi u Sonnet għall-veloċità. OmniRoute jimmonitorja l-kwota għal kull mudell!

M’hemmx browser fuq il-host ta’ OmniRoute? Ħaddem `claude setup-token` kull fejn tkun illoggjat fi Claude Code u waħħal it-token ta’ sena fit-tab **Setup Token**. Ara [Claude Code b’token ta’ konfigurazzjoni](../providers/CLAUDE_CODE_SETUP_TOKEN.md).

Ir-rotot kompatibbli ma’ Claude u Claude Code jippreservaw il-livell ta’ sforz ta’ ħsieb `max` għall-mudelli Opus u Sonnet. Il-mudelli Haiku ma jaċċettawx il-livell ta’ sforz `max`, għalhekk OmniRoute jbaxxi dik it-talba għal baġit għoli ta’ ħsieb qabel jibgħatha lis-servizz upstream.

#### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Qabbad Codex
→ Login OAuth (port 1455)
→ Irrisettjar kull 5 sigħat + kull ġimgħa

Mudelli:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark
```

#### GitHub Copilot

```bash
Dashboard → Providers → Qabbad GitHub
→ OAuth permezz ta’ GitHub
→ Irrisettjar kull xahar (fl-1 tax-xahar)

Mudelli:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview
```

### 💰 Providers Irħas

#### GLM-4.7 (Irrisettjar kuljum, $0.6/1M)

1. Irreġistra: [Zhipu AI](https://open.bigmodel.cn)
2. Ikseb ċavetta API minn Coding Plan
3. Dashboard → Żid Ċavetta API: Provider: `glm`, Ċavetta API: `your-key`

**Uża:** `glm/glm-4.7` — **Parir Professjonali:** Coding Plan joffri kwota 3× akbar bi 1/7 tal-ispiża! Jirrisettja kuljum fl-10:00 AM.

#### MiniMax M2.1 (Irrisettjar kull 5 sigħat, $0.20/1M)

1. Irreġistra: [MiniMax](https://www.minimax.io)
2. Ikseb ċavetta API → Dashboard → Żid Ċavetta API

**Uża:** `minimax/MiniMax-M2.1` — **Parir Professjonali:** L-orħos għażla għal kuntest twil (1M tokens)!

#### Kimi K2 ($9/xahar b’rata fissa)

1. Abbona: [Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. Ikseb ċavetta API → Dashboard → Żid Ċavetta API

**Uża:** `kimi/kimi-k2.5` — **Parir Professjonali:** Prezz fiss ta’ $9/xahar għal 10M tokens = spiża effettiva ta’ $0.90/1M!

#### Baidu Qianfan / ERNIE

1. Irreġistra: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. Oħloq ċavetta API ta’ Qianfan → Dashboard → Żid Ċavetta API: Provider: `qianfan`

**Uża:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1`, jew ID ieħor ta’ mudell Qianfan kompatibbli ma’ OpenAI.

### 🆓 Providers B’XEJN

Il-providers b’xejn li ma jeħtiġux awtentikazzjoni għandhom swiċċ ħdejn **Ma hija meħtieġa l-ebda awtentikazzjoni** fil-paġna tal-provider tagħhom.
Meta titfih, dak il-provider jiġi diżattivat, jitneħħa mill-veduti konfigurati/kompatti ta’ Providers, u l-mudelli tiegħu jitneħħew minn `/v1/models`.

#### Qoder (9 mudelli B’XEJN)

```bash
Dashboard → Qabbad Qoder → Login OAuth → L-aċċess huwa soġġett għal-limiti attwali tal-provider

Mudelli: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3
```

#### Kiro (Claude B’XEJN)

```bash
Dashboard → Qabbad Kiro → AWS Builder ID jew Google/GitHub → ~50 kreditu/xahar

Mudelli: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```

---

## 🎨 Kombinazzjonijiet

Tista' terġa' tordna l-karti tal-kombinazzjonijiet direttament f'**Dashboard → Combos** billi tiġbed il-manku ta' kull karta. L-ordni tiġi mħżuna f'SQLite u terġa' titwaqqaf meta terġa' tibda.

### Eżempju 1: Massimizza l-Abbonament → Riserva Irħasa

```
Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.3/1M)

Use in CLI: premium-coding
```

### Eżempju 2: B'XEJN biss (Spiża Ċikka)

```
Name: free-combo
Models:
  1. if/kimi-k2.7-code (listed free access; provider limits may apply)
  2. kr/qwen3-coder-next (Kiro free fallback)

Cost: currently listed as $0; terms and availability may change
```

---

## 🔦 Integrazjoni CLI

### Cursor IDE

**Użu ta' Cursor bħala klijent OmniRoute** (instradi chat ta' Cursor permezz ta' OmniRoute):

```
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [mill-dashboard tal-omniroute]
  Model: cc/claude-opus-4-7
```

**Użu ta' OmniRoute bħala fornitur ta' Cursor** (OmniRoute jistenna lill-Cursor upstream): prefer
**Dashboard → Providers → Cursor → Login with Cursor**. F'Docker, ara
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md).

### Claude Code

Edit `~/.claude/settings.json`:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}
```

Użu l-endpoint root kompatibbli ma' Claude hawn. Tagħlaqx `/v1` ma' `ANTHROPIC_BASE_URL`.

### Codex CLI

```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```

### OpenClaw

Edit `~/.openclaw/openclaw.json`:

```json
{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}
```

**Jew uża l-Dashboard:** CLI Tools → OpenClaw → Auto-config

### Cline / Continue / RooCode

```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [mill-dashboard]
Model: cc/claude-opus-4-7
```

---

## 🚀 Twaqqif

### npm globali install (Rikomandat)

```bash
npm install -g omniroute

# Oħloq direttorju tal-konfigurazzjoni
mkdir -p ~/.omniroute

# Oħloq fajl .env (ara .env.example)
cp .env.example ~/.omniroute/.env

# Beda s-server
omniroute
# Jew b'port abbinali:
omniroute --port 3000
```

L-CLI awtomatikament jgħabbi `.env` minn `~/.omniroute/.env` jew `./.env`.

### Triq il-tray

Bedal OmniRoute fil-tray tas-sistema:

```bash
omniroute serve --tray
```

Il-kmand jirritorna wara li s-server u t-tray ikunu lesti.

Is-server jibqa' mingħajr il-terminal.

It-tray mode jappoġġa macOS, Windows, u sessions Linux b'interfaċċi grafika. It-tray mode ma jiftaħx l-dashboard awtomatikament.

Uża l-menu tal-tray għal dawn l-azzjonijiet:

- Ftaħ l-dashboard.
- Ftaħ `/dashboard/logs`.
- Biddel l-awto-bidu.
- Waqqaf OmniRoute.

Tagħmilx `--tray` ma' dawn l-għażliet:

- `--daemon`
- `--log`
- `--no-recovery`

Dawn il-mudelli jeħtieġu proprjetà differenti tal-proċess.

Ekwiżizzjoni ta' bidu fil-login li jmiss tal-magna:

```bash
omniroute autostart enable
```

L-awto-bidu juża t-tray mode fuq macOS, Windows, u sessions Linux b'interfaċċi grafika. Linux Headless juża s-servizz attwali tal-systemd user.

Tixħirx l-awto-bidu fil-login:

```bash
omniroute autostart disable
```

### Tneħħija

Meta m'għadekx teħtieġ OmniRoute, noffrulek żewġ scripts ħfief għat-tneħħija nadifa:

| Kmand                    | Azzjoni                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `npm run uninstall`      | Jneħħi l-app tal-sistema iżda **jżomm il-DB u l-konfigurazzjonijiet tiegħek** f'`~/.omniroute`. |
| `npm run uninstall:full` | Jneħħi l-app U **jħassar permanentement il-konfigurazzjonijiet, ċavetti, u databases kollha**.  |

> Nota: Biex tħaddem dawn il-kmandi, mur fil-folder tal-proġett OmniRoute (jekk klonjajtu) u ħaddemhom. Barra minn hekk, jekk installat globalment, tista' sempliċement tħaddem `npm uninstall -g omniroute`.

### Twaqqif VPS

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Jew: pm2 start npm --name omniroute -- start
```

### Twaqqif PM2 (RAM Baxxa)

Għal servers b'RAM limitata, uża l-għażla tal-limitu tal-memorja:

```bash
# B'limitu ta' 512MB (default)
pm2 start npm --name omniroute -- start

# Jew b'limitu tal-memorja abbinali
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Jew uża ecosystem.config.js
pm2 start ecosystem.config.js
```

Oħloq `ecosystem.config.js`:

```javascript
module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};
```

### Docker

```bash
# Bini ta' stampa (default = runner-cli b'codex/claude/droid installat minn qabel)
docker build -t omniroute:cli .

# Mod portable (rikomandat)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```

Għall-mod host-integrated b'binaries CLI, ara t-taqsima Docker fil-dokumentazzjoni ewlenija.

### Void Linux (xbps-src)

L-utenti tal-Void Linux jistgħu jippakkjaw u jinstallaw OmniRoute b'mod nattiv jużand il-framework tal-kross-kompilazzjoni `xbps-src`. Dan jawtomatizza l-bini standalone tal-Node/js flimkien mal-`better-sqlite3` native bindings meħtieġa.

<details>
<summary><b>Ara l-mudell xbps-src</b></summary>

```bash
# Fajl tal-mudell għal 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Iddetermina l-arqa CPU tal-mira għal node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Installa d-dipendenzi kollha – omitti l-scripts
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Bni l-bundle standalone Next.js
	npm run build

	# 3) Kopja l-assetti statiċi fil-standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Ġabar il-binding nativ better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Poġġi l-binding imġabar fil-bundle standalone
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Neħħi l-bundles ta' @img speċifiċi għall-arqa
	rm -rf .next/standalone/node_modules/@img

	# 7) Kopja d-dipendenzi runtime tal-pino li ġew omessi mill-analiżi statika Next.js:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Prevjeni t-tneħħija ta' direttorji vojta tal-app router Next.js mill-hook post-install
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}
```

</details>

### Varjabbli tal-Ambjent

| Varjabbli                               | Default                              | Deskrizzjoni                                                                                                                                     |
| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `JWT_SECRET`                            | `omniroute-default-secret-change-me` | Sigriet għat-tiffirma tal-JWT (**biddel fil-produzzjoni**)                                                                                       |
| `INITIAL_PASSWORD`                      | `CHANGEME`                           | Password tal-ewwel login                                                                                                                         |
| `DATA_DIR`                              | `~/.omniroute`                       | Direttorju tad-dejta (db, użu, logħob)                                                                                                           |
| `PORT`                                  | default tal-frawwerk                 | Port tas-servizz (`20128` fil-eżempji)                                                                                                           |
| `HOSTNAME`                              | default tal-frawwerk                 | Jorbot il-host (Docker default għal `0.0.0.0`)                                                                                                   |
| `NODE_ENV`                              | default runtime                      | Waħħal `production` għat-twaqqif                                                                                                                 |
| `NEXT_PUBLIC_BASE_URL`                  | `http://localhost:20128`             | URL pubbliku bażiċi murija lill-dashboard u esposta lis-sserver (tissostitwixxi l-`BASE_URL` antika)                                             |
| `NEXT_PUBLIC_CLOUD_URL`                 | `https://omniroute.dev`              | URL bażiċi tal-endpoint tal-sinkronizzazzjoni cloud (tissostitwixxi l-`CLOUD_URL` antika)                                                        |
| `API_KEY_SECRET`                        | `endpoint-proxy-api-key-secret`      | Sigriet HMAC għall-API keys ġenerati                                                                                                             |
| `REQUIRE_API_KEY`                       | `false`                              | Infurza Bearer API key fuq `/v1/*`                                                                                                               |
| `ALLOW_API_KEY_REVEAL`                  | `false`                              | Tippermetti lill-utenti tal-dashboard awtentikati jikxfu l-valuri kompluti tal-API key洢żżati meta jitolbuhom                                    |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70`                                 | Frekwenza tal-ġdid tas-server għad-dejta tal-Provider Limits maħżuna; il-buttuni tal-ġdid tal-UI għadhom jistimulaw is-sinkronizzazzjoni manwali |
| `DISABLE_SQLITE_AUTO_BACKUP`            | `false`                              | Tixħirx il-prints awtomatiċi SQLite qabel il-kitbiet/importazzjoni/rkupru; il-backups manwali għadhom jaħdmu                                     |
| `APP_LOG_TO_FILE`                       | `true`                               | Jippermetti l-output tal-log tal-applikazzjoni u tal-awditjar fuq il-disk                                                                        |
| `AUTH_COOKIE_SECURE`                    | `false`                              | Tifforza cookie `Secure` tal-awtentikazzjoni (wara reverse proxy HTTPS)                                                                          |
| `CLOUDFLARED_BIN`                       | ma twarrabx                          | Uża binarju `cloudflared` eżistenti minflok l-downloads immaniġġjati                                                                             |
| `CLOUDFLARED_PROTOCOL`                  | `http2`                              | Trasport għat-Quick Tunnels immaniġġjati (`http2`, `quic`, jew `auto`)                                                                           |
| `OMNIROUTE_MEMORY_MB`                   | `512`                                | Limitu tal-heap tal-Node.js f'MB                                                                                                                 |
| `PROMPT_CACHE_MAX_SIZE`                 | `50`                                 | Daqs massimu ta' dħul tal-cache tal-prompt                                                                                                       |
| `SEMANTIC_CACHE_MAX_SIZE`               | `100`                                | Daqs massimu ta' dħul tal-cache semantiku                                                                                                        |

Għar-riferenza sħiħa tal-varjabbli tal-ambjent, ara l-[README](../README.md).

## 📊 Mudelli Disponibbli

<details>
<summary><b>Uri l-mudelli kollha disponibbli</b></summary>

> Il-lista ta' hawn taħt ġiet magħżula minn `open-sse/config/providerRegistry.ts` għal v3.8.0. Il-katalaġi tal-cloud (Gemini, OpenRouter, eċċ.) jiġu ssinkronizzati b'mod dinamiku — għall-katalaġi sħiħ ħaj issir miftuħ il- **Dashboard → Providers → [provider] → Available Models** jew sejjaħ `GET /api/models/catalog`.
>
> Jekk il-lista interna ta' provajder mmur, uża **Import from /models** fuq dik il-paġna (jew ippermetti **Auto-Sync**) biex tġib il-katalaġi tal-upstream ħaj. Dan ġie vverifikat fil-v3.8.50 għal LLM7.io (`gemini-3.1-flash-lite`) u UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); l-aċċess anonimu ta' Pollinations baqa' limited mill-upstream waqt l-istess test pass.

**Claude Code (`cc/`)** — Pro/Max OAuth: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`

**Codex (`cx/`)** — Plus/Pro OAuth: `cx/gpt-5.5` (+ livelli ta' sforz: `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark`

**GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime`

**Kiro (`kr/`)** — FREE OAuth: uża l-katalaġi ħaj murien taħt **Dashboard → Providers → Kiro → Available Models**. Il-disponibbiltà tiddependi fuq il-kont u l-pjan.

**Qoder (`if/`)** — FREE OAuth: `if/qwen3.8-max-preview`, `if/qwen3.7-max`, `if/qwen3.7-plus`, `if/kimi-k3`, `if/kimi-k2.7-code`, `if/glm-5.2`, `if/deepseek-v4-pro`, `if/deepseek-v4-flash`, `if/minimax-m3`

**GLM (`glm/`, `glm-cn/`, `zai/`, `glmt/`)** — $0.2–0.6/1M: `glm/glm-5.1`, `glm/glm-5`, `glm/glm-5-turbo`, `glm/glm-4.7`, `glm/glm-4.7-flash`, `glm/glm-4.6`, `glm/glm-4.6v`, `glm/glm-4.5`, `glm/glm-4.5v`, `glm/glm-4.5-air`

**MiniMax (`minimax/`, `minimax-cn/`)** — $0.2/1M: `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed`

**Kimi (`kimi/`, `kimi-coding/`, `kimi-coding-apikey/`)** — $9/xahar flat jew per-use: `kimi/kimi-k2.6`, `kimi/kimi-k2.5`

**DeepSeek (`ds/`)** — API key: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash`

**Groq (`groq/`)** — Ultra-fast: `groq/llama-3.3-70b-versatile`, `groq/meta-llama/llama-4-maverick-17b-128e-instruct`, `groq/qwen/qwen3-32b`, `groq/openai/gpt-oss-120b`

**xAI (`xai/`)** — Grok nattiv: `xai/grok-4.3`, `xai/grok-4.20-multi-agent-0309`, `xai/grok-4.20-0309-reasoning`, `xai/grok-4.20-0309-non-reasoning`

**Mistral (`mistral/`)** — Hosted fl-UE: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest`

**Perplexity (`pplx/`)** — Bis-searċi: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar`

**Together AI (`together/`)** — Open-source: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (b'xejn), `together/meta-llama/Llama-Vision-Free`, `together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free`, `together/deepseek-ai/DeepSeek-R1`, `together/Qwen/Qwen3-235B-A22B`, `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8`

**Fireworks AI (`fireworks/`)** — Inferrenzi veloċi: `fireworks/accounts/fireworks/models/kimi-k2p6`, `fireworks/accounts/fireworks/models/minimax-m2p7`, `fireworks/accounts/fireworks/models/qwen3p6-plus`, `fireworks/accounts/fireworks/models/glm-5p1`, `fireworks/accounts/fireworks/models/deepseek-v4-pro`

**Cerebras (`cerebras/`)** — Wafer-scale: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b`

**Cohere (`cohere/`)** — Fokus fuq RAG: `cohere/command-a-reasoning-08-2025`, `cohere/command-a-vision-07-2025`, `cohere/command-a-03-2025`, `cohere/command-r-08-2024`

**NVIDIA NIM (`nvidia/`)** — Enterprise: `nvidia/z-ai/glm-5.1`, `nvidia/minimaxai/minimax-m2.7`, `nvidia/google/gemma-4-31b-it`, `nvidia/mistralai/mistral-small-4-119b-2603`, `nvidia/mistralai/mistral-large-3-675b-instruct-2512`, `nvidia/qwen/qwen3.5-397b-a17b`, `nvidia/deepseek-ai/deepseek-v4-pro`, `nvidia/openai/gpt-oss-120b`, `nvidia/nvidia/nemotron-3-super-120b-a12b`

**Baidu Qianfan (`qianfan/`)** — ERNIE: `qianfan/ernie-5.1`, `qianfan/ernie-5.0-thinking-latest`, `qianfan/ernie-x1.1`

**Ollama Cloud (`ollama-cloud/`)**: `ollama-cloud/deepseek-v4-pro`, `ollama-cloud/deepseek-v4-flash`, `ollama-cloud/kimi-k2.6`, `ollama-cloud/glm-5.1`, `ollama-cloud/minimax-m2.7`, `ollama-cloud/gemma4:31b`, `ollama-cloud/qwen3.5:399b`

**Gemini (Google Cloud `gemini/`)**: Issinkronizzat ħaj skont il-API key minn Google — ebda lista statika. Qabbad key fil- **Dashboard → Providers** imbagħad uża **Available Models** biex timporta l-katalaġi attwali (pereż. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`).

**Provajderi kompatibbli oħra** (magħżula): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (permezz ta' `aws-bedrock`), `azure-ai`, `openrouter` (katalaġi pass-through), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Kull wieħed iżomm il-lista tal-mudelli tiegħu stess fil-`providerRegistry.ts` u jista' jiġi ssinkronizzat awtomatikament meta l-provajder jiżvela endpoint `/models`.

**Nota dwar l-IDs tal-mudelli:** OmniRoute juża IDs nattivi tal-provajder (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `groq-4.20-0309-reasoning`). Xi IDs jinkludu versjonijiet bil-punti għaliex hekk qed tistenna l-API ta' fuq. Jekk mudelli mhux elenkat hawn fuq, ħdimt `omniroute models --search <term>` jew sejjaħ `GET /api/models/catalog` biex tikkonferma d-disponibbiltà.

</details>

---

## 🧩 Karatteristiċi Avvanzati

### Mudelli Personalizzati

Żid kwalunkwe ID ta’ mudell ma’ kwalunkwe fornitur mingħajr ma tistenna aġġornament tal-app:

```bash
# Permezz tal-API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# Elenka: curl http://localhost:20128/api/provider-models?provider=openai
# Neħħi: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```

Jew uża d-Dashboard: **Fornituri → [Fornitur] → Mudelli Personalizzati**.

Noti:

- Il-fornituri kompatibbli ma’ OpenRouter u OpenAI/Anthropic jiġu ġestiti biss minn **Mudelli Disponibbli**. Iż-żieda manwali, l-importazzjoni u s-sinkronizzazzjoni awtomatika kollha jispiċċaw fl-istess lista ta’ mudelli disponibbli, għalhekk ma hemmx sezzjoni separata ta’ Mudelli Personalizzati għal dawk il-fornituri.
- Is-sezzjoni **Mudelli Personalizzati** hija maħsuba għal fornituri li ma jipprovdux importazzjonijiet ġestiti ta’ mudelli disponibbli.

### Fornituri Personalizzati Kompatibbli ma’ OpenAI

Kwalunkwe gateway li juża l-API ta’ OpenAI (proxy awtoospitat, vLLM, aggregatur ta’ parti terza)
jista’ jiżdied bħala node ta’ fornitur għalih:

1. **Fornituri → Żid Wieħed Kompatibbli ma’ OpenAI**.
2. **Isem**: tikketta tal-wiri għan-node.
3. **Prefiss**: l-isem tar-routing. Il-klijenti jsejħu l-mudelli bħala `<prefix>/<model>`, għalhekk node bil-
   prefiss `mygw` jipprovdi `mygw/gpt-4o-mini`. Meħtieġ; ma hemm ebda restrizzjoni fuq il-karattri.
4. **Tip ta’ API**: il-familja tal-endpoint li jipprovdi l-gateway (Chat Completions, Responses,
   Embeddings, awdjo, immaġnijiet).
5. **URL Bażi**: l-għerq tal-API, sa u inkluż `/v1` (pereżempju
   `https://gateway.example.com/v1`), mhux il-path sħiħ `/chat/completions`. Gateways b’
   paths mhux standard jistabbilixxuhom taħt **Settings Avvanzati** (path taċ-chat, path tal-mudelli).
6. Il-qasam **Ċavetta tal-API (għall-Iċċekkjar)** jittestja biss il-konnessjoni. Wara li toħloq in-node,
   iftaħ u uża **Żid Konnessjoni** biex taħżen iċ-ċavetta li se tintuża mit-talbiet.

In-node jingħata ID intern fil-forma `openai-compatible-<apiType>-<uuid>`; qatt ma għandek
għalfejn tittajpjah, għax il-prefiss huwa l-isem pubbliku.

#### Prefissi riżervati

Prefiss ma jistax ikun l-ID jew alias ta’ fornitur inkorporat (pereżempju `openai`, `cf`), u lanqas
l-ID ta’ fornitur irtirat. Ir-resolver tal-mudelli jiċċekkja l-IDs u l-aliases inkorporati qabel
in-nodes personalizzati, għalhekk node li juża wieħed minn dawk il-prefissi qatt ma jirċievi traffiku:
`<prefix>/model` jintbagħat lill-fornitur inkorporat minflok, jew jingħalaq b’mod sigur jekk dak il-fornitur
ikun ġie rtirat. Il-ħolqien jew l-editjar ta’ node b’tali prefiss jiġi rrifjutat b’dan il-messaġġ:

```text
prefix: "<prefix>" huwa prefiss ta’ fornitur riżervat — agħżel prefiss differenti (IDs/aliases riżervati ma jistgħux jintużaw għal nodes personalizzati għax talbiet bħal <prefix>/model jintbagħtu lil fornitur inkorporat jew jingħalqu b’mod sigur meta jiġi rtirat)
```

Agħżel prefiss distint (`mygw`, `acme-proxy`). Jekk talbiet lil node personalizzat ifallu bi
żball li jsemmi fornitur inkorporat jew il-kredenzjali tiegħu, iċċekkja jekk il-prefiss tan-node huwiex
riżervat: nodes issejvjati qabel ma kienet teżisti din ir-regola għadhom maħżuna, iżda l-prefiss tagħhom jibgħat it-traffiku
lill-fornitur inkorporat. Editja n-node u agħtih prefiss ġdid.

### Katina ta’ Peers ta’ OmniRoute

Gateway OmniRoute ieħor jista’ jiżdied bħala fornitur **Personalizzat kompatibbli ma’ OpenAI**. Uża l-
URL bażi `/v1` tal-peer u ċavetta tal-API dedikata bl-inqas privileġġi possibbli maħruġa minn dak il-peer.

Għal ktajjen reċiproċi jew b’diversi hops, attiva l-protezzjoni fakultattiva kontra loops fuq kull gateway:

```bash
# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```

```bash
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```

It-talbiet mibgħuta lil URL ta’ peer li jkun espliċitament fil-lista permessa biss jirċievu l-header
`X-OmniRoute-Peer-Trace`. Gateway jirrifjuta ID ta’ istanza ripetut jew baġit ta’ hops
eżawrit b’HTTP `508 Loop Detected`; il-fornituri upstream ordinarji ma jirċievu ebda metadata tal-peer.

Il-katina ta’ peers mhijiex replikazzjoni tad-database jew failover tal-host. Kull gateway iżomm
stat, caches, counters tar-rata u sessions ta’ SQLite indipendenti. Uża reverse proxy b’kontrolli tas-saħħa jew
failover tal-klijent għal disponibbiltà attiva/passiva jew attiva/attiva, u qatt timmonta database SQLite waħda
f’diversi istanzi OmniRoute li jkunu qed jaħdmu.

### Routes Dedikati tal-Fornituri

Idderieġi t-talbiet direttament lil fornitur speċifiku b’validazzjoni tal-mudell:

```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
```

Il-prefiss tal-fornitur jiżdied awtomatikament jekk ikun nieqes. Mudelli li ma jaqblux jirritornaw `400`.

### Konfigurazzjoni tal-Proxy tan-Network

```bash
# Issettja l-proxy globali
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Proxy għal kull fornitur
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Ittestja l-proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```

**Preċedenza:** Speċifiku għaċ-ċavetta → Speċifiku għall-combo → Speċifiku għall-fornitur → Globali → Ambjent.

### API tal-Katalgu tal-Mudelli

```bash
curl http://localhost:20128/api/models/catalog
```

Jirritorna mudelli raggruppati skont il-fornitur bit-tipi (`chat`, `embedding`, `image`).

### Sinkronizzazzjoni mal-Cloud

- Issinkronizza l-fornituri, il-combos u s-settings bejn l-apparati
- Sinkronizzazzjoni awtomatika fl-isfond b’timeout + fail-fast
- Ippreferi `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` min-naħa tas-server fil-produzzjoni

### Mina Rapida ta’ Cloudflare

- Disponibbli f’**Dashboard → Endpoints** għal Docker u skjeramenti oħra ospitati lokalment
- Joħloq URL temporanju `https://*.trycloudflare.com` li jgħaddi t-traffiku lill-endpoint attwali tiegħek kompatibbli ma’ OpenAI `/v1`
- L-ewwel attivazzjoni tinstalla `cloudflared` biss meta jkun meħtieġ; startjar mill-ġdid sussegwenti jerġa’ juża l-istess binarju ġestit
- Quick Tunnels ma jiġux restawrati awtomatikament wara startjar mill-ġdid ta’ OmniRoute jew tal-kontejner; erġa’ attivahom mid-dashboard meta jkun meħtieġ
- L-URLs tat-tunnel huma temporanji u jinbidlu kull darba li twaqqaf jew tistartja t-tunnel
- Managed Quick Tunnels jużaw HTTP/2 bħala t-trasport awtomatiku biex jevitaw twissijiet storbjużi dwar il-buffer UDP ta’ QUIC f’kontejners b’riżorsi limitati
- Issettja `CLOUDFLARED_PROTOCOL=quic` jew `auto` jekk trid tegħleb l-għażla tat-trasport ġestit
- Issettja `CLOUDFLARED_BIN` jekk tippreferi tuża binarju `cloudflared` installat minn qabel minflok it-tniżżil ġestit
- Il-pannelli ta’ Cloudflare Quick Tunnel, Tailscale Funnel, u ngrok Tunnel jistgħu jintwerew jew jinħbew f’**Settings → Appearance**. Il-ħabi ta’ pannell ma jwaqqafx tunnel li jkun qed jaħdem.

### Intelliġenza tal-Gateway tal-LLM (Fażi 9)

- **Cache Semantiku** — Jaħżen awtomatikament fil-cache tweġibiet mhux streaming b’temperature=0 (aqbeż dan b’`X-OmniRoute-No-Cache: true`)
- **Idempotenza tat-Talbiet** — Jelimina talbiet duplikati fi żmien 5s permezz tal-header `Idempotency-Key` jew `X-Request-Id`
- **Traċċar tal-Progress** — Avvenimenti SSE `event: progress` li trid tagħżel li tattiva permezz tal-header `X-OmniRoute-Progress: true`

---

### Ambjent ta’ Esperimentazzjoni għat-Traduttur

Aċċessibbli permezz ta’ **Dashboard → Translator**. Sib u solvi problemi u viżwalizza kif OmniRoute jittraduċi t-talbiet tal-API bejn il-fornituri.

| Modalità                          | Għan                                                                                                             |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Ambjent ta’ Esperimentazzjoni** | Agħżel il-formati tas-sors/tad-destinazzjoni, waħħal talba, u ara minnufih l-output tradott                      |
| **Tester taċ-Chat**               | Ibgħat messaġġi taċ-chat diretti permezz tal-proxy u spezzjona ċ-ċiklu sħiħ tat-talba/tweġiba                    |
| **Bank tat-Testijiet**            | Ħaddem testijiet f’lott fuq diversi kombinazzjonijiet ta’ formati biex tivverifika l-korrettezza tat-traduzzjoni |
| **Monitoraġġ Dirett**             | Ara t-traduzzjonijiet f’ħin reali hekk kif it-talbiet jgħaddu mill-proxy                                         |

**Każijiet ta’ użu:**

- Sib u solvi għaliex kombinazzjoni speċifika ta’ klijent/fornitur tfalli
- Ivverifika li t-tags tal-ħsieb, is-sejħiet tal-għodod, u l-prompts tas-sistema jiġu tradotti b’mod korrett
- Qabbel id-differenzi fil-format bejn il-formati ta’ OpenAI, Claude, Gemini, u Responses API

---

### Strateġiji tar-Rotot

Ikkonfigura permezz ta’ **Dashboard → Settings → Routing**. Id-dashboard juri s-sitt strateġiji l-aktar użati; il-combos u l-auto-router jappoġġjaw internament sett usa’.

**Strateġiji viżibbli fid-dashboard (rotot fil-livell tal-kont):**

| Strateġija                        | Deskrizzjoni                                                                                                               |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Imla l-Ewwel**                  | Juża l-kontijiet skont l-ordni ta’ prijorità — il-kont primarju jieħu ħsieb it-talbiet kollha sakemm ma jibqax disponibbli |
| **Rotazzjoni Ċiklika**            | Jdur fuq il-kontijiet kollha b’limitu sticky konfigurabbli (default: 3 sejħiet għal kull kont)                             |
| **P2C (Qawwa ta’ Żewġ Għażliet)** | Jagħżel 2 kontijiet każwali u jidderieġi lejn dak bl-aħjar stat — jibbilanċja t-tagħbija filwaqt li jqis l-istat           |
| **Każwali**                       | Jagħżel kont b’mod każwali għal kull talba permezz ta’ taħlit Fisher-Yates                                                 |
| **L-Inqas Użat**                  | Jidderieġi lejn il-kont bl-eqdem timestamp `lastUsedAt`, u jqassam it-traffiku b’mod uniformi                              |
| **Ottimizzat għall-Ispiża**       | Jidderieġi lejn il-kont bl-inqas valur ta’ prijorità, u jottimizza għall-fornituri bl-inqas spiża                          |

**Strateġiji avvanzati tal-combo u awtomatiċi** (konfigurabbli għal kull combo jew permezz tal-prefissi `auto/*` — ara [AUTO-COMBO.md](../routing/AUTO-COMBO.md)):

- `priority` — ordni stretta, qatt ma juża rotazzjoni ċiklika
- `weighted` — qsim proporzjonali tat-traffiku skont il-piżijiet ta’ kull mudell
- `fill-first` — juża l-ewwel mudell sakemm jintlaħqu l-limiti
- `round-robin` / `strict-random` / `random`
- `p2c` (Qawwa ta’ Żewġ Għażliet)
- `least-used` u `cost-optimized`
- `auto` — immexxi mill-punteġġ fost il-kandidati kollha
- `lkgp` (L-Aħħar Fornitur Tajjeb Magħruf) — iżomm mal-aħħar fornitur li rnexxa, imbagħad jirrikorri għar-regoli
- `context-optimized` — jagħżel il-mudell bl-akbar tieqa ta’ kuntest ħielsa
- `context-relay` — jgħaqqad mudelli b’kuntest twil għal interazzjonijiet sussegwenti

#### Header Estern għal Sessjoni Sticky

Għall-affinità ta’ sessjoni esterna (pereżempju, aġenti Claude Code/Codex wara reverse proxies), ibgħat:

```http
X-Session-Id: your-session-key
```

OmniRoute jaċċetta wkoll `x_session_id` u jirritorna ċ-ċavetta effettiva tas-sessjoni f’`X-OmniRoute-Session-Id`.

Jekk tuża Nginx u tibgħat headers bil-format tal-linja ta’ taħt, attiva:

```nginx
underscores_in_headers on;
```

#### Aliases tal-Mudelli b’Wildcards

Oħloq mudelli b’wildcards biex tassenja mill-ġdid l-ismijiet tal-mudelli:

```
Mudell: claude-sonnet-*     →  Mira: cc/claude-sonnet-4-6
Mudell: gpt-*               →  Mira: gh/gpt-5.3-codex
```

Il-wildcards jappoġġjaw `*` (kwalunkwe karattri) u `?` (karattru wieħed).

#### Ktajjen ta’ Fallback

Iddefinixxi ktajjen globali ta’ fallback li japplikaw għat-talbiet kollha:

```
Katina: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7
```

---

### Kombinazzjonijiet Komuni ta’ Fornituri u Mudelli tar-Rotot

Dawn huma eżempji ta’ mudelli biex tgħaqqad diversi fornituri u tidderieġi bejniethom f’OmniRoute:

#### 1. Combo għal Aġent tal-Ikkowdjar: Raġunament Avvanzat b’Fallback għall-Ispiża/Veloċità

Ideali għal aġenti tal-ikkowdjar (OpenCode, Claude Code, Cursor, Cline). Inizjalment jidderieġi lejn mudelli ta’ raġunament mill-aktar avvanzati, u jirrikorri għal mudelli veloċi tal-ikkowdjar meta jispiċċaw il-kwoti jew iseħħu żbalji.

- **Dashboard**: Combos → New Combo → Name: `agent-coding` → Strategy: `Priority`
- **Mudelli**:
  1. `claude/claude-sonnet-4-6` (Aġent primarju tal-ikkowdjar)
  2. `openai/gpt-4o` (Fallback sekondarju b’kapaċità għolja)
  3. `deepseek/deepseek-v4-flash` (Fallback effiċjenti ħafna u kosteffettiv)

```bash
# Eżempju permezz tal-API
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-coding",
    "strategy": "priority",
    "models": [
      { "model": "claude/claude-sonnet-4-6" },
      { "model": "openai/gpt-4o" },
      { "model": "deepseek/deepseek-v4-flash" }
    ]
  }'
```

#### 2. Combo b'Failover Awtomatiku tal-Livell Bla Ħlas

Jikkatina diversi fornituri bla ħlas u mingħajr ċwievet biex jimmassimizza l-ħin ta' disponibbiltà mingħajr spejjeż tal-API.

- **Strateġija**: `Least Used` jew `Round Robin` (tqassam it-tagħbija bejn il-kwoti)
- **Mudelli**:
  1. `groq/llama-3.3-70b-versatile`
  2. `gemini/gemini-2.5-flash`
  3. `cerebras/gpt-oss-120b`

```bash
# Eżempju permezz tas-CLI
omniroute combo create free-stack \
  --models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
  --strategy round-robin
```

#### 3. Pipeline Multimodali / Viżjoni u Test

Tqabbil ta' mudelli speċjalizzati tal-viżjoni ma' ġenerazzjoni ta' test b'veloċità għolja għal flussi tax-xogħol li jinvolvu l-fehim tal-immaġnijiet u l-ġenerazzjoni tal-kodiċi.

- **Mudell**: Combo `Priority` li jelenka l-ewwel il-mudelli li jappoġġjaw il-viżjoni u fl-aħħar mudell ta' test/kodiċi b'rendiment għoli.
- **Mudelli**:
  1. `gemini/gemini-2.5-pro` (Fehim b'saħħtu tal-immaġnijiet/kontenut multimodali)
  2. `openai/gpt-4o` (Użu bbilanċjat tal-viżjoni u tal-għodod)
  3. `deepseek/deepseek-v4-flash` (Ġenerazzjoni ta' test/kodiċi)

---

### Reżiljenza u Circuit Breakers

Ikkonfigura permezz ta' **Dashboard → Settings → Resilience**.

OmniRoute jimplimenta reżiljenza fil-livell tal-fornitur b'ħames komponenti:

1. **Kju tat-Talbiet u Ritmu** — Kontroll tat-talbiet fil-livell tas-sistema:
   - **Talbiet Kull Minuta (RPM)** — Għadd massimu ta' talbiet kull minuta għal kull kont
   - **Ħin Minimu Bejn it-Talbiet** — Intervall minimu f'millisekondi bejn it-talbiet
   - **Għadd Massimu ta' Talbiet Konkorrenti** — Għadd massimu ta' talbiet simultanji għal kull kont

2. **Perjodu ta' Stennija tal-Konnessjoni** — Konfigurazzjoni għal kull tip ta' awtentikazzjoni għal konnessjoni waħda wara fallimenti li jistgħu jerġgħu jiġu ppruvati:
   - **Perjodu Bażi ta' Stennija** — Intervall ta' stennija predefinit għal fallimenti upstream li jistgħu jerġgħu jiġu ppruvati
   - **Uża Suġġerimenti Upstream għall-Prova mill-Ġdid** — Jirrispetta `Retry-After` awtorevoli jew suġġerimenti ta' reset meta jingħataw
   - **Għadd Massimu ta' Passi ta' Backoff** — Livell massimu ta' backoff esponenzjali għal fallimenti ripetuti

3. **Circuit Breaker tal-Fornitur** — Jissorvelja l-fallimenti minn tarf sa tarf tal-fornitur, jimmarka fornitur bħala degradat fil-limitu ta' twissija kkonfigurat, u jiftaħ il-breaker meta jintlaħaq il-limitu ta' fallimenti kkonfigurat:
   - **Limitu ta' Degradazzjoni** — Fallimenti konsekuttivi tal-fornitur qabel ma jidħol fi `DEGRADED`
   - **Limitu ta' Fallimenti** — Fallimenti konsekuttivi tal-fornitur qabel ma jidħol fi `OPEN`
   - **Timeout għar-Reset** — Intervall ta' żmien qabel ma l-fornitur jerġa' jiġi ttestjat
   - **CLOSED** (Tajjeb) — It-talbiet jgħaddu b'mod normali
   - **DEGRADED** — It-talbiet jibqgħu għaddejjin filwaqt li jiġu ssorveljati aktar fallimenti
   - **OPEN** — Il-fornitur jiġi mblukkat temporanjament wara fallimenti ripetuti
   - **HALF_OPEN** — Qed jiġi ttestjat jekk il-fornitur irkuprax

   Il-limiti tar-rata `429` speċifiċi għall-konnessjoni jibqgħu f'**Perjodu ta' Stennija tal-Konnessjoni** u ma jingħaddux għall-breaker tal-fornitur.

   L-istat waqt it-tħaddim tal-breaker tal-fornitur jintwera biss f'**Dashboard → Health**.

4. **Stenna l-Perjodu ta' Stennija** — Jekk kull konnessjoni kandidata tkun diġà fil-perjodu ta' stennija, OmniRoute jista' jistenna sal-ewwel tmiem ta' perjodu ta' stennija u awtomatikament jerġa' jipprova l-istess talba tal-klijent.

5. **Sejbien Awtomatiku tal-Limitu tar-Rata** — Meta l-fornituri upstream jirritornaw intervalli espliċiti ta' stennija, dawk is-suġġerimenti jieħdu preċedenza fuq il-perjodu lokali ta' stennija tal-konnessjoni meta l-issettjar ikun attivat.

**Parir Professjonali:** Uża l-paġna **Health** biex tispezzjona u tirrisettja l-breakers attivi tal-fornituri wara interruzzjoni. Il-paġna Resilience tibdel il-konfigurazzjoni biss.

---

### Esportazzjoni / Importazzjoni tad-Database

Immaniġġja l-backups tad-database f'**Dashboard → Settings → System & Storage**.

| Azzjoni                      | Deskrizzjoni                                                                                                                                                               |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Esporta d-Database**       | Iniżżel id-database SQLite attwali bħala fajl `.sqlite`                                                                                                                    |
| **Esporta Kollox (.tar.gz)** | Iniżżel arkivju sħiħ ta' backup li jinkludi: id-database, l-issettjar, il-combos, il-konnessjonijiet tal-fornituri (mingħajr kredenzjali), il-metadata taċ-ċwievet tal-API |
| **Importa d-Database**       | Itella' fajl `.sqlite` biex jissostitwixxi d-database attwali. Backup ta' qabel l-importazzjoni jinħoloq awtomatikament sakemm `DISABLE_SQLITE_AUTO_BACKUP=true`           |

```bash
# API: Esporta d-database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Esporta kollox (arkivju sħiħ)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: Importa d-database
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"
```

**Validazzjoni tal-Importazzjoni:** Il-fajl importat jiġi vvalidat għall-integrità (kontroll pragma ta' SQLite), għat-tabelli meħtieġa (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), u għad-daqs (massimu ta' 100MB).

**Każijiet ta' Użu:**

- Ittrasferixxi OmniRoute bejn magni
- Oħloq backups esterni għall-irkupru minn diżastri
- Aqsam il-konfigurazzjonijiet bejn il-membri tat-tim (esporta kollox → aqsam l-arkivju)

---

### Dashboard tal-Issettjar

Il-paġna tal-issettjar hija organizzata f'**7 tabs** għal navigazzjoni faċli:

| Tab            | Kontenut                                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ġenerali**   | Għodod tal-ħażna tas-sistema, imġiba predefinita, viżibbiltà tal-mini tal-endpoint                                                                                                                            |
| **Dehra**      | Kontrolli tat-tema (ċara/skura/sistema), viżibbiltà tal-istrixxa tal-ġenb, swiċċijiet tal-pannelli għall-kards tal-mini Cloudflare/Tailscale/ngrok                                                            |
| **IA**         | Baġit tal-ħsieb (mgħoddi kif inhu / tneħħija awtomatika / personalizzat / adattiv — ara [THINKING_BUDGET.md](./THINKING_BUDGET.md)), prompt globali tas-sistema, statistika tal-cache tal-prompts             |
| **Sigurtà**    | Settings tal-login/password, Kontroll tal-Aċċess bl-IP, awtentikazzjoni tal-API għal `/models`, Imblukkar tal-Fornituri, protezzjoni kontra l-injezzjoni fil-prompts                                          |
| **Rotot**      | Strateġija globali tar-rotot (Imla l-Ewwel / Ċiklu Sekwenzjali / P2C / Każwali / L-Inqas Użat / Ottimizzat għall-Ispiża), aliases tal-mudelli b'wildcard, ktajjen ta' fallback, valuri predefiniti tal-combos |
| **Reżiljenza** | Kju tat-talbiet, cooldown tal-konnessjoni, konfigurazzjoni tal-circuit breaker tal-fornitur, u mġiba ta' stennija għall-cooldown                                                                              |
| **Avvanzat**   | Konfigurazzjoni globali tal-proxy (HTTP/SOCKS5), sostituzzjonijiet tal-proxy għal kull fornitur                                                                                                               |

Ġenerali ma għadux jirrepeti n-noti dwar il-logging u l-cache li jinqraw biss. Is-settings taż-żamma u
l-ottimizzazzjoni tad-database jinħażnu permezz ta' `/api/settings/database`; it-tindif manwali tal-cache juża
`DELETE /api/cache`. Il-limiti massimi tar-ringieli fir-reġistri tat-talbiet u tal-proxy huma kkontrollati minn
`CALL_LOGS_TABLE_MAX_ROWS` u `PROXY_LOGS_TABLE_MAX_ROWS`.

---

### Ġestjoni tal-Ispejjeż u tal-Baġit

Aċċessibbli permezz ta' **Dashboard → Spejjeż**.

| Tab            | Għan                                                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Baġit**      | Issettja limiti tal-infiq għal kull ċavetta tal-API b'baġits ta' kuljum/kull ġimgħa/kull xahar u traċċar f'ħin reali |
| **Prezzijiet** | Ara u editja l-entrati tal-prezzijiet tal-mudelli — spiża għal kull 1K token ta' input/output għal kull fornitur     |

```bash
# API: Issettja baġit
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: Ikseb l-istatus attwali tal-baġit
curl http://localhost:20128/api/usage/budget
```

**Traċċar tal-Ispejjeż:** Kull talba tirreġistra l-użu tat-tokens u tikkalkula l-ispiża billi tuża t-tabella tal-prezzijiet. Ara d-dettalji f'**Dashboard → Użu** skont il-fornitur, il-mudell, u ċ-ċavetta tal-API.

---

### Traskrizzjoni tal-Awdjo

OmniRoute jappoġġja t-traskrizzjoni tal-awdjo permezz tal-endpoint kompatibbli ma' OpenAI:

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# Eżempju b'curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"
```

`deepgram/nova-3` hija r-rotta nattiva ta' Deepgram u teħtieġ ċavetta tal-API ta' Deepgram.
Jekk OpenRouter biss huwa kkonfigurat, uża `openrouter/deepgram/nova-3`.

Fornituri ta' **Diskors għal Test (traskrizzjoni)**:

- `openai/` (kompatibbli ma' whisper)
- `groq/` (Groq Whisper Turbo)
- `deepgram/` (familja Nova)
- `assemblyai/`
- `nvidia/` (Parakeet, Canary)
- `huggingface/` (varjanti ta' whisper)
- `qwen/`

Fornituri ta' **Test għal Diskors (`POST /v1/audio/speech`)**:

- `openai/` (tts-1, tts-1-hd)
- `hyperbolic/`
- `deepgram/` (Aura)
- `nvidia/` (Magpie TTS)
- `elevenlabs/`
- `huggingface/`
- `inworld/`
- `cartesia/`
- `playht/`
- `kie/`
- `aws-polly/`
- `xiaomi-mimo/`
- `coqui/`, `tortoise/`
- `qwen/`

Formati tal-awdjo appoġġjati għat-traskrizzjoni: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Il-formati tal-output tat-TTS jiddependu mill-fornitur (mp3, wav, opus, pcm, mulaw).

---

### Strateġiji tal-Ibbilanċjar tal-Combos

Ikkonfigura l-ibbilanċjar għal kull combo f'**Dashboard → Combos → Oħloq/Editja → Strateġija**.

| Strateġija                    | Deskrizzjoni                                                                        |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| **Ċiklu Sekwenzjali**         | Tgħaddi minn mudell għal ieħor b'mod sekwenzjali                                    |
| **Prijorità**                 | Dejjem tipprova l-ewwel mudell; tuża fallback biss f'każ ta' żball                  |
| **Każwali**                   | Tagħżel mudell każwali mill-combo għal kull talba                                   |
| **Ibbilanċjata bil-Piżijiet** | Tqassam ir-rotot proporzjonalment skont il-piżijiet assenjati lil kull mudell       |
| **L-Inqas Użat**              | Tibgħat it-talba lejn il-mudell bl-inqas talbiet reċenti (tuża l-metriċi tal-combo) |
| **Ottimizzata għall-Ispiża**  | Tibgħat it-talba lejn l-orħos mudell disponibbli (tuża t-tabella tal-prezzijiet)    |

Il-valuri predefiniti globali tal-combos jistgħu jiġu ssettjati f'**Dashboard → Settings → Rotot → Valuri Predefiniti tal-Combos**.
B'mod predefinit, it-timeouts tal-miri tal-combo jirtu t-timeout attwali tat-talba. Uża **Timeout tal-mira
(sekondi)** fil-valuri predefiniti tal-combos jew f'combo individwali biss meta limitu iqsar għal kull mira għandu
jattiva fallback aktar malajr.

L-ottimizzazzjonijiet tal-combos b'latenza żero jridu jiġu attivati espliċitament. Ħalli **Ottimizzazzjonijiet b'latenza żero** diżattivati biex
tipprevjeni lil dawn il-karatteristiċi tal-latenza milli jikkompetu mal-miri tal-fallback, jaqbżu miri abbażi tal-istorja tat-TTFT,
jew jikkompressaw it-talbiet ta' fallback; l-attivazzjoni tippermetti hedging ikkonfigurat, qbiżiet predittivi tat-TTFT,
u kompressjoni proattiva tal-fallback biex il-fedeltà tar-rotot/talbiet tiġi skambjata ma' latenza aktar baxxa fit-tarf.

Iddiżattiva l-**buffer tat-tokens tar-raġunament** meta l-fornituri upstream jeħtieġu limiti stretti ta’
`max_tokens` / `maxOutputTokens`. Meta jkun attivat, ir-routing ikkombinat iżid spazju addizzjonali għall-mudelli
ta’ raġunament biss għal mudelli b’limitu tal-output magħruf u jħalli l-limitu tat-tokens tal-klijent l-istess meta
l-valur ibbufferjat sikur ikun jaqbeż dak il-limitu. Jekk il-limitu tal-klijent ikun diġà ogħla minn limitu magħruf,
OmniRoute jnaqqsu għal dak il-limitu qabel ma jibgħat it-talba upstream.

---

### Dashboard tas-Saħħa

Aċċessah permezz ta’ **Dashboard → Health**. Ħarsa ġenerali f’ħin reali lejn is-saħħa tas-sistema b’6 kards:

| Kard                        | X’Turi                                                                          |
| --------------------------- | ------------------------------------------------------------------------------- |
| **Status tas-Sistema**      | Ħin ta’ tħaddim, verżjoni, użu tal-memorja, direttorju tad-data                 |
| **Saħħa tal-Fornituri**     | Stat waqt it-tħaddim tas-circuit breaker globali tal-fornituri                  |
| **Limiti tar-Rata**         | Perjodi ta’ stennija attivi tal-konnessjonijiet għal kull kont bil-ħin li fadal |
| **Imblukkar Attiv**         | Imblukkar attiv speċifiku għall-mudell u esklużjonijiet temporanji              |
| **Cache tal-Firem**         | Statistika tal-cache tad-deduplikazzjoni (ċwievet attivi, rata ta’ hits)        |
| **Telemetrija tal-Latenza** | Aggregazzjoni tal-latenza p50/p95/p99 għal kull fornitur                        |

**Parir Professjonali:** Il-paġna Health taġġorna ruħha awtomatikament kull 10 sekondi. Uża l-kard tas-circuit breaker biex tidentifika liema fornituri qed jesperjenzaw problemi.

---

## 🤖 Awto-Routjar (B’ebda konfigurazzjoni)

OmniRoute jittrasmetti b’**awto-router mmexxi b’iskor** li jagħżel l-aħjar mudell għal kull talba fost il-provdituri kollha konnessi — l-ebda kombo x’tżomm. Agħti biss it-talba b’wieħed mill-prefissi `auto/*` u l-Omniroute se jkabbar kombo virtwali fuq il-post, billi jskora l-kandidati skont id-dewmien, l-ispiża, ir-rata ta’ suċċess, l-adattament tal-kuntest, l-adattament tal-mudell għall-impjiegi, it-telf reċenti, il-kwota, u l-kundizzjonijiet tal-ksur tal-ċirkuwitu.

| Prefiss        | Jottimizza għal                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `auto`         | Default bilanċjat (dewmien × ispiża × rata ta’ suċċесс)                                                              |
| `auto/coding`  | Xogħlijiet tal-kodifikazzjoni: jippreferixxi Claude, GPT-5, GLM, Kimi, Qwen Coder, il-kodifikaturi DeepSeek          |
| `auto/cheap`   | L-iqsar $/token, jaccetta aktar dewmien                                                                              |
| `auto/fast`    | L-iqsar dewmien, injora l-ispiża                                                                                     |
| `auto/offline` | Provdituri biss lokali (Ollama, vLLM, llama.cpp) — utli għal ambjenti mħottas                                        |
| `auto/smart`   | Kwalità tar-ragunament l-ewwel (Opus, GPT-5 xhigh, R1, ragunament GLM 5.1)                                           |
| `auto/lkgp`    | "Provdituri Magħrufa Tajbin ta’ l-Aħħar" — imwaħħal mal-aħħar provditur ta’ suċċесс, imbagħad jirrikorri għar-regoli |

Eżempju:

```bash
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactor dan il-funzjoni Python" }],
    "stream": true
  }'
```

L-awto-router huwa deskritt b’mod sħiħ f’[AUTO-COMBO.md](../routing/AUTO-COMBO.md) — inkluż kif tista’ taġġusta l-piżijiet tal-iskor, tissanzjona provdituri, u tispezzjona d-deċiżjonijiet tar-routjar f’**Dashboard → Auto Combo**.

---

## 🔌 Integrazzjoni MCP & A2A

L-Omniroute huwa kemm **server MCP** (Protokoll tal-Kuntest tal-Mudell) kif ukoll **server A2A** (Agent-to-Agent JSON-RPC 2.0). Kwalunkwe IDE jew provditur tal-aġenti kompatibbli mal-MCP jista’ sejjaħ għall-għodod tal-Omniroute direttament — l-ebda wrapper addizzjonali meħtieġ.

### Trasporti MCP

- **SSE**: `http://localhost:20128/api/mcp/sse`
- **Streamable HTTP**: `http://localhost:20128/api/mcp/stream`
- **stdio**: `omniroute --mcp` (għal plugins tal-IDE li jippreferixxu l-stdio)

### Konnetti Claude Desktop

Editja `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) jew l-ekwivalenti fuq Windows/Linux:

```json
{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}
```

### Konnetti Cursor / Continue / VS Code MCP

Ipprovdilhom l-URL SSE `http://localhost:20128/api/mcp/sse` u API key ġenerata f’**Dashboard → API Keys**.

### Ambiti

L-MCP bħalissa jiddefinixxi 32 ambitu magħruf. Kull Bearer key jista’ jiġi limitat għal ambitti speċifiċi — ara [MCP-SERVER.md](../frameworks/MCP-SERVER.md) għall-inventarju awtorevoli tal-ambiti u l-għodod, u [A2A-SERVER.md](../frameworks/A2A-SERVER.md) għas-skema JSON-RPC.

---

## 🧩 Sistema ta' Ħiliet

OmniRoute toffri **qafas ta' ħiliet estensibbli** (`src/lib/skills/`) sabiex l-agenti u l-punt tat-tmiem A2A jistgħu jwettqu rutini speċifiċi għal domini (eż. `code-review`, `summarize`, `extract-facts`, `web-research`).

- **Interfaċi tal-Marketplace** — Stenna u tinstalla ħiliet minn **Dashboard → Ħiliet**
- **Ambiti fuq iċ-ċavetta** — Irstrinġu liema ċavetti tal-API jistgħu jsejħu liema ħiliet
- **Ħiliet personalizzati** — Waqqa' fajl TypeScript f' `src/lib/a2a/skills/`, irreġistrah, u immedjatament isir invokabbli permezz tal-A2A

Referenza sħiħa: [SKILLS.md](../frameworks/SKILLS.md).

---

## 💾 Sistema tal-Memorja

OmniRoute jippreżerva **memorja twila tal-konverżazzjoni** b'retrieval ibridu:

- **SQLite FTS5** għal tiftixa bil-kelma mal-turns li għaddew
- **Ħażna vetturali ta' Qdrant** (għażla) għal tifkira semantika
- **Spezzjoni awtomatika tal-fatti** — L-entitajiet, il-preferenzi, u d-deċiżjonijiet jiġu rrasummjati wara kull session u maħżuna fil- `memory_facts`
- Il-memorji huma skopjati skont iċ-ċavetta tal-API u skont is-sessjoni

Immaniġġja l-mororji f' **Dashboard → Memorja** (tiftixa, teditja, esportazzjoni, tneħħija). L-isuperfiċi HTTP (`/api/memory/*`) tippermetti lill-agenti jippromwovu u jistaqsu l-fatti b'mod programmatiku — ara [MEMORY.md](../frameworks/MEMORY.md).

---

## 🔔 Webhooks

Abbona għall-avvenimenti tal-OmniRoute għal monitoraġġ u awtomazzjoni f'ħin reali.

- Oħloq webhook f' **Dashboard → Webhooks** b'URL ta' skop u sigriet tal-iffirma HMAC
- L-avvenimenti disponibbli: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed`
- Kull payload jinkludi `X-OmniRoute-Signature` (HMAC-SHA256) għal verifika
- Storji: 3 attentat b'retroċessjoniment esponenzjali, imbagħad il-queue tal-mewt

Is-sema sħiħa f' [WEBHOOKS.md](../frameworks/WEBHOOKS.md).

---

## ☁️ Aġenti tal-Cloud

OmniRoute jintegra ma' aġenti tal-kodiċi tal-cloud (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**) sabiex tista' tiddispatchja xogħlijiet li jdumu fit-tul minn l-istess dashboard li tiġġestixxi r-rotta lokali tiegħek.

- Oħloq xogħlijiet f' **Dashboard → Aġenti tal-Cloud** jew permezz ta' `POST /api/v1/agents/tasks`
- Iġbor l-istatus, il-logs, u l-artifatti għal kull xogħol
- Ġib ċavetta tal-API tiegħek stess għal kull fornitur — il-kredenzjali qatt ma ħarġu minn l-istanza tal-OmniRoute

Referenza sħiħa: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md).

---

## 🛠️Ġestjoni Programmatika

Tista' timmaniġġja kull riżorsa tal-OmniRoute (fornituri, kombos, ċavetti, settings) permezz ta' HTTP billi tuża **ċavetta Bearer b' l-ambitu `manage`**.

Ġenera l-ċavetta f' **Dashboard → Ċavetti tal-API → Ċavetta Ġdida → Ambitu: manage**, imbagħad:

```bash
# Lista tal-fornituri
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Żid konnessjoni mal-fornitur
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# Oħloq combo
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# Lista/ħoloq ċavetti tal-API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'
```

Ara [API_REFERENCE.md](../reference/API_REFERENCE.md) għall-katalgu sħiħ tal-punti tat-tmiem u l-isemi tal-istedina/rispons.

---

## 💻 CLI Interna

OmniRoute jipprovdi CLI intern (`omniroute …`) għat-twaqqif, dijanjostika, u kontroll waqt l-isfond. Dan huwa **separat mill-paġna "Għodod CLI" fil-dashboard**, li tikkonfigura CLIs ta' parti terza (Claude Code, Cursor, Codex, Cline, …) sabiex ikunu jistgħu jikkomunikaw ma' OmniRoute.

```bash
omniroute setup                    # Wizard interattiv (password, fornituri, kombinazzjonijiet)
omniroute setup --non-interactive  # Ħaġar għal CI
omniroute doctor                   # Dijanjostika tas-saħħa (dir. tad-dett, DB, fornituri, portijiet)
omniroute providers available      # Elenka l-fornituri appoġġjati
omniroute providers list           # Elenka konnessjonijiet ikkonfigurati
omniroute providers test <id>      # Test ħaj ta' konnessjoni ta' fornitur
omniroute combos list              # Elenka l-kombinazzjonijiet
omniroute combos switch <name>     # Waqqaf kombinazzjoni default
omniroute models                   # Elenka mudelli disponibbli (--json, --search)
omniroute keys add | list | remove # Ġestixxi ċav API mill-terminal
omniroute backup                   # Fenfas ta' konfigurazzjoni + DB
omniroute restore [<timestamp>]    # Irrestorja minn fenfas
omniroute health                   # Saħħa dettaljata (breakers, cache, memorja)
omniroute quota                    # Użu tal-kwota tal-fornitur
omniroute mcp status               # Statut tal-server MCP
omniroute a2a status               # Statut tal-server A2A
omniroute tunnel list|create|stop  # Tunelli Cloudflare/Tailscale/ngrok
omniroute reset-password           # Ġeddid il-password tal-amministratur
omniroute --mcp                    # Daħħal server MCP permezz ta' stdio
omniroute --port 3000              # Daħħal il-server fuq port personaliżżat
```

Parir: għaqqad `omniroute doctor --json` mal-għodda ta' monitoraġġ tiegħek biex twissi meta konnessjonijiet tal-fornituri m'humiex fl-isħun.

---

## 🖥️ Applikazzjoni Desktop (Electron)

OmniRoute huwa disponibbli bħala applikazzjoni desktop nattiva għal Windows, macOS, u Linux.

### Twaqqif

```bash
# Mill-dir. electron:
cd electron
npm install

# Modalità żvilupp (għaqqad ma' server Next.js ta' żvilupp li qed jaħdem):
npm run dev

# Modalità produzzjoni (tuża build standard):
npm start
```

### Twaqqif ta' Installaturi

```bash
cd electron
npm run build          # Pjattaforma attwali
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universali)
npm run build:linux    # Linux (.AppImage)
```

Output → `electron/dist-electron/`

### Karatteristiċi Ċav

| Karatteristika                        | Twaħħal                                                           |
| ------------------------------------- | ----------------------------------------------------------------- |
| **Disponibbiltà tal-Server**          | Jivverifika qabel ma juri l-fenestra (bla skrin bħal din)         |
| **Tray tal-Isistema**                 | Naqqas għal-tray, ibdel il-port, ħarba minn menu tray             |
| **Ġestjoni tal-Port**                 | Ibdel port tal-server minn tray (ijerra mill-ġdid awtomatikament) |
| **Politika ta' Sigurtà tal-Kontenut** | CSP ristrett permezz ta' intestaturi session                      |
| **Munzell Wieħed**                    | Biss wieħed mill-app jeħtieġ jaħdem f'ħin wieħed                  |
| **Modalità Offline**                  | Is-server NextRoute inklux jaħdem mingħajr internet               |

### Variabbli tal-Ambjent

| Variabbja             | Default | Twaħħal                               |
| --------------------- | ------- | ------------------------------------- |
| `OMNIROUTE_PORT`      | `20128` | Port tal-server                       |
| `OMNIROUTE_MEMORY_MB` | `512`   | Limitu tal-ħira Node.js (64–16384 MB) |

📖 Dokumentazzjoni sħiħa: [`electron/README.md`](../../electron/README.md)