adiuvAI/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Update local agent documentation to reflect changes in user_id and session_id handling; add marketing strategy document; update skills-lock.json with new Remotion best practices; update website subproject commit.

Browse Source
This commit is contained in:
Roberto Musso
2026-04-11 02:15:59 +02:00
parent bc2c76d2bb
commit 54eb863c52
84 changed files with 8825 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/llm-provider-report.html
View File

@@ -623,7 +623,7 @@
<div class="section-head reveal">
<p class="label">Architettura</p>
<h2>Funzionalit&agrave; Agentiche</h2>
<p class="subtitle">Cinque componenti AI distinti, ognuno con requisiti specifici di modello.</p>
<p class="subtitle">Sei componenti AI distinti, ognuno con requisiti specifici di modello.</p>
</div>
<div class="features-grid">
@@ -662,12 +662,23 @@
<div class="feature-card reveal">
<div class="feature-icon">&#x2699;</div>
<h3>Batch Agents</h3>
<p>Agenti schedulati per raccolta dati da filesystem locale e cloud (Gmail, Teams, Outlook). Cron-based.</p>
<h3>Background Agents</h3>
<p>Agenti schedulati per raccolta dati da filesystem locale e cloud (Gmail, Teams, Outlook). Loop tool-calling multi-turno, API Standard.</p>
<div class="feature-reqs">
<span class="req-tag">Tool Calling Multi-Turno</span>
<span class="req-tag">Output Strutturato</span>
<span class="req-tag">Tool Calling Robusto</span>
<span class="req-tag">Esecuzione Lunga</span>
<span class="req-tag">API Standard</span>
</div>
</div>
<div class="feature-card reveal">
<div class="feature-icon">&#x1f6e0;</div>
<h3>Setup Agent</h3>
<p>Journey conversazionale interattiva per configurare un agente. L&rsquo;utente risponde a domande guidate, il LLM esplora la directory e produce un <code>AgentConfig</code> JSON validato.</p>
<div class="feature-reqs">
<span class="req-tag">Conversazionale</span>
<span class="req-tag">Qualit&agrave; Linguistica</span>
<span class="req-tag">Tool Calling + Reasoning</span>
</div>
</div>
@@ -788,7 +799,8 @@
<button class="tab-btn active" data-tab="home">Home Chat</button>
<button class="tab-btn" data-tab="floating">Floating Chat</button>
<button class="tab-btn" data-tab="brief">Daily Brief</button>
<button class="tab-btn" data-tab="batch">Batch Agents</button>
<button class="tab-btn" data-tab="batch">Background Agents</button>
<button class="tab-btn" data-tab="setup">Setup Agent</button>
<button class="tab-btn" data-tab="embed">Embeddings</button>
</div>
@@ -986,10 +998,13 @@
<div class="table-wrap reveal">
<div class="table-header">
<div>
<h3>&#x2699; Batch Agents</h3>
<span class="desc">Tool Calling Robusto + Output Strutturato</span>
<h3>&#x2699; Background Agents</h3>
<span class="desc">Tool Calling Multi-Turno &mdash; API Standard (non Batch)</span>
</div>
</div>
<div style="margin: 0 0 16px; padding: 12px 18px; background: var(--warn-bg); border: 1px solid var(--warn-border); border-radius: var(--radius-sm); font-size: 0.85rem; color: var(--warn); line-height: 1.6;">
<strong>&#x26a0; Nota architetturale:</strong> Il Batch API dei provider LLM <em>non &egrave; compatibile</em> con gli agenti di processing (<code>unified-processor</code>, <code>cloud-processor</code>). Il loop di tool-calling (fino a 12 turni per file) richiede risultati sincroni dal client Electron via WebSocket — un round-trip interattivo che il Batch API asincrono non supporta. Usare esclusivamente <strong>API Standard</strong>, a prezzi di listino senza sconto batch.
</div>
<div class="table-scroll">
<table>
<thead>
@@ -998,24 +1013,24 @@
<tbody>
<tr style="background: rgba(52,211,153,0.04);">
<td><strong>OpenAI</strong></td>
<td><span class="model-name">GPT-4.1 (Batch)</span></td>
<td><span class="price" style="color:var(--green)">$1.00</span></td>
<td><span class="price" style="color:var(--green)">$4.00</span></td>
<td><strong>50% sconto batch</strong>, eccellente output strutturato</td>
<td><span class="model-name">GPT-4.1 Mini</span></td>
<td><span class="price" style="color:var(--green)">$0.40</span></td>
<td><span class="price" style="color:var(--green)">$1.60</span></td>
<td><strong>Ottimo rapporto qualit&agrave;/costo</strong>, tool calling affidabile, API Standard</td>
</tr>
<tr>
<td>Anthropic</td>
<td><span class="model-name">Claude Sonnet 4.6 (Batch)</span></td>
<td><span class="price">$1.50</span></td>
<td><span class="price">$7.50</span></td>
<td>50% batch, tool use superiore, 300K output</td>
<td><span class="model-name">Claude Sonnet 4.6</span></td>
<td><span class="price">$3.00</span></td>
<td><span class="price">$15.00</span></td>
<td>Miglior tool use del mercato, se qualit&agrave; &egrave; priorit&agrave; assoluta</td>
</tr>
<tr>
<td>Google</td>
<td><span class="model-name">Gemini 2.5 Pro (Batch)</span></td>
<td><span class="price">$0.625</span></td>
<td><span class="price">$5.00</span></td>
<td>50% batch, alta qualit&agrave; reasoning</td>
<td><span class="model-name">Gemini 2.5 Flash</span></td>
<td><span class="price">$0.30</span></td>
<td><span class="price">$2.50</span></td>
<td>Ottimo reasoning, tool calling affidabile, costo input molto basso</td>
</tr>
<tr>
<td>Mistral</td>
@@ -1026,10 +1041,10 @@
</tr>
<tr>
<td>Groq</td>
<td><span class="model-name">Qwen3 32B (Batch)</span></td>
<td><span class="price">$0.145</span></td>
<td><span class="price">$0.295</span></td>
<td>50% batch, molto economico</td>
<td><span class="model-name">Qwen3 32B</span></td>
<td><span class="price">$0.29</span></td>
<td><span class="price">$0.59</span></td>
<td>Molto economico, velocit&agrave; elevata; qualit&agrave; tool calling inferiore ai proprietari</td>
</tr>
<tr>
<td>Cerebras</td>
@@ -1044,6 +1059,72 @@
</div>
</div>
<!-- SETUP AGENT -->
<div class="tab-panel" id="tab-setup">
<div class="table-wrap reveal">
<div class="table-header">
<div>
<h3>&#x1f6e0; Setup Agent</h3>
<span class="desc">Journey Conversazionale &mdash; Qualit&agrave; Linguistica + Reasoning</span>
</div>
</div>
<div style="margin: 0 0 16px; padding: 12px 18px; background: rgba(99,102,241,0.08); border: 1px solid rgba(99,102,241,0.25); border-radius: var(--radius-sm); font-size: 0.85rem; color: var(--accent-3); line-height: 1.6;">
<strong>&#x2139; Profilo diverso dai Background Agents:</strong> Il setup &egrave; un&rsquo;interazione <em>real-time con l&rsquo;utente</em> (3&ndash;15 turni, <code>temperature=0.4</code>). Il volume &egrave; basso (poche sessioni per utente nel tempo), quindi il costo &egrave; trascurabile anche con modelli premium. Priorit&agrave;: qualit&agrave; della conversazione e accuratezza nel produrre l&rsquo;<code>AgentConfig</code> JSON finale.
</div>
<div class="table-scroll">
<table>
<thead>
<tr><th>Provider</th><th>Modello</th><th>Input $/MTok</th><th>Output $/MTok</th><th>Motivazione</th></tr>
</thead>
<tbody>
<tr style="background: rgba(52,211,153,0.04);">
<td><strong>OpenAI</strong></td>
<td><span class="model-name">GPT-4.1</span></td>
<td><span class="price" style="color:var(--green)">$2.00</span></td>
<td><span class="price" style="color:var(--green)">$8.00</span></td>
<td><strong>Ottimo bilanciamento</strong> qualit&agrave;/costo per conversazioni guidate, JSON output affidabile</td>
</tr>
<tr>
<td>Anthropic</td>
<td><span class="model-name">Claude Sonnet 4.6</span></td>
<td><span class="price">$3.00</span></td>
<td><span class="price">$15.00</span></td>
<td>Massima qualit&agrave; conversazionale e instruction-following; costo giustificato dalla rarità delle sessioni</td>
</tr>
<tr>
<td>Google</td>
<td><span class="model-name">Gemini 2.5 Flash</span></td>
<td><span class="price">$0.30</span></td>
<td><span class="price">$2.50</span></td>
<td>Buona qualit&agrave; conversazionale a costo molto basso; opzione se si vuole contenere ogni spesa</td>
</tr>
<tr>
<td>OpenAI</td>
<td><span class="model-name">GPT-4.1 Mini</span></td>
<td><span class="price">$0.40</span></td>
<td><span class="price">$1.60</span></td>
<td>Alternativa budget; qualit&agrave; conversazionale sufficiente, JSON output meno affidabile</td>
</tr>
<tr>
<td>Mistral</td>
<td><span class="model-name">Mistral Large 3</span></td>
<td><span class="price">$2.00</span></td>
<td><span class="price">$6.00</span></td>
<td>EU data residency; buona qualit&agrave; per il setup journey</td>
</tr>
<tr>
<td>Groq / Cerebras</td>
<td class="na-cell">&mdash;</td>
<td class="na-cell">&mdash;</td>
<td class="na-cell">&mdash;</td>
<td class="na-cell">Non consigliati: qualit&agrave; conversazionale insufficiente per journey multi-turno</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<!-- EMBEDDINGS -->
<div class="tab-panel" id="tab-embed">
<div class="table-wrap reveal">
@@ -1097,14 +1178,14 @@
<div class="section-head reveal">
<p class="label">Simulazione</p>
<h2>Stima Costi Mensili per Utente</h2>
<p class="subtitle">Basata su un utilizzo tipico: 500 home, 300 floating, 210 brief, 100 batch, 1000 embeddings al mese.</p>
<p class="subtitle">Basata su un utilizzo tipico: 500 home, 300 floating, 210 brief, 100 background agent runs, 10 setup turns (≈2 sessioni), 1000 embeddings al mese.</p>
</div>
<div class="table-wrap reveal">
<div class="table-header">
<div>
<h3>Calcolo Dettagliato</h3>
<span class="desc">Token medi: Home 2K/1K &bull; Floating 500/300 &bull; Brief 1.5K/500 &bull; Batch 3K/2K &bull; Embed 500</span>
<span class="desc">Token medi: Home 2K/1K &bull; Floating 500/300 &bull; Brief 1.5K/500 &bull; Background Agent 3K/2K &bull; Setup 4K/500 &bull; Embed 500</span>
</div>
</div>
<div class="cost-bars" id="costChart">
@@ -1152,13 +1233,22 @@
<td><span class="price">$0.032 + $0.042 = $0.07</span></td>
</tr>
<tr>
<td>Batch Agents</td>
<td>Background Agents</td>
<td>OpenAI</td>
<td><span class="model-name">GPT-4.1 (Batch)</span></td>
<td><span class="model-name">GPT-4.1 Mini</span></td>
<td>100</td>
<td>300K</td>
<td>200K</td>
<td><span class="price">$0.30 + $0.80 = $1.10</span></td>
<td><span class="price">$0.12 + $0.32 = $0.44</span></td>
</tr>
<tr>
<td>Setup Agent</td>
<td>OpenAI</td>
<td><span class="model-name">GPT-4.1</span></td>
<td>10 turns</td>
<td>40K</td>
<td>5K</td>
<td><span class="price">$0.08 + $0.04 = $0.12</span></td>
</tr>
<tr>
<td>Embeddings</td>
@@ -1171,7 +1261,7 @@
</tr>
<tr style="background: var(--surface-2);">
<td colspan="6" style="text-align:right; font-weight:600; color:var(--ink);">Totale Mensile per Utente</td>
<td><span class="price" style="color:var(--green); font-size:1rem;">~$2.78</span></td>
<td><span class="price" style="color:var(--green); font-size:1rem;">~$2.24</span></td>
</tr>
</tbody>
</table>
@@ -1202,12 +1292,13 @@
<li><span class="fn">Home Chat</span> <span class="mdl">Gemini 2.5 Flash</span></li>
<li><span class="fn">Floating Chat</span> <span class="mdl">Gemini 2.5 Flash-Lite</span></li>
<li><span class="fn">Daily Brief</span> <span class="mdl">GPT-4.1 Nano</span></li>
<li><span class="fn">Batch Agents</span> <span class="mdl">GPT-4.1 Batch</span></li>
<li><span class="fn">Background Agents</span> <span class="mdl">GPT-4.1 Mini</span></li>
<li><span class="fn">Setup Agent</span> <span class="mdl">GPT-4.1</span></li>
<li><span class="fn">Embeddings</span> <span class="mdl">text-embedding-3-small</span></li>
</ul>
<div class="strategy-cost">
<span class="cost-label">Costo stimato/utente/mese</span>
<span class="cost-value highlight">~$2.78</span>
<span class="cost-value highlight">~$2.24</span>
</div>
<p class="strategy-pros"><strong>Pro:</strong> Costo ottimale, qualit&agrave; massima per feature. <strong>Contro:</strong> 2 API key da gestire (Google + OpenAI).</p>
</div>
@@ -1221,14 +1312,15 @@
<li><span class="fn">Home Chat</span> <span class="mdl">Llama 3.3 70B</span></li>
<li><span class="fn">Floating Chat</span> <span class="mdl">Llama 4 Scout</span></li>
<li><span class="fn">Daily Brief</span> <span class="mdl">Llama 3.1 8B</span></li>
<li><span class="fn">Batch Agents</span> <span class="mdl">Qwen3 32B Batch</span></li>
<li><span class="fn">Background Agents</span> <span class="mdl">Qwen3 32B</span></li>
<li><span class="fn">Setup Agent</span> <span class="mdl">GPT-4.1 Mini</span></li>
<li><span class="fn">Embeddings</span> <span class="mdl">OpenAI (esterno)</span></li>
</ul>
<div class="strategy-cost">
<span class="cost-label">Costo stimato/utente/mese</span>
<span class="cost-value" style="color:var(--blue);">~$1.05</span>
<span class="cost-value" style="color:var(--blue);">~$1.30</span>
</div>
<p class="strategy-pros"><strong>Pro:</strong> Ultra economico, velocit&agrave; record (394&ndash;840 TPS). <strong>Contro:</strong> Qualit&agrave; tool calling inferiore ai proprietari. Serve OpenAI per embeddings.</p>
<p class="strategy-pros"><strong>Pro:</strong> Ultra economico, velocit&agrave; record (394&ndash;840 TPS). <strong>Contro:</strong> Qualit&agrave; tool calling inferiore ai proprietari. Serve OpenAI per embeddings e setup.</p>
</div>
<!-- ENTERPRISE -->
@@ -1240,14 +1332,15 @@
<li><span class="fn">Home Chat</span> <span class="mdl">GPT-4.1</span></li>
<li><span class="fn">Floating Chat</span> <span class="mdl">GPT-4.1 Mini</span></li>
<li><span class="fn">Daily Brief</span> <span class="mdl">GPT-4.1 Nano</span></li>
<li><span class="fn">Batch Agents</span> <span class="mdl">GPT-4.1 Batch</span></li>
<li><span class="fn">Background Agents</span> <span class="mdl">GPT-4.1 Mini</span></li>
<li><span class="fn">Setup Agent</span> <span class="mdl">GPT-4.1</span></li>
<li><span class="fn">Embeddings</span> <span class="mdl">text-embedding-3-small</span></li>
</ul>
<div class="strategy-cost">
<span class="cost-label">Costo stimato/utente/mese</span>
<span class="cost-value" style="color:var(--warn);">~$6.20</span>
<span class="cost-value" style="color:var(--warn);">~$6.85</span>
</div>
<p class="strategy-pros"><strong>Pro:</strong> Ecosistema unificato, ZDR, affidabilit&agrave; massima, 1 sola API key. <strong>Contro:</strong> Costo 2&ndash;6x superiore alle alternative.</p>
<p class="strategy-pros"><strong>Pro:</strong> Ecosistema unificato, ZDR, affidabilit&agrave; massima, 1 sola API key. <strong>Contro:</strong> Costo 3&ndash;7x superiore alle alternative.</p>
</div>
</div>
@@ -1283,8 +1376,13 @@
</div>
<div class="why-card reveal">
<h4>&#x2699; GPT-4.1 Batch per Agenti</h4>
<p>Gli agenti batch non richiedono risposta in tempo reale. Lo <strong>sconto batch 50%</strong> di OpenAI rende GPT-4.1 imbattibile a <span class="highlight-model">$1.00/$4.00</span>. Il suo output strutturato e tool calling sono tra i migliori del mercato, cruciali per operazioni CRUD affidabili.</p>
<h4>&#x2699; GPT-4.1 Mini (Standard) per Background Agents</h4>
<p>Il Batch API dei provider LLM <strong>non &egrave; applicabile</strong> agli agenti di processing: il loop tool-calling (<code>unified-processor</code>, <code>cloud-processor</code>) richiede fino a 12 turni sincroni per file, con ogni risultato di tool restituito dal client Electron via WebSocket prima che parta il turno successivo — incompatibile con il modello asincrono e fire-and-forget del Batch API. Si usa quindi l&rsquo;<strong>API Standard</strong>. GPT-4.1 Mini a <span class="highlight-model">$0.40/$1.60</span> offre un ottimo bilanciamento: tool calling affidabile per operazioni CRUD multi-step, output strutturato consistente, e costo contenuto che non subisce la moltiplicazione del loop (ogni file pu&ograve; generare pi&ugrave; chiamate LLM in sequenza).</p>
</div>
<div class="why-card reveal">
<h4>&#x1f6e0; GPT-4.1 per Setup Agent</h4>
<p>Il setup journey &egrave; fondamentalmente diverso dagli agenti di processing: &egrave; una <strong>conversazione interattiva real-time</strong> con l&rsquo;utente (3&ndash;15 turni, <code>temperature=0.4</code>) che deve guidare con domande sensate, esplorare la directory con tool calling e produrre un <code>AgentConfig</code> JSON valido alla fine. GPT-4.1 a <span class="highlight-model">$2.00/$8.00</span> &egrave; la scelta giusta: qualit&agrave; conversazionale e instruction-following superiori a Mini, con un impatto sul costo <strong>trascurabile</strong> dato il basso volume (≈2 sessioni/mese per utente). Usare GPT-4.1 Mini per risparmiare $0.09/mese non vale la degradazione nell&rsquo;UX del setup.</p>
</div>
<div class="why-card reveal">
@@ -1374,12 +1472,14 @@
// ── Cost Chart ────────────────────────────────────
// Usage: 500 home (2K in + 1K out), 300 floating (500 in + 300 out),
// 210 brief (1.5K in + 500 out), 100 batch (3K in + 2K out), 1000 embeds (500 in)
// 210 brief (1.5K in + 500 out), 100 background agent runs (3K in + 2K out),
// 10 setup turns (2 sessioni × 5 turni, 4K in + 500 out), 1000 embeds (500 in)
const usage = {
home: { msgs: 500, inTok: 2000, outTok: 1000 },
float: { msgs: 300, inTok: 500, outTok: 300 },
brief: { msgs: 210, inTok: 1500, outTok: 500 },
batch: { msgs: 100, inTok: 3000, outTok: 2000 },
home: { msgs: 500, inTok: 2000, outTok: 1000 },
float: { msgs: 300, inTok: 500, outTok: 300 },
brief: { msgs: 210, inTok: 1500, outTok: 500 },
batch: { msgs: 100, inTok: 3000, outTok: 2000 },
setup: { msgs: 10, inTok: 4000, outTok: 500 },
embed: { msgs: 1000, inTok: 500 }
};
@@ -1390,36 +1490,45 @@
return inCost + outCost;
}
// Nota: il Batch API LLM non è compatibile con gli agenti di processing (loop
// tool-calling sincrono). I prezzi degli agenti usano l'API Standard, non batch.
// Setup agent usa un modello di qualità superiore (interattivo, basso volume).
const strategies = [
{
name: 'Multi-Provider',
color: 'green',
cost: calcCost('home', 0.30, 2.50) + calcCost('float', 0.10, 0.40) + calcCost('brief', 0.10, 0.40) + calcCost('batch', 1.00, 4.00) + (1000 * 500 / 1e6) * 0.02
// agents: GPT-4.1 Mini ($0.40/$1.60) | setup: GPT-4.1 ($2.00/$8.00)
cost: calcCost('home', 0.30, 2.50) + calcCost('float', 0.10, 0.40) + calcCost('brief', 0.10, 0.40) + calcCost('batch', 0.40, 1.60) + calcCost('setup', 2.00, 8.00) + (1000 * 500 / 1e6) * 0.02
},
{
name: 'Groq Budget',
color: 'blue',
cost: calcCost('home', 0.59, 0.79) + calcCost('float', 0.11, 0.34) + calcCost('brief', 0.05, 0.08) + calcCost('batch', 0.145, 0.295) + (1000 * 500 / 1e6) * 0.02
// agents: Qwen3 32B ($0.29/$0.59) | setup: GPT-4.1 Mini ($0.40/$1.60, esterno)
cost: calcCost('home', 0.59, 0.79) + calcCost('float', 0.11, 0.34) + calcCost('brief', 0.05, 0.08) + calcCost('batch', 0.29, 0.59) + calcCost('setup', 0.40, 1.60) + (1000 * 500 / 1e6) * 0.02
},
{
name: 'OpenAI Enterprise',
color: 'amber',
cost: calcCost('home', 2.00, 8.00) + calcCost('float', 0.40, 1.60) + calcCost('brief', 0.10, 0.40) + calcCost('batch', 1.00, 4.00) + (1000 * 500 / 1e6) * 0.02
// agents: GPT-4.1 Mini ($0.40/$1.60) | setup: GPT-4.1 ($2.00/$8.00)
cost: calcCost('home', 2.00, 8.00) + calcCost('float', 0.40, 1.60) + calcCost('brief', 0.10, 0.40) + calcCost('batch', 0.40, 1.60) + calcCost('setup', 2.00, 8.00) + (1000 * 500 / 1e6) * 0.02
},
{
name: 'Anthropic Full',
color: 'purple',
cost: calcCost('home', 3.00, 15.00) + calcCost('float', 1.00, 5.00) + calcCost('brief', 1.00, 5.00) + calcCost('batch', 1.50, 7.50) + (1000 * 500 / 1e6) * 0.02
// agents: Claude Sonnet 4.6 ($3.00/$15.00) | setup: Claude Sonnet 4.6
cost: calcCost('home', 3.00, 15.00) + calcCost('float', 1.00, 5.00) + calcCost('brief', 1.00, 5.00) + calcCost('batch', 3.00, 15.00) + calcCost('setup', 3.00, 15.00) + (1000 * 500 / 1e6) * 0.02
},
{
name: 'Mistral EU',
color: 'teal',
cost: calcCost('home', 1.00, 3.00) + calcCost('float', 0.20, 0.60) + calcCost('brief', 0.20, 0.60) + calcCost('batch', 2.00, 6.00) + (1000 * 500 / 1e6) * 0.02
// agents: Mistral Large 3 ($2.00/$6.00) | setup: Mistral Large 3
cost: calcCost('home', 1.00, 3.00) + calcCost('float', 0.20, 0.60) + calcCost('brief', 0.20, 0.60) + calcCost('batch', 2.00, 6.00) + calcCost('setup', 2.00, 6.00) + (1000 * 500 / 1e6) * 0.02
},
{
name: 'Google Full',
color: 'pink',
cost: calcCost('home', 0.30, 2.50) + calcCost('float', 0.10, 0.40) + calcCost('brief', 0.10, 0.40) + calcCost('batch', 0.625, 5.00) + (1000 * 500 / 1e6) * 0.15
// agents: Gemini 2.5 Flash ($0.30/$2.50) | setup: Gemini 2.5 Flash
cost: calcCost('home', 0.30, 2.50) + calcCost('float', 0.10, 0.40) + calcCost('brief', 0.10, 0.40) + calcCost('batch', 0.30, 2.50) + calcCost('setup', 0.30, 2.50) + (1000 * 500 / 1e6) * 0.15
}
];