3a455e48d2
- Add MCP servers documentation (n8n, context7, sequential-thinking) - Update README.md with complete project structure and requirements.txt - Transform agents.md into comprehensive agent staff catalog (9 agents) - Update CHANGELOG.md with [Unreleased] MCP entries - Fix ingestion_script.md acceptance criteria checkboxes - Add .opencode/opencode.json to .gitignore for security - Include new agent configs: n8n_specialist_agent, context_auditor_agent - Include new skill playbooks: n8n_automation, context7_documentation Security: API credentials in .opencode/opencode.json are now gitignored
216 lines
7.2 KiB
Markdown
216 lines
7.2 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 | *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).
|
|
|
|
### Prerequisiti
|
|
|
|
- **Python** 3.12 o superiore
|
|
- **Bash** 4.0+
|
|
- **curl** (GNU coreutils)
|
|
- **Node.js** 18+ (per i MCP servers)
|
|
|
|
### 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
|
|
```
|
|
|
|
|
|
## 🤖 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>
|