asset-finance-modeler

Comprehensive financial modeling engine for SaaS and other assets, exposed as MCP tools.

V1 covers SaaS (Gestnova baseline shipped); Plan 4 adds an intelligence layer (knowledge base, workflows, contextual memory). Designed to scale to renewables, real estate, generic business.

Architecture

• core/ — asset-agnostic primitives (TimeGrid, GrowthCurve, AmortizationSchedule, statements, valuation, scenario)

• assets/saas/ — SaaS schema + engines + orchestrator (SaasModel) + presets

• store/ — SQLite scenarios + exports + compare + sensitivity

• cli/ — argparse CLI

• mcp_server/ — MCP stdio server exposing 30 tools total:

  • 18 finance.simulate.* tools (run, clone, compare, sensitivity, export…)

  • 3 finance.track.* stubs (V2)

  • 3 finance.knowledge.* tools — FAISS-backed semantic search over 30+ financial concepts

  • 3 finance.workflows.* tools — declarative multi-step analysis recipes (pricing_impact, valuation_summary…)

  • 3 finance.context.* tools — per-tenant persistent memory, semantically searchable

• intelligence/ — embeddings (sentence-transformers MiniLM), KnowledgeBase, WorkflowEngine, ContextMemory

Related MCP server: Enterprise MCP Knowledge Platform

Quickstart (dev)

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                                  # ≥193 tests
ruff check src/ tests/                  # clean
mypy src/                               # clean

CLI usage

PYTHONPATH=src python -m asset_finance_modeler.cli.main list-models
PYTHONPATH=src python -m asset_finance_modeler.cli.main run --preset gestnova --output summary
PYTHONPATH=src python -m asset_finance_modeler.cli.main run --preset gestnova \
    --override 'revenue.sources[0].pricing.per_unit_per_period=250' \
    --output report

MCP server

PYTHONPATH=src python -m asset_finance_modeler.mcp_server.server

Configure your MCP client to point to this command via stdio. See docs/INTEGRATION.md for wiring into Gestnova/Ian.

Intelligence layer (Plan 4)

The modeler now ships a structured intelligence layer — no extra LLM in the chain; all intelligence is retrieval + workflow execution.

# Knowledge base: semantic search over financial concepts (30 seeded entries, bilingual ES/EN)
reg["finance.knowledge.search"].handler({"query": "qué es LTV/CAC saludable", "top_k": 3})

# Workflows: run a multi-step analysis with one call
reg["finance.workflows.run"].handler({
    "workflow_id": "pricing_impact_analysis",
    "inputs": {"base_scenario_id": "scn-xxx", "prices": [200, 300, 400]},
})

# Context memory: store and recall per-tenant decisions
reg["finance.context.store"].handler({"tenant_id": "gestnova", "key": "pricing-2026-05",
    "value": "Decided to keep pricing at 300€/agent after EV analysis"})
reg["finance.context.search"].handler({"tenant_id": "gestnova", "query": "pricing decision"})

Specs and plans

• docs/superpowers/specs/2026-05-14-asset-finance-modeler-design.md — design

• docs/superpowers/plans/2026-05-14-plan-1-foundation-engine.md — done

• docs/superpowers/plans/2026-05-14-plan-2-scenarios-store-exports-cli.md — done

• docs/superpowers/plans/2026-05-14-plan-3-mcp-server.md — done

• docs/superpowers/plans/2026-05-15-plan-4-intelligent-toolkit.md — done

Qué incluye y qué no

Este repositorio es el motor: los modelos, el servidor MCP con sus herramientas y una colección de presets de referencia (BESS, solar, eólica, datacenter, negocio, alquiler y la vía híbrida consolidada).

Los presets traen cifras redondas de ejemplo, no de ningún proyecto real. Sirven para que el motor se ejecute de punta a punta nada más instalarlo, y para que los tests comprueben siempre lo mismo. Para un caso de verdad se pasan los parámetros propios.

Licencia

MIT. Úsalo, modifícalo y véndelo si te sirve. Hecho en Gestnova.