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

170
docs/specs/ai_pipeline.md
View File

@@ -10,13 +10,13 @@
## 1. Overview
### 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
```
+-------------+ +--------------+ +-------------+ +--------------+
| Script |---->| n8n |---->| OpenAI |---->| Notifica |
| Script |---->| n8n |---->| OpenRouter |---->| Notifica |
| Bash | | Webhook | | GPT-4o | | Telegram/ |
| Ingestion | | Workflow | | -mini | | Slack |
+-------------+ +--------------+ +-------------+ +--------------+
@@ -36,7 +36,7 @@ L'AI Processing Pipeline è il cuore intelligente di LogWhisperer AI. Trasforma
| Vincolo | Valore | Rationale |
|---------|--------|-----------|
| **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 |
| **Lingua** | Italiano | Target audience italiano |
| **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 |
|-----------|--------|-------------|
| **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 |
| **Temperature** | 0.3 | Deterministico, meno creativo |
| **Timeout** | 10 secondi | Buffer sopra i 5s target |
| **Response Format** | `json_object` | Forza output JSON valido |
### 3.2 Payload API
### 3.3 Payload API
```json
{
"model": "gpt-4o-mini",
"model": "openai/gpt-4o-mini",
"messages": [
{
"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 |
|---------|--------|---------------|
| Input tokens (avg) | ~500 | $0.000075 |
| Output tokens (avg) | ~200 | $0.00012 |
| **Totale/chiamata** | ~700 | **~$0.0002** |
| Chiamate/mese (stimato) | 1000 | **~$0.20/mese** |
| Input tokens (avg) | ~500 | $0.00006 |
| Output tokens (avg) | ~200 | $0.00009 |
| **Totale/chiamata** | ~700 | **~$0.00015** |
| Chiamate/mese (stimato) | 1000 | **~$0.15/mese** |
**Risparmio vs OpenAI diretto: ~25%**
#### Strategie di Contenimento
@@ -230,35 +252,57 @@ RICORDA: L'utente potrebbe essere non-tecnico. Spiega in italiano semplice.`;
#### Fallback Scenarios
```javascript
// Se OpenAI non disponibile o costo eccessivo
// Se OpenRouter non disponibile o errore API
const fallbackResponse = {
sintesi: "Errore rilevato (analisi AI non disponibile)",
severita: "medium",
comando: null,
sicuro: true,
note: "Controlla manualmente il log. OpenAI API non disponibile.",
note: "Controlla manualmente il log. OpenRouter API non disponibile.",
richiede_conferma: 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.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:
```javascript
// ============================================================================
// n8n Code Node: OpenAI Processor
// n8n Code Node: OpenRouter Processor
// ============================================================================
// Input: JSON dal nodo precedente (log data)
// Output: Oggetto con analisi AI o fallback
// Provider: OpenRouter (accesso a 300+ modelli AI)
const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
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)
const SYSTEM_PROMPT = `Sei LogWhisperer AI...`;
@@ -272,9 +316,9 @@ const truncatedLog = inputData.raw_log
? inputData.raw_log.substring(0, maxLogLength)
: 'Nessun log fornito';
// Prepara payload per OpenAI
// Prepara payload per OpenRouter
const payload = {
model: "gpt-4o-mini",
model: "openai/gpt-4o-mini", // Formato OpenRouter: provider/modello
messages: [
{
role: "system",
@@ -301,16 +345,18 @@ const payload = {
// Timeout configurazione
const TIMEOUT_MS = 10000;
async function callOpenAI() {
async function callOpenRouter() {
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
const response = await fetch(OPENAI_API_URL, {
const response = await fetch(OPENROUTER_API_URL, {
method: 'POST',
headers: {
'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),
signal: controller.signal
@@ -319,22 +365,26 @@ async function callOpenAI() {
clearTimeout(timeoutId);
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 aiResponse = JSON.parse(data.choices[0].message.content);
// Aggiungi info modello usato (per tracking)
const modelUsed = data.model || 'unknown';
// Merge con dati originali
return {
...inputData,
ai_analysis: aiResponse,
ai_status: 'success',
ai_timestamp: new Date().toISOString()
ai_timestamp: new Date().toISOString(),
ai_model: modelUsed
};
} catch (error) {
console.error('OpenAI Error:', error.message);
console.error('OpenRouter Error:', error.message);
// Fallback response
return {
@@ -355,7 +405,7 @@ async function callOpenAI() {
}
// Esegui chiamata
return await callOpenAI();
return await callOpenRouter();
```
### 4.2 Configurazione Environment Variables
@@ -363,11 +413,20 @@ return await callOpenAI();
Aggiungere in n8n (Settings -> Environment):
```bash
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_TIMEOUT=10000
OPENAI_MAX_TOKENS=500
# OpenRouter Configuration
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx
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
@@ -431,7 +490,7 @@ function validateAIResponse(response) {
| 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" |
| **Rate Limiting** | Troppe richieste | Queue + retry | "Analisi in coda" |
| **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)
```javascript
// Pattern da rimuovere prima di inviare a OpenAI
// Pattern da rimuovere prima di inviare ad OpenRouter/AI
const SENSITIVE_PATTERNS = [
/password[=:]\s*\S+/gi,
/passwd[=:]\s*\S+/gi,
@@ -524,7 +583,7 @@ function sanitizeLog(log) {
}
```
#### Flag API OpenAI
#### Flag API OpenRouter
```json
{
@@ -602,11 +661,11 @@ function validateCommandSafety(command) {
- [ ] **Formato JSON**: Risposta sempre valida e parsabile
- [ ] **Performance**: 95% delle risposte < 5 secondi
- [ ] **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)
- [ ] **Lingua**: Output sempre in italiano comprensibile
- [ ] **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
---
@@ -674,7 +733,7 @@ function validateCommandSafety(command) {
- Nessun comando distruttivo suggerito
#### TC-005: API Timeout
**Test:** Simulare timeout OpenAI
**Test:** Simulare timeout OpenRouter
**Expected:** Fallback con `ai_status` = "fallback"
### 9.2 Test Automation
@@ -686,26 +745,26 @@ import json
class TestAIPipeline:
def test_oom_response(self, openai_client):
def test_oom_response(self, openrouter_client):
log = "OutOfMemoryError: Java heap space"
response = openai_client.analyze(log)
response = openrouter_client.analyze(log)
assert response["severita"] == "critical"
assert "memoria" in response["sintesi"].lower()
assert response["sicuro"] == True
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"
response = openai_client.analyze(log)
response = openrouter_client.analyze(log)
dangerous = ["rm -rf", "mkfs", "dd if=/dev/zero"]
for cmd in dangerous:
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"
response = openai_client.analyze(log)
response = openrouter_client.analyze(log)
required = ["sintesi", "severita", "comando", "sicuro", "note", "richiede_conferma"]
for field in required:
@@ -851,8 +910,9 @@ class TestAIPipeline:
## 11. Implementation Checklist
### Pre-Implementazione
- [ ] Verificare API key OpenAI configurata in n8n
- [ ] Confermare quota API sufficiente
- [ ] Registrarsi su openrouter.ai e ottenere API key
- [ ] Configurare OPENROUTER_API_KEY in n8n
- [ ] Verificare quota credits su OpenRouter (minimo $5)
- [ ] Review system prompt con team sicurezza
### Implementazione
@@ -873,11 +933,17 @@ class TestAIPipeline:
## 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/)
- [GPT-4o-mini Pricing](https://openai.com/pricing)
- [OpenRouter Pricing](https://openrouter.ai/models)
- [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:**