LogWhispererAI/README.md

LogWhispererAI 🌌 aka Sacchi's Server Sentinel

UVP: Il DevOps tascabile che traduce i crash del tuo server e ti dice l'esatto comando per risolverli in sicurezza, senza farti perdere ore su StackOverflow.

🎯 Visione del Progetto

LogWhispererAI trasforma i log di sistema e database spesso incomprensibili in alert azionabili descritti in "plain language". È pensato per piccole web agency e freelance che gestiscono infrastrutture (AWS, DigitalOcean, VPS) senza avere un sistemista senior dedicato.

🚀 Stato di Sviluppo

Feature	Stato	Sprint
✅ Log Ingestion Script	Completato	Sprint 1
✅ AI Processing Pipeline	Completato	Sprint 2
✅ Alerting (Telegram)	Completato	Sprint 2
🚧 Landing Page & Onboarding	In corso (~80%)	Sprint 3

Funzionalità MVP

• Log Ingestion ✅: Script Bash leggero per il monitoraggio (tail -f) di log critici (syslog, nginx, postgres). Invia payload JSON via HTTP POST a webhook. Script disponibili in scripts/.

• AI Processing Pipeline ✅: Workflow n8n completo che riceve log via webhook, valida HMAC, analizza con OpenRouter (GPT-4o-mini) e restituisce JSON con analisi e comando risolutivo. Workflow in workflows/logwhisperer_ingest.json.

• Alerting Umano ✅: Notifiche su Telegram con sintesi del problema, severità e comando esatto. Configurazione in docs/telegram_setup.md.

• Landing Page 🚧: Interfaccia web React + Vite + Tailwind CSS con Hero, Problem/Solution, How It Works, e Demo Interattiva. In sviluppo in frontend/.

🛠️ Stack Tecnologico Core Logic: Python 3.12+ (in venv) Automation: n8n (self-hosted) Database: Supabase / PostgreSQL AI: GPT-4o-mini / Claude 3.5 Sonnet Agentic Dev: OpenCode.ai

🛠️ Setup per lo Sviluppo

Il progetto segue una metodologia Spec-Driven e TDD (Test-Driven Development).

Prerequisiti

• Python 3.12 o superiore
• Bash 4.0+
• curl (GNU coreutils)
• Node.js 18+ (per i MCP servers e frontend)
• npm 9+ (per il frontend)

Clone e setup

# Clone
git clone https://github.com/LucaSacchiNet/LogWhispererAI.git
cd LogWhispererAI

# Ambiente virtuale
python3 -m venv venv
source venv/bin/activate

# Installazione dipendenze
pip install -r requirements.txt

Configurazione MCP (OpenCode.ai)

Il progetto utilizza tre MCP (Model Context Protocol) servers per estendere le capacità dell'agente AI:

1. sequential-thinking - Problem solving strutturato
2. context7 - Recupero documentazione contestuale delle librerie
3. n8n - Integrazione con workflow automation

La configurazione è già presente in .opencode/opencode.json. Per utilizzarla:

# Assicurati di avere npx installato
npm install -g npx

# Avvia OpenCode
opencode

Nota sulla sicurezza: Le credenziali n8n sono configurate nel file .opencode/opencode.json. Non committare mai questo file con credenziali di produzione.

Eseguire i Test

# Attiva l'ambiente virtuale
source venv/bin/activate

# Esegui tutti i test
pytest tests/test_logwhisperer.py -v

# Test con coverage (opzionale)
pytest tests/test_logwhisperer.py -v --tb=short

Usare lo Script di Log Ingestion

# Installazione (interattiva)
./scripts/install.sh

# Verifica configurazione
./scripts/logwhisperer.sh --validate

# Test pattern matching
./scripts/logwhisperer.sh --dry-run --test-line "FATAL: database error"

# Avvio monitoraggio
./scripts/logwhisperer.sh --config /etc/logwhisperer/config.env

Sviluppo Frontend (Landing Page)

Il progetto include una landing page moderna costruita con React, Vite e Tailwind CSS.

# Entra nella directory frontend
cd frontend

# Installa le dipendenze (prima volta)
npm install

# Avvia il server di sviluppo
npm run dev

# Build per produzione
npm run build

# Preview della build
npm run preview

Stack Frontend:

• React 18 + TypeScript - UI library con type safety
• Vite - Build tool veloce con HMR
• Tailwind CSS - Utility-first CSS framework
• PostCSS + Autoprefixer - Processing CSS

La landing page sarà disponibile su http://localhost:5173 durante lo sviluppo.

Nota sulla Demo Interattiva: La sezione "Demo Interattiva" nella landing page utilizza dati mock statici per scopi dimostrativi. Non effettua chiamate API reali a OpenRouter o al backend. I log di esempio e le relative analisi sono predefiniti nel codice frontend. Per una demo funzionante con AI reale, è necessario implementare un backend sicuro (vedi docs/roadmap_ideas.md).

Sviluppo con Docker (Consigliato)

Per un ambiente di sviluppo isolato e consistente, utilizza Docker Compose:

# Avvia il container di sviluppo
docker compose up -d

# La landing page sarà disponibile su http://localhost:5173
# Modifica i file in frontend/src/ e vedi le modifiche in tempo reale (HMR)

# Visualizza i log
docker compose logs -f frontend

# Ferma il container
docker compose down

Vantaggi Docker:

• Ambiente isolato e riproducibile
• Hot Module Replacement (HMR) funzionante
• Nessun conflitto con Node.js installato sul sistema
• Facile da condividere con il team

Stack Frontend:

• React 18 + TypeScript - UI library con type safety
• Vite - Build tool veloce con HMR
• Tailwind CSS - Utility-first CSS framework
• PostCSS + Autoprefixer - Processing CSS

🤖 Agenti AI (OpenCode.ai)

Il progetto utilizza uno staff di agenti specializzati definiti in AGENTS.md:

Agente	Ruolo
@product-manager	Definisce roadmap e valida UVP
@tech-lead	Architettura e specifiche tecniche
@python-developer	Implementazione Python (TDD)
@bash-expert	Script Bash e ottimizzazioni
@security-auditor	Vulnerabilità e compliance
@qa-engineer	Test suite e coverage
@documentation-agent	Docs e changelog

Per avviare una sessione di sviluppo:

opencode

📜 Metodologia e Standard

• Git: Conventional Commits (feat:, fix:, docs:, test:)
• Changelog: Common Changelog standard
• Testing: Pytest per logica Python e test integrazione per script Bash
• Metodo Sacchi: Safety first, little often, double check

Documentazione

• docs/prd.md - Product Requirements Document
• docs/specs/ - Specifiche tecniche per ogni sprint
• docs/reviews/ - Project Review post-sprint
• docs/1.setup_procedure/ - Procedure di setup OpenCode.ai
• docs/sprint1_verification.md - Report verifica sprint

📁 Struttura del Progetto

LogWhispererAI/
├── AGENTS.md                    # Regole agenti e Metodo Sacchi
├── CHANGELOG.md                 # Log modifiche
├── README.md                    # Questo file
├── LICENSE.md                   # Licenza proprietaria
├── requirements.txt             # Dipendenze Python (pytest, requests)
├── docs/
│   ├── prd.md                   # Product Requirements Document
│   ├── specs/
│   │   └── ingestion_script.md  # Specifica tecnica Sprint 1
│   ├── reviews/
│   │   └── sprint1_review.md    # Project Review Sprint 1
│   ├── 1.setup_procedure/       # Setup OpenCode.ai
│   │   ├── setup.md             # Procedura setup
│   │   └── agents.md            # Configurazione agenti
│   └── sprint1_verification.md  # Report verifica
├── scripts/
│   ├── logwhisperer.sh          # Script principale
│   └── install.sh               # Script installazione
├── tests/
│   ├── __init__.py
│   └── test_logwhisperer.py     # Test suite Python
├── tools/
│   └── fake-backend/            # Mock API server per sviluppo frontend
│       ├── server.js            # Server Express mock
│       ├── Dockerfile           # Containerizzazione
│       └── README.md            # Documentazione tool
└── .opencode/
    ├── opencode.json            # Configurazione MCP servers
    ├── agents/                  # Configurazioni agenti individuali
    │   ├── tech-lead.md
    │   ├── product-manager.md
    │   ├── python-developer.md
    │   ├── bash-expert.md
    │   ├── security-auditor.md
    │   ├── qa-engineer.md
    │   ├── documentation-agent.md
    │   ├── n8n_specialist_agent.md
    │   └── context_auditor_agent.md
    └── skills/                  # Playbook condivisi
        ├── TDD_Python_Specialist/
        ├── Git_and_Changelog/
        ├── n8n_automation_mastery/
        └── context7_documentation_retrivial/

🛠️ Tools di Sviluppo

Fake Backend (Mock API)

Per sviluppare e testare il frontend senza dipendere dal backend reale:

# Avvia il mock API server
cd tools/fake-backend
npm install
node server.js

# Oppure con Docker
docker compose up fake-backend -d

Endpoint: http://localhost:3000/api/analyze

Simula le risposte AI con delay di 1.5s. Utile per:

• Sviluppo UI offline
• Testing senza costi API
• Demo senza dipendenze esterne

Vedi docs/tools_fake_backend.md per documentazione completa.

⚖️ Licenza e Note Legali

Questo software è proprietà riservata di Luca Sacchi Ricciardi.

Tutti i diritti sono riservati. Per ogni controversia derivante dall'uso o dallo sviluppo di questo software, il foro competente in via esclusiva è il Foro di Milano, Italia.

Per i dettagli completi, consultare il file LICENSE.md.

👨‍💻 Autore

Luca Sacchi Ricciardi

• 🌐 Sito Web / Blog
• 📺 Canale YouTube
• 🔗 LinkedIn
• ✉️ luca@lucasacchi.net

---

LogWhispererAI - "Safety first, little often, double check"