chapi-ai

Paquete reutilizable de chatbot de IA con RAG (Retrieval-Augmented Generation): se instala en distintos proyectos para dar a los usuarios finales un chat que responde preguntas ancladas estrictamente a una fuente de conocimiento propia (un PDF), nunca con conocimiento general del modelo. Cada proyecto que lo instale puede darle su propia personalidad y elegir su propio proveedor de IA.

Documentación completa y guiada paso a paso: docs/README.md.

Características

• Multi-proveedor de IA: Anthropic, OpenAI, Google y Groq vía el Vercel AI SDK, sin adaptadores hechos a mano por proveedor.
• Grounding no configurable: las reglas de "no salirse de la fuente" están fijas en el núcleo — ningún proyecto que instale el paquete puede desactivarlas.
• RAG desde PDF: extracción de texto, chunking, embeddings (Voyage AI) y recuperación semántica, todo incluido.
• Adaptadores de backend: Express, Next.js, Convex y cualquier runtime serverless basado en la Fetch API, todos hablando el mismo contrato HTTP simple, con un helper opcional de CORS (chapi-ai/adapters/cors) para cuando frontend y backend viven en orígenes distintos.
• Widget de UI en Vue: un Web Component (<chapi-chat>) con Shadow DOM, en tres modos (embebido, botón flotante arrastrable, pantalla completa), con modo claro/oscuro automático y Markdown mínimo en las respuestas.
• i18n: español e inglés, extensible.

Requisitos

• Node.js ≥ 26 (fijado en .nvmrc; con nvm: nvm use)
• pnpm ≥ 12 (el packageManager en package.json fija la versión exacta usada en desarrollo)

Instalación

pnpm add chapi-ai

Además, instala el SDK del proveedor de IA que vayas a usar (solo ese — los otros tres son peerDependencies opcionales, no se instalan si no los pides):

pnpm add @ai-sdk/anthropic   # o @ai-sdk/openai, @ai-sdk/google, @ai-sdk/groq

Esto es deliberado: así no arrastras los SDKs de los tres proveedores que no vas a usar. Ver docs/03-providers.md para el detalle.

Uso rápido

import { createBot, createKnowledgeStore, ingestPdf } from 'chapi-ai';
import { readFile } from 'node:fs/promises';

// 1. Ingiere tu fuente de conocimiento (una sola vez, o cuando cambie el PDF)
const pdf = await readFile('./manual-de-producto.pdf');
const chunks = await ingestPdf(new Uint8Array(pdf), { apiKey: process.env.VOYAGE_API_KEY! });

const knowledgeStore = createKnowledgeStore();
knowledgeStore.add(chunks);

// 2. Crea el bot
const bot = createBot({
  provider: { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-sonnet-5' },
  persona: {
    name: 'Chapi',
    description: 'Eres el asistente de soporte de una tienda de bicicletas online.',
    language: 'es',
  },
  knowledgeStore,
  embedding: { apiKey: process.env.VOYAGE_API_KEY! },
});

// 3. Chatea (streaming)
const result = await bot.streamChat('¿Cuántos días tengo para devolver un producto?');
for await (const part of result.textStream) {
  process.stdout.write(part);
}

Si la pregunta no está cubierta por el PDF ingerido, el bot responde con un mensaje de fallback fijo en vez de inventar una respuesta — eso es el grounding, y no se puede desactivar desde fuera del núcleo.

Para el detalle de cada pieza (proveedores, RAG, persona, adaptadores, widget), ve a docs/README.md.

Configuración (variables de entorno)

Cada proveedor de IA necesita su propia API key. Solo hacen falta las de los proveedores que realmente uses:

| Proveedor | Variable de entorno | Se usa para | |---|---|---| | Anthropic | ANTHROPIC_API_KEY | Chat | | OpenAI | OPENAI_API_KEY | Chat | | Google | GOOGLE_GENERATIVE_AI_API_KEY | Chat | | Groq | GROQ_API_KEY | Chat | | Voyage AI | VOYAGE_API_KEY | Embeddings (RAG) |

Crea un .env en tu proyecto (nunca lo subas a git) con las que necesites:

ANTHROPIC_API_KEY=sk-ant-...
VOYAGE_API_KEY=pa-...

Más detalle sobre cada proveedor, cómo elegir modelo, y errores comunes: docs/03-providers.md.

Backends soportados

| Backend | Import | |---|---| | Next.js (App Router) | chapi-ai/adapters/nextjs | | Serverless (Vercel Functions, Cloudflare Workers, Deno…) | chapi-ai/adapters/serverless | | Express / Node | chapi-ai/adapters/express | | Convex | chapi-ai/adapters/convex |

Todos hablan el mismo contrato: POST con { "message": string }, respuesta en streaming de texto plano. Ninguno añade cabeceras CORS por defecto — si tu frontend y tu backend viven en orígenes distintos (el caso normal si usas el widget), envuelve el handler con withCors de chapi-ai/adapters/cors. Detalle completo: docs/07-backend-adapters.md.

Widget de UI

<script type="module" src="ruta/a/chapi-chat.js"></script>
<chapi-chat endpoint="/api/chat" persona-name="Chapi" locale="es" mode="inline"></chapi-chat>

mode acepta inline (se ajusta al contenedor), launcher (botón flotante arrastrable) o fullscreen. Sigue automáticamente el modo claro/oscuro del sistema operativo del visitante (personalizable con variables CSS), y renderiza Markdown mínimo (negrita, cursiva, código inline) en las respuestas. Detalle completo: docs/08-widget.md.

Scripts de desarrollo

| Comando | Qué hace | |---|---| | pnpm build | Compila el núcleo (TypeScript → dist/) | | pnpm build:widget | Compila el widget de Vue (Vite → dist/widget/chapi-chat.js) | | pnpm test | Corre la suite de tests (Vitest) | | pnpm lint | Corre ESLint (incluye .ts y .vue) | | pnpm format | Formatea todo el proyecto con Prettier | | pnpm dev | Ejecuta scripts/try-claude.ts (llamada manual de prueba a un proveedor) | | pnpm dev:widget | Servidor de desarrollo del widget (Vite) | | pnpm dev:widget-server | Backend de prueba local para el widget |

Documentación

• docs/README.md — manual completo, pensado para quien se une al proyecto sin contexto previo.
• CONTRIBUTING.md — cómo levantar el entorno, convenciones de código y cómo contribuir.
• SKILL.md — guía paso a paso para que un asistente de IA (Claude, u otro) integre chapi-ai en tu proyecto de principio a fin. Se publica dentro del propio paquete (node_modules/chapi-ai/SKILL.md), así que sigue disponible aunque solo hayas instalado la dependencia sin clonar este repo.

Licencia

Apache License 2.0 — ver LICENSE.