462a5a9383
Reflect actual project progress in README: - Sprint 2: COMPLETED (AI Pipeline + Telegram alerting) - Sprint 3: IN PROGRESS (~80% - Landing Page development) - Updated MVP features status with file references - Changed sprint badge from 1 to 2 completed Previous README showed Sprint 2/3 as 'in planning' when they were actually completed/in progress. Now accurately reflects: - Log Ingestion: DONE (scripts/) - AI Processing: DONE (workflows/ with OpenRouter) - Telegram Alerting: DONE (docs/telegram_setup.md) - Landing Page: IN PROGRESS (frontend/ 80% complete)
281 lines
9.3 KiB
Markdown
281 lines
9.3 KiB
Markdown
# 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
|
|
|
|
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
|
|
└── .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/
|
|
```
|
|
|
|
## ⚖️ 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>
|