<div align="center">

<img src="assets/vapora.svg" alt="Vapora Logo" width="400">


🌊 Intelligent Development Orchestration Platform  <br>
🎯 Specialized agents orchestrate pipelines for your team  <br>
🤖 Multi-IA router (Claude, OpenAI, Gemini, Ollama) <br>
⚡ Built with Rust from backend to frontend <br>

[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org)
[![Kubernetes](https://img.shields.io/badge/kubernetes-ready-326CE5.svg)](https://kubernetes.io)
[![Istio](https://img.shields.io/badge/istio-service%20mesh-466BB0.svg)](https://istio.io)
[![Tests](https://img.shields.io/badge/tests-218%2B%20passing-green.svg)](crates/)

[Features](#features) • [Quick Start](#quick-start) • [Architecture](#architecture) • [Docs](docs/) • [Contributing](#contributing)

</div>

  ---

  ```txt
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      ╦  ╦╔═╗╔═╗╔═╗╦═╗╔═╗
      ╚╗╔╝╠═╣╠═╝║ ║╠╦╝╠═╣
       ╚╝ ╩ ╩╩  ╚═╝╩╚═╩ ╩
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      Vaporate complexity
  Where ideas vaporize into reality
```

 ## 🌟 What is Vapora v1.2?

  **VAPORA** is a **13-crate Rust workspace** (218+ tests) delivering an **intelligent development orchestration platform** where teams and AI agents collaborate seamlessly to solve the 4 critical problems in parallel:

  - ✅ **Context Switching** (Developers unified in one system instead of jumping between tools)
  - ✅ **Knowledge Fragmentation** (Team decisions, code, and docs discoverable with RAG)
  - ✅ **Manual Coordination** (Specialized agents orchestrate pipelines automatically)
  - ✅ **Dev-Ops Friction** (Unified visibility from code changes through deployment)

  Additional capabilities:
  - 🤖 **Specialized agents** (Architect, Developer, Reviewer, Tester, Documenter, Marketer, Presenter, DevOps, Monitor, Security, ProjectManager, DecisionMaker - customizable & extensible)
  - 🧠 **Multi-IA intelligent routing** (Claude, OpenAI, Gemini, Ollama selected per task)
  - ☁️ **Self-hosted on Kubernetes** (no SaaS, complete control, Provisioning-based deployment)

  ### Key Highlights

  - **🎨 Glassmorphism UI**: Vaporwave aesthetics with UnoCSS, Leptos reactive WASM
  - **🤖 Specialized Agent Orchestration**: NATS JetStream coordination, parallel pipeline execution with approval gates
  - **🧠 Multi-IA Router**: Hybrid routing (rules + dynamic + manual override) for optimal LLM per task
  - **🚀 Full-Stack Rust**: Frontend (Leptos), Backend (Axum), Agents, Infrastructure
  - **☁️ K8s Native**: Istio service mesh, Rook Ceph storage, Cedar policy engine RBAC
  - **📚 RAG Integration**: Semantic search over Vapora docs, guides, code, and project materials
  - **🔒 Multi-Tenant**: SurrealDB scope isolation, fine-grained Cedar policies, complete audit trails

  ---

  ## ✨ Features

  ### 📋 Project Management

  - **Kanban Board**: Drag-and-drop tasks across Todo → Doing → Review → Done columns
  - **Real-time Collaboration**: Optimistic updates for instant UI feedback
  - **Smart Organization**: Feature tags, priority levels, task ordering
  - **Responsive Design**: Works seamlessly from mobile to ultra-wide displays

### 🧠 Intelligent Learning & Cost Optimization (Phase 5.3 + 5.4)

  - **Per-Task-Type Learning**: Agents build expertise profiles from execution history
  - **Recency Bias**: Recent performance weighted 3x (last 7 days) for adaptive selection
  - **Budget Enforcement**: Hard caps per role (monthly/weekly) with automatic fallback
  - **Cost-Efficient Routing**: Quality/cost ratio optimization for provider selection
  - **Learning Curves**: Track agent improvement over time with confidence scoring
  - **Prometheus Metrics**: Real-time budget utilization, fallback triggers, cost per provider
  - **Gradual Production Rollout**: 4-week canary deployment with automated rollback

  ### 🤖 Specialized AI Agents (Customizable & Extensible)

  Select, tune, or extend agents for your pipeline orchestration needs. Default agents include:

  **Parallel Agent Coordination**:
  - 🏗️ **Architect** (Claude Opus): System design & ADRs
  - 💻 **Developer** (Claude Sonnet): Code implementation [scales 5-20]
  - 👀 **CodeReviewer** (Claude Sonnet): Quality assurance & CR
  - 🧪 **Tester** (Claude Sonnet): Tests & benchmarks
  - 📚 **Documenter** (GPT-4): Docs & root files
  - 📢 **Marketer** (Claude Sonnet): Marketing content
  - 🎤 **Presenter** (Claude Sonnet): Presentations & slides
  - ⚙️ **DevOps** (Claude Sonnet): CI/CD & deployment
  - 👁️ **Monitor** (Gemini Flash): Health & alerting [real-time]
  - 🔒 **Security** (Claude Opus): Audit & compliance [can block]
  - 📊 **ProjectManager** (Claude Sonnet): Roadmap & tracking
  - 🎯 **DecisionMaker** (Claude Opus): Conflict resolution

  **Multi-IA Router**: Transparent LLM selection per task context
  - ✅ Automatic selection based on task complexity/latency/cost
  - ✅ Manual override capability with audit logging
  - ✅ Fallback chains (e.g., Claude Opus → GPT-4 → Claude Sonnet)
  - ✅ Cost tracking & budget alerts per agent role
  - ✅ **Learning-based agent selection**: Agents improve from execution history
  - ✅ **Budget enforcement**: Per-role cost limits with automatic fallback
  - ✅ **Cost-efficient routing**: Quality/cost optimization per task type

  ### 🏗️ Infrastructure

  - **Kubernetes Native**: Built for K8s (K3s, RKE2, or vanilla)
  - **Istio Service Mesh**: mTLS, circuit breakers, rate limiting out of the box
  - **Secrets Management**: RustyVault or Cosmian KMS (Rust-native)
  - **Storage**: Rook Ceph for distributed persistent volumes
  - **CI/CD**: Tekton Pipelines with Gitea integration
  - **Registry**: Zot for lightweight OCI artifact storage
  - **Observability**: Prometheus + Grafana + Loki + Tempo + Kiali

  ---

  ## 🛠️ Tech Stack

  ### Backend

<pre>
  Rust                 Async runtime with Tokio
  Axum                 Fast, ergonomic web framework
  SurrealDB            Multi-model database with scopes
  NATS JetStream       Message queue for agent jobs
  Rig                  AI agent framework
  fastembed            Local embeddings for RAG
</pre>

  ### Frontend

<pre>
  Leptos               Reactive Rust WASM framework
  UnoCSS               Instant on-demand atomic CSS
  leptos-use           Hooks and utilities
  thaw                 Component library
</pre>

  ### Infrastructure

<pre>
  Kubernetes           Orchestration (K3s/RKE2)
  Istio                Service mesh + ingress
  Rook Ceph            Distributed storage
  Tekton               Cloud-native CI/CD
  RustyVault           Secrets management
  Zot                  OCI registry
  Gitea                Self-hosted Git
</pre>

  ### Agents & LLM

<pre>
  Rig                  LLM agent framework with tool calling
  fastembed            Local embeddings for semantic search (RAG)
  NATS JetStream       Message queue for async agent coordination
  Cedar                Policy engine for fine-grained RBAC
  MCP Gateway          Model Context Protocol plugin system
  Learning Profiles    Per-task-type expertise with recency bias
  Budget Manager       Per-role cost limits with automatic fallback
  Knowledge Graph      Temporal execution history with learning curves
  Claude API           Anthropic Claude (Opus, Sonnet, Haiku)
  OpenAI API           GPT-4, GPT-4o, GPT-3.5-turbo
  Gemini API           Google Gemini (2.0 Pro, Flash, 1.5 Pro)
  Ollama               Local LLMs (Llama 2, Mistral, etc.)
</pre>

  ---

  ## 🚀 Quick Start

  ### Prerequisites

  - **Rust 1.75+** ([rustup](https://rustup.rs))
  - **Node.js 20+** (for UnoCSS)
  - **Docker** (for local development)
  - **Kubernetes cluster** (for production)

  ### Local Development

  ```bash
  # Clone the repository
  git clone https://github.com/vapora-platform/vapora
  cd vapora

  # Install dependencies
  cargo build

  # Available Just recipes (50+ commands)
  just help              # Show all available recipes
  just help build        # Show build recipes
  just help test         # Show test recipes
  just help ci           # Show CI recipes

  # Setup SurrealDB (Docker)
  docker run -d --name surrealdb \
    -p 8000:8000 \
    surrealdb/surrealdb:latest \
    start --bind 0.0.0.0:8000 file://data/database.db

  # Run migrations
  cd migrations && surrealdb import --conn http://localhost:8000 *.surql

  # Start backend
  cd ../vapora-backend
  cargo run

  # Start frontend (new terminal)
  cd ../vapora-frontend
  trunk serve

  Visit http://localhost:3000 🎉

  Docker Compose (Full Stack)

  docker compose up -d

  Includes: Backend, Frontend, SurrealDB, NATS, MCP Gateway

```

### Production Deployment (Kubernetes)

```bash
# Build and push Docker images
nu scripts/build-docker.nu --registry docker.io --tag v1.2.0 --push

# Update secrets
edit kubernetes/03-secrets.yaml  # Add your API keys

# Deploy to Kubernetes
nu scripts/deploy-k8s.nu

# Or use Provisioning (advanced)
cd provisioning/vapora-wrksp
provisioning workflow run workflows/deploy-full-stack.yaml
```

**See full deployment guide**: [`Deployment Guide`](docs/setup/deployment.md)

  ---
  ## 🏗️ Architecture

```
  ┌─────────────────────────────────────────────────────┐
  │           Frontend (Leptos + UnoCSS)                │
  │  Glassmorphism UI • Kanban Board • Drag & Drop      │
  └────────────────────┬────────────────────────────────┘
                       │
                       ▼
  ┌─────────────────────────────────────────────────────┐
  │           Istio Ingress Gateway                     │
  │  mTLS • Rate Limiting • Circuit Breaker • Telemetry │
  └────────────────────┬────────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
     ┌────────┐  ┌──────────┐  ┌───────────────┐
     │ Axum   │  │ Agent    │  │ MCP Gateway   │
     │ API    │  │ Runtime  │  │               │
     └───┬────┘  └────┬─────┘  └───────┬───────┘
         │            │                 │
         │            │                 ▼
         │            │         ┌──────────────┐
         │            │         │ MCP Plugins  │
         │            │         │ - Code       │
         │            │         │ - RAG        │
         │            │         │ - GitHub     │
         │            │         │ - Jira       │
         │            │         └──────────────┘
         │            │                │
         ▼            ▼                ▼
     ┌─────────────────────────────────────┐
     │        SurrealDB Cluster            │
     │     (Rook Ceph Persistent Vol)      │
     └─────────────────────────────────────┘
                       │
                       ▼
     ┌─────────────────────────────────────┐
     │    RustyVault / Cosmian KMS         │
     │    (Secrets + Key Management)       │
     └─────────────────────────────────────┘
```

  Data Flow

  1. User interacts with Leptos UI (Kanban board)
  2. API calls go through Istio Ingress with mTLS
  3. Axum backend handles CRUD operations
  4. SurrealDB stores projects, tasks, agents (multi-tenant scopes)
  5. Agent jobs queued in NATS JetStream
  6. Agent Runtime invokes MCP Gateway
  7. MCP Gateway routes to OpenAI/Claude with plugin tools
  8. Results streamed back to UI with optimistic updates

  ---
  📸 Screenshots

  Kanban Board with Glassmorphism

```
  ┌─────────────────────────────────────────────────────────┐
  │  Vapora         🔍 Search    Projects  Agents  + New    │
  ├─────────────────────────────────────────────────────────┤
  │                                                         │
  │            📌       🔵        🟣        ✅                │
  │       ┌─────────┬─────────┬─────────┬─────────┐         │
  │       │  TODO   │  DOING  │ REVIEW  │    DONE │         │
  │       │   (5)   │   (3)   │   (2)   │  (12)   │         │
  │       ├─────────┼─────────┼─────────┼─────────┤         │
  │       │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │         │
  │       │ │Task │ │ │Task │ │ │Task │ │ │Task │ │         │
  │       │ │Card │ │ │Card │ │ │Card │ │ │Card │ │         │
  │       │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │         │
  │       │         │         │         │         │         │
  │       │  Glass  │ Neon    │ Vapor   │ Fluid   │         │
  │       │  Blur   │ Glow    │ Waves   │ Motion  │         │
  │       └─────────┴─────────┴─────────┴─────────┘         │
  └─────────────────────────────────────────────────────────┘
```

  Agent Plugin Marketplace

```
  ┌─────────────────────────────────────────────────────────┐
  │  MCP Plugins                             🔌 Install New │
  ├─────────────────────────────────────────────────────────┤
  │  ┌──────────────────────────────────────────┐           │
  │  │ 🔍 Code Analysis Plugin                  │           │
  │  │ Analyze code with tree-sitter + LLM      │           │
  │  │ • Rust, TypeScript, Python               │           │
  │  │ • Complexity metrics                     │           │
  │  │ [✓ Installed]                            │           │
  │  └──────────────────────────────────────────┘           │
  │                                                         │
  │  ┌──────────────────────────────────────────┐           │
  │  │ 📚 RAG Search Plugin                     │           │
  │  │ Semantic search over Vapora docs & code  │           │
  │  │ • Local embeddings (fastembed)           │           │
  │  │ • Indexes: guides/, FEATURES, .coder/    │           │
  │  │ [✓ Installed]                            │           │
  │  └──────────────────────────────────────────┘           │
  └─────────────────────────────────────────────────────────┘

```

  ---
  📦 Project Structure

```text
  vapora/
  ├── crates/
  │   ├── vapora-shared/           # Core models, errors, types
  │   ├── vapora-backend/          # Axum REST API (40+ endpoints, 79 tests)
  │   ├── vapora-agents/           # Agent orchestration + learning profiles (67 tests)
  │   ├── vapora-llm-router/       # Multi-provider routing + budget (53 tests)
  │   ├── vapora-swarm/            # Swarm coordination + Prometheus (6 tests)
  │   ├── vapora-knowledge-graph/  # Temporal KG + learning curves (13 tests)
  │   ├── vapora-frontend/         # Leptos WASM UI (Kanban)
  │   ├── vapora-mcp-server/       # MCP protocol gateway
  │   ├── vapora-tracking/         # Task/project storage layer
  │   ├── vapora-telemetry/        # OpenTelemetry integration
  │   ├── vapora-analytics/        # Event pipeline + usage stats
  │   ├── vapora-worktree/         # Git worktree management
  │   └── vapora-doc-lifecycle/    # Documentation management
  ├── assets/
  │   ├── web/                     # Landing page (optimized + minified)
  │   │   ├── src/index.html      # Source (readable, 26KB)
  │   │   ├── index.html          # Production (minified, 18KB)
  │   │   ├── minify.sh           # Auto-minification script
  │   │   └── README.md           # Web assets guide
  │   └── vapora.svg              # Logo
  ├── kubernetes/                  # K8s manifests (base, overlays, platform)
  ├── migrations/                  # SurrealDB migrations
  ├── config/                      # Configuration files (TOML)
  └── docs/                        # Product documentation

  # Total: 13 crates, 218+ tests
```

  ---
  🔌 MCP Plugin Development

  Create custom agents with the MCP plugin system:

```rust
  use vapora_mcp::{Plugin, Tool, Resource};

  #[derive(Plugin)]
  pub struct MyCustomPlugin;

  impl Plugin for MyCustomPlugin {
      fn name(&self) -> &str {
          "my-custom-plugin"
      }

      fn tools(&self) -> Vec<Tool> {
          vec![
              Tool::new("my_tool")
                  .description("Does something cool")
                  .parameter("input", "string")
          ]
      }
  }

  #[async_trait]
  impl ToolExecutor for MyCustomPlugin {
      async fn execute_tool(
          &self,
          tool: &str,
          params: serde_json::Value
      ) -> Result<serde_json::Value> {
          match tool {
              "my_tool" => {
                  // Your logic here
                  Ok(json!({"result": "success"}))
              }
              _ => Err(anyhow!("Unknown tool"))
          }
      }
  }
  ```

  See docs/mcp-plugins.md for full guide.

  ---
  🚢 Deployment with Provisioning

  Using Provisioning (not Helm) for declarative K8s infrastructure:

```bash
  # Navigate to Provisioning workspace
  cd provisioning/vapora-wrksp

  # Deploy full VAPORA stack (KCL + Taskservs + Workflows)
  provisioning workflow run workflows/deploy-full-stack.yaml

  # This creates:
  # - K8s cluster (K3s/RKE2) with Cilium CNI
  # - Istio service mesh with mTLS
  # - Rook Ceph storage
  # - SurrealDB (3 replicas, 50Gi storage)
  # - Redis (3 replicas, 20Gi storage)
  # - NATS JetStream (3 replicas, 30Gi storage)
  # - Axum backend (3-10 replicas)
  # - Leptos frontend (2 replicas)
  # - Agent runtime (3-50 replicas, HPA enabled)
  # - LLM Router (2-5 replicas)
  # - MCP Gateway (2-5 replicas)

  # Access UI
  open https://vapora.example.com

  # Scale developer agents
  provisioning taskserv scale vapora-agents --agent developer --replicas 15

  # Monitor health
  provisioning health-check --services all

  Environment Variables

  # Backend
  SURREAL_URL=http://surrealdb:8000
  NATS_URL=nats://nats:4222
  MCP_GATEWAY_URL=http://mcp-gateway:8080
  RUSTYVAULT_ADDR=https://rustyvault:8200

  # Frontend
  VITE_API_URL=https://api.vapora.dev

  # Secrets (stored in RustyVault)
  OPENAI_API_KEY=sk-...
  ANTHROPIC_API_KEY=sk-ant-...
```

  ---
  🧪 Testing

```bash
  # Backend tests
  cd vapora-backend
  cargo test

  # Frontend tests
  cd vapora-frontend
  cargo test --target wasm32-unknown-unknown

  # Integration tests
  cargo test --workspace

  # E2E tests (requires running services)
  ./scripts/run-e2e-tests.sh

```

  ---
  📊 Monitoring

  Access Grafana dashboards:

  kubectl port-forward -n observability svc/grafana 3000:80

  Pre-configured dashboards:
  - Vapora Overview: Request rates, latencies, errors
  - Agent Metrics: Job queue depth, execution times, token usage
  - Istio Service Mesh: Traffic flows, mTLS status
  - Ceph Storage: Capacity, IOPS, health

  ---
  📚 Documentation & Specifications

  VAPORA v1.0 is built on comprehensive specifications organized by domain:

  **Core Specifications** (guides/core/):
  - **VAPORA-ARCHITECTURE-V2.md**: 4-layer architecture (Frontend, API, Service, Data, Infrastructure)
  - **AGENT-REGISTRY-COORDINATION.md**: 12 agent roles, NATS message patterns, health checking
  - **MULTI-IA-ROUTER.md**: Hybrid routing system (rules + dynamic + override), cost tracking
  - **MULTI-AGENT-WORKFLOWS.md**: End-to-end workflows with parallel execution & approval gates
  - **ROLES-PERMISSIONS-PROFILES.md**: Cedar policy engine, team profiles, fine-grained RBAC
  - **TASK-AGENT-DOC-MANAGER-V2.md**: Multi-agent task orchestration & decision extraction

  **Integration Specifications** (guides/integration/):
  - **DOC-LIFECYCLE-INTEGRATION.md**: Dual-mode (plugin + standalone) documentation management
  - **PROVISIONING-INTEGRATION.md**: KCL schemas, taskservs, workflows for K8s deployment
  - **RAG-INTEGRATION.md**: Semantic search with hybrid retrieval & embedding strategy

  **Component Specifications** (guides/):
  - **SESSION-LIFECYCLE-MANAGER.md**: .coder/ organization, metadata extraction, decision capture
  - **ROOT-FILES-KEEPER.md**: Keep README, CHANGELOG, ROADMAP always updated
  - **MIGRATION-PLAN.md**: Gradual migration path for existing projects

  **Deployment Guide** (provisioning/vapora-wrksp/):
  - workspace.toml: Master configuration (agents, LLM, monitoring, backup)
  - taskservs/: Service definitions for backend, frontend, agents, LLM router, MCP gateway
  - kcl/: Infrastructure as Code schemas (cluster, services, storage, agents, multi-ia)
  - workflows/: Batch operations (deploy, scale, upgrade, disaster-recovery)
  - README.md: Quick start and operation guide

  **References**:
  - guides/archive/v1-single-agent/: Legacy v1.0 specifications for historical reference

  ---
  ## 🤝 Contributing

  We welcome contributions! Please see CONTRIBUTING.md.

  Development Workflow

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing)
  5. Open a Pull Request

  Code Style

  - Rust: Follow rustfmt and clippy recommendations
  - Frontend: Use UnoCSS shortcuts, avoid inline styles
  - Commits: Conventional commits (feat:, fix:, docs:, etc.)

  ---
  📄 License

  Dual-licensed under:

  - MIT License (LICENSE-MIT)
  - Apache License 2.0 (LICENSE-APACHE)

  You may choose either license.

  ---
  🙏 Acknowledgments

  Inspired by:
  - https://github.com/transcend-engineering/archon - Original glassmorphism UI concept
  - https://github.com/docker/mcp-gateway - MCP integration pattern
  - https://rook.io - Ceph storage operator
  - https://istio.io - Service mesh architecture

  Built with ❤️ using Rust 🦀

  ---
  🔗 Links

  - Website: https://vapora.dev
  - Documentation: https://docs.vapora.dev
  - GitHub: https://github.com/vapora-platform/vapora
  - Discord: https://discord.gg/vapora
  - Twitter: https://twitter.com/VaporaPlatform

  ---
  #readme

  Made with vaporwave dreams and Rust reality ✨

  ---
  Archivos Adicionales Recomendados

  CONTRIBUTING.md

  # Contributing to Vapora

  Thank you for your interest in contributing to Vapora!

  ## Code of Conduct

  Be respectful, inclusive, and constructive.

  ## Development Setup

  See [README.md](README.md#-quick-start) for setup instructions.

  ## Pull Request Process

  1. Update documentation for any API changes
  2. Add tests for new features
  3. Ensure `cargo clippy` and `cargo fmt` pass
  4. Update CHANGELOG.md

  ## Coding Standards

  - **Rust**: Idiomatic Rust, avoid `unwrap()`, use `?` operator
  - **Error Handling**: Use `anyhow::Result` for services, custom errors for API
  - **Documentation**: All public items must have doc comments
  - **Tests**: Unit tests for services, integration tests for API

  ## Commit Messages

  Follow [Conventional Commits](https://www.conventionalcommits.org/):

  feat: add code analysis plugin
  fix: resolve race condition in task reordering
  docs: update MCP plugin guide
  chore: bump dependencies


  LICENSE-MIT y LICENSE-APACHE

---

⚠️ **Brand Assets Location**: See [`./assets/`](./assets/) for complete brand system including logo variations, color palettes, and interactive preview → [Open Logo Preview](./assets/vapora_logo.html)

---
