BvA Narrator

Budget vs actuals → driver-attribution variance commentary, not just numbers.

finance-ai-labs · FP&A · Monthly close

---

The problem

BvA reports show the variance. They almost never explain it. The CFO ends up writing the same paragraph every month. The agent should write the first draft.

What it does

• Budget + actuals ingest
• Variance decomposition: volume × rate × mix
• Driver attribution per GL line
• Plain-English variance commentary in CFO voice
• Materiality threshold filter so the narrative stays signal-only

Architecture

flowchart LR
  B[Budget] --> V[Variance engine]
  A[Actuals] --> V
  V --> D[Driver decomp]
  D --> AGT[Narrator agent]
  AGT --> M[BvA memo]

Loading

Quickstart

git clone https://github.com/sheharyarmonnoo/bva-narrator.git
cd bva-narrator && pip install -e ".[dev]"
python -m bva_narrator examples/period.json

Set your LLM key in .env:

cp .env.example .env
# OPENAI_API_KEY=sk-...    (or ANTHROPIC_API_KEY)

Sample output

See examples/ for sample inputs and expected outputs. Run:

python -m bva_narrator examples/sample.json

Project layout

src/bva_narrator/        package
examples/            sample inputs + expected outputs
tests/               pytest
docs/                deeper notes
.github/             CI + assets

Roadmap

• Multi-tenant input adapters
• Provider-agnostic prompt registry
• Streamlit dashboard
• Audit-trail export

Why this exists

This repo is part of finance-ai-labs — a set of agentic-AI products covering the workflows a PE-backed CFO actually owns: M&A underwriting, GL automation, payor analytics, covenant compliance, 13-week cash, board reporting, and the rest of the operating cadence. The agents do the mechanics. The CFO keeps the judgment.

Built by

Sheharyar Monnoo — Director of Finance at a PE-backed healthcare platform. Building the finance operating system for the next-decade CFO.

Portfolio · LinkedIn · Book a call

---

_{MIT licensed · Built with pydantic, openpyxl, and a homegrown agentic loop — no framework magic.}