# 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-1%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 | *In pianificazione* | Sprint 2 |
| 🔄 Alerting (Telegram/Slack) | *In pianificazione* | Sprint 2-3 |
| 🔄 Landing Page & Onboarding | *In pianificazione* | 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.

- **AI Processing Pipeline** 🔄: Workflow su n8n che analizza i log tramite LLM (OpenAI/Anthropic) applicando il Metodo Sacchi (Safety first, little often, double check).

- **Alerting Umano** 🔄: Notifiche su Telegram/Slack con sintesi del problema, severità e comando esatto per la mitigazione.

🛠️ 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).

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

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


## 🤖 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/sprintN_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
├── docs/
│   ├── prd.md                   # Product Requirements Document
│   ├── specs/
│   │   └── ingestion_script.md  # Specifica tecnica Sprint 1
│   ├── reviews/
│   │   └── sprint1_review.md    # Project Review Sprint 1
│   └── sprint1_verification.md  # Report verifica
├── scripts/
│   ├── logwhisperer.sh          # Script principale
│   └── install.sh               # Script installazione
├── tests/
│   ├── __init__.py
│   └── test_logwhisperer.py     # Test suite Python
└── .opencode/
    ├── agents/                  # Configurazioni agenti
    └── skills/                  # Skills TDD e Git
```

## ⚖️ 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>