Firefly III for Hermes

Finanzas personales desde una conversación

Firefly III for Hermes es una integración nativa entre Hermes Agent y Firefly III. Su objetivo es permitir que una persona consulte y, cuando lo habilite de forma explícita, gestione su información financiera desde el chat y desde una página de Finanzas dentro de Hermes Desktop.

Firefly III permanece como fuente de verdad. Hermes aporta una capa conversacional para formular preguntas, resumir información y navegar los datos sin crear otra base financiera paralela.

El reto principal no es únicamente conectar dos APIs. Introducir un agente en un dominio sensible exige separar con claridad lectura, interpretación, preparación y ejecución, además de impedir que un texto almacenado dentro de una transacción pueda comportarse como una instrucción para el modelo.

Solo lectura por defecto

La primera superficie funcional utiliza una allowlist cerrada de siete herramientas para comprobar la conexión, consultar cuentas, listar o buscar transacciones, revisar categorías y presupuestos, y generar resúmenes mensuales.

La página nativa de Finanzas incorpora onboarding, diagnóstico de conexión, permisos y un dashboard de solo lectura con cuentas, saldos, presupuestos, transacciones recientes y resúmenes separados por moneda. La interfaz no convierte páginas parciales en totales ni suma importes de divisas distintas.

Los datos devueltos por Firefly III se tratan siempre como contenido no confiable. Esto incluye descripciones que parezcan pedir al agente que ignore instrucciones, revele el token o ejecute otra herramienta.

Seguridad como decisión de producto

El Personal Access Token se entrega mediante el mecanismo de secretos de Hermes y permanece en el backend. No se almacena en el renderer, la conversación, la configuración normal, SQLite, los logs ni las respuestas del agente.

El cliente REST aplica una superficie reducida y explícita: exige HTTPS salvo loopback local, valida y codifica cada segmento dinámico, rechaza redirecciones, no utiliza proxies ambientales y limita tiempo, tamaño, páginas y filas. Los importes se representan con Decimal, nunca con float, y los errores públicos se redactan antes de cruzar hacia la interfaz o el chat.

La arquitectura comparte modelos, repositorios y políticas entre las herramientas conversacionales y el backend visual. Los handlers de Hermes y la UI permanecen como adaptadores finos, evitando que una regla financiera exista en varios sitios con resultados distintos.

Escrituras bajo control humano

El proyecto está construyendo un flujo de escritura basado en preparar, revisar y confirmar. El modelo puede llegar a preparar un gasto, ingreso o transferencia, pero la aprobación debe producirse en una superficie visual que llama directamente al backend, fuera del control exclusivo del agente.

Actualmente existen la política que decide si una intención puede admitirse y un borrador canónico e inmutable con importe, moneda, fecha, cuentas y fingerprint reproducible. Todavía no están implementados el almacén de operaciones pendientes, la herramienta de preparación, la tarjeta de confirmación, el envío a Firefly III ni la verificación posterior por lectura.

Las eliminaciones, operaciones masivas, reglas, recurrencias, adjuntos y exportaciones permanecen fuera del alcance de la primera versión. La configuración también conserva las escrituras deshabilitadas y el modo de solo lectura activado por defecto.

Sistema y estado actual

El núcleo está construido con Python 3.11 o superior y biblioteca estándar siempre que es suficiente. Un plugin nativo de Hermes registra las herramientas y la skill conversacional; dashboard/plugin_api.py expone una API privada para Desktop y desktop/plugin.js utiliza React, React Query y los componentes proporcionados por el host sin incorporar otro bundle.

La base de código incluye contratos tipados, fixtures sintéticas de distintas versiones de Firefly III, tests unitarios, de integración, contrato, seguridad y evaluaciones específicas para selección de herramientas y prompt injection almacenada. El desarrollo sigue una estrategia TDD y añade gates de tipos, lint, cobertura, auditoría de dependencias y escaneo de secretos.

El plugin continúa en pre-alpha. La lectura y la experiencia Desktop se han verificado localmente con datos sintéticos y el runtime real de Hermes, pero la escritura completa, el hardening final, el empaquetado y la publicación de una versión estable siguen en construcción.

Explorar el proyecto

• Consultar el plugin en GitHub