# 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.

[![Tests](https://img.shields.io/badge/tests-12%2F12%20passing-brightgreen)]()
[![Version](https://img.shields.io/badge/version-0.1.0-blue)]()
[![Sprint](https://img.shields.io/badge/sprint-2%20completed-success)]()
[![Status](https://img.shields.io/badge/status-active%20development-orange)]()


🎯 Visione del Progetto

LogWhisperer AI 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
# 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:

```bash
# 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:
```bash
opencode
```


## 📜 Metodologia e Standard

- **Git**: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`)
- **Changelog**: [Common Changelog](https://common-changelog.org/) 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:

```bash
# 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](LICENSE.md).

## 👨‍💻 Autore

**Luca Sacchi Ricciardi**

- 🌐 [Sito Web / Blog](https://lucasacchi.net)
- 📺 [Canale YouTube](https://www.youtube.com/@lucasacchinet)
- 🔗 [LinkedIn](https://www.linkedin.com/in/lucasacchi)
- ✉️ luca@lucasacchi.net

---

<p align="center">
  <em>LogWhispererAI - "Safety first, little often, double check"</em>
</p>