Bash4LLM+: 가볍고 의존성 없는 LLM API Bash 래퍼

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 Tip ⏩ 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 Flag Argomento Effetto --refresh-models , --refresh-model no Aggiorna la lista modelli (richiede API key). --list-models no Stampa lista modelli (formato interattivo). --list-models-raw no Stampa lista modelli in formato raw (una riga per modello). --list-providers no Stampa lista provider. --list-providers-raw no Stampa provider in formato raw. --set-default <model> sì Imposta modello di default persistente per il provider attivo. -m <model> , --model <model> sì Imposta modello per questa esecuzione. --provider <name> sì Imposta provider da CLI. --provider no Se senza argomento → apre selezione interattiva. Input (file, JSON, template, batch) Flag Argomento Effetto -f <file> sì Aggiunge file a FILE_INPUTS . --json-input <json> sì Imposta input JSON (formato OpenAI-like). --template <name> sì Applica template da BASH4LLM_TEMPLATES_DIR . --batch <file> sì Esegue richieste batch (una riga = un prompt). Sessioni Flag Argomento Effetto --session <id> sì Abilita sessione con ID specifico. --session-window [n] opzionale Imposta finestra sessione (default 10 se non fornito). --init-session si Inizializza in sicurezza una sessione vuota (creando i file NDJSON e i metadati) e la registra nell'indice globale delle sessioni, senza effettuare chiamate API. Richiede l'uso congiunto di --session <id> . Parametri modello / generazione Flag Argomento Effetto --system <text> sì Imposta system prompt. --ture <n> sì Imposta parametro temperatura (da 0.0 a 2.0, alias canonico). --temperature <n> sì Alias di --ture . --max <n> sì Imposta max token. Output e salvataggio Flag Argomento Effetto --save no Forza salvataggio output. --nosave no Disabilita salvataggio. --out <path> sì Percorso file/directory output. --threshold <n> sì Soglia dimensione in byte per salvataggio automatico (default: 1000). --json no Output JSON raw integro. --pretty no Output JSON formattato. --text no Output testuale standard estratto (comportamento predefinito). --raw no Output testuale grezzo escludendo separazioni finali. Modalità operative Flag Argomento Effetto --dry-run no Nessuna chiamata API reale (comportamento simulato). --quiet no Riduce l'output non necessario e sopprime i titoli su TTY. --stream no Streaming asincrono attivo. --no-stream no Disattiva streaming asincrono. --chat no Modalità chat interattiva REPL. --bootstrap-only no Esegue solo validazione percorsi/lock e termina. Configurazione e diagnostica Flag Argomento Effetto --show-config no Mostra configurazione completa attiva. --diagnostics no Esegue diagnostica completa del sistema. --version no Stampa versione dello script e termina. -h , --help no Mostra help interattivo formattato da file. Installazione extras Flag Argomento Effetto --install-extras opzionale Installa extras; può accettare directory sorgente. --install-extras=<dir> sì Installa extras da directory sorgente specifica. Terminazione parsing Flag Effetto -- Termina parsing opzioni. -* Opzione sconosciuta → errore. * Argomento posizionale → aggiunto a ARGS . 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 -m/--model model.$PROVIDER auto‑selezione provider ( auto_select_model_<provider> ) prima voce della whitelist ( models.txt ) 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, edg