kamaludu/bash4llm

Source: https://github.com/kamaludu/bash4llm

Bash4LLM⁺ 🇮🇹 🇬🇧

Bash4LLM⁺ — wrapper CLI sicuro, Bash‑first e completamente auditabile per l’API Chat Completions compatibile OpenAI di Groq (ed estendibile ad altri provider).

Bash4LLM⁺ è un singolo script Bash, auto‑contenuto, leggibile e verificabile.
Scaricalo, rendilo eseguibile, esporta la tua API key e inizia subito a usarlo.

Compatibile con ambienti Unix‑like: Linux, macOS, WSL, Cygwin, Termux (Android), BSD.

Caratteristiche principali

• Lista modelli dinamica
  tramite GET https://api.groq.com/openai/v1/models
  → nessun modello hardcoded.

• Sicurezza by design
  → nessun uso di /tmp, nessun eval, permessi restrittivi, validazione provider avanzata.

• Struttura modulare a sezioni
  → PRECORE_BOOT, PRECORE_RUN, PROVIDER, CORE_SETUP, CORE_PROVIDER.

• Sistema di Stato UI (ui_state)
  → il CORE espone costantemente metadati in formato JSON atomico per l’integrazione con GUI o strumenti esterni (es. Home Assistant).

• Streaming e non‑streaming
  → output in tempo reale o completo a fine risposta.

• Salvataggio automatico
  → per output lunghi oltre una soglia configurabile.

• Gestione modelli avanzata
  → refresh, lista, default persistente, whitelist dinamica, auto‑selezione.

• Extras opzionali
  → provider aggiuntivi (come Gemini, Hugging Face, Mistral), template, documentazione, strumenti di sicurezza.

• Pronto per Termux / Android
  → rileva automaticamente l’ambiente Termux bypassando flock (spesso instabile o limitato a livello kernel/SELinux su Android) e devia trasparentemente la gestione della concorrenza sul robusto meccanismo di directory lock (mkdir atomico).

Modello di minaccia (versione breve)

Bash4LLM⁺ è progettato per ambienti single‑user (PC/laptop, server personali).

• I provider sono codice eseguito nella tua shell: devono risiedere in directory sicure di tua proprietà.
• Variabili come BASH4LLM_EXTRAS_DIR e BASH4LLM_TMPDIR sono considerate configurazione fidata.
• Lo script non esegue mai l’output del modello.
• I rischi TOCTOU e i limiti del parsing JSON/SSE sono mitigati e documentati.

Dettagli completi in SECURITY.

Requisiti

Bash4LLM⁺ richiede che i seguenti pacchetti (o equivalenti) siano disponibili nel PATH:

• bash
• coreutils
• findutils
• util-linux
• gawk
• curl
• jq

Installazione

⏩ FAST FORWARD (Installazione Rapida)

Esegui questi comandi nel tuo terminale per avviare subito Bash4LLM⁺:

# 1. Clona il repository (solo l'ultimo commit per massima velocità)
git clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm  

# 2. Crea una cartella di lavoro ed estrai l'eseguibile
mkdir -p bash4llm
cp repo-bash4llm/bin/bash4llm bash4llm/
chmod +x bash4llm/bash4llm

# 3. Entra nella cartella e aggiorna i modelli 
cd bash4llm 
./bash4llm --refresh-models

Lo script ti chiederà l’inserimento della tua chiave API per il provider di default (Groq): Enter API key for provider groq (env GROQ_API_KEY):

Inserisci la tua API key, poi esportala per non doverla più inserire durante la sessione:

export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxx"

Consigliato: installa gli Extras opzionali:

# 4. Installazione degli Extras
./bash4llm --install-extras ../repo-bash4llm/extras/

Usa Bash4llm ⚡

Istruzioni dettagliate in: INSTALL

In breve:

chmod +x bash4llm
export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxx"
./bash4llm --help

Extras opzionali:

./bash4llm --install-extras

Con opzioni:

• --source <dir>
• --force
• --dry-run
• installazione selettiva:
  ./bash4llm --install-extras provider1 templateA

Uso rapido

Prompt diretto:

./bash4llm "scrivi una breve poesia in italiano"

Prompt multilinea:

./bash4llm <<'EOF'
scrivi una breve poesia
in italiano
EOF

Input da file:

./bash4llm -f prompt.txt

Pipe:

echo "spiegami la relatività" | ./bash4llm

Modello specifico:

./bash4llm -m llama-3.3-70b-versatile "scrivi un saggio breve"

Dry run:

./bash4llm --dry-run "ciao"

Provider esterno (se installato):

./bash4llm --provider gemini "traduci questo"

Comandi, flag e opzioni disponibili

Modelli e provider

Input (file, JSON, template, batch)

Sessioni

Parametri modello / generazione

Output e salvataggio

Modalità operative

Configurazione e diagnostica

Installazione extras

Terminazione parsing

Configurazione e modelli

File di configurazione

• $BASH4LLM_CONFIG_DIR/config
  → parametri locali (MODEL, TURE, MAX_TOKENS, FORMAT, THRESHOLD)

• $BASH4LLM_CONFIG_DIR/model.$PROVIDER
  → modello predefinito per provider

• $MODELS_FILE
  → whitelist modelli aggiornata da --refresh-models

Precedenza selezione modello

1. -m/--model
2. model.$PROVIDER
3. auto‑selezione provider (auto_select_model_<provider>)
4. prima voce della whitelist (models.txt)
5. configurazione globale legacy config (MODEL=...)

File temporanei e output

• Nessun uso di /tmp a livello di sistema operativo condiviso.
• File temporanei isolati in directory $RUN_TMPDIR con permessi 700 (umask 077).
• File salvati con permessi 600.
• Con --out Bash4LLM⁺ crea la directory se possibile.

📁 Sistema di Stato UI (ui_state)

Bash4LLM⁺ espone metadati operativi destinati a GUI/strumenti esterni tramite file JSON atomici in:

$BASH4LLM_CONFIG_DIR/ui_state

Contiene:

• sessions/<id>.json → stato sessione (active, msg_count, last_ts)
• sessions/index.json → elenco sessioni
• last_api.json → ultimo risultato API (http_status, req_id, edgecase_detected, ecc.)
• last_history.json → ultimo salvataggio history
• provider_capabilities.json → capacità provider attivo (streaming, refresh_models)

La GUI (extra opzionale) legge solo questi file per i placeholder CGI.

📘 Memoria contestuale in Bash4LLM⁺

Bash4LLM⁺ non mantiene memoria da solo.
La memoria esiste solo se attivi una sessione tramite --session.

Ogni sessione crea un file NDJSON persistente:

$BASH4LLM_HISTORY_DIR/sessions/<session_id>.ndjson

E Bash4LLM⁺ mantiene i metadati della sessione in:

$BASH4LLM_CONFIG_DIR/ui_state/sessions/<session_id>.json

Questi metadati sono la fonte canonica per GUI/strumenti esterni.

🟩 Uso corretto di --session

./bash4llm --session chat1 "Ciao"
./bash4llm --session chat1 "Riassumi ciò che ho detto"

🟩 Uso corretto di --session-window

./bash4llm --session chat1 --session-window 10 "continua"

🟧 Regola fondamentale

Per avere memoria contestuale devi sempre includere --session <id>.

Note di sicurezza

• Nessun eval.
• Nessuna esecuzione dell’output del modello.
• Provider = codice: mantieni extras/providers sicuro.
• Variabili d’ambiente = configurazione fidata.
• TOCTOU mitigato.

Codici di uscita

Variabili principali

Licenza

Bash4LLM⁺ è distribuito sotto licenza GPL v3.
Vedi LICENSE.

Contatti

Autore: Cristian Evangelisti
Email: opensource​@​cevangel.​anonaddy.​me
Repository: https://github.com/kamaludu/bash4llm