527 lines
26 KiB
HTML
527 lines
26 KiB
HTML
|
<!DOCTYPE HTML>
|
|||
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|||
|
|
<head>
|
|||
|
|
<!-- Book generated using mdBook -->
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<title>VAPORA Architecture - VAPORA Platform Documentation</title>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Custom HTML head -->
|
|||
|
|
|
|||
|
|
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|||
|
|
<meta name="theme-color" content="#ffffff">
|
|||
|
|
|
|||
|
|
<link rel="icon" href="../favicon.svg">
|
|||
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|||
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|||
|
|
<link rel="stylesheet" href="../css/general.css">
|
|||
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|||
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|||
|
|
|
|||
|
|
<!-- Fonts -->
|
|||
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|||
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|||
|
|
|
|||
|
|
<!-- Highlight.js Stylesheets -->
|
|||
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|||
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|||
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|||
|
|
|
|||
|
|
<!-- Custom theme stylesheets -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Provide site root and default themes to javascript -->
|
|||
|
|
<script>
|
|||
|
|
const path_to_root = "../";
|
|||
|
|
const default_light_theme = "light";
|
|||
|
|
const default_dark_theme = "dark";
|
|||
|
|
</script>
|
|||
|
|
<!-- Start loading toc.js asap -->
|
|||
|
|
<script src="../toc.js"></script>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div id="mdbook-help-container">
|
|||
|
|
<div id="mdbook-help-popup">
|
|||
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|||
|
|
<div>
|
|||
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|||
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|||
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|||
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div id="body-container">
|
|||
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|||
|
|
<script>
|
|||
|
|
try {
|
|||
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|||
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|||
|
|
|
|||
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|||
|
|
}
|
|||
|
|
} catch (e) { }
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|||
|
|
<script>
|
|||
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|||
|
|
let theme;
|
|||
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|||
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|||
|
|
const html = document.documentElement;
|
|||
|
|
html.classList.remove('light')
|
|||
|
|
html.classList.add(theme);
|
|||
|
|
html.classList.add("js");
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|||
|
|
|
|||
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|||
|
|
<script>
|
|||
|
|
let sidebar = null;
|
|||
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|||
|
|
if (document.body.clientWidth >= 1080) {
|
|||
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|||
|
|
sidebar = sidebar || 'visible';
|
|||
|
|
} else {
|
|||
|
|
sidebar = 'hidden';
|
|||
|
|
}
|
|||
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|||
|
|
html.classList.remove('sidebar-visible');
|
|||
|
|
html.classList.add("sidebar-" + sidebar);
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|||
|
|
<!-- populated by js -->
|
|||
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|||
|
|
<noscript>
|
|||
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|||
|
|
</noscript>
|
|||
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|||
|
|
<div class="sidebar-resize-indicator"></div>
|
|||
|
|
</div>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
<div id="page-wrapper" class="page-wrapper">
|
|||
|
|
|
|||
|
|
<div class="page">
|
|||
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|||
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|||
|
|
<div class="left-buttons">
|
|||
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|||
|
|
<i class="fa fa-bars"></i>
|
|||
|
|
</label>
|
|||
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|||
|
|
<i class="fa fa-paint-brush"></i>
|
|||
|
|
</button>
|
|||
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|||
|
|
</ul>
|
|||
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|||
|
|
<i class="fa fa-search"></i>
|
|||
|
|
</button>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
|||
|
|
|
|||
|
|
<div class="right-buttons">
|
|||
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|||
|
|
<i id="print-button" class="fa fa-print"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
|||
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../architecture/vapora-architecture.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|||
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div id="search-wrapper" class="hidden">
|
|||
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|||
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|||
|
|
</form>
|
|||
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|||
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|||
|
|
<ul id="searchresults">
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|||
|
|
<script>
|
|||
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|||
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|||
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|||
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|||
|
|
});
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<div id="content" class="content">
|
|||
|
|
<main>
|
|||
|
|
<h1 id="vapora-architecture"><a class="header" href="#vapora-architecture">VAPORA Architecture</a></h1>
|
|||
|
|
<h2 id="multi-agent-multi-ia-cloud-native-platform"><a class="header" href="#multi-agent-multi-ia-cloud-native-platform">Multi-Agent Multi-IA Cloud-Native Platform</a></h2>
|
|||
|
|
<p><strong>Status</strong>: Production Ready (v1.2.0)
|
|||
|
|
<strong>Date</strong>: January 2026</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-executive-summary"><a class="header" href="#-executive-summary">📊 Executive Summary</a></h2>
|
|||
|
|
<p><strong>VAPORA</strong> is a <strong>cloud-native platform for multi-agent software development</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>✅ <strong>12 specialized agents</strong> working in parallel (Architect, Developer, Reviewer, Tester, Documenter, etc.)</li>
|
|||
|
|
<li>✅ <strong>Multi-IA routing</strong> (Claude, OpenAI, Gemini, Ollama) optimized per task</li>
|
|||
|
|
<li>✅ <strong>Full-stack Rust</strong> (Backend, Frontend, Agents, Infrastructure)</li>
|
|||
|
|
<li>✅ <strong>Kubernetes-native</strong> deployment via Provisioning</li>
|
|||
|
|
<li>✅ <strong>Self-hosted</strong> - no SaaS dependencies</li>
|
|||
|
|
<li>✅ <strong>Cedar-based RBAC</strong> for teams and access control</li>
|
|||
|
|
<li>✅ <strong>NATS JetStream</strong> for inter-agent coordination</li>
|
|||
|
|
<li>✅ <strong>Learning-based agent selection</strong> with task-type expertise</li>
|
|||
|
|
<li>✅ <strong>Budget-enforced LLM routing</strong> with automatic fallback</li>
|
|||
|
|
<li>✅ <strong>Knowledge Graph</strong> for execution history and learning curves</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-4-layer-architecture"><a class="header" href="#-4-layer-architecture">🏗️ 4-Layer Architecture</a></h2>
|
|||
|
|
<pre><code>┌─────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ Frontend Layer │
|
|||
|
|
│ Leptos CSR (WASM) + UnoCSS Glassmorphism │
|
|||
|
|
│ │
|
|||
|
|
│ Kanban Board │ Projects │ Agents Marketplace │ Settings │
|
|||
|
|
└──────────────────────────────┬──────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
Istio Ingress (mTLS)
|
|||
|
|
│
|
|||
|
|
┌──────────────────────────────┴──────────────────────────────────────┐
|
|||
|
|
│ API Layer │
|
|||
|
|
│ Axum REST API + WebSocket (Async Rust) │
|
|||
|
|
│ │
|
|||
|
|
│ /tasks │ /agents │ /workflows │ /auth │ /projects │
|
|||
|
|
│ Rate Limiting │ Auth (JWT) │ Compression │
|
|||
|
|
└──────────────────────────────┬──────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
┌────────────────────┼────────────────────┐
|
|||
|
|
│ │ │
|
|||
|
|
┌─────────▼────────┐ ┌────────▼────────┐ ┌────────▼─────────┐
|
|||
|
|
│ Agent Service │ │ LLM Router │ │ MCP Gateway │
|
|||
|
|
│ Orchestration │ │ (Multi-IA) │ │ (Plugin System) │
|
|||
|
|
└────────┬─────────┘ └────────┬────────┘ └────────┬─────────┘
|
|||
|
|
│ │ │
|
|||
|
|
└────────────────────┼───────────────────┘
|
|||
|
|
│
|
|||
|
|
┌────────────────────┼───────────────────┐
|
|||
|
|
│ │ │
|
|||
|
|
┌────▼─────┐ ┌──────▼──────┐ ┌────▼──────┐
|
|||
|
|
│SurrealDB │ │NATS Jet │ │RustyVault │
|
|||
|
|
│(MultiTen)│ │Stream (Jobs)│ │(Secrets) │
|
|||
|
|
└──────────┘ └─────────────┘ └───────────┘
|
|||
|
|
│
|
|||
|
|
┌─────────▼─────────┐
|
|||
|
|
│ Observability │
|
|||
|
|
│ Prometheus/Grafana│
|
|||
|
|
│ Loki/Tempo (Logs) │
|
|||
|
|
└───────────────────┘
|
|||
|
|
</code></pre>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-component-overview"><a class="header" href="#-component-overview">📋 Component Overview</a></h2>
|
|||
|
|
<h3 id="frontend-leptos-wasm"><a class="header" href="#frontend-leptos-wasm">Frontend (Leptos WASM)</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Kanban Board</strong>: Drag-drop task management with real-time updates</li>
|
|||
|
|
<li><strong>Project Dashboard</strong>: Project overview, metrics, team stats</li>
|
|||
|
|
<li><strong>Agent Marketplace</strong>: Browse, install, configure agent plugins</li>
|
|||
|
|
<li><strong>Settings</strong>: User preferences, workspace configuration</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Tech</strong>: Leptos (reactive), UnoCSS (styling), WebSocket (real-time)</p>
|
|||
|
|
<h3 id="api-layer-axum"><a class="header" href="#api-layer-axum">API Layer (Axum)</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>REST Endpoints</strong> (40+): Full CRUD for projects, tasks, agents, workflows</li>
|
|||
|
|
<li><strong>WebSocket API</strong>: Real-time task updates, agent status changes</li>
|
|||
|
|
<li><strong>Authentication</strong>: JWT tokens, refresh rotation</li>
|
|||
|
|
<li><strong>Rate Limiting</strong>: Per-user/IP throttling</li>
|
|||
|
|
<li><strong>Compression</strong>: gzip for bandwidth optimization</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Tech</strong>: Axum (async), Tokio (runtime), Tower middleware</p>
|
|||
|
|
<h3 id="service-layer"><a class="header" href="#service-layer">Service Layer</a></h3>
|
|||
|
|
<p><strong>Agent Orchestration</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Agent registry with capability-based discovery</li>
|
|||
|
|
<li>Task assignment via SwarmCoordinator with load balancing</li>
|
|||
|
|
<li>Learning profiles for task-type expertise</li>
|
|||
|
|
<li>Health checking with automatic agent removal</li>
|
|||
|
|
<li>NATS JetStream integration for async coordination</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>LLM Router</strong> (Multi-Provider):</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Claude (Opus, Sonnet, Haiku)</li>
|
|||
|
|
<li>OpenAI (GPT-4, GPT-4o)</li>
|
|||
|
|
<li>Google Gemini (2.0 Pro, Flash)</li>
|
|||
|
|
<li>Ollama (Local open-source models)</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Provider Selection Strategy</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Rules-based routing by task complexity/type</li>
|
|||
|
|
<li>Learning-based selection by agent expertise</li>
|
|||
|
|
<li>Budget-aware routing with automatic fallback</li>
|
|||
|
|
<li>Cost efficiency ranking (quality/cost ratio)</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>MCP Gateway</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Plugin protocol for external tools</li>
|
|||
|
|
<li>Code analysis, RAG, GitHub, Jira integrations</li>
|
|||
|
|
<li>Tool calling and resource management</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="data-layer"><a class="header" href="#data-layer">Data Layer</a></h3>
|
|||
|
|
<p><strong>SurrealDB</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Multi-tenant scopes for workspace isolation</li>
|
|||
|
|
<li>Nested tables for relational data</li>
|
|||
|
|
<li>Full-text search for task/doc indexing</li>
|
|||
|
|
<li>Versioning for audit trails</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>NATS JetStream</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Reliable message queue for agent jobs</li>
|
|||
|
|
<li>Consumer groups for load balancing</li>
|
|||
|
|
<li>At-least-once delivery guarantee</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>RustyVault</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>API key storage (OpenAI, Anthropic, Google)</li>
|
|||
|
|
<li>Encryption at rest</li>
|
|||
|
|
<li>Audit logging</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-data-flow-task-execution"><a class="header" href="#-data-flow-task-execution">🔄 Data Flow: Task Execution</a></h2>
|
|||
|
|
<pre><code>1. User creates task in Kanban → API POST /tasks
|
|||
|
|
2. Backend validates and persists to SurrealDB
|
|||
|
|
3. Task published to NATS subject: tasks.{type}.{priority}
|
|||
|
|
4. SwarmCoordinator subscribes, selects best agent:
|
|||
|
|
- Learning profile lookup (task-type expertise)
|
|||
|
|
- Load balancing (success_rate / (1 + load))
|
|||
|
|
- Scoring: 0.3*load + 0.5*expertise + 0.2*confidence
|
|||
|
|
5. Agent receives job, calls LLMRouter.select_provider():
|
|||
|
|
- Check budget status (monthly/weekly limits)
|
|||
|
|
- If budget exceeded: fallback to cheap provider (Ollama/Gemini)
|
|||
|
|
- If near threshold: prefer cost-efficient provider
|
|||
|
|
- Otherwise: rule-based routing
|
|||
|
|
6. LLM generates response
|
|||
|
|
7. Agent processes result, stores execution in KG
|
|||
|
|
8. Result persisted to SurrealDB
|
|||
|
|
9. Learning profiles updated (background sync, 30s interval)
|
|||
|
|
10. Budget tracker updated
|
|||
|
|
11. WebSocket pushes update to frontend
|
|||
|
|
12. Kanban board updates in real-time
|
|||
|
|
</code></pre>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-security--multi-tenancy"><a class="header" href="#-security--multi-tenancy">🔐 Security & Multi-Tenancy</a></h2>
|
|||
|
|
<p><strong>Tenant Isolation</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>SurrealDB scopes: <code>workspace:123</code>, <code>team:456</code></li>
|
|||
|
|
<li>Row-level filtering in all queries</li>
|
|||
|
|
<li>No cross-tenant data leakage</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Authentication</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>JWT tokens (HS256)</li>
|
|||
|
|
<li>Token TTL: 15 minutes</li>
|
|||
|
|
<li>Refresh token rotation (7 days)</li>
|
|||
|
|
<li>HTTPS/mTLS enforced</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Authorization</strong> (Cedar Policy Engine):</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Fine-grained RBAC per workspace</li>
|
|||
|
|
<li>Roles: Owner, Admin, Member, Viewer</li>
|
|||
|
|
<li>Resource-scoped permissions: create_task, edit_workflow, etc.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Audit Logging</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>All significant actions logged: task creation, agent assignment, provider selection</li>
|
|||
|
|
<li>Timestamp, actor, action, resource, result</li>
|
|||
|
|
<li>Searchable in SurrealDB</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-learning--cost-optimization"><a class="header" href="#-learning--cost-optimization">🚀 Learning & Cost Optimization</a></h2>
|
|||
|
|
<h3 id="multi-agent-learning-phase-53"><a class="header" href="#multi-agent-learning-phase-53">Multi-Agent Learning (Phase 5.3)</a></h3>
|
|||
|
|
<p><strong>Learning Profiles</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Per-agent, per-task-type expertise tracking</li>
|
|||
|
|
<li>Success rate calculation with recency bias (7-day window, 3× weight)</li>
|
|||
|
|
<li>Confidence scoring to prevent overfitting</li>
|
|||
|
|
<li>Learning curves for trend analysis</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Agent Scoring Formula</strong>:</p>
|
|||
|
|
<pre><code>final_score = 0.3*base_score + 0.5*expertise_score + 0.2*confidence
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="cost-optimization-phase-54"><a class="header" href="#cost-optimization-phase-54">Cost Optimization (Phase 5.4)</a></h3>
|
|||
|
|
<p><strong>Budget Enforcement</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Per-role budget limits (monthly/weekly in cents)</li>
|
|||
|
|
<li>Three-tier policy:
|
|||
|
|
<ol>
|
|||
|
|
<li>Normal: Rule-based routing</li>
|
|||
|
|
<li>Near-threshold (>80%): Prefer cheaper providers</li>
|
|||
|
|
<li>Budget exceeded: Automatic fallback to cheapest provider</li>
|
|||
|
|
</ol>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Provider Fallback Chain</strong> (cost-ordered):</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Ollama (free local)</li>
|
|||
|
|
<li>Gemini (cheap cloud)</li>
|
|||
|
|
<li>OpenAI (mid-tier)</li>
|
|||
|
|
<li>Claude (premium)</li>
|
|||
|
|
</ol>
|
|||
|
|
<p><strong>Cost Tracking</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Per-provider costs</li>
|
|||
|
|
<li>Per-task-type costs</li>
|
|||
|
|
<li>Real-time budget utilization</li>
|
|||
|
|
<li>Prometheus metrics: <code>vapora_llm_budget_utilization{role}</code></li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-monitoring--observability"><a class="header" href="#-monitoring--observability">📊 Monitoring & Observability</a></h2>
|
|||
|
|
<p><strong>Prometheus Metrics</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>HTTP request latencies (p50, p95, p99)</li>
|
|||
|
|
<li>Agent task execution times</li>
|
|||
|
|
<li>LLM token usage per provider</li>
|
|||
|
|
<li>Database query performance</li>
|
|||
|
|
<li>Budget utilization per role</li>
|
|||
|
|
<li>Fallback trigger rates</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Grafana Dashboards</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>VAPORA Overview: Request rates, errors, latencies</li>
|
|||
|
|
<li>Agent Metrics: Job queue depth, execution times, token usage</li>
|
|||
|
|
<li>LLM Routing: Provider distribution, cost per role</li>
|
|||
|
|
<li>Istio Mesh: Traffic flows, mTLS status</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Structured Logging</strong> (via tracing):</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>JSON output in production</li>
|
|||
|
|
<li>Human-readable in development</li>
|
|||
|
|
<li>Searchable in Loki</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-deployment"><a class="header" href="#-deployment">🔄 Deployment</a></h2>
|
|||
|
|
<p><strong>Development</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>docker compose up</code> starts all services locally</li>
|
|||
|
|
<li>SurrealDB, NATS, Redis included</li>
|
|||
|
|
<li>Hot reload for backend changes</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Kubernetes</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Istio service mesh for mTLS and traffic management</li>
|
|||
|
|
<li>Horizontal Pod Autoscaling (HPA) for agents</li>
|
|||
|
|
<li>Rook Ceph for persistent storage</li>
|
|||
|
|
<li>Sealed secrets for credentials</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Provisioning</strong> (Infrastructure as Code):</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Nickel KCL for declarative K8s manifests</li>
|
|||
|
|
<li>Taskservs for service definitions</li>
|
|||
|
|
<li>Workflows for multi-step deployments</li>
|
|||
|
|
<li>GitOps-friendly (version-controlled configs)</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-key-design-patterns"><a class="header" href="#-key-design-patterns">🎯 Key Design Patterns</a></h2>
|
|||
|
|
<h3 id="1-hierarchical-decision-making"><a class="header" href="#1-hierarchical-decision-making">1. Hierarchical Decision Making</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>Level 1: Agent Selection (WHO) → Learning profiles</li>
|
|||
|
|
<li>Level 2: Provider Selection (HOW) → Budget manager</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="2-graceful-degradation"><a class="header" href="#2-graceful-degradation">2. Graceful Degradation</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>Works without budget config (learning still active)</li>
|
|||
|
|
<li>Fallback providers ensure task completion even when budget exhausted</li>
|
|||
|
|
<li>NATS optional (in-memory fallback available)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="3-recency-bias-in-learning"><a class="header" href="#3-recency-bias-in-learning">3. Recency Bias in Learning</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>7-day exponential decay prevents "permanent reputation"</li>
|
|||
|
|
<li>Allows agents to recover from bad periods</li>
|
|||
|
|
<li>Reflects current capability, not historical average</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="4-confidence-weighting"><a class="header" href="#4-confidence-weighting">4. Confidence Weighting</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>min(1.0, executions/20)</code> prevents overfitting</li>
|
|||
|
|
<li>New agents won't be preferred on lucky streak</li>
|
|||
|
|
<li>Balances exploration vs. exploitation</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-related-documentation"><a class="header" href="#-related-documentation">📚 Related Documentation</a></h2>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong><a href="agent-registry-coordination.html">Agent Registry & Coordination</a></strong> — Agent orchestration patterns</li>
|
|||
|
|
<li><strong><a href="multi-agent-workflows.html">Multi-Agent Workflows</a></strong> — Workflow execution and coordination</li>
|
|||
|
|
<li><strong><a href="multi-ia-router.html">Multi-IA Router</a></strong> — Provider selection and routing</li>
|
|||
|
|
<li><strong><a href="roles-permissions-profiles.html">Roles, Permissions & Profiles</a></strong> — RBAC implementation</li>
|
|||
|
|
<li><strong><a href="task-agent-doc-manager.html">Task, Agent & Doc Manager</a></strong> — Task orchestration and docs sync</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<p><strong>Status</strong>: ✅ Production Ready
|
|||
|
|
<strong>Version</strong>: 1.2.0
|
|||
|
|
<strong>Last Updated</strong>: January 2026</p>
|
|||
|
|
|
|||
|
|
</main>
|
|||
|
|
|
|||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|||
|
|
<!-- Mobile navigation buttons -->
|
|||
|
|
<a rel="prev" href="../../architecture/index.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../../architecture/agent-registry-coordination.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<div style="clear: both"></div>
|
|||
|
|
</nav>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|||
|
|
<a rel="prev" href="../../architecture/index.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../../architecture/agent-registry-coordination.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
window.playground_copyable = true;
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script src="../elasticlunr.min.js"></script>
|
|||
|
|
<script src="../mark.min.js"></script>
|
|||
|
|
<script src="../searcher.js"></script>
|
|||
|
|
|
|||
|
|
<script src="../clipboard.min.js"></script>
|
|||
|
|
<script src="../highlight.js"></script>
|
|||
|
|
<script src="../book.js"></script>
|
|||
|
|
|
|||
|
|
<!-- Custom JS scripts -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|