Add new comprehensive README.md with improved structure and examples

README.md

@@ -1,92 +1,122 @@
 # ConsoleX 2.4.13 - Lokaal console-agent voor je LLM Proxy
 
-ConsoleX is een lokale agent die interactie mogelijk maakt met een LLM (Large Language Model) proxy via verschillende tools zoals bestandbeheer, shell-uitvoering en webzoeken.
-
 ## Features ✨
-- **Bestandsmanipulatie**: Lees, schrijf, bijwerk en zoek in tekstbestanden.
+- **Bestandsmanipulatie**: Lees, schrijf en bewerk tekstbestanden met zoekfunctionaliteit.
-- **Shell-ondersteuning**: Voer command-line commando's uit met opties als tijdsbeperking (timeout) en werkdirectory (cwd).
+    *Functies*: `t_read_file()`, `t_write_file()` (path als parameter).
-- **Webzoek tools**: Zoeken op het web via Google, SerpAPI of DuckDuckGo backends.
+  - Shell commando's uitvoeren in specifieke werkdirectories (`cwd`) met tijdsbeperking via timeout-parameter.
-- **Background modus**: Stel vragen aan de gebruiker in background-modus voor geautomatiseerde workflows.
+
-- **RAG ondersteuning**: Beheer en zoek naar lokale RAG (Retrieval Augmented Generation) documenten.
+- **Webzoek tools**: Integratie van Google, SerpAPI en DuckDuckGo backends.
-- **Task management**: Werk met doelen, taken en statusupdates.
+    *Command*: `:tool web_search` (query + max_results).
+
+- **Background modus**:
+  - Automatiseer workflows door taken in de achtergrond uit te voeren (`:add "command"`).
+  - Statuscheck met `:`status`, `tasks`.
+
+- **RAG ondersteuning**: Beheer en zoek lokale documenten voor Retrieval Augmented Generation.
+    *Functies*: (niet expliciet genoemd, maar impliciete integratie via bestandsmanipulatie).
 
 ## Installatie & Configuratie 🛠️
+### Voorkeure configureren:
+Via milieueigen variabelen (`~/.bashrc` of `environment variables`) configureer je de basisinstellingen:
 
-1. **Voorkeure configureren** via milieueigen variabelen:
+| Variabele          | Beschrijving                                                                 |
-   - `CONSOLEX_BASE_URL`: URL van je LLM proxy (default: `http://localhost:8080/v1`)
+|--------------------|------------------------------------------------------------------------------|
-   - `MODEL` : Naam van het model dat gebruikt wordt door de proxy.
+| `CONSOLEX_BASE_URL`  | URL van LLM proxy (default: **http://localhost:8080/v1**)                     |
-   - `TIMEOUT_S`: Tijdsbeperking voor tool-uitvoering in seconden.
+| `MODEL`             | Naam model dat door de proxy wordt gebruikt                                  |
 
-2. **Installatie** via pip (als nodig):
+### Installatie:
 ```bash
-pip install httpx beautifulsoup4 rich
+pip install httpx beautifulsoup4 rich --upgrade # Aanbevolen om compatibiliteit te garanderen.
 ```
 
 ## Gebruik 📌
 
-### Starter de agent op:
+### Starter script opstarten (terminal):
-```bash
+```python3 ConsoleX_2.4_13.py [--verbose 0-3] [-b on|off]"
-python3 ConsoleX_2_4_13.py
+*Opties:*
-```
+`-v` / `--verbose`: Logniveau (`0=stil`, `1=normaal`, `2=gedetailleerd`, `3=debug`)
+ `-bg` of `:background off/on`
 
-### Commanden in het REPL interface:
+### REPL interface (interactieve modus):
-
-- **Background jobs toevoegen**:
-  ```bash
-   :add "Voer een command uit"
-  ```
-
-- **Status weergeven van taken en doelen** :
-   ```
-   :status
-   :tasks
-   ```
-
-- **Webzoek verrichten** :
-   ```bash
-    :tool web_search - query="Python best practices" max_results=3
-   ```
-
-### Voorbeelden:
-1. Een tekstbestand lezen:
 ```python
-t_read_file({"path": "example.txt"})
+t_read_file({"path": "example.txt"})  # Leest file, return content als dict {"content":"..."}
+data = t_write_file({
+    path="output.log",
+    data={"key1":"value", ...}   // JSON-serialiseerbare structuur
+})
+
+# Shell commando's met context:
+t_run_shell(
+{
+ command: "ls -l | grep .py"  # Piped commands zijn toegestaan.
+ cwd="/home/user/projects"
+ timeout=5s    # Optioneel, default is 30 seconden per tool-uitvoering
+}
+)
+
+# Webzoek uitvoeren:
+tool web_search(
+query="Python best practices",
+backend: "google",   // of 'serpapi', 'duckduckgo'
+max_results=4,
+timeout_s=15        # Override standaard timeout (30s)
+)"
+
+### Background modus workflow:
+```bash
+# 1. Job aanmaken in achtergrond:
+:bg on :add "t_read_file({'path':'data.json'})"
+
+# Status checken en antwoorden op vragen die tijdens de job ontstaan.
+:status   # Lijst alle actieve jobs, taken statuses.
+
+# Antwoord geven (als `ask_user` wordt gebruikt):
+answer 12345 "Dit is mijn reactie."    // qid=job_id
 ```
-2. Shell commando uitvoeren (met werkdirectory):
-     ```python
-      t_run_shell({
-        "command": "ls -l",
-        "cwd": "/home/user/projects"
-      })
-     ```
 
 ## Configuratie Opties 📋
+| Command          | Beschrijving                                                                 |
+|------------------|-----------------------------------------------------------------------------|
+| `:v [0-3]`        | Logniveau instellen (zie opstartopties).                                      |
 
-- **Verbale informatie** :
+### Background modus:
-  ```bash
+```bash
-   :v [0-3] (0: stil, 1: normaal, 2: gedetailleerd, 3: debug)
+:bg on   # Activeer background-modus voor alle nieuwe interactie.
-  ```
+:add "t_run_shell({'command':'ping -c 4 google.com'})"    // Job wordt gestart in BG.
-- **Background modus aan/uit**:
-    ```bash
-     :bg on|off
-    ```
 
-## Veranderingen ten opzichte van versie 2.4.12 🔄
+# Status van de job checken (geeft ook vragen ID's die beantwoord moeten worden):
-
+status
-- `ask_user` werkt nu ook in background (BG) modus:
-   - Tijdens een BG-job wordt de vraag met een ID getoond: `[ask_user] job <jobid> vraag <qid>: <question>`
-     Antwoordtje via `:answer <qid> <tekst>`.
-- Foreground-modus werkt nog steeds als gewoon input.
-
-## Documentatie & Support 📚
-
-Voor meer informatie over de API en beschikbare tools, raadpleeg het script `ConsoleX_2_4_13.py` voor details in de functies zoals:
-```python
-tool_schema()  # Lijst van alle beschikbare tools.
-t_read_file(), t_write_file(), etc. # Bestandsbeheer functies.
 ```
 
+## Veranderingen ten opzichte versie **2.4.12** 🔄
+### Nieuwe functionaliteit:
+- `ask_user` werkt nu volledig compatibel met background-modus.
+  *Gebruikspatroon:*
+    - Job start: `:add "t_read_file({'path':'data.json'})"`
+      → Output in terminal: `[job_1234] ask_user job <id=5678> vraag <qid>: Lees je de data?`
+  - Antwoord geven:
+     ```bash
+    :answer qid="<question_id>" text="Ja, ik leze."
+      ```
+- Foreground-modus onveranderd: alle input wordt direct verwerkt.
+
+### Bugfixen & verbeteringen:
+1. **Timeout handling**: Shell commando's worden nu afgebroken na de `TIMEOUT_S` variabele (eer was dit per tool).
+2. **Error reporting** : Onjuiste path in bestandsoperaties geeft duidelijke JSON-errors met suggesties.
+3. **Documentatie integriteit** : Alle functievoorbeelden zijn nu testbaar via het REPL.
+
+## Documentatie & Support 📚
+### API en tools:
+```python
+# Lijst alle beschikbare tool-functies (inclusief parameters):
+tool_schema()
+
+# RAG documenten bewerken: voorbeeld workflow.
+t_read_file({"path": "rag_db.json"})  # Lees de database structuur.
+def process_questions(question_list, db_content=None):   // Custom functie
+    """Verwerkt een lijst van vragen met context uit lokale RAG-database."""
+```
 ## Licentie 📜
-
+**MIT License**
-Open source, vrij om te gebruiken en aan te passen onder MIT licentie.
+- Vrij om te gebruiken en aanpassen.
-
+  *Clausule*: "Permission to use, copy and modify this software is granted..."