FinLedger

Un libro de contabilidad financiera local con tres superficies de lectura, además de un servidor MCP para que un agente pueda consultarlas:

• expenses: cuentas de gastos, conciliadas con reembolsos entre pares

• investments: saldos de corretaje, tenencias y actividad

• income: nómina (bruto, retenciones, neto)

Los gastos y las inversiones comparten un almacén y nada más. Una cuenta lleva un domain explícito, y cada consulta de gastos se une a través de él, de modo que una compra de acciones no puede llegar al emparejador de reembolsos.

El emparejador se basa en reglas. Se abstiene cuando no está seguro. Un humano o agente confirma antes de que un emparejamiento reduzca el gasto neto.

Las transacciones reales, los recibos de nómina y las claves de API permanecen en tu máquina (~/.finledger/ledger.db, .env). Este repositorio incluye solo código y un conjunto de evaluación sintético.

Instalación

Python 3.10+. El libro, el emparejador, el bucle MCP y el arnés de evaluación son de la biblioteca estándar. pypdf es opcional y solo se necesita para importar recibos de nómina en PDF.

pip install -e .

Related MCP server: MCP Agent - AI Expense Tracker

Servidor MCP

python3 -m finledger.mcp_server --db ~/.finledger/ledger.db

18 herramientas, con espacios de nombres expenses_*, investments_* e income_*, además de savings_rate, accounts, sync y reconcile.

Ejemplo de Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "finledger": {
      "command": "python3",
      "args": ["-m", "finledger.mcp_server"]
    }
  }
}

La ruta predeterminada del libro es ~/.finledger/ledger.db.

CLI

finledger sync
finledger reconcile
finledger review
finledger serve

finledger serve abre un escritorio local en :8770. En macOS también puedes hacer doble clic en scripts/Expense Desk.command.

Fuentes en vivo opcionales (pon las credenciales en .env, nunca lo confirmes):

Copia .env.example a .env.

Evaluación pública

El conjunto dorado publicado es sintético. Se genera con scripts/make_sample_data.py y vive en data-sample/. Cada fila de transacción está marcada como synthetic: true. Es un conjunto de cobertura para los comportamientos del emparejador (emparejamiento limpio, fan-in, agrupación, padre de salida entre pares, créditos de comerciante, notas débiles, gemelos de fuentes cruzadas). No son datos reales anonimizados.

python3 scripts/eval_public.py
# equivalent:
python3 -m reconcile.eval --matcher rules_v0

Números que puedes reproducir desde este repositorio

Medido en data-sample/ con rules_v0 (ventana ±90 días, umbral de autoemparejamiento 0.75):

Vuelve a ejecutar python3 scripts/eval_public.py para actualizar estos números. Dos falsos positivos restantes en la muestra son debilidades reales del emparejador, incluida la regla de aumento de recall por emojis que se excede.

Lo que no está en este repositorio

Un conjunto dorado privado de aproximadamente 92 ejemplos etiquetados se usó durante el desarrollo. Nombra personas reales y compras reales y no se publica. No trates los números de la muestra como una reproducción de ese conjunto. Corpus diferente, tamaño diferente, puntuaciones diferentes.

Este repositorio no afirma una precisión de autoemparejamiento del 100%.

Emparejador

Consulta reconcile/README.md. Versión corta:

Etiqueta el corpus de muestra con python3 labeling/app.py (por defecto usa data-sample/).

Licencia

MIT