Added Dockerfile and instructions for using Colibrì through a docker container

docker/Dockerfile

@@ -0,0 +1,15 @@
+FROM debian:stable-slim 
+
+# We install the necessary packages to download and compile the code
+RUN apt-get update && \
+	apt-get install -y locales git build-essential python3 python3-pip && \
+	rm -rf /var/lib/apt/lists/* && \
+	mkdir /app
+
+# Let's clone the repository
+WORKDIR /app
+RUN git clone https://github.com/JustVugg/colibri.git .
+WORKDIR /app/c
+# It's time to compile
+RUN ./setup.sh && ./coli build
+

docker/README.IT.md

@@ -0,0 +1,454 @@
+_Read the read me in [English](README.md)._
+
+
+# Guida a Colibrì - Motore di Inferenza Locale
+
+Una guida semplice per eseguire **Colibrì**, un motore di inferenza locale basato su GLM 5.2, senza conoscenze di programmazione. Se hai già Docker installato, sei a buon punto.
+
+---
+
+## 📋 Sommario
+
+- [Cosa è Colibrì?](#cosa-è-colibrì)
+- [Cosa serve](#cosa-serve)
+    - [Hardware](#hardware)
+    - [Software](#software)
+- [Come iniziare](#come-iniziare)
+    - [Passo 1: Scarica il modello](#passo-1-scarica-il-modello)
+    - [Passo 2: Scarica il Dockerfile di Colibrì](#passo-2-scarica-il-dockerfile-di-colibrì)
+    - [Passo 3: Compila l'immagine Docker](#passo-3-compila-limmagine-docker)
+    - [Passo 4: Avvia Colibrì](#passo-4-avvia-colibr%C3%AC)
+    - [Cosa significa quel comando?](#cosa-significa-quel-comando)
+    - [Usare Colibrì](#usare-colibrì)
+- [Entrare in una console Linux dentro il container](#entrare-in-una-console-linux-dentro-il-container)
+- [Risoluzione dei problemi](#risoluzione-dei-problemi)
+- [Note tecniche](#note-tecniche)
+- [Domande frequenti](#domande-frequenti)
+- [Supporto e contributi](#supporto-e-contributi)
+- [Test sul mio PC](#test-sul-mio-pc)
+
+---
+
+## Cosa è Colibrì?
+
+Colibrì è un'applicazione che ti permette di eseguire un modello di intelligenza artificiale (GLM 5.2) direttamente sul tuo computer, senza connettersi a server esterni. È possbile anche farlo girare in Docker, che isola l'applicazione dal resto del sistema.
+
+> **Nota importante**: Il modello è molto grande. Attendi anche diversi minuti per una risposta a una domanda semplice, specialmente con poca RAM. Alla fine di questo readme vedrai il risultato sul mio PC (senza scheda grafica discreta) e arrivo a 0.01 token al secondo.
+
+---
+
+## Cosa serve
+
+### Hardware
+
+| Memoria RAM | Funziona? | Note |
+|:---:|:---:|---|
+| < 16 GB | ❌ No | Memoria insufficiente |
+| 24 GB | ⚠️ Forse | Possibile, da testare |
+| 32 GB | ✅ Sì | Il minimo (ma vedi sezione memoria su Windows) |
+| 48+ GB | ✅ Sì | Meglio |
+
+Inoltre: un **disco SSD veloce** è essenziale. Colibrì usa il disco come memoria aggiuntiva. Con una scheda grafica NVidia è ancora meglio.
+
+### Software
+
+- **Docker Desktop** (Windows, Mac, Linux) — [scarica qui](https://www.docker.com/products/docker-desktop/)
+- **Python** (solo se vuoi scaricare il modello da casa tua)
+  - Windows: [python.org](https://www.python.org) oppure Microsoft Store
+  - Linux: `apt-get install python3 python3-pip`
+  - Mac: [python.org](https://www.python.org) oppure Homebrew
+
+Non serve nessun ambiente di compilazione. Tutto avviene dentro il container Docker.
+
+---
+
+## Come iniziare
+
+### Passo 1: Scarica il modello
+
+Il modello GLM 5.2 è circa **360 GB**. Scegli uno di questi metodi:
+
+#### Metodo A: Con Python (consigliato)
+
+1. **Installa la libreria per Hugging Face:**
+   ```bash
+   python -m pip install -U huggingface_hub[cli]
+   ```
+   Su Linux, usa `python3` al posto di `python`.
+
+2. **Scarica il modello** (apri il terminale nella cartella dove lo vuoi salvare):
+   ```bash
+   hf_download mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp --local-dir .
+   ```
+   
+   **Esempio**: se vuoi salvarlo in `C:\LLM\models\glm-5.2` (Windows):
+   - Apri PowerShell in quella cartella
+   - Copia e incolla il comando sopra
+   - Attendi (molto)
+
+#### Metodo B: Senza Python (solo se necessario)
+
+Se sei su Windows e non riesci con Python:
+- Scarica manualmente da [Hugging Face](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp)
+- Decomprimi in una cartella (es. `C:\LLM\models\glm-5.2`)
+
+---
+
+### Passo 2: Scarica il Dockerfile di Colibrì
+
+1. Vai a: https://github.com/JustVugg/colibri/blob/main/docker/Dockerfile
+2. Clicca il pulsante **Download** (icona ⬇️) in alto a destra
+3. Salva il file in una cartella (es. `C:\LLM\Colibrì`)
+
+---
+
+### Passo 3: Compila l'immagine Docker
+
+Apri il terminale (PowerShell su Windows, Terminal su Mac/Linux) **nella cartella dove hai salvato il Dockerfile** e digita:
+
+**Windows:**
+```bash
+docker build -t colibri-i .
+```
+
+**Linux/Mac:**
+```bash
+sudo docker build -t colibri-i .
+```
+
+Attendi che finisca (pochi minuti). Se tutto va bene, vedrai: `Successfully tagged colibri-i:latest`
+
+> **Se vuoi recepire gli aggiornamenti del repository**: Cancella prima l'immagine vecchia con `docker rmi colibri-i` e ricompila.
+
+---
+
+### Passo 4: Avvia Colibrì
+
+Apri il terminale e digita il comando sottostante (sostituisci `C:\LLM\models\glm-5.2` con il percorso reale del tuo PC):
+
+**Windows** (PowerShell):
+```bash
+$MODEL_PATH="C:\LLM\models\glm-5.2"
+docker run --rm -it --name colibri-c `
+  -v "$MODEL_PATH`:/app/glm-5.2" `
+  -e COLI_MODEL=/app/glm-5.2 `
+  colibri-i ./coli chat
+```
+
+**Mac/Linux** (Terminal/Bash):
+```bash
+MODEL_PATH="/path/to/glm-5.2"
+docker run --rm -it --name colibri-c \
+  -v "$MODEL_PATH:/app/glm-5.2" \
+  -e COLI_MODEL=/app/glm-5.2 \
+  colibri-i ./coli chat
+```
+
+**Esempio per Linux:**
+```bash
+MODEL_PATH="/home/user/LLM/glm-5.2"
+docker run --rm -it --name colibri-c \
+  -v "$MODEL_PATH:/app/glm-5.2" \
+  -e COLI_MODEL=/app/glm-5.2 \
+  colibri-i ./coli chat
+```
+
+---
+
+### Cosa significa quel comando?
+
+| Parte | Spiegazione |
+|-------|-------------|
+| `docker run` | Avvia un container |
+| `--rm` | Cancella il container quando chiudi |
+| `-it` | Modalità interattiva (puoi scrivere e leggere) |
+| `-v "PERCORSO:/app/glm-5.2"` | Collega il tuo modello dentro il container |
+| `-e COLI_MODEL=/app/glm-5.2` | Dice a Colibrì dove trovare il modello |
+| `colibri-i` | Nome dell'immagine Docker |
+| `./coli chat` | Avvia Colibrì in modalità chat |
+
+---
+
+### Usare Colibrì
+
+Una volta avviato, vedrai un prompt come questo:
+
+```
+  ──────────────────────────────────────────────────────────
+  type and press Enter · Ctrl-C stops the answer · :more continues · :reset clears memory · :q exits
+```
+
+**Comandi utili:**
+- `Scrivi una domanda + Invio` → Ricevi la risposta
+- `Ctrl + C` → Interrompi la risposta
+- `:reset` → Cancella la memoria della conversazione
+- `:q` → Esci
+
+**Esempio di uso:**
+```
+› Quanti abitanti ha la Cina?
+
+La Cina è attualmente il paese più popoloso al mondo. 
+La popolazione è di circa 1,41 miliardi di abitanti.
+```
+
+Il modello capisce **italiano, inglese, cinese e altre lingue**, anche se è ottimizzato per inglese e cinese.
+
+---
+
+## Entrare in una console Linux dentro il container
+
+Se vuoi esplorare il container come fosse una macchina Linux normale:
+
+```bash
+docker run --rm -it --name colibri-c \
+  -v "PERCORSO_MODELLO:/app/glm-5.2" \
+  -e COLI_MODEL=/app/glm-5.2 \
+  colibri-i /bin/bash
+```
+
+Ora sei dentro Linux. Digita `exit` per uscire.
+
+---
+
+## Risoluzione dei problemi
+
+### ❌ "Docker non trovato"
+
+**Causa**: Docker non è installato o il terminale non lo riconosce.
+
+**Soluzione**:
+1. Reinstalla [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+2. Riavvia il computer
+3. Apri un nuovo terminale e riprova
+
+---
+
+### ❌ "Out of memory" (memoria insufficiente) o container che si chiude subito
+
+**Causa**: Il tuo computer non ha abbastanza RAM, oppure su Windows, WSL usa meno memoria di quella disponibile.
+
+**Soluzione per Windows (WSL):**
+
+1. Apri PowerShell e controlla la memoria disponibile a WSL:
+   ```bash
+   wsl
+   cat /proc/meminfo | grep MemTotal
+   exit
+   ```
+   Dividi il numero per 1.073.741.824 (è 1024³) per averlo in GB.
+
+2. Se WSL usa meno di quello che hai, crea un file di configurazione:
+   - Apri un editor di testo (Notepad va bene)
+   - Copia questo:
+     ```ini
+     [wsl2]
+     memory=24GB
+     processors=12
+     swap=16GB
+     ```
+   - Salva il file con il nome: `.wslconfig` (con il punto)
+   - Posizionalo in: `C:\Users\TuoNomeUtente\`
+
+3. Riavvia WSL da PowerShell:
+   ```bash
+   wsl --shutdown
+   wsl
+   ```
+
+4. Controlla di nuovo:
+   ```bash
+   # cat /proc/meminfo | grep MemTotal
+   # exit
+   ```
+
+**Soluzione per Mac/Linux**: Aumenta la RAM disponibile a Docker dalle impostazioni di Docker Desktop, oppure aggiungi più RAM al computer.
+
+---
+
+### ❌ La risposta è molto lenta
+
+**Cause possibili**:
+1. Il disco è lento
+2. Hai poca RAM
+3. Colibrì sta usando il disco come memoria aggiuntiva (normale)
+
+**Come controllare la velocità del disco:**
+
+**Windows** (PowerShell da amministratore):
+```bash
+winsat disk -drive C
+```
+Cambia `C` con la lettera del tuo disco.
+
+**Linux/Mac** (Terminal):
+```bash
+sudo hdparm -Tt /dev/sda
+```
+Cambia `/dev/sda` con il tuo disco (vedi con `lsblk` per Linux).
+
+Un **SSD NVMe moderno** arriva a 15 GB/sec. Se il tuo è sotto 2-3 GB/sec, è lento.
+
+---
+
+### ❌ "Permission denied" su Linux
+
+**Causa**: Docker richiede permessi da amministratore.
+
+**Soluzione - Opzione 1** (rapida):
+```bash
+sudo docker build -t colibri-i .
+sudo docker run ... (come sopra, con sudo davanti)
+```
+
+**Soluzione - Opzione 2** (permanente):
+```bash
+sudo usermod -aG docker $USER
+# Riavvia il computer
+docker run ... (senza sudo)
+```
+
+---
+
+### ❌ "Image not found" o errore durante il build
+
+**Causa**: Il Dockerfile è corrotto o non nella cartella giusta.
+
+**Soluzione**:
+1. Verifica che il Dockerfile sia nella cartella dove apri il terminale:
+   ```bash
+   ls Dockerfile  # Mac/Linux
+   dir Dockerfile # Windows
+   ```
+2. Riscarica il Dockerfile dal repository GitHub
+3. Elimina l'immagine vecchia: `docker rmi colibri-i`
+4. Riprova il build
+
+---
+
+### ❌ "hf_download: command not found"
+
+**Causa**: La libreria Hugging Face non è installata correttamente.
+
+**Soluzione**:
+```bash
+pip install -U huggingface_hub[cli]
+# oppure su Linux/Mac:
+pip3 install -U huggingface_hub[cli]
+```
+
+Poi riprova il comando `hf_download`.
+
+---
+
+### ❌ Il modello non si scarica (timeout o errori di rete)
+
+**Cause**: Connessione lenta o instabile, Hugging Face temporaneamente non disponibile.
+
+**Soluzione**:
+1. Attendi e riprova il comando `hf_download`
+2. Se continua, scarica manualmente da [qui](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp)
+3. Decomprimi il file ZIP nella cartella desiderata
+
+---
+
+## Note tecniche
+
+### Perché il disco è importante?
+
+Colibrì usa il disco come "RAM aggiuntiva" virtuale (paging). Un disco **veloce** è cruciale per prestazioni decenti.
+
+- **SSD NVMe** (consigliato): 1-15 GB/sec
+- **SSD SATA**: 0.5-1 GB/sec
+- **Hard disk meccanico**: 0.05-0.1 GB/sec ❌ (troppo lento)
+
+Se il tuo disco è lento, le risposte saranno molto lente anche con molta RAM.
+
+---
+
+### Configurazione di default consigliata per WLS su Windows
+
+Se hai **esattamente 32 GB di RAM** e usi Windows, è molto probabile che WLS di default sia settato per non consumare più di 16 GB di RAM. Bisogna aumentare questo limite [Risoluzione dei problemi](#risoluzione-dei-problemi) . Nel mio caso ho adottato questa configurazione:
+```ini
+[wsl2]
+memory=24GB
+processors=12
+swap=16GB
+```
+
+Ovvero, nel mio caso, ho lasciato 8 GB di RAM e 4 CPU a Windows e dato 24 GB e 12 processori a WSL + Linux.
+
+---
+
+## Domande frequenti
+
+**D: E se ho meno di 32 GB di RAM?**  
+R: Probabile che non funzioni bene. Puoi provare se hai 24 GB, ma non è garantito.
+
+**D: Posso aumentare la velocità di risposta?**  
+R: Sì, in parte:
+- Usa un SSD NVMe veloce
+- Aumenta la RAM
+- Riduci la complessità delle domande
+- Usa `:reset` per cancellare la memoria e alleggerire il carico
+
+**D: Posso usare Colibrì senza Docker?**  
+R: Colibrì è nato così, ma questa guida assume Docker. Per compilare da sorgente, vedi il repository GitHub.
+
+**D: Quanta connessione internet mi serve dopo aver scaricato il modello?**  
+R: Zero. Colibrì funziona completamente offline.
+
+---
+
+## Supporto e contributi
+
+Se trovi errori o hai suggerimenti per migliorare questa guida, aprici una issue o una pull request sul repository GitHub di Colibrì.
+
+Buon divertimento! 🐦
+
+---
+
+## Test sul mio PC
+
+Nel primo caso ho fatto una domanda in italiano, nel secondo in giapponese, e nel terzo ho rifatto la domanda in giapponese ma ho richiesto una risposta in italiano. 
+
+```
+PS C:\quack\llm\colibri\docker> docker run --rm -it --name colibri-c -v "C:\quack\llm\models\glm-5.2:/app/glm-5.2" -e COLI_MODEL=/app/glm-5.2 colibri-i ./coli chat
+
+     ▄▀▀▀▄  ▄        colibrì v1.0
+  ▄▄▄▄▀▀▀▀▄▀▀        tiny engine, immense model
+      ▀▀▀▀▀▀▀        GLM-5.2 · 744B MoE · int4 · streaming CPU
+        ▀▀▀▀         chat · glm-5.2 · ram -GB · topp off
+          ▀
+  ──────────────────────────────────────────────────────────
+  type and press Enter · Ctrl-C stops the answer · :more continues · :reset clears memory · :q exits
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ › Quanti abitanti ha la Cina?                                                                  │
+  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+  ◆ colibrì
+  La Cina è attualmente il paese più popoloso al mondo (sebbene, secondo alcune stime recenti, sia stata ormai superata dall'India).
+
+  La popolazione totale della Repubblica Popolare Cinese è di circa 1,41 miliardi di abitanti (dati del 2020-2022 circa).
+  └─ 76 tok · 0.04 tok/s · hit 3% · RSS 15.9 GB · 2012s
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ › 漫画「ワンピース」の主人公の名前を教えてください。名前だけで、それ以上のコメントはありません。                                              │
+  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+  ◆ colibrì
+  ルフィ
+  └─ 2 tok · 0.01 tok/s · hit 1% · RSS 16.7 GB · 260s
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ › 漫画「ワンピース」の主人公の名前を教えてください。名前だけで、それ以上のコメントはありません。イタリア語で返信                                      │
+  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+  ◆ colibrì
+  Il nome del protagonista di One Piece è Monkey D. Luffy.
+  └─ 14 tok · 0.02 tok/s · hit 2% · RSS 17.3 GB · 593s
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ ›
+  ```

docker/README.md

@@ -0,0 +1,488 @@
+_Leggi il leggimi in [Italiano](README.IT.md)._
+
+
+# Colibrì Guide - Local Inference Engine
+
+A simple guide to running **Colibrì**, a local inference engine based on GLM 5.2, without needing programming knowledge. If you already have Docker installed, you are well on your way.
+
+---
+
+## 📋 Table of Contents
+
+* [What is Colibrì?](https://www.google.com/search?q=#what-is-colibr%C3%AC)
+* [Requirements](https://www.google.com/search?q=#requirements)
+    * [Hardware](https://www.google.com/search?q=#hardware)
+    * [Software](https://www.google.com/search?q=#software)
+* [How to get started](https://www.google.com/search?q=#how-to-get-started)
+    * [Step 1: Download the model](https://www.google.com/search?q=#step-1-download-the-model)
+    * [Step 2: Download the Colibrì Dockerfile](https://www.google.com/search?q=#step-2-download-the-colibr%C3%AC-dockerfile)
+    * [Step 3: Build the Docker image](https://www.google.com/search?q=#step-3-build-the-docker-image)
+    * [Step 4: Start Colibrì](https://www.google.com/search?q=#step-4-start-colibr%C3%AC)
+    * [What does that command mean?](https://www.google.com/search?q=#what-does-that-command-mean)
+    * [Using Colibrì](https://www.google.com/search?q=#using-colibr%C3%AC)
+* [Entering a Linux console inside the container](https://www.google.com/search?q=#entering-a-linux-console-inside-the-container)
+* [Troubleshooting](https://www.google.com/search?q=#troubleshooting)
+* [Technical notes](https://www.google.com/search?q=#technical-notes)
+* [Frequently Asked Questions](https://www.google.com/search?q=#frequently-asked-questions)
+* [Support and contributions](https://www.google.com/search?q=#support-and-contributions)
+* [Tests on my PC](https://www.google.com/search?q=#tests-on-my-pc)
+
+---
+
+## What is Colibrì?
+
+Colibrì is an application that allows you to run an artificial intelligence model (GLM 5.2) directly on your computer, without connecting to external servers. It is also possible to run it in Docker, which isolates the application from the rest of the system.
+
+> **Important note**: The model is very large. Expect to wait several minutes for an answer to a simple question, especially with low RAM. At the end of this readme, you will see the result on my PC (without a discrete graphics card), and I reach 0.01 tokens per second.
+
+---
+
+## Requirements
+
+### Hardware
+
+| RAM Memory | Works? | Notes |
+| --- | --- | --- |
+| < 16 GB | ❌ No | Insufficient memory |
+| 24 GB | ⚠️ Maybe | Possible, needs testing |
+| 32 GB | ✅ Yes | The minimum (but see memory section for Windows) |
+| 48+ GB | ✅ Yes | Better |
+
+Additionally: a **fast SSD** is essential. Colibrì uses the disk as additional memory. Having an NVidia graphics card is even better.
+
+### Software
+
+* **Docker Desktop** (Windows, Mac, Linux) — [download here](https://www.google.com/search?q=https://www.docker.com/products/docker-desktop/)
+* **Python** (only if you want to download the model yourself)
+* Windows: [python.org](https://www.google.com/search?q=https://www.python.org) or Microsoft Store
+* Linux: `apt-get install python3 python3-pip`
+* Mac: [python.org](https://www.google.com/search?q=https://www.python.org) or Homebrew
+
+No build environment is needed. Everything happens inside the Docker container.
+
+---
+
+## How to get started
+
+### Step 1: Download the model
+
+The GLM 5.2 model is approximately **360 GB**. Choose one of these methods:
+
+#### Method A: Using Python (recommended)
+
+1. **Install the library for Hugging Face:**
+```bash
+python -m pip install -U huggingface_hub[cli]
+```
+
+On Linux, use `python3` instead of `python`.
+2. **Download the model** (open the terminal in the folder where you want to save it):
+```bash
+hf_download mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp --local-dir .
+```
+
+**Example**: if you want to save it in `C:\LLM\models\glm-5.2` (Windows):
+* Open PowerShell in that folder
+* Copy and paste the command above
+* Wait (a long time)
+
+#### Method B: Without Python (only if necessary)
+
+If you are on Windows and cannot get it to work with Python:
+
+* Download manually from [Hugging Face](https://www.google.com/search?q=https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp)
+* Unzip into a folder (e.g., `C:\LLM\models\glm-5.2`)
+
+---
+
+### Step 2: Download the Colibrì Dockerfile
+
+1. Go to: [https://github.com/JustVugg/colibri/blob/main/docker/Dockerfile](https://www.google.com/search?q=https://github.com/JustVugg/colibri/blob/main/docker/Dockerfile)
+2. Click the **Download** button (⬇️ icon) in the top right
+3. Save the file in a folder (e.g., `C:\LLM\Colibrì`)
+
+---
+
+### Step 3: Build the Docker image
+
+Open the terminal (PowerShell on Windows, Terminal on Mac/Linux) **in the folder where you saved the Dockerfile** and type:
+
+**Windows:**
+
+```bash
+docker build -t colibri-i .
+```
+
+**Linux/Mac:**
+
+```bash
+sudo docker build -t colibri-i .
+```
+
+Wait for it to finish (a few minutes). If everything goes well, you will see: `Successfully tagged colibri-i:latest`
+
+> **If you want to receive repository updates**: First delete the old image with `docker rmi colibri-i` and rebuild.
+
+---
+
+### Step 4: Start Colibrì
+
+Open the terminal and type the command below (replace `C:\LLM\models\glm-5.2` with the actual path on your PC):
+
+**Windows** (PowerShell):
+
+```bash
+$MODEL_PATH="C:\LLM\models\glm-5.2"
+docker run --rm -it --name colibri-c `
+  -v "$MODEL_PATH`:/app/glm-5.2" `
+  -e COLI_MODEL=/app/glm-5.2 `
+  colibri-i ./coli chat
+```
+
+**Mac/Linux** (Terminal/Bash):
+
+```bash
+MODEL_PATH="/path/to/glm-5.2"
+docker run --rm -it --name colibri-c \
+  -v "$MODEL_PATH:/app/glm-5.2" \
+  -e COLI_MODEL=/app/glm-5.2 \
+  colibri-i ./coli chat
+```
+
+**Example for Linux:**
+
+```bash
+MODEL_PATH="/home/user/LLM/glm-5.2"
+docker run --rm -it --name colibri-c \
+  -v "$MODEL_PATH:/app/glm-5.2" \
+  -e COLI_MODEL=/app/glm-5.2 \
+  colibri-i ./coli chat
+```
+
+---
+
+### What does that command mean?
+
+| Part | Explanation |
+| --- | --- |
+| `docker run` | Starts a container |
+| `--rm` | Deletes the container when you close it |
+| `-it` | Interactive mode (you can write and read) |
+| `-v "PATH:/app/glm-5.2"` | Mounts your model inside the container |
+| `-e COLI_MODEL=/app/glm-5.2` | Tells Colibrì where to find the model |
+| `colibri-i` | Name of the Docker image |
+| `./coli chat` | Starts Colibrì in chat mode |
+
+---
+
+### Using Colibrì
+
+Once started, you will see a prompt like this:
+
+```
+  ──────────────────────────────────────────────────────────
+  type and press Enter · Ctrl-C stops the answer · :more continues · :reset clears memory · :q exits
+
+```
+
+**Useful commands:**
+
+* `Write a question + Enter` → Receive the answer
+* `Ctrl + C` → Stop the answer
+* `:reset` → Clear conversation memory
+* `:q` → Exit
+
+**Usage example:**
+
+```
+› How many inhabitants does China have?
+
+China is currently the most populous country in the world. 
+The population is approximately 1.41 billion people.
+
+```
+
+The model understands **Italian, English, Chinese, and other languages**, although it is optimized for English and Chinese.
+
+---
+
+## Entering a Linux console inside the container
+
+If you want to explore the container as if it were a normal Linux machine:
+
+```bash
+docker run --rm -it --name colibri-c \
+  -v "MODEL_PATH:/app/glm-5.2" \
+  -e COLI_MODEL=/app/glm-5.2 \
+  colibri-i /bin/bash
+```
+
+Now you are inside Linux. Type `exit` to leave.
+
+---
+
+## Troubleshooting
+
+### ❌ "Docker not found"
+
+**Cause**: Docker is not installed or the terminal does not recognize it.
+
+**Solution**:
+
+1. Reinstall [Docker Desktop](https://www.google.com/search?q=https://www.docker.com/products/docker-desktop/)
+2. Restart your computer
+3. Open a new terminal and try again
+
+---
+
+### ❌ "Out of memory" or container closes immediately
+
+**Cause**: Your computer does not have enough RAM, or on Windows, WSL is using less memory than available.
+
+**Solution for Windows (WSL):**
+
+1. Open PowerShell and check the memory available to WSL:
+```bash
+wsl
+cat /proc/meminfo | grep MemTotal
+exit
+```
+
+
+Divide the number by 1,073,741,824 (which is 1024³) to get it in GB.
+2. If WSL uses less than what you have, create a configuration file:
+* Open a text editor (Notepad is fine)
+* Copy this:
+```ini
+[wsl2]
+memory=24GB
+processors=12
+swap=16GB
+
+```
+
+* Save the file with the name: `.wslconfig` (with the dot)
+* Place it in: `C:\Users\YourUsername\`
+
+3. Restart WSL from PowerShell:
+```bash
+wsl --shutdown
+wsl
+```
+
+4. Check again:
+```bash
+# cat /proc/meminfo | grep MemTotal
+# exit
+```
+
+**Solution for Mac/Linux**: Increase the RAM available to Docker from the Docker Desktop settings, or add more RAM to the computer.
+
+---
+
+### ❌ The answer is very slow
+
+**Possible causes**:
+
+1. The disk is slow
+2. You have low RAM
+3. Colibrì is using the disk as additional memory (normal)
+
+**How to check disk speed:**
+
+**Windows** (PowerShell as administrator):
+
+```bash
+winsat disk -drive C
+```
+
+Change `C` with your disk letter.
+
+**Linux/Mac** (Terminal):
+
+```bash
+sudo hdparm -Tt /dev/sda
+```
+
+Change `/dev/sda` with your disk (check with `lsblk` on Linux).
+
+A **modern NVMe SSD** reaches 15 GB/sec. If yours is under 2-3 GB/sec, it is slow.
+
+---
+
+### ❌ "Permission denied" on Linux
+
+**Cause**: Docker requires administrator permissions.
+
+**Solution - Option 1** (quick):
+
+```bash
+sudo docker build -t colibri-i .
+sudo docker run ... (as above, with sudo in front)
+```
+
+**Solution - Option 2** (permanent):
+
+```bash
+sudo usermod -aG docker $USER
+# Restart the computer
+docker run ... (without sudo)
+```
+---
+
+### ❌ "Image not found" or error during build
+
+**Cause**: The Dockerfile is corrupted or not in the right folder.
+
+**Solution**:
+
+1. Verify that the Dockerfile is in the folder where you open the terminal:
+```bash
+ls Dockerfile  # Mac/Linux
+dir Dockerfile # Windows
+```
+
+2. Redownload the Dockerfile from the GitHub repository
+3. Delete the old image: `docker rmi colibri-i`
+4. Retry the build
+
+---
+
+### ❌ "hf_download: command not found"
+
+**Cause**: The Hugging Face library is not installed correctly.
+
+**Solution**:
+
+```bash
+pip install -U huggingface_hub[cli]
+# or on Linux/Mac:
+pip3 install -U huggingface_hub[cli]
+```
+
+Then retry the `hf_download` command.
+
+---
+
+### ❌ The model does not download (timeout or network errors)
+
+**Causes**: Slow or unstable connection, Hugging Face temporarily unavailable.
+
+**Solution**:
+
+1. Wait and retry the `hf_download` command
+2. If it continues, download manually from [here](https://www.google.com/search?q=https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp)
+3. Unzip the ZIP file into the desired folder
+
+---
+
+## Technical notes
+
+### Why is the disk important?
+
+Colibrì uses the disk as "additional virtual RAM" (paging). A **fast** disk is crucial for decent performance.
+
+* **NVMe SSD** (recommended): 1-15 GB/sec
+* **SATA SSD**: 0.5-1 GB/sec
+* **Rotational hard disk**: 0.05-0.1 GB/sec ❌ (too slow)
+
+If your disk is slow, the answers will be very slow even with a lot of RAM.
+
+---
+
+### Recommended default configuration for WLS on Windows
+
+If you have **exactly 32 GB of RAM** and are using Windows, it is very likely that WLS by default is set to consume no more than 16 GB of RAM. We need to increase this limit [Troubleshooting](https://www.google.com/search?q=#troubleshooting) . In my case I adopted this configuration:
+
+```ini
+[wsl2]
+memory=24GB
+processors=12
+swap=16GB
+
+```
+
+That is, in my case, I left 8 GB of RAM and 4 CPUs to Windows and gave 24 GB and 12 processors to WSL + Linux.
+
+---
+
+## Frequently Asked Questions
+
+**Q: What if I have less than 32 GB of RAM?**
+
+A: It is likely that it will not work well. You can try if you have 24 GB, but it is not guaranteed.
+
+**Q: Can I increase the response speed?**
+
+A: Yes, partly:
+
+* Use a fast NVMe SSD
+* Increase RAM
+* Reduce the complexity of questions
+* Use `:reset` to clear memory and lighten the load
+
+**Q: Can I use Colibrì without Docker?**
+
+A: Colibrì was born that way, but this guide assumes Docker. To build from source, see the GitHub repository.
+
+**Q: How much internet connection do I need after downloading the model?**
+
+A: Zero. Colibrì works completely offline.
+
+---
+
+## Support and contributions
+
+If you find errors or have suggestions for improving this guide, open an issue or a pull request on the Colibrì GitHub repository.
+
+Have fun! 🐦
+
+---
+
+## Tests on my PC
+
+In the first case, I asked a question in Italian; in the second, in Japanese; and in the third, I repeated the question in Japanese but requested an answer in Italian.
+
+```
+PS C:\quack\llm\colibri\docker> docker run --rm -it --name colibri-c -v "C:\quack\llm\models\glm-5.2:/app/glm-5.2" -e COLI_MODEL=/app/glm-5.2 colibri-i ./coli chat
+
+     ▄▀▀▀▄  ▄        colibrì v1.0
+  ▄▄▄▄▀▀▀▀▄▀▀        tiny engine, immense model
+      ▀▀▀▀▀▀▀        GLM-5.2 · 744B MoE · int4 · streaming CPU
+        ▀▀▀▀         chat · glm-5.2 · ram -GB · topp off
+          ▀
+  ──────────────────────────────────────────────────────────
+  type and press Enter · Ctrl-C stops the answer · :more continues · :reset clears memory · :q exits
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ › Quanti abitanti ha la Cina?                                                                  │
+  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+  ◆ colibrì
+  La Cina è attualmente il paese più popoloso al mondo (sebbene, secondo alcune stime recenti, sia stata ormai superata dall'India).
+
+  La popolazione totale della Repubblica Popolare Cinese è di circa 1,41 miliardi di abitanti (dati del 2020-2022 circa).
+  └─ 76 tok · 0.04 tok/s · hit 3% · RSS 15.9 GB · 2012s
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ › 漫画「ワンピース」の主人公の名前を教えてください。名前だけで、それ以上のコメントはありません。                                              │
+  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+  ◆ colibrì
+  ルフィ
+  └─ 2 tok · 0.01 tok/s · hit 1% · RSS 16.7 GB · 260s
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ › 漫画「ワンピース」の主人公の名前を教えてください。名前だけで、それ以上のコメントはありません。イタリア語で返信                                      │
+  ╰────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+  ◆ colibrì
+  Il nome del protagonista di One Piece è Monkey D. Luffy.
+  └─ 14 tok · 0.02 tok/s · hit 2% · RSS 17.3 GB · 593s
+
+  ╭────────────────────────────────────────────────────────────────────────────────────────────────╮
+  │ ›
+
+```
+
+[source: 1]