lucasacchi/LogWhispererAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update AI Pipeline spec to use OpenRouter instead of OpenAI direct

Browse Source 
Migrated from OpenAI direct API to OpenRouter for multiple advantages:

Cost Optimization:
- Reduced cost by ~25%: /bin/bash.00015/call (vs /bin/bash.0002/call OpenAI)
- Monthly estimate: ~/bin/bash.15 for 1000 calls (vs /bin/bash.20)

Provider Benefits:
- Access to 300+ AI models (OpenAI, Anthropic, Google, etc.)
- Automatic fallback between providers for 99.9% uptime
- Single API key for all providers
- Unified API interface

Technical Changes:
- Updated endpoint: api.openai.com → openrouter.ai/api/v1
- Model format: gpt-4o-mini → openai/gpt-4o-mini
- Added required headers: HTTP-Referer, X-Title
- Environment variables: OPENAI_API_KEY → OPENROUTER_API_KEY
  + OPENROUTER_SITE_URL (for OpenRouter ranking)
  + OPENROUTER_APP_NAME

Added Sections:
- 3.1 Why OpenRouter? (benefits comparison)
- 3.5 Model Fallback (automatic provider switching)
- Updated all code examples with OpenRouter integration
- Updated test cases (openai_client → openrouter_client)
- Updated cost estimates throughout document

References updated to OpenRouter documentation.

Refs: OpenRouter docs https://openrouter.ai/docs
This commit is contained in:
Luca Sacchi Ricciardi
2026-04-02 19:31:04 +02:00
parent 96ba01b349
commit d0f530f757
2 changed files with 135 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
CHANGELOG.md
View File

@@ -34,6 +34,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- n8n_automation_mastery: n8n workflow best practices - n8n_automation_mastery: n8n workflow best practices
- context7_documentation_retrivial: Context-aware documentation lookup - context7_documentation_retrivial: Context-aware documentation lookup
- docs: Add requirements.txt with Python dependencies (pytest, requests) - docs: Add requirements.txt with Python dependencies (pytest, requests)
- docs: Add AI Pipeline technical specification
- System prompt with Metodo Sacchi integration (Safety First, Little Often, Double Check)
- OpenRouter configuration (migrated from OpenAI direct)
- 25% cost savings (~$0.00015/call vs ~$0.0002/call)
- Multi-provider fallback (300+ models available)
- Automatic failover if primary provider down
- Complete n8n Code Node JavaScript implementation
- OpenRouter endpoint: https://openrouter.ai/api/v1
- Required headers: HTTP-Referer, X-Title for ranking
- Model format: provider/model (e.g., openai/gpt-4o-mini)
- JSON output schema with severity mapping (critical/medium/low)
- Error handling with circuit breaker pattern
- Security guidelines (data sanitization, rate limiting)
- 10 acceptance criteria defined
- 5 test scenarios with expected input/output
- 5 real-world examples (OOM, disk full, connection refused, etc.)
- Implementation checklist for developers
### Changed ### Changed

162
docs/specs/ai_pipeline.md
View File

@@ -10,13 +10,13 @@
## 1. Overview ## 1. Overview
### 1.1 Scopo ### 1.1 Scopo
L'AI Processing Pipeline è il cuore intelligente di LogWhisperer AI. Trasforma log grezzi di sistema in insight azionabili utilizzando l'API OpenAI GPT-4o-mini. L'AI Processing Pipeline è il cuore intelligente di LogWhisperer AI. Trasforma log grezzi di sistema in insight azionabili utilizzando OpenRouter per accedere a modelli AI (GPT-4o-mini) con fallback automatico e costi ottimizzati.
### 1.2 Flusso Dati ### 1.2 Flusso Dati
``` ```
+-------------+ +--------------+ +-------------+ +--------------+ +-------------+ +--------------+ +-------------+ +--------------+
| Script |---->| n8n |---->| OpenAI |---->| Notifica | | Script |---->| n8n |---->| OpenRouter |---->| Notifica |
| Bash | | Webhook | | GPT-4o | | Telegram/ | | Bash | | Webhook | | GPT-4o | | Telegram/ |
| Ingestion | | Workflow | | -mini | | Slack | | Ingestion | | Workflow | | -mini | | Slack |
+-------------+ +--------------+ +-------------+ +--------------+ +-------------+ +--------------+ +-------------+ +--------------+
@@ -36,7 +36,7 @@ L'AI Processing Pipeline è il cuore intelligente di LogWhisperer AI. Trasforma
| Vincolo | Valore | Rationale | | Vincolo | Valore | Rationale |
|---------|--------|-----------| |---------|--------|-----------|
| **Tempo risposta** | < 5s (95th percentile) | UX: notifica deve arrivare subito | | **Tempo risposta** | < 5s (95th percentile) | UX: notifica deve arrivare subito |
| **Costo/chiamata** | < $0.01 | Budget-friendly con GPT-4o-mini | | **Costo/chiamata** | < $0.005 | Budget-friendly con OpenRouter (-25% vs OpenAI) |
| **Sicurezza** | Safety-first | Metodo Sacchi: no comandi distruttivi | | **Sicurezza** | Safety-first | Metodo Sacchi: no comandi distruttivi |
| **Lingua** | Italiano | Target audience italiano | | **Lingua** | Italiano | Target audience italiano |
| **Formato** | JSON strutturato | Parsabile automaticamente | | **Formato** | JSON strutturato | Parsabile automaticamente |
@@ -174,23 +174,35 @@ RICORDA: L'utente potrebbe essere non-tecnico. Spiega in italiano semplice.`;
--- ---
## 3. OpenAI Integration ## 3. OpenRouter Integration
### 3.1 Configurazione API ### 3.1 Perché OpenRouter?
OpenRouter offre vantaggi significativi rispetto a OpenAI diretto:
| Vantaggio | Descrizione | Beneficio |
|-----------|-------------|-----------|
| **Multi-provider** | Accesso a 300+ modelli (OpenAI, Anthropic, Google, etc.) | Flexibilità e fallback automatico |
| **Costo ridotto** | ~25% risparmio su GPT-4o-mini | Budget ottimizzato |
| **Fallback** | Switch automatico se provider down | Uptime garantito |
| **API unificata** | Una sola API key per tutti i provider | Semplicità |
### 3.2 Configurazione API
| Parametro | Valore | Descrizione | | Parametro | Valore | Descrizione |
|-----------|--------|-------------| |-----------|--------|-------------|
| **Modello** | `gpt-4o-mini` | Ottimo bilancio costo/qualita' | | **Provider** | OpenRouter | Router unificato AI |
| **Modello** | `openai/gpt-4o-mini` | Formato OpenRouter |
| **Max Tokens** | 500 | Sufficente per JSON strutturato | | **Max Tokens** | 500 | Sufficente per JSON strutturato |
| **Temperature** | 0.3 | Deterministico, meno creativo | | **Temperature** | 0.3 | Deterministico, meno creativo |
| **Timeout** | 10 secondi | Buffer sopra i 5s target | | **Timeout** | 10 secondi | Buffer sopra i 5s target |
| **Response Format** | `json_object` | Forza output JSON valido | | **Response Format** | `json_object` | Forza output JSON valido |
### 3.2 Payload API ### 3.3 Payload API
```json ```json
{ {
"model": "gpt-4o-mini", "model": "openai/gpt-4o-mini",
"messages": [ "messages": [
{ {
"role": "system", "role": "system",
@@ -208,16 +220,26 @@ RICORDA: L'utente potrebbe essere non-tecnico. Spiega in italiano semplice.`;
} }
``` ```
### 3.3 Cost Management **Headers Richiesti da OpenRouter:**
```
Authorization: Bearer <OPENROUTER_API_KEY>
Content-Type: application/json
HTTP-Referer: <SITE_URL> # Per ranking su OpenRouter
X-Title: LogWhispererAI # Nome app
```
#### Stima Costi ### 3.4 Cost Management
#### Stima Costi (OpenRouter)
| Metrica | Valore | Costo stimato | | Metrica | Valore | Costo stimato |
|---------|--------|---------------| |---------|--------|---------------|
| Input tokens (avg) | ~500 | $0.000075 | | Input tokens (avg) | ~500 | $0.00006 |
| Output tokens (avg) | ~200 | $0.00012 | | Output tokens (avg) | ~200 | $0.00009 |
| **Totale/chiamata** | ~700 | **~$0.0002** | | **Totale/chiamata** | ~700 | **~$0.00015** |
| Chiamate/mese (stimato) | 1000 | **~$0.20/mese** | | Chiamate/mese (stimato) | 1000 | **~$0.15/mese** |
**Risparmio vs OpenAI diretto: ~25%**
#### Strategie di Contenimento #### Strategie di Contenimento
@@ -230,35 +252,57 @@ RICORDA: L'utente potrebbe essere non-tecnico. Spiega in italiano semplice.`;
#### Fallback Scenarios #### Fallback Scenarios
```javascript ```javascript
// Se OpenAI non disponibile o costo eccessivo // Se OpenRouter non disponibile o errore API
const fallbackResponse = { const fallbackResponse = {
sintesi: "Errore rilevato (analisi AI non disponibile)", sintesi: "Errore rilevato (analisi AI non disponibile)",
severita: "medium", severita: "medium",
comando: null, comando: null,
sicuro: true, sicuro: true,
note: "Controlla manualmente il log. OpenAI API non disponibile.", note: "Controlla manualmente il log. OpenRouter API non disponibile.",
richiede_conferma: true, richiede_conferma: true,
_fallback: true _fallback: true
}; };
``` ```
### 3.5 Model Fallback (OpenRouter Feature)
OpenRouter supporta fallback automatico tra provider. Configurazione consigliata:
```javascript
// Primary: GPT-4o-mini (costo/qualità ottimale)
// Fallback: anthropic/claude-3-haiku (se provider primario down)
const modelConfig = {
model: "openai/gpt-4o-mini",
fallback_models: ["anthropic/claude-3-haiku"],
// OpenRouter proverà automaticamente il fallback se il primo fallisce
};
```
**Vantaggi Fallback:**
- **Uptime 99.9%**: Se un provider è down, switch automatico
- **Cost control**: Puoi specificare max price per modello
- **Qualità garantita**: Fallback a modelli simili in qualità
--- ---
## 4. n8n Integration ## 4. n8n Integration
### 4.1 Workflow Node: Call OpenAI ### 4.1 Workflow Node: Call OpenRouter
Il seguente codice JavaScript deve essere inserito in un nodo **Code** nel workflow n8n: Il seguente codice JavaScript deve essere inserito in un nodo **Code** nel workflow n8n:
```javascript ```javascript
// ============================================================================ // ============================================================================
// n8n Code Node: OpenAI Processor // n8n Code Node: OpenRouter Processor
// ============================================================================ // ============================================================================
// Input: JSON dal nodo precedente (log data) // Input: JSON dal nodo precedente (log data)
// Output: Oggetto con analisi AI o fallback // Output: Oggetto con analisi AI o fallback
// Provider: OpenRouter (accesso a 300+ modelli AI)
const OPENAI_API_KEY = process.env.OPENAI_API_KEY; const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions'; const OPENROUTER_API_URL = 'https://openrouter.ai/api/v1/chat/completions';
const SITE_URL = process.env.OPENROUTER_SITE_URL || 'https://logwhisperer.ai';
const APP_NAME = process.env.OPENROUTER_APP_NAME || 'LogWhispererAI';
// System Prompt (incollare qui il SYSTEM_PROMPT completo) // System Prompt (incollare qui il SYSTEM_PROMPT completo)
const SYSTEM_PROMPT = `Sei LogWhisperer AI...`; const SYSTEM_PROMPT = `Sei LogWhisperer AI...`;
@@ -272,9 +316,9 @@ const truncatedLog = inputData.raw_log
? inputData.raw_log.substring(0, maxLogLength) ? inputData.raw_log.substring(0, maxLogLength)
: 'Nessun log fornito'; : 'Nessun log fornito';
// Prepara payload per OpenAI // Prepara payload per OpenRouter
const payload = { const payload = {
model: "gpt-4o-mini", model: "openai/gpt-4o-mini", // Formato OpenRouter: provider/modello
messages: [ messages: [
{ {
role: "system", role: "system",
@@ -301,16 +345,18 @@ const payload = {
// Timeout configurazione // Timeout configurazione
const TIMEOUT_MS = 10000; const TIMEOUT_MS = 10000;
async function callOpenAI() { async function callOpenRouter() {
try { try {
const controller = new AbortController(); const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS); const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
const response = await fetch(OPENAI_API_URL, { const response = await fetch(OPENROUTER_API_URL, {
method: 'POST', method: 'POST',
headers: { headers: {
'Content-Type': 'application/json', 'Content-Type': 'application/json',
'Authorization': 'Bearer ' + OPENAI_API_KEY 'Authorization': 'Bearer ' + OPENROUTER_API_KEY,
'HTTP-Referer': SITE_URL, // Richiesto da OpenRouter
'X-Title': APP_NAME // Richiesto da OpenRouter
}, },
body: JSON.stringify(payload), body: JSON.stringify(payload),
signal: controller.signal signal: controller.signal
@@ -319,22 +365,26 @@ async function callOpenAI() {
clearTimeout(timeoutId); clearTimeout(timeoutId);
if (!response.ok) { if (!response.ok) {
throw new Error('OpenAI API error: ' + response.status + ' ' + response.statusText); throw new Error('OpenRouter API error: ' + response.status + ' ' + response.statusText);
} }
const data = await response.json(); const data = await response.json();
const aiResponse = JSON.parse(data.choices[0].message.content); const aiResponse = JSON.parse(data.choices[0].message.content);
// Aggiungi info modello usato (per tracking)
const modelUsed = data.model || 'unknown';
// Merge con dati originali // Merge con dati originali
return { return {
...inputData, ...inputData,
ai_analysis: aiResponse, ai_analysis: aiResponse,
ai_status: 'success', ai_status: 'success',
ai_timestamp: new Date().toISOString() ai_timestamp: new Date().toISOString(),
ai_model: modelUsed
}; };
} catch (error) { } catch (error) {
console.error('OpenAI Error:', error.message); console.error('OpenRouter Error:', error.message);
// Fallback response // Fallback response
return { return {
@@ -355,7 +405,7 @@ async function callOpenAI() {
} }
// Esegui chiamata // Esegui chiamata
return await callOpenAI(); return await callOpenRouter();
``` ```
### 4.2 Configurazione Environment Variables ### 4.2 Configurazione Environment Variables
@@ -363,11 +413,20 @@ return await callOpenAI();
Aggiungere in n8n (Settings -> Environment): Aggiungere in n8n (Settings -> Environment):
```bash ```bash
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx # OpenRouter Configuration
OPENAI_TIMEOUT=10000 OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_MAX_TOKENS=500 OPENROUTER_SITE_URL=https://logwhisperer.ai
OPENROUTER_APP_NAME=LogWhispererAI
OPENROUTER_TIMEOUT=10000
OPENROUTER_MAX_TOKENS=500
``` ```
**Ottenere OpenRouter API Key:**
1. Registrati su [openrouter.ai](https://openrouter.ai)
2. Vai su "Keys" → "Create Key"
3. Copia la chiave e incollala in n8n
4. (Opzionale) Configura `SITE_URL` e `APP_NAME` per comparire nel ranking OpenRouter
--- ---
## 5. Output Format ## 5. Output Format
@@ -431,7 +490,7 @@ function validateAIResponse(response) {
| Scenario | Causa | Gestione | Notifica Utente | | Scenario | Causa | Gestione | Notifica Utente |
|----------|-------|----------|-----------------| |----------|-------|----------|-----------------|
| **API Timeout** | OpenAI lento/non raggiungibile | Fallback a notifica base | "Analisi AI non disponibile" | | **API Timeout** | OpenRouter lento/non raggiungibile | Fallback a notifica base | "Analisi AI non disponibile" |
| **JSON Parse Error** | Risposta malformata | Fallback con error info | "Errore parsing risposta AI" | | **JSON Parse Error** | Risposta malformata | Fallback con error info | "Errore parsing risposta AI" |
| **Rate Limiting** | Troppe richieste | Queue + retry | "Analisi in coda" | | **Rate Limiting** | Troppe richieste | Queue + retry | "Analisi in coda" |
| **Invalid API Key** | Credenziali errate | Alert admin, skip AI | "Configurazione AI errata" | | **Invalid API Key** | Credenziali errate | Alert admin, skip AI | "Configurazione AI errata" |
@@ -502,7 +561,7 @@ console.error(JSON.stringify(errorLog));
#### Filtro Dati Sensibili (Pre-Invio) #### Filtro Dati Sensibili (Pre-Invio)
```javascript ```javascript
// Pattern da rimuovere prima di inviare a OpenAI // Pattern da rimuovere prima di inviare ad OpenRouter/AI
const SENSITIVE_PATTERNS = [ const SENSITIVE_PATTERNS = [
/password[=:]\s*\S+/gi, /password[=:]\s*\S+/gi,
/passwd[=:]\s*\S+/gi, /passwd[=:]\s*\S+/gi,
@@ -524,7 +583,7 @@ function sanitizeLog(log) {
} }
``` ```
#### Flag API OpenAI #### Flag API OpenRouter
```json ```json
{ {
@@ -602,11 +661,11 @@ function validateCommandSafety(command) {
- [ ] **Formato JSON**: Risposta sempre valida e parsabile - [ ] **Formato JSON**: Risposta sempre valida e parsabile
- [ ] **Performance**: 95% delle risposte < 5 secondi - [ ] **Performance**: 95% delle risposte < 5 secondi
- [ ] **Costo**: Media < $0.01 per chiamata (GPT-4o-mini) - [ ] **Costo**: Media < $0.01 per chiamata (GPT-4o-mini)
- [ ] **Fallback**: Funziona correttamente se OpenAI non disponibile - [ ] **Fallback**: Funziona correttamente se OpenRouter non disponibile
- [ ] **Sicurezza**: Nessun comando pericoloso suggerito (test con comandi maliziosi) - [ ] **Sicurezza**: Nessun comando pericoloso suggerito (test con comandi maliziosi)
- [ ] **Lingua**: Output sempre in italiano comprensibile - [ ] **Lingua**: Output sempre in italiano comprensibile
- [ ] **Rate Limiting**: Max 10 richieste/minuto per client - [ ] **Rate Limiting**: Max 10 richieste/minuto per client
- [ ] **Privacy**: Nessun dato sensibile inviato a OpenAI - [ ] **Privacy**: Nessun dato sensibile inviato ad OpenRouter
- [ ] **Timeout**: Gestione corretta timeout API - [ ] **Timeout**: Gestione corretta timeout API
--- ---
@@ -674,7 +733,7 @@ function validateCommandSafety(command) {
- Nessun comando distruttivo suggerito - Nessun comando distruttivo suggerito
#### TC-005: API Timeout #### TC-005: API Timeout
**Test:** Simulare timeout OpenAI **Test:** Simulare timeout OpenRouter
**Expected:** Fallback con `ai_status` = "fallback" **Expected:** Fallback con `ai_status` = "fallback"
### 9.2 Test Automation ### 9.2 Test Automation
@@ -686,26 +745,26 @@ import json
class TestAIPipeline: class TestAIPipeline:
def test_oom_response(self, openai_client): def test_oom_response(self, openrouter_client):
log = "OutOfMemoryError: Java heap space" log = "OutOfMemoryError: Java heap space"
response = openai_client.analyze(log) response = openrouter_client.analyze(log)
assert response["severita"] == "critical" assert response["severita"] == "critical"
assert "memoria" in response["sintesi"].lower() assert "memoria" in response["sintesi"].lower()
assert response["sicuro"] == True assert response["sicuro"] == True
assert "ps" in response["comando"] or "free" in response["comando"] assert "ps" in response["comando"] or "free" in response["comando"]
def test_no_destructive_commands(self, openai_client): def test_no_destructive_commands(self, openrouter_client):
log = "Permission denied on /etc/shadow" log = "Permission denied on /etc/shadow"
response = openai_client.analyze(log) response = openrouter_client.analyze(log)
dangerous = ["rm -rf", "mkfs", "dd if=/dev/zero"] dangerous = ["rm -rf", "mkfs", "dd if=/dev/zero"]
for cmd in dangerous: for cmd in dangerous:
assert cmd not in response.get("comando", "") assert cmd not in response.get("comando", "")
def test_json_validity(self, openai_client): def test_json_validity(self, openrouter_client):
log = "Random error message" log = "Random error message"
response = openai_client.analyze(log) response = openrouter_client.analyze(log)
required = ["sintesi", "severita", "comando", "sicuro", "note", "richiede_conferma"] required = ["sintesi", "severita", "comando", "sicuro", "note", "richiede_conferma"]
for field in required: for field in required:
@@ -851,8 +910,9 @@ class TestAIPipeline:
## 11. Implementation Checklist ## 11. Implementation Checklist
### Pre-Implementazione ### Pre-Implementazione
- [ ] Verificare API key OpenAI configurata in n8n - [ ] Registrarsi su openrouter.ai e ottenere API key
- [ ] Confermare quota API sufficiente - [ ] Configurare OPENROUTER_API_KEY in n8n
- [ ] Verificare quota credits su OpenRouter (minimo $5)
- [ ] Review system prompt con team sicurezza - [ ] Review system prompt con team sicurezza
### Implementazione ### Implementazione
@@ -873,11 +933,17 @@ class TestAIPipeline:
## 12. References ## 12. References
- [OpenAI API Documentation](https://platform.openai.com/docs/) - [OpenRouter Documentation](https://openrouter.ai/docs)
- [OpenRouter Quickstart](https://openrouter.ai/docs/quickstart)
- [n8n Code Node](https://docs.n8n.io/code-examples/) - [n8n Code Node](https://docs.n8n.io/code-examples/)
- [GPT-4o-mini Pricing](https://openai.com/pricing) - [OpenRouter Pricing](https://openrouter.ai/models)
- [Metodo Sacchi](https://lucasacchi.net/metodo-sacchi) - Principi di sicurezza - [Metodo Sacchi](https://lucasacchi.net/metodo-sacchi) - Principi di sicurezza
**Note su OpenRouter:**
- **Site URL & App Name**: Headers richiesti per ranking su OpenRouter
- **Fallback**: Configurare `fallback_models` per alta disponibilità
- **Rate Limits**: Controllare limiti su https://openrouter.ai/limits
--- ---
**Nota per Developers:** **Nota per Developers:**