Overview

¿Qué es synapseForge?

synapseForge es un paquete de Python (distribuido en PyPI) que te permite crear proyectos completos de agentes de IA desde cero. Con un solo comando, generás un proyecto full-stack con backend, frontend, branding, dependencias y todo lo necesario para empezar a trabajar.

El foco está puesto en que puedas dedicarte a definir el comportamiento del agente — sus skills, tools, sub-agentes, base de conocimiento (RAG) y reglas de negocio — sin tener que armar la infraestructura técnica cada vez.

¿Qué obtenés al usar synapseForge?

• Una CLI con comandos claros para crear, personalizar, ejecutar y empaquetar proyectos.
• Un backend robusto listo para producción con FastAPI, streaming en tiempo real, persistencia y motor de agentes.
• Un frontend moderno con chat, historial, adjuntos, panel de configuración y base de conocimiento.
• Un sistema de agentes extensible basado en archivos Markdown: skills, tools externas, sub-agentes y colecciones RAG se cargan dinámicamente.
• Un build distribuible: con un comando compilás todo a un .exe + frontend estático, empaquetado en un zip.

Quickstart

Crear un proyecto

Crear un proyecto nuevo toma menos de un minuto. Asumiendo que ya tenés synapseForge instalado:

# Inicializar un proyecto en el directorio actual
synapseForge init .

# O especificar una ruta (la crea si no existe)
synapseForge init mi-proyecto

# Levantar el proyecto en modo desarrollo
synapseForge run .

# Abrir el navegador en http://localhost:5173

El comando init abre una interfaz gráfica donde cargás tu logo, definís el nombre de la empresa, los colores y demás datos. Una vez completado, tenés un proyecto listo para correr con run.

Comandos principales

Instalación

Requisitos

API key: para usar la app necesitás al menos una API key de un proveedor cloud — OpenRouter, Google Gemini o Groq, todos con capa gratis. Se carga desde la pantalla inicial de configuración (o Configuración → Providers). Ollama es opcional: solo si querés modelos locales.

Instalación desde PyPI

La forma más rápida:

pip install synapseForge

El paquete trae solo dos dependencias propias; el resto se resuelve a nivel de proyecto.

Instalación desde el código fuente

Si querés contribuir o usar la última versión de desarrollo:

git clone https://github.com/synapse-ai-hub/synapseForge.git
cd synapseForge
python -m venv .venv
source .venv/bin/activate     # En Windows: .venv\Scripts\activate
pip install -e .

Verificar que todo está bien

synapseForge --help

Si ves la lista de comandos, la instalación fue exitosa.

Crear proyecto

El comando init

El comando init arma un proyecto completo. Por defecto usa el directorio actual; si le pasás una ruta, la crea si no existe.

synapseForge init                       # usa el directorio actual
synapseForge init ./mi-proyecto         # ruta explícita
synapseForge init d:/proyectos/nuevo    # también acepta rutas absolutas

El proceso paso a paso

Cuando ejecutás init, se abre una ventana con los siguientes pasos:

1. Datos del proyecto — Cargás el logo de la empresa, el logo del cliente (opcional), nombre de empresa, owner, legal, nombre del repositorio, nombre del cliente y colores hexadecimales (opcional).
2. Extracción de la plantilla — Se toma la plantilla base (incluida en el paquete o descargada desde GitHub) y se copia al directorio destino.
3. Entorno virtual — Se crea un venv aislado dentro del proyecto.
4. Dependencias de Python — Se instalan las dependencias del backend dentro del venv.
5. Dependencias de Node — Se corre npm install en el frontend.
6. Logos — Se copia el logo de empresa a la carpeta src/ y el logo de cliente al frontend.
7. Favicon — Se genera automáticamente un .ico a partir del logo del cliente.
8. Colores — Si no ingresaste colores manualmente, se extraen del logo del cliente los colores dominantes.
9. Configuración — Se guardan todos los datos ingresados en un archivo de configuración.
10. Reemplazo de placeholders — Se reemplazan todos los placeholders (nombre de empresa, colores, etc.) en cada archivo del proyecto.

Los colores del proyecto

En la pestaña Colores (tanto en init como en colors) definís la paleta de la app. Cada color tiene un uso concreto:

• Color principal — El color de marca de la app: el botón de enviar, la barra de actividad mientras el asistente genera, la opción seleccionada del menú, los enlaces dentro de las respuestas y el anillo de foco del campo de chat.
• Color secundario — Los detalles suaves: el borde que se ilumina al hacer clic en un campo, el anillo de la conversación seleccionada y los bordes de las tarjetas del panel de configuración.
• Color de texto sobre el principal — El color del texto y los íconos que van encima del color principal: la flecha del botón de enviar, el texto de los botones y el ícono del avatar del asistente.
• Segundo color del degradé — El color final del degradé de los botones y el avatar (el inicio es el color principal).
• Usar degradé — Si lo desactivás, botones y avatar usan el color principal liso en lugar del degradé.

¿Qué pasa con el directorio destino?

• Si no existe → se crea y se extrae la plantilla limpia.
• Si existe y está vacío → se extrae la plantilla sin conflictos.
• Si existe con archivos → se extrae encima; los archivos del template sobrescriben los existentes, y los que no están en el template quedan tal cual.

Estructura del proyecto generado

mi-proyecto/
├── backend/             # Backend FastAPI
├── frontend/            # Frontend React + Vite + TypeScript
├── config/              # Configuración del proyecto
├── store/               # Store de tools y skills
├── on_boarding/         # Onboarding para desarrolladores
├── .env.example
├── .gitignore
├── LICENSE
└── README.md

Configuración externa del usuario

¿Qué es?

Además de los archivos del proyecto, synapseForge lee archivos del usuario desde una carpeta de configuración personal. Acá viven tus tools personalizadas, tus agentes definidos a medida, tus skills, tus colecciones RAG y la configuración de servidores MCP.

¿Dónde está esa carpeta?

• En Linux o macOS: ~/.config/synapseForge/
• En Windows: %USERPROFILE%\.config\synapseForge\

El sistema crea esta carpeta automáticamente al iniciar si no existe. No tenés que preocuparte por prepararla.

¿Qué hay adentro?

Todo esto se lee en tiempo de ejecución, así que podés agregar, modificar o quitar archivos sin reinstalar nada. Solo necesitás reiniciar el backend para que los cambios tomen efecto.

config.yaml — permisos del agente principal

El agente principal (el router) no tiene tools ni skills directas por defecto — solo puede delegar tareas mediante task. Si existe ~/.config/synapseForge/config.yaml, sus permisos se toman de ahí (misma lógica que el frontmatter de los agentes):

permissions:
  tool:
    read: allow
  skill:
    mi_skill: allow
  task:
    explorador: allow

• Si el archivo no existe → el agente principal queda solo con task (delegación siempre disponible).
• Si existe → usa solo los permisos explícitos del yaml.
• task está siempre disponible: si el yaml no lo lista, puede delegar a todos los sub-agentes; si lo lista, solo a los indicados.

Base de conocimiento (RAG)

¿Qué es?

El sistema de RAG (Retrieval-Augmented Generation) te permite armar una base de conocimiento que el agente consulta para responder con información específica de tu dominio. El contenido se guarda en colecciones vectoriales (ChromaDB) y se busca por similitud coseno.

Requisito: la base de conocimiento necesita una API key de OpenRouter (tiene capa gratis) cargada en Configuración → Providers. Sin esa key, esta sección queda deshabilitada — el resto de la app funciona normalmente.

¿Cómo se organiza?

El contenido se agrupa en colecciones. Cada colección es un tema o fuente de información independiente (similar a NotebookLM). Podés tener tantas colecciones como necesites, y cada agente accede solo a las que tiene permitidas.

¿Qué podés cargar?

• Archivos — PDF, Word (DOCX/DOC), TXT, Markdown, CSV, XLSX/XLS, JSON, XML, YAML, Python. Se extrae el texto, se divide en chunks (con overlap inteligente) y se guarda.
• Páginas web — Se fetchea el contenido, se convierte a texto, se divide en chunks y se guarda. La URL se conserva en el metadata y el HTML crudo en el primer chunk.

¿Cómo se crea una colección?

Desde la pestaña Crear → Gestionar RAG (modo dev) se abre la página de gestión de RAG, donde podés:

1. Crear una colección con un nombre (en minúsculas, sin espacios, solo [a-z0-9-], mínimo 3 caracteres).
2. Seleccionar la colección y subir archivos (arrastrá y soltá o seleccioná) o agregar una URL.
3. Eliminar colecciones cuando ya no las necesites.

¿Cómo la usa el agente?

El agente usa la tool nativa rag para consultar una colección. Devuelve los 5 chunks más similares a la consulta. Deny by default: un agente solo puede consultar las colecciones que declara explícitamente en su frontmatter:

permission:
  rag:
    mi_coleccion: allow

Esto te permite tener muchas colecciones y darle a cada agente solo las que necesita.

Skills

¿Qué es una skill?

Una skill es un paquete de conocimiento o procedimiento que el agente puede usar cuando la tarea lo requiera. A diferencia de las tools (que ejecutan código), las skills proveen instrucciones, plantillas y convenciones que guían al modelo sobre cómo responder.

¿Cómo está organizada una skill?

Cada skill vive en su propia subcarpeta dentro de ~/.config/synapseForge/skills/. El nombre de la carpeta es el nombre exacto de la skill:

skills/
├── analisis/
│   ├── SKILL.md
│   └── references/       # (opcional) archivos de referencia
│       ├── productos.md
│       └── api.md
└── websearch/
    └── SKILL.md

El archivo SKILL.md es el corazón de la skill: contiene una sección de metadatos al inicio (frontmatter YAML) y el cuerpo con las instrucciones que el modelo va a leer. Dentro del cuerpo, podés incluir una sección ## Reference Guide para documentación de referencia.

Control de acceso

Deny by default: si un agente no declara explícitamente qué skills puede usar, no tiene ninguna skill disponible. Cada agente debe especificar en su archivo qué skills puede usar mediante el bloque permission.skill: en el frontmatter. Esto te permite mantener un repositorio grande de skills y darle a cada agente solo las que necesita.

Nota sobre contexto: tanto las skills como las tools disponibles consumen contexto de ventana. Se recomienda que cada agente declare solo las skills que realmente necesita para sus tareas específicas.

Cómo crear una skill

Podés crear una skill de dos formas:

1. Manualmente: creá una subcarpeta dentro de ~/.config/synapseForge/skills/ con un nombre corto y descriptivo (en minúsculas, sin espacios), y dentro un archivo SKILL.md con frontmatter YAML (name y description mínimo) y el cuerpo con las instrucciones.
2. Con el LLM: desde la pestaña Crear → Crear Skill (modo dev) o por Telegram. El LLM hace una entrevista iterativa y genera el SKILL.md y los archivos necesarios automáticamente.

En el agente que va a usar la skill, declará el permiso en el frontmatter: permission.skill.{nombre_skill}: allow. Reiniciá el backend para que la nueva skill se cargue.

Buenas prácticas

• El nombre de la carpeta es el identificador: usá nombres únicos y descriptivos.
• La descripción es lo primero que ve el modelo: tiene que ser clara y específica sobre cuándo conviene usar la skill.
• Mantené el cuerpo conciso. Si necesitás mucho detalle, mové las partes extensas a la sección ## Reference Guide o a archivos en references/.
• Recordá: las skills no ejecutan código. Si necesitás que el agente haga algo concreto (consultar una API, transformar datos), eso va en una tool.

Tools (herramientas externas)

¿Qué es una tool?

Las tools externas son funciones Python que el agente puede invocar para hacer cosas concretas: consultar una base de datos, hacer una búsqueda web, enviar un mail, leer un archivo, etc. Cada tool es un archivo Python autocontenido que el sistema descubre, carga y registra automáticamente.

¿Cómo está organizada una tool?

Cada tool es un archivo .py suelto dentro de ~/.config/synapseForge/tools/:

tools/
├── consultar_clientes.py     # una tool por archivo
├── enviar_mail.py
├── lib/                       # (opcional) código compartido
│   ├── .env                   # variables de entorno para uso standalone
│   └── data/                  # datos estáticos compartidos
└── ...

Tools nativas (built-in)

Además de las tools externas, el sistema incluye tools nativas escritas en Python que están incorporadas en el core. Estas tools también deben ser habilitadas explícitamente por cada agente. Las tools nativas incluyen:

Características clave

• Auto-descubrimiento: el sistema escanea la carpeta y carga cada .py como una tool separada.
• Schema automático: el sistema genera la descripción y los parámetros de la tool a partir del código, sin que tengas que escribir nada extra.
• Aislamiento: cada tool es independiente. Si una falla al cargar, las demás siguen funcionando.
• Modo dual: podés probar la tool desde la línea de comandos sin tener que correr el agente entero.
• Tolerancia a fallos: las tools devuelven los errores como texto en vez de crashear.

Reglas importantes

• La función principal debe ser async.
• Todos los parámetros tienen que tener type hints (anotaciones de tipo).
• La función tiene que devolver texto (lo que el modelo va a leer).
• El nombre de la función principal tiene que coincidir con el nombre del archivo (sin la extensión).
• Toda la lógica va dentro de un try/except que devuelve el error como string.
• Las operaciones bloqueantes se ejecutan en un thread aparte para no trabar al agente.
• Si la tool necesita credenciales, se leen de un .env propio dentro de la carpeta lib/.

Control de acceso

Deny by default: si un agente no declara explícitamente qué tools puede usar, no tiene ninguna tool disponible (ni las externas ni las nativas). Cada agente debe especificar en su archivo qué tools puede usar mediante el bloque permission: en el frontmatter. Esto te permite tener un repositorio grande de tools y darle a cada agente solo las que necesita.

Nota sobre contexto: tanto las tools como las skills disponibles consumen contexto de ventana. Se recomienda que cada agente declare solo las tools que realmente necesita para sus tareas específicas.

Cómo crear una tool

1. Creá un archivo nombre_tool.py directamente en ~/.config/synapseForge/tools/. No dentro de subcarpetas.
2. Al inicio del archivo, escribí una descripción corta de una línea (máximo 80 caracteres). Esa descripción es la primera cosa que ve el modelo cuando evalúa si la tool le sirve.
3. Definí la función principal como async def nombre_tool(...) con type hints y un docstring que explique qué hace cada parámetro.
4. Implementá la lógica dentro de un try/except que devuelva el error como string.
5. Si la tool hace operaciones bloqueantes (consultas a base de datos, llamadas HTTP), envolvélas para que se ejecuten en un thread aparte y no bloqueen al agente.
6. Agregá un bloque if __name__ == "__main__" al final para poder probar la tool desde la línea de comandos.
7. Si la tool necesita credenciales o configuración, creá un archivo tools/lib/.env con las variables necesarias.
8. Probalo de forma independiente: python tools/nombre_tool.py argumento.
9. Reiniciá el backend para que la nueva tool se cargue en el agente.

Buenas prácticas

• Una tool = un archivo. Si querés compartir código entre tools, poné ese código en tools/lib/.
• Elegí nombres descriptivos: el nombre del archivo (sin .py) es el que el modelo va a usar para invocarla.
• Devolvé texto conciso. Si la tool genera mucho contenido, resumilo o apuntá a un archivo.
• Validá los tipos de los parámetros por las dudas: a veces el modelo manda los valores en un formato distinto al esperado.

MCP (Model Context Protocol)

¿Qué es MCP?

MCP (Model Context Protocol) es un protocolo estándar que permite conectar el agente con servidores externos que exponen herramientas y datos. Cada servidor MCP aporta tools que el agente puede invocar igual que cualquier otra herramienta.

¿Cómo se configuran los servidores?

Los servidores MCP se configuran en ~/.config/synapseForge/mcp.json como un array JSON:

[
  {
    "label": "nombre-servidor",
    "transport": "stdio",
    "command": ["node", "/ruta/al/servidor/index.js"]
  }
]

stdio es para servidores locales; http (con server_url) para servidores remotos.

Estado y tolerancia a fallos

• Las tools de cada servidor se descubren automáticamente al iniciar y se registran como tools del agente.
• Cada servidor tiene su propio timeout: si falla o no responde, se aísla — se marca en rojo en la interfaz y el resto del sistema sigue funcionando normalmente.
• El estado de cada servidor se muestra en la pestaña MCP del panel de agentes: Conectado (verde) o Error (rojo).

Sub-agentes

¿Qué es un sub-agente?

El sistema permite que un agente delegue tareas a sub-agentes especializados. Cada sub-agente es una configuración completa con su propio prompt, sus propias tools permitidas, sus propias skills permitidas, sus propias colecciones RAG permitidas y sus propios parámetros del modelo.

Esto te permite construir sistemas complejos donde cada agente se enfoca en lo que sabe hacer, en lugar de tener un solo agente gigante que intenta hacer todo.

¿Cómo se define un agente?

Cada agente es un archivo .md dentro de ~/.config/synapseForge/agents/. El archivo tiene dos partes: metadatos al inicio (en formato YAML) y el cuerpo con la instrucción del agente (en Markdown).

Metadatos del agente

Los metadatos se escriben al principio del archivo, entre líneas de guiones. Incluyen:

• Nombre — Identificador del agente. Tiene que coincidir con el nombre del archivo (sin la extensión .md).
• Descripción — Una línea que describe qué hace el agente. Se usa en listados y búsquedas.
• Parámetros del modelo — Temperatura, top-p, modelo, semilla, etc.
• Permisos — Qué tools, skills y colecciones RAG puede usar este agente, y cuáles no.

Parámetros del modelo

Podés ajustar cómo se comporta el modelo cuando ejecuta este agente:

Permisos

El sistema de permisos te permite controlar qué tools, skills y colecciones RAG están disponibles para cada agente. Deny by default: si un agente no declara permisos, no tiene acceso a ninguna tool, skill ni colección. Cada agente debe declarar explícitamente qué puede usar.

Nota sobre contexto: tanto las tools como las skills disponibles consumen contexto de ventana. Se recomienda que cada agente declare solo las que realmente necesita para sus tareas específicas.

El cuerpo del agente (system prompt)

Todo el texto debajo de los metadatos es la instrucción del agente. Acá definís:

• El rol y la personalidad del agente.
• Las reglas de negocio que tiene que seguir.
• El formato esperado de las respuestas.
• Las instrucciones sobre cómo usar las tools disponibles.
• Cualquier contexto específico del dominio.

No hay límite de extensión: escribí todo lo que haga falta para que el agente entienda qué tiene que hacer.

Cómo crear un agente

1. Creá un archivo nombre-agente.md directamente en ~/.config/synapseForge/agents/. El nombre del archivo (sin .md) es el identificador.
2. Al inicio del archivo, escribí los metadatos en frontmatter YAML: nombre (debe coincidir con el archivo), descripción, parámetros del modelo y permisos de tools/skills/rag.
3. Debajo, escribí el cuerpo con la instrucción del agente: personalidad, reglas, formato de respuesta, etc.
4. El agente queda disponible para ser invocado por otros agentes (incluido el principal) usando el comando de delegación de tareas.
5. Reiniciá el backend para que el nuevo agente se cargue en el sistema.

AGENT.md — comportamiento general

El archivo AGENT.md (si existe en ~/.config/synapseForge/agents/) se inyecta como sección ## Behavior en el system prompt de todos los agentes (el principal y los sub-agentes), antes de la sección ## MANDATORY:. No reemplaza el system prompt de nadie: el principal usa system_prompt.md y cada sub-agente usa su propio .md. Sirve para definir el comportamiento general del proyecto (compatibilidad con opencode/claude code).

Además, al final del system prompt de todos los agentes se inyecta la sección ## MANDATORY: con las reglas obligatorias de fidelidad: ejecutar el objetivo del usuario sin agregar ni inventar nada, formular preguntas si hay dudas, e iterar con tools o sub-agentes hasta cumplirlo.

Interfaz de usuario

¿Qué incluye?

La aplicación incluye una interfaz web moderna con chat, historial de conversaciones, un panel de configuración y un panel de agentes. La interfaz se abre automáticamente cuando ejecutás synapseForge run.

Creación (modo desarrollador)

El panel lateral incluye una sección Crear (modo dev) con accesos a las páginas standalone que se abren en una nueva pestaña del navegador:

• Crear Skill: formulario con nombre, tarea, cuándo usarla, cuándo NO, y material de referencia. El LLM busca skills existentes que coincidan; si no encuentra, genera una nueva.
• Gestionar RAG: página para crear colecciones RAG, subir archivos y agregar URLs, procesada con ChromaDB.

En las pantallas iniciales de creación (skill, tool y agente) podés elegir con qué modelo cloud se genera el elemento: seleccionás proveedor y modelo y pulsás Aplicar. La selección es efímera (solo vale para esa tarea mientras la pestaña está abierta); si no aplicás ninguna, se usa el modelo por defecto.

Cada página muestra un indicador de trabajo mientras el backend procesa. Al finalizar, muestra un mensaje de éxito.

Panel de agentes (modo desarrollador)

La pestaña Agente (modo dev) muestra el estado de los elementos del agente, con opción de eliminarlos:

• Tools — Lista las tools disponibles (nativas + externas) con su descripción.
• Skills — Lista las skills instaladas.
• Agentes — Lista los sub-agentes configurados.
• MCP — Lista los servidores MCP con su estado (Conectado/Error).
• RAG — Lista las colecciones de la base de conocimiento.

Panel de configuración

En el panel lateral, hay una pestaña de Configuración con las siguientes opciones:

Proveedor y modelo

Podés seleccionar el proveedor de modelos (Ollama local, Groq, Google Gemini u OpenRouter) y el modelo específico a utilizar. La selección se persiste entre sesiones y se aplica con el botón Aplicar. Al primer arranque aparece una pantalla inicial de configuración (que podés saltar) para cargar tus API keys; sin ningún proveedor disponible, el chat y los creadores quedan bloqueados hasta configurar uno.

Providers (API keys)

En la sección Providers podés cargar la API key de cada proveedor cloud (Groq, Google Gemini, OpenRouter). Cada key es opcional: si no cargás una key para un proveedor, ese proveedor no está disponible. Las keys se guardan cifradas en la base de datos SQLite interna y no se vuelven a mostrar después de guardarlas. Al guardar una key se valida contra la API del proveedor: si es inválida se rechaza; si es válida, el proveedor queda disponible de inmediato en los selectores.

Contexto (turnos)

Controla cuántos turnos de conversación se mantienen en el contexto del modelo. -1 significa todo el historial. Reducir este número ayuda a controlar el uso de tokens y el costo.

Modo verbose

Activando el modo verbose, la interfaz muestra tarjetas visuales para las llamadas a tools y las delegaciones a sub-agentes, lo que facilita entender qué está haciendo el agente en cada momento.

Instrucciones y documentos

Podés subir archivos (PDF, Word, TXT, Markdown, CSV, JSON, YAML, XML, Python) que se usarán como contexto adicional para el agente. Estos archivos se procesan y se inyectan en el system prompt del agente, proporcionando información de empresa, instrucciones o datos de referencia. Los archivos subidos aparecen en una lista con opción de eliminarlos individualmente.

Chat

La interfaz de chat muestra los mensajes de usuario y asistente en burbujas. Los mensajes del asistente pueden incluir:

• Texto — Respuesta del modelo, con streaming en tiempo real.
• Tarjetas de tool — Cuando el modelo invoca una tool, se muestra el nombre y los argumentos.
• Tarjetas de sub-agente — Cuando se delega a un sub-agente, se muestra el nombre y el resultado.
• Adjuntos — Los archivos que el usuario sube aparecen como chips debajo del mensaje.

Gauge de contexto

En el header del chat hay un velocímetro que muestra el porcentaje de ventana de contexto usado por la sesión actual. Se llena de verde a rojo a medida que se acerca al límite del modelo.

Agenda (tareas programadas)

En el header, el botón Agenda abre el panel de tareas programadas, donde podés indicarle al agente qué hacer y cuándo, sin estar presente:

• Agregar una tarea: descripción de lo que tiene que hacer el agente, hora (HH:MM) y días de la semana.
• Editar el horario de una tarea existente (hora y días).
• Eliminar tareas.
• Guardar: valida todas las tareas antes de confirmar (descripción presente, horario válido, al menos un día).

La zona horaria se toma directamente del sistema. Las tareas se ejecutan con el modelo y proveedor seleccionados, como si las hubieras pedido desde el chat.

Notificaciones

Junto al botón de Agenda hay una campanita que acumula una notificación por cada ejecución de tarea programada: indica si terminó con éxito o falló, con fecha y hora. Cada ejecución también se notifica por Telegram (ver la sección Telegram).

Historial

En el panel lateral, bajo la pestaña Conversaciones, se listan todas las sesiones de chat. Podés crear nuevas conversaciones, seleccionar sesiones anteriores y eliminar conversaciones existentes.

Telegram

¿Qué es?

El template incluye un bot de Telegram que actúa como control remoto del agente. El bot hace long-polling contra la Telegram Bot API y actúa como puente: cuando llega un mensaje lo publica en el event bus, el frontend lo recibe vía /api/events y corre el mismo flujo de chat que si hubieras escrito en la web. Cuando el backend termina, envía la respuesta final de vuelta a Telegram.

Arquitectura

• El bot solo emite eventos (telegram_message, telegram_command, telegram_create) al event bus.
• El frontend recibe esos eventos y ejecuta el flujo normal (chatService.sendMessage → POST /api/chat).
• Al terminar el request, el backend entrega la respuesta final a Telegram.
• Para la creación de skills/RAG, el bot emite telegram_create con open/close para abrir/cerrar la ventana correspondiente en el frontend.

Variables de entorno

Comandos

Los comandos que necesitan un argumento (/usar, /borrar, /proveedor, /modelo, /crear, /archivo, /agendar, /horario, /eliminar_tarea) usan un sistema de pregunta y respuesta: el bot muestra la lista de opciones y espera que el usuario responda con el texto. /cancelar (o la palabra "cancelar") aborta la espera.

Creación de skills y RAG por Telegram

El bot detecta la intención de crear una skill o un RAG (por ejemplo, "crear skill" o "crear rag") y entra en un modo de creación:

• Skill: abre la página de creación de skills en el frontend y guía la entrevista. Al crear la skill, la ventana se cierra.
• RAG: abre la página de gestión de RAG en el frontend. Tras cada acción (crear colección, subir archivo, agregar URL) pregunta en Telegram si querés terminar; respondé "sí" para cerrar la ventana o "no" para seguir. El comando terminar también cierra la ventana.

Funcionalidades

• Notas de voz: se transcriben localmente con faster-whisper y se envían como mensaje.
• Adjuntos: los archivos enviados con el botón de adjuntar de Telegram se descargan y procesan igual que el backend (extracción de texto con extract_text_from_bytes).
• Toggle en el frontend: el header tiene un toggle para activar/desactivar el bot (persistido en SQLite).
• Descarte de mensajes en cola: al reactivar el bot, se descartan los mensajes que llegaron mientras estaba apagado (solo se procesan los nuevos). Al activar, el frontend muestra un contador de 3 segundos para que no envíes durante el descarte.
• Notificaciones de tareas programadas: cada vez que se ejecuta una tarea programada, el resultado (éxito o error, con fecha y hora) se envía a Telegram siempre, independientemente de si el bot está habilitado para trabajar.

Gestión de la agenda por Telegram

Las tareas programadas también se gestionan desde Telegram, con el mismo flujo de pregunta y respuesta que el resto de los comandos:

• /agenda lista las tareas vigentes.
• /agendar pregunta qué tiene que hacer el agente y a qué hora, y crea la tarea.
• /horario permite cambiar hora y días de una tarea existente.
• /eliminar_tarea elimina una tarea.

API Reference

¿Qué expone el backend?

El backend expone una API HTTP con streaming para el chat, y endpoints REST para gestionar sesiones, configuración, base de conocimiento y otras operaciones.

Endpoints principales

El endpoint de chat (streaming)

El endpoint de chat devuelve los eventos en formato Server-Sent Events. Cada evento es un objeto JSON con un tipo y su contenido asociado. Los tipos principales son:

• chunk — Fragmentos de la respuesta del modelo que se van acumulando en pantalla.
• tool_call — El modelo decidió usar una tool. Incluye el nombre y los argumentos.
• tool_result — La respuesta que devolvió la tool.
• subagent_event — El agente principal delegó a un sub-agente. Incluye el nombre del sub-agente y su contenido.
• session_title — El título generado para la sesión.
• done — Marca el final del stream e incluye el ID de la sesión.
• error — Un error durante el procesamiento.

Modelo de sesión

• Cada sesión tiene un ID único que se crea al enviar el primer mensaje.
• Los mensajes se numeran por turnos dentro de cada sesión.
• Los adjuntos (archivos) se almacenan vinculados a la sesión y al turno correspondiente.
• Límite de adjuntos: hasta 3 archivos por mensaje, con un máximo total de 25 MB. Esto se hace para cuidar el contexto del modelo.

Deploy en local

Introducción

El flujo de desarrollo local está pensado para ser lo más simple posible: un solo comando levanta todo.

Requisitos

• Python 3.12 o superior.
• Node.js 20 o superior.
• Haber corrido synapseForge init al menos una vez en el directorio (para tener el venv y las dependencias instaladas).

Levantar el proyecto

cd mi-proyecto
# Activar el entorno virtual primero
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux/Mac
synapseForge run .

Este comando:

1. Verifica que el entorno virtual esté activado.
2. Levanta el backend con autoreload (los cambios se reflejan automáticamente) y espera a que responda.
3. Levanta el frontend con Vite, que incluye hot-reload de los cambios.
4. Abre el navegador automáticamente en la URL del frontend.

Configurar las claves de tu proveedor

Para usar la app necesitás al menos una API key de un proveedor cloud. Al primer arranque aparece una pantalla de configuración donde podés cargarlas directamente (también desde Configuración → Providers). Recomendaciones con capa gratis: OpenRouter, Google Gemini y Groq. Ollama es opcional: solo si querés correr modelos locales.

Importante: la base de conocimiento necesita específicamente una API key de OpenRouter (capa gratis). Sin ella esa sección queda deshabilitada; el resto funciona con cualquier proveedor.

Las keys se guardan cifradas en la base de datos SQLite interna, se validan contra la API del proveedor al guardarlas y no se vuelven a mostrar.

Probar en otra máquina de la red

Si querés acceder desde otra computadora o dispositivo:

1. Cambiá la URL del backend en el frontend para que apunte a la IP de la máquina que corre el servidor.
2. Asegurate de que el backend esté escuchando en todas las interfaces de red (no solo en localhost).
3. Abrí los puertos necesarios en el firewall.
4. Ajustá la configuración de CORS en el backend para permitir el origen desde donde vas a acceder.

Deploy en cloud

Introducción

Para distribuir el agente como producto terminado, synapseForge incluye un comando que compila todo a un ejecutable standalone más el frontend, todo empaquetado en un zip listo para distribuir.

Build con el comando launch

synapseForge launch -p ./mi-proyecto -n "MiApp"

Este comando hace tres cosas:

1. Compila el backend en un ejecutable standalone que incluye todas las dependencias de Python.
2. Compila el frontend en archivos estáticos optimizados para producción.
3. Empaqueta todo en un zip distribuible: el ejecutable, el frontend compilado, el entorno virtual, el launcher, la configuración, la licencia, el README y la documentación.

Checklist previo al build

Antes de generar el build, asegurate de que la configuración de producción esté lista:

• La URL del backend debe apuntar al dominio público donde se va a servir la app.
• La configuración de CORS en el backend debe permitir ese dominio.
• Las API keys de los proveedores se cargan desde la app (Configuración → Providers) y quedan cifradas en la base de datos interna; nunca hardcodeadas en el código.

Despliegue en un servidor propio (VPS)

1. Subí el zip generado al servidor.
2. Descomprimilo en la ubicación que prefieras.
3. Configurá un reverse proxy (Nginx es lo más común) para redirigir el tráfico al puerto del backend.
4. El reverse proxy debe tener un timeout largo (varios minutos) para que el streaming funcione bien.
5. Configurá el ejecutable para que arranque automáticamente con el sistema (con systemd en Linux).
6. Activá HTTPS con Let's Encrypt.

Un ejemplo de configuración de Nginx para este escenario:

server {
    listen 80;
    server_name miagente.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}

Despliegue con Docker

Si preferís usar contenedores, synapseForge incluye una configuración lista para usar:

docker compose up -d --build

El contenedor compila el frontend y lo sirve desde el backend en una sola aplicación. Solo necesitás exponer el puerto 8000.

Plataformas cloud recomendadas

• VPS clásico (Hetzner, DigitalOcean, Vultr) — Más control y mejor precio. Ideal para proyectos que necesitan un servidor siempre encendido.
• Servicios de contenedores (AWS ECS, Google Cloud Run, Azure Container Apps) — Para escalar según demanda. Pagás solo por lo que usás.
• Plataformas de deploy simplificado (Fly.io, Railway) — Deploy directo desde el repositorio de Git. Ideales para iterar rápido.