Glosario
Definiciones cortas y opinionadas de los términos que vas a encontrar en el resto del manual. Está ordenado alfabéticamente — si solo necesitas refrescar uno, ve directo desde el índice de la derecha.
§ 1.5.1 ADK #
Agent Development Kit, el framework de Google para construir
agentes con LLMs. Da la abstracción de LlmAgent,
Runner, sesiones, eventos y FunctionTool.
Arkos Note corre sobre @google/adk 1.0 con un único
LlmAgent raíz que carga skills por demanda.
§ 1.5.2 Baúl de memoria #
Almacenamiento de largo plazo del usuario para fotos, audios, PDFs
y notas. Los archivos viven en Cloudflare R2; la
metadata (descripción, fecha, tags) y los chunks con
embeddings viven en PostgreSQL en las tablas
BaulItem y BaulChunk. Búsqueda
semántica vía pgvector y embeddings de
gemini-embedding-001 (768 dimensiones).
§ 1.5.3 Embedding · pgvector #
Un embedding es un vector de números que representa el "significado" de un texto. Dos textos parecidos quedan cerca en el espacio vectorial; eso es lo que hace que búsquedas como "el lugar del arroz negro" funcionen aunque el texto guardado diga "restaurante con tinta de calamar".
pgvector es la extensión de PostgreSQL que añade el
tipo vector y operadores de similitud (cosine,
L2, inner-product). Arkos Note lo usa con índices HNSW para
consultas rápidas en el baúl.
§ 1.5.4 Gemini Flash #
Familia de LLMs de Google. Arkos Note usa
gemini-2.5-flash como modelo principal por su balance
de velocidad y calidad para chat con tools, y cae a
gemini-2.5-flash-lite automáticamente cuando se abre
el circuit breaker. Para visión usa la misma familia con
capacidades multimodales nativas.
§ 1.5.5 Multimodal #
Capacidad del modelo de procesar varias modalidades de entrada en el mismo prompt: texto, imagen, audio (transcrito) y PDF. En Arkos Note significa que puedes mandar una foto del menú con un caption de texto y el modelo entiende los dos juntos.
§ 1.5.6 OAuth #
Protocolo estándar para que tú autorices a una app a acceder a un
recurso tuyo (Google Calendar) sin compartirle tu
contraseña. Cada permiso se llama scope; Arkos Note pide
los mínimos necesarios para cada función. Los tokens se guardan
cifrados y los puedes revocar desde
myaccount.google.com/permissions.
§ 1.5.7 Saldo prepaid #
Modelo de cobro por consumo. Recargas un monto vía Stripe, se descuenta cada vez que Arkos toca un proveedor externo (LLM, embeddings, transcripción, mensajes de WhatsApp salientes) más un margen. No hay suscripción; cuando el saldo llega a cero, el bot pausa y te avisa.
§ 1.5.8 sessionId #
Identificador (UUID) de tu conversación activa con Arkos.
Persiste en PostgreSQL e incluye historial, estado y metadata. Se
archiva tras un periodo idle o al mandar /nuevo.
WhatsApp y chat web comparten sessionId bajo la
misma sessionKey (wa-user-<id>),
así que es la misma memoria en ambos canales.
§ 1.5.9 Skill · Tool #
Una tool (o "function tool") es una función con
schema y descripción que el modelo puede invocar. Ejemplos:
crearEvento, crearLista,
guardarEnBaul.
Una skill es un paquete de tools relacionadas que
se carga por demanda con load_skill. Las skills de
Arkos hoy son: calendar, baul,
listas, gastos, saldo y
contactos.
Las tools de recordatorios y preferencias son core —
siempre disponibles sin cargar skill.
§ 1.5.10 Sub-procesador #
Tercero al que Arkos Note transfiere datos para operar el servicio. Hoy son: Meta (WhatsApp Business Cloud API), Google (Gemini, Calendar), Deepgram (transcripción de audio), Stripe (pagos) y Cloudflare (Pages para la landing y R2 para el baúl). La lista completa con jurisdicciones está en la política de privacidad.
§ 1.5.11 WhatsApp Business API #
Canal oficial de Meta para que negocios reciban y envíen mensajes en WhatsApp programáticamente. Arkos Note lo usa para todo el flujo entrante (webhook a un worker con cola Redis) y saliente. Tiene reglas: la ventana de 24 horas permite mandarte texto libre solo si tú escribiste primero en ese plazo; fuera de esa ventana, los mensajes proactivos del bot (recordatorios programados, prompts agendados) usan templates pre-aprobados.
§ 1.5.12 Otros términos útiles #
Circuit breaker
Mecanismo del backend que detecta fallas repetidas del modelo
principal (3 fallas en 60 segundos) y conmuta a un modelo
secundario (gemini-2.5-flash-lite) durante 5 minutos
para mantener el servicio en pie. Tú no notas nada salvo que las
respuestas pueden ser un poco menos elaboradas durante ese rato.
Reset de sesión
Mandar /nuevo o /reset archiva la
conversación activa y arranca una limpia, sin contexto previo. La
sesión vieja no se borra: queda accesible desde el sidebar del
chat web. Útil cuando cambias de tema y quieres que el modelo no
arrastre lo anterior.
Scope OAuth
Permiso granular que Google te pide aprobar al conectar tu cuenta. Cada feature de Arkos depende de uno o varios. Los scopes reales aparecen detallados en Instalación en 60s y, con su justificación legal, en la política de privacidad.
Wrappers de billing
Capa interna del backend (billableGemini,
billableDeepgram, billableWhatsapp) que
envuelve cada llamada a un proveedor pagado y registra el consumo
contra tu saldo. No interactúas con esto directamente — se
menciona aquí porque es el motivo de que cada operación tenga un
costo asignable y rastreable.