@vantus/assistant-widget

v1.2.38

Published

a month ago

Vantus AI Assistant Widget — embeddable IIFE for any website

0High
0Medium
0Low

vantus

Vantus — AI-Powered Assistant Widget SaaS

Iron MVP 1.0 — Lanzamiento certificado por el Tribunal de Arquitectura (25/25 Correctness Properties validadas)

Vantus es una plataforma SaaS B2B de grado empresarial que permite a cualquier empresa desplegar un widget de asistente inteligente inexpugnable, conectado a un motor de IA (RAG) con aislamiento multi-tenant garantizado por construcción.

🏛️ Estado del Proyecto

| Fase | Estado | Specs | Tests | Tribunal | |------|--------|-------|-------|----------| | Fase 1 — Widget UX | ✅ Cerrada | 5 | 100% | Validado | | Fase 2 — Base de Datos | ✅ Cerrada | 2 | 100% | Validado | | Fase 3 — Panel Cliente | ✅ Cerrada | 5 | 100% | Validado | | Fase 4 — AI Core | ✅ Cerrada | 10 | 220/220 | Validado | | Fase 5 — Distribution | ✅ Cerrada | 3 | 100% | Validado | | Fase 6 — Ops & E2E | ✅ Cerrada | 6 | Grand Slam | Validado | | Fase 7 — v2.0 Platform | ✅ Cerrada | 8 | 137/137 + 29/29 | Validado Opus | | Fase 8 — El Canal (WhatsApp) | ✅ Cerrada | 6 | 6/6 | Validado | | Fase 9 — Aprendizaje Vivo (Moat) | ✅ Cerrada | 8 | 416/416 | Validado | | Fase 10 — El Embudo (Go-to-Market) | ✅ Cerrada | 7 | 41/41 | Validado | | Fase 11 — Escala y Gobierno | 🔄 En progreso | 33 | — | — | | Fase 12 — Reseller & White-Label | 🔲 Propuesta | — | — | Pendiente validación |

Veredicto del Tribunal: 🟢 LUZ VERDE — GA v2.0 CERTIFICADA (2026-05-20)

Veredictos:

Iron MVP: docs/audits/SUPREME-TRIBUNAL-VERDICT-IRON-MVP-20260516.md
v2.0 Phase 7: docs/audits/029-phase7-opus-validation.md (GO ✅ limpio)

🏗️ Arquitectura

┌─────────────┐     ┌─────────────┐     ┌─────────────────────────────────────────┐
│   Widget    │────▶│   Edge      │────▶│         AI Core (FastAPI)               │
│   (JS)      │     │ (CloudFlare)│     │  LangGraph · RAG · Tools · SSE          │
└─────────────┘     └─────────────┘     └─────────────────────────────────────────┘
                                               │
                    ┌────────────┬─────────────┼────────────┬────────────┐
                    ▼            ▼             ▼            ▼            ▼
               ┌────────┐  ┌─────────┐  ┌──────────┐  ┌────────┐  ┌──────────┐
               │Postgres│  │ Qdrant  │  │  Redis   │  │  KMS   │  │  Stripe  │
               │(RLS)   │  │(Vectors)│  │(Cache)   │  │(AWS)   │  │(Billing) │
               └────────┘  └─────────┘  └──────────┘  └────────┘  └──────────┘

Capas y Garantías de Aislamiento

| Capa | Tecnología | Garantía Multi-tenant | |------|-----------|-----------------------| | Widget | Vanilla JS IIFE | Sanitización XSS (sanitizeHtml) y Auth via API Key | | Panel | Next.js 16.2.4 + SSR | Middleware de seguridad y Contexto de Usuario SSR | | AI Core | FastAPI + LangGraph | AgentContext inyectado, protección contra Prompt Injection | | Vector DB | Qdrant Cloud | Filtro must obligatorio en SecureVectorStore (PBT n5-51) | | Database | Supabase (Postgres 15) | FORCE ROW LEVEL SECURITY en el 100% de las tablas | | KMS | AES-256-GCM | Envelope encryption con account_id como AAD obligatorio |

🚀 Características Implementadas

Widget Inteligente (v2.0)

💬 Acciones sugeridas con topic tags y textarea auto-resize.
📎 Carga de archivos (imágenes/audio) con previsualización.
🎟️ Tarjetas de cupones, carruseles de productos, y botones de pago inline.
📝 Formularios interactivos para captura de leads integrados.
🎙️ Audio Responses — TTS con OpenAI + selector de modo audio/texto.
🗺️ Embed Map — Mapas de OpenStreetMap inline.
🎬 Video Embed — YouTube/Vimeo dentro del chat.
📅 Date Picker — Selector de fecha/hora para citas.
✅ Action Confirmation — Tarjetas Aceptar/Cancelar.
📊 Data Table — Tablas comparativas inline.
🖼️ Image Carousel — Carrusel genérico de imágenes con zoom.
🗣️ Language Detection — Auto-detección de idioma del visitante.
📝 Conversation Logging — Debug log para desarrolladores.
📡 SSE Streaming — Respuestas en tiempo real con canal meta para audio/sources.

Panel de Administración (SaaS)

🏭 Widget Factory: Generación segura de API Keys y snippets.
🔐 Seguridad Avanzada: MFA TOTP, validación zxcvbn y chequeo HIBP.
💳 Billing Industrial: Gestión de planes vía Stripe con Feature Gating.
📊 Analytics Engine: KPI cards, Recharts, métricas de agente, exportación CSV.
📨 Master Inbox: 3-paneles con Realtime, notas internas, filtros, asignación.
🤖 AI Co-pilot / Modo Sombra: Borradores de IA para agentes humanos en tiempo real.
🎓 AI Training Center: Captura de correcciones RLHF desde el inbox.
👥 Team Management: Invitaciones por token, roles Admin/Agent, soft-delete.
🏷️ Leads Center: CRM Kanban (New→Won/Lost), atribución UTM, exportación CSV.
🔔 Handoff Logic: IA→Humano, Round-Robin, notificaciones Telegram/Email.
📈 Prompt Copilot: URL Scraper + Varita Mágica One-Click Enhance.

WhatsApp Business API (vía Kapso)

📱 Inbound Gateway: Verificación HMAC + mapeo phone_id→tenant fail-closed.
📤 Outbound Dispatcher: Adapter Kapso SDK, número de salida bound al mapeo.
🛡️ Fair-Use Guard: Rate-limit ≤20 msg/min, ≤1,000 msg/día, anti-dominó.
🔌 Connection Flow: Hosted Onboarding + Manual Setup en panel.
🚨 Kill-Switch: Suspender número/tenant abusivo antes de marcar paraguas Kapso.
💾 Quota Manager: Cuotas centralizadas GET /api/v1/whatsapp/quota.

AI Core — Motor RAG Multi-tenant

🧠 LangGraph Orchestrator: Bucle conversacional con checkpointer Postgres.
🔍 Intelligent RAG: Qdrant con filtro must por project_id, citación de fuentes.
🧠 Hybrid Memory: Redis + Postgres, summarization buffer, sesiones 24h.
🏭 Dynamic Prompt Factory: Jinja2 SandboxedEnvironment, cache Redis.
⚡ Semantic Cache / CAG: Cache SHA256 tenant-scoped + model tiering (gpt-4o-mini default).
🎯 RLHF Priority Sync: Correcciones aprobadas → Qdrant como Super-Fragmentos.
📊 RAG Eval Harness: "Preguntas doradas" por tenant, scoring por cosine similarity.
🛡️ Safety Guards: Moderación OpenAI, anti-jailbreak regex, rate limiting por IP/sesión.

Ecosistema y Distribución

🧪 Grand Slam Testing: E2E Playwright + Vitest + pytest (aislamiento por test).
🏭 CI/CD Industrial: Docker multi-stage non-root, SRI, manifest.json, GitHub Actions.
🩺 Deep Healthcheck: Autodiagnóstico con protección Thundering Herd.
✉️ Post-Purchase Drip: Campaña de onboarding idempotente con backoff exponencial.
📦 Paquete npm React: @vantus/react-widget (SSR-safe, CJS+ESM+DTS).
🔌 Plugin WordPress: Settings API, sanitización, visibilidad por shortcode.
📄 Landing Page Pública: SSR con Next.js, Stripe Checkout, Wizard de onboarding, SEO.

📦 Estructura del Repo

vantus-chat-widget/
├── js/                          # Widget Vanilla JS (source of truth)
│   └── chat-widget.js           # IIFE autocontenido (180 KB raw / 47.6 KB gzip)
├── ai-core/                     # Python FastAPI AI Core
│   ├── app/
│   │   ├── main.py              # FastAPI app + lifespan
│   │   ├── routes/
│   │   │   └── chat.py          # POST /chat/stream (SSE) + meta channel
│   │   ├── services/
│   │   │   ├── vector_store.py  # SecureVectorStore (Qdrant)
│   │   │   ├── ingestion/       # Chunker + Embedder + Pipeline
│   │   │   ├── extraction/      # PDF/DOCX/TXT/CSV/MD extractors
│   │   │   ├── rag/             # HybridRetriever + ContextFormatter
│   │   │   ├── tts.py           # TTS synthesis (OpenAI adapter)
│   │   │   ├── provider_hub.py  # BYOK + multi-provider adapters
│   │   │   └── kms.py           # AES-256 envelope encryption
│   │   ├── integrations/        # Third-party adapters (TTS, WhatsApp)
│   │   │   └── tts/
│   │   │       └── openai_tts.py
│   │   ├── models/
│   │   │   └── graph.py         # ChatRequest + conversation_mode
│   │   └── settings.py          # TTS_ENABLED, TTS_VOICE, etc.
│   ├── tests/
│   └── pyproject.toml
├── client-panel/                # Next.js 16 Panel de Cliente
│   ├── src/app/(panel)/         # Dashboard, Inbox, Leads, Analytics, Team
│   ├── src/app/(marketing)/     # Landing page, Pricing, Checkout, Onboarding
│   └── src/actions/             # Server Actions (auth, team, billing, etc.)
├── packages/
│   ├── react/                   # @vantus/react-widget (npm)
│   └── wordpress/               # Vantus Assistant Widget (WP plugin)
├── supabase/
│   ├── migrations/              # 15+ migraciones SQL con RLS estricto
│   └── functions/               # Edge Functions (handoff, drip-dispatcher, stripe-webhook)
├── .kiro/specs/                 # Especificaciones atómicas (n1-01 a n5-73)
├── docs/
│   ├── ARCHITECTURE-MASTER-BLUEPRINT.md  # Constitución técnica
│   ├── audits/                  # 32+ auditorías del Tribunal
│   ├── IMPLEMENTATION-ORDER.md  # Roadmap de fases (1–12)
│   ├── ROADMAP.md               # Roadmap público con features
│   ├── PROGRESS.md              # Registro de sesiones
│   └── adr/                     # Architecture Decision Records
├── dist/                        # Artefactos de build (gitignored)
├── tests/                       # Tests de build (manifest, SRI, size)
└── README.md

🧪 Tests

# Widget — Build pipeline tests
npm test

# AI Core — Pytest suite
cd ai-core
poetry run pytest tests/
poetry run ruff check .
poetry run mypy app/

# Client Panel — Vitest
npx vitest run

# Global E2E — Playwright Grand Slam
cd client-panel
npx playwright test

📋 Instalación

Snippet (IIFE)

data-ai-core-url no es opcional: sin él el widget deduce el backend del dominio de la página y no responde. Para fijar una versión con integrity, y para el resto de atributos, ver docs/WIDGET-INTEGRATION.md.

<script src="https://cdn.vantus.io/chat-widget.latest.js"
        data-api-key="vx_live_tu_llave"
        data-ai-core-url="https://cmia.vantus.io"
        async></script>

🛣️ Roadmap (Fases 11–12)

Fase 11 — Escala y Gobierno (En Progreso)

[ ] Super-Admin Shell: Layout maestro, Org Directory, Project Factory.
[ ] Impersonation Engine: Login-as seguro con auditoría dual.
[ ] Feature Entitlements: Activar/desactivar módulos por cuenta.
[ ] Analytics BI Center: MRR, Churn, LTV global consolidado.
[ ] Platform Audit Logs: Logs forenses inmutables (SOC2 ready).
[ ] Global Search Palette: CMD+K omnipresente.
[ ] Integraciones CRM: HubSpot, Pipedrive, Zoho (adapters bidireccionales).
[ ] Support Ticketing: Helpdesk Kanban con IDs únicos y prioridades.
[ ] Notification Center: Campana, drawer, Realtime, preferencias por categoría.
[ ] Transactional Email Engine: Outbox unificado Resend + 8 plantillas + backoff.
[ ] Cost Guard Limiter: Conteo de tokens (tiktoken) + Redis locks para BYOK.
[ ] Telemetry Observability: Latencias de IA, tasa de acierto RAG, dashboards.
[ ] DevOps Infrastructure: Redis Pub/Sub, balanceadores, escala horizontal.

Fase 12 — Reseller & White-Label (Propuesta)

⚠️ PENDIENTE DE VALIDACIÓN — Discutir y analizar esta propuesta con Chris.

[ ] Rol client: Usuario invitado con acceso limitado a widgets asignados.
[ ] Asignación granular: user_widgets con permisos (can_edit, can_view_analytics).
[ ] Panel de Reseller: Crear/gestionar sub-clientes, asignar widgets, métricas agregadas.
[ ] White-Label básico: Logo propio y dominio CNAME para panel de clientes finales.
[ ] Billing recursivo: Markup de precios, contadores de uso por sub-cuenta.

📜 Gobernanza

Este proyecto ha sido construido y auditado bajo el Protocolo TRIBUNAL v2.0, garantizando que cada línea de código cumple con la Constitución Técnica del Master Blueprint.

Auditorías recientes:

Iron MVP (2026-05-16): GO ✅
v2.0 Phase 7 (2026-05-20): GO ✅ limpio (Score 8.3/10 → 9.2/10)
WhatsApp Kapso (2026-06-03): 6/6 specs cerrados, Gates G1–G4 cerrados
Aprendizaje Vivo (2026-06-06): 8/8 specs cerrados, 416/416 tests

Sellado por el Tribunal Supremo — 2026-06-07